Using divisions with Contact Center

Use Zoom Contact Center divisions to organize agents into distinct, independently managed business units. Divisions are designed for large organizations with separate business units that operate independently and do not need to share data, variables, or configurations between units.

If you are not yet using divisions, make sure you understand them and their impact before enabling divisions. For managing access within departments of a single organization that need to share data, consider using role-based access control instead.

You can manage divisions through the admin portal or programmatically using the API. To get started, make sure you have Edit permission and a valid access token for API operations.

For step-by-step instructions on creating divisions in the admin portal and understanding the impact of moving or deleting divisions, see Creating divisions for Zoom Customer Experience (ZCX).

Configure your app for API calls

To use Division APIs, division scopes are required. Add the required OAuth scopes to your admin-managed OAuth application or server-to-server (S2S) application.

The following OAuth scopes are required:

division:write:admin – Grants permission to create and modify divisions
division:read:admin – Grants permission to read information about divisions
division:read:division:admin – Grants granular read access to specific divisions

To generate your access token, send a POST request to https://zoom.us/oauth/token using your Client ID and Client Secret.

For a general OAuth app, follow the user authorization flow to generate your access token.
For an S2S application, use a basic authorization header to generate your token.

Send the following request, replacing <account_id>, <client_id>, and <client_secret> with your app credentials.

Example request

POST https://zoom.us/oauth/token?grant_type=account_credentials&account_id=<account_id>
Username - <client_id>
Password - <client_secret>

Understanding division-based access control

Division APIs return different results based on the caller's authorization level. Access control varies depending on the admin role:

Super Admin - Can view and manage all divisions and their resources across the entire organization.
Division Admin - Can only view and manage resources within their assigned division.

Using the X-Zoom-Division-Id header

Use the X-Zoom-Division-Id request header to scope API operations to a specific division. Super Admins can use this header to manage resources in divisions other than their own. Division Admins must use this header when working with division-specific endpoints.

Note

Not all Contact Center API endpoints support the X-Zoom-Division-Id header.

List all divisions

To retrieve all available division IDs and their corresponding names, use the List divisions endpoint. You'll need these division IDs when using API endpoints that support divisions.

Send the following request, replacing <access_token> with your access token.

Example request

curl https://api.zoom.us/v2/divisions \
  --header 'Authorization: Bearer <access_token>'

Example response

{
    "next_page_token": "",
    "page_size": 30,
    "total_records": 2,
    "divisions": [
        {
            "division_id": "<division_id>",
            "division_name": "Main Division",
            "division_description": "Main Division",
            "is_main_division": true,
            "total_members": 2
        },
        {
            "division_id": "<division_id>",
            "division_name": "Demo-1",
            "division_description": "Demo-1",
            "is_main_division": false,
            "total_members": 2
        }
    ]
}

Get division details

To retrieve detailed information about a specific division, use the following endpoint.

Send the following request, replacing <division_id> with your division ID and <access_token> with your access token.

Example request

curl https://api.zoom.us/v2/divisions/<division_id> \
  --header 'Authorization: Bearer <access_token>'

Example response

{
    "division_id": "<division_id>",
    "division_name": "Main Division",
    "division_description": "",
    "is_main_division": true
}

Create a division

Create a division ID and name programmatically using the division endpoint.

When you successfully create a division, the API returns a response containing the division details.

Send the following request, replacing <access_token> with your access token and updating the division name and description as needed.

Example request

curl -X POST https://api.zoom.us/v2/divisions \
  --header 'Authorization: Bearer <access_token>' \
  --header 'Content-Type: application/json' \
  --data '{
    "division_name": "Demo Division",
    "division_description": "Demo Division"
  }'

Example response

{
    "division_id": "<division_id>",
    "division_name": "Demo Division",
    "division_description": "Demo Division"
}

Working with division-scoped resources

After creating divisions, you can use the X-Zoom-Division-Id request header to perform division-specific operations with supported Contact Center API endpoints. The following example demonstrates adding a user to a specific division.

A Super Admin can add a user to a specific division by including the X-Zoom-Division-Id header in the request.

For information on this endpoint, see Create a user's profile.

Send the following request, replacing <division_id> with your division ID, <access_token> with your access token, and updating the user details in the request body.

Example request

curl -X POST https://api.zoom.us/v2/contact_center/users \
  --header 'X-Zoom-Division-Id: <division_id>' \
  --header 'Authorization: Bearer <access_token>' \
  --header 'Content-Type: application/json' \
  --data '{
    "user_id": "<user_id>",
    "user_email": "user@example.com",
    "role_id": "<role_id>",
    "country_iso_code": "US",
    "client_integration": "Default",
    "user_access": "active",
    "region_id": "<region_id>",
    "channel_settings": {
      "multi_channel_engagements": {
        "enable": true,
        "max_agent_load": 50,
        "email_max_agent_load": 50
      },
      "concurrent_message_capacity": 4,
      "concurrent_email_capacity": 4
    },
    "package_name": "elite",
    "emergency_calling": true
  }'

Example response

{
    "cc_user_id": "<cc_user_id>",
    "user_id": "<user_id>",
    "role_id": "<role_id>",
    "role_name": "Agent",
    "display_name": "User Name",
    "user_email": "user@example.com",
    "client_integration": "Default",
    "status_id": "0",
    "status_name": "Offline",
    "country_iso_code": "US",
    "channel_settings": {
        "multi_channel_engagements": {
            "enable": true,
            "max_agent_load": 50,
            "email_max_agent_load": 50
        },
        "concurrent_message_capacity": 4,
        "concurrent_email_capacity": 4,
        "concurrent_work_item_capacity": 4
    },
    "user_access": "active",
    "region_id": "<region_id>",
    "region_name": "Main Region",
    "division_id": "<division_id>",
    "division_name": "Main Division",
    "package_name": "elite",
    "emergency_calling": true,
    "user_occupied_rules": [
        {
            "key": "voice_or_video",
            "value": 100
        }
    ]
}