# Using divisions with Contact Center

<!-- WARNING: THIS FILE WAS AUTOGENERATED! DO NOT EDIT! -->

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)](https://support.zoom.com/hc/en/article?id=zm_kb&sysparm_article=KB0081842).

## Configure your app for API calls

To use [Division APIs](/docs/api/users/#tag/divisions), 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**

```bash
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. For the full list of endpoints that do, see [Division-supported APIs](/docs/contact-center/library/reference/division-supported-apis).

## List all divisions

To retrieve all available division IDs and their corresponding names, use the [List divisions](/docs/api/users/#tag/divisions/get/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**

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

**Example response**

```json
{
    "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**

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

**Example response**

```json
{
    "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**

```bash
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**

```json
{
    "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](/docs/api/contact-center/#tag/users/post/contact_center/users).

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**

```bash
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**

```json
{
    "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
        }
    ]
}
```