Contact Center

OpenAPI Version: 3.1.1
API Version: 2

The Contact Center APIs allow developers to interface with Contact Center features programmatically.

Servers

URL: https://api.zoom.us/v2

Operations

List address books

Method: GET
Path: /contact_center/address_books
Tags: Address Books

Return a list of all address books.

Scopes: contact_center_contact:read:admin

Granular Scopes: contact_center:read:list_address_books:admin

Rate Limit Label: MEDIUM

Responses

Status: 200 HTTP Status Code: `200` Address books list returned.

Content-Type: application/json

address_books

array — Information about the address books.

Items:
- address_book_description
  
  string — The address book's description.
- address_book_id
  
  string — The address book's ID.
- address_book_name
  
  string — The address book's name.
- total_contacts
  
  integer — The address book's total number of contacts.
- unit_id
  
  string — The address book unit's ID.
- unit_name
  
  string — The address book unit's name.
next_page_token

string — Use the next page token to paginate through large result sets. A next page token is returned whenever the set of available results exceeds the current page size. This token's expiration period is 15 minutes.
page_size

integer, default: 30 — The number of records returned within a single API call.
total_records

integer — The total number of all the records available across pages.

Example:

{
  "next_page_token": "R4aF9Oj0fVM2hhezJTEmSKaBSkfesDwGy42",
  "page_size": 30,
  "total_records": 1,
  "address_books": [
    {
      "address_book_id": "zeYjXoDOS_eV1QmTpj63PQ",
      "address_book_name": "Address Book",
      "address_book_description": "This is an address book.",
      "total_contacts": 30,
      "unit_id": "zeYjXoDOS_eV1QmTpj63PQ",
      "unit_name": "Unit"
    }
  ]
}

Status: 400 HTTP Status Code: `400` Bad Request Error Code: `1902` The `unit_id` field cannot be an empty value.

Status: 404 HTTP Status Code: `404` Not Found Error Code: `1901` Unit does not exist: $unitId.

Status: 429 HTTP Status Code: `429` Too Many Requests. For more information, see [rate limits](/docs/api/rest/rate-limits/).

Create an address book

Method: POST
Path: /contact_center/address_books
Tags: Address Books

Create an address book. An address book is a collection of consumer information like display names, phone numbers, and locations.

Scopes: contact_center_contact:write:admin

Granular Scopes: contact_center:write:address_book:admin

Rate Limit Label: LIGHT

Request Body

Content-Type: application/json

address_book_description

string — The address book's description.
address_book_name

string — The address book's name.
unit_id

string — The address book's unit ID.

Example:

{
  "unit_id": "zeYjXoDOS_eV1QmTpj63PQ",
  "address_book_name": "Address Book",
  "address_book_description": "This is an address book."
}

Responses

Status: 201 HTTP Status Code: `201` Address book created.

Content-Type: application/json

address_book_description

string — The address book's description.
address_book_id

string — The address book's ID.
address_book_name

string — The address book's name.
unit_id

string — The address book unit's ID.
unit_name

string — The address book unit's name.

Example:

{
  "address_book_id": "zeYjXoDOS_eV1QmTpj63PQ",
  "address_book_name": "Address Book",
  "address_book_description": "This is an address book.",
  "unit_id": "zeYjXoDOS_eV1QmTpj63PQ",
  "unit_name": "Unit"
}

Status: 400 HTTP Status Code: `400` Bad Request Error Code: `1902` The `unit_id` field cannot be an empty value. Error Code: `1903` The `address_book_name` field cannot be an empty value. Error Code: `2003` The address book name is not supported. Error Code: `2002` Address book already exists.

Status: 404 HTTP Status Code: `404` Not Found Error Code: `1901` Unit does not exist: $unitId.

Status: 429 HTTP Status Code: `429` Too Many Requests. For more information, see [rate limits](/docs/api/rest/rate-limits/).

List a contact's custom fields

Method: GET
Path: /contact_center/address_books/contacts/{contactId}/custom_fields
Tags: Address Books

List all custom fields on a contact.

Scopes: contact_center_contact:read:admin

Granular Scopes: contact_center:read:address_book_custom_field:admin

Rate Limit Label: MEDIUM

Responses

Status: 200 HTTP Status Code: 200 Contact custom fields are returned.

Content-Type: application/json

custom_fields

array — Array of custom field list.

Items:
- custom_field_id (required)
  
  string — The custom field's ID.
- custom_field_name (required)
  
  string — The custom field's name.
- data_type (required)
  
  string, possible values: "string", "number", "boolean", "email", "phone", "percent", "currency", "dateTime", "pick_list" — The custom field's data type. * string * number * boolean * email * phone - E.164 format * percent * currency * dateTime - unix timestamp * pick_list
- custom_field_value
  
  string — The contact's custom field value.
- outdated
  
  boolean — Whether the `custom_field_value` is outdated.
next_page_token

string — Use the next page token to paginate through large result sets. A next page token is returned whenever the set of available results exceeds the current page size. This token's expiration period is 15 minutes.
page_size

integer, default: 30 — The number of records returned within a single API call.

Example:

{
  "next_page_token": "R4aF9Oj0fVM2hhezJTEmSKaBSkfesDwGy42",
  "page_size": 30,
  "custom_fields": [
    {
      "custom_field_id": "7381d210-360e-4fbd-86e4-33eb7109b084",
      "custom_field_name": "Preferred Contact Method",
      "data_type": "pick_list",
      "custom_field_value": "phone",
      "outdated": false
    }
  ]
}

Status: 400 HTTP Status Code: `400` Bad Request

Status: 401 HTTP Status Code: `401` Unauthorized

Status: 403 HTTP Status Code: `403` Forbidden

Status: 404 HTTP Status Code: `404` Not Found Error Code: `2101` Contact does not exist: $contactId.

Status: 429 HTTP Status Code: `429` Too Many Requests. For more information, see [rate limits](/docs/api/rate-limits/).

List an address book's custom fields

Method: GET
Path: /contact_center/address_books/custom_fields
Tags: Address Books

Return all address book custom fields.

Scopes: contact_center_contact:read:admin

Granular Scopes: contact_center:read:address_book_custom_field:admin

Rate Limit Label: MEDIUM

Responses

Status: 200 The address book's custom fields list is returned.

Content-Type: application/json

custom_fields

array — Information about the address book custom fields.

Items:
- custom_field_id (required)
  
  string — The custom field's ID.
- custom_field_name (required)
  
  string — The custom field's name.
- data_type (required)
  
  string, possible values: "string", "number", "boolean", "email", "phone", "percent", "currency", "dateTime", "pick_list" — The custom field's data type. string number boolean email phone - E.164 format percent currency dateTime - unix timestamp pick_list
- address_books
  
  array — The address books associated with the custom field.
  
  Items:
  - address_book_id
    
    string — The address book's ID.
  - address_book_name
    
    string — The address book's name.
- custom_field_description
  
  string — The custom field's description.
- default_value
  
  string — The custom field's default value.
- pick_list_values
  
  array — Specify the list of supported values for the picklist. This is only valid when data_type is pick_list.
  
  Items:
  
  string
- show_in_inbound_notification
  
  boolean — Whether or not to show the custom fields on the inbound engagement notification in the Zoom client.
- show_in_profile_tab
  
  boolean — Whether or not to show the custom fields on the profile tab in the Zoom client.
- show_in_transferred_calls
  
  boolean — Whether or not to show the custom fields in calls transferred to Zoom Phone.
- use_as_external_url_parameter
  
  boolean — Whether or not to use the `custom_field_name` in defining external URLs launched for each engagement. When set to `true`, the `custom_field_name` should not contain any spaces.
- use_as_routing_profile_parameter
  
  boolean — Whether or not to use the custom fields in the consumer routing profile.
next_page_token

string — Use the next page token to paginate through large result sets. A next page token returns whenever the set of available results exceeds the current page size. This token's expiration period is 15 minutes.
page_size

number — The number of records returned within a single API call.
total_records

number — The total number of all the records available across pages.

Example:

{
  "next_page_token": "R4aF9Oj0fVM2hhezJTEmSKaBSkfesDwGy42",
  "page_size": 30,
  "total_records": 1,
  "custom_fields": [
    {
      "custom_field_id": "7381d210 Contact Method",
      "custom_field_name": "Preferred Contact Method",
      "custom_field_description": "Custom field for contact method",
      "data_type": "pick_list",
      "default_value": "phone",
      "pick_list_values": [
        "phone"
      ],
      "address_books": [
        {
          "address_book_id": "X2e_jsLNRkCjI0sQg2kRQQ",
          "address_book_name": "Jill's address book"
        }
      ],
      "use_as_routing_profile_parameter": true,
      "use_as_external_url_parameter": false,
      "show_in_transferred_calls": true,
      "show_in_inbound_notification": true,
      "show_in_profile_tab": false
    }
  ]
}

Status: 400 HTTP Status Code: `400` Bad Request

Status: 429 HTTP Status Code: `429` Too Many Requests. For more information, see [rate limits](/docs/api/rate-limits/).

Create an address book custom field

Method: POST
Path: /contact_center/address_books/custom_fields
Tags: Address Books

Create an address book custom field.

Scopes: contact_center_contact:write:admin

Granular Scopes: contact_center:write:address_book_custom_field:admin

Rate Limit Label: LIGHT

Request Body

Content-Type: application/json

custom_field_name (required)

string — The custom field's name.
data_type (required)

string, possible values: "string", "number", "boolean", "email", "phone", "percent", "currency", "dateTime", "pick_list" — The custom field's data type. string number boolean email phone - E.164 format percent currency dateTime - unix timestamp pick_list
address_book_ids

array — The address book IDs that should be associated with the custom field.

Items:

string — The address book's ID.
custom_field_description

string — The custom field's description.
default_value

string — The custom field's default value.
pick_list_values

array — Specify the list of supported values for the picklist. This is only valid when `data_type` is `pick_list`.

Items:

string
show_in_inbound_notification

boolean — Controls whether or not to show the custom fields on the inbound engagement notification in the Zoom client.
show_in_profile_tab

boolean — Controls whether or not to show the custom fields on the profile tab in the Zoom client.
show_in_transferred_calls

boolean — Controls whether or not to show the custom fields in calls transferred to Zoom Phone.
use_as_external_url_parameter

boolean — Controls whether or not to use the `custom_field_name` in defining external URLs launched for each engagement. When set to `true`, the `custom_field_name` should not contain any spaces.
use_as_routing_profile_parameter

boolean — Controls whether or not to use the custom fields in the consumer routing profile.

Example:

{
  "custom_field_name": "Preferred Contact Method",
  "custom_field_description": "The custom field for contact method",
  "data_type": "pick_list",
  "default_value": "phone",
  "pick_list_values": [
    "phone"
  ],
  "address_book_ids": [
    "X2e_jsLNRkCjI0sQg2kRQQ"
  ],
  "use_as_routing_profile_parameter": true,
  "use_as_external_url_parameter": false,
  "show_in_transferred_calls": true,
  "show_in_inbound_notification": true,
  "show_in_profile_tab": false
}

Responses

Status: 201 Custom field created.

Content-Type: application/json

custom_field_id (required)

string — The custom field's ID.
custom_field_name (required)

string — The custom field's name.
data_type (required)

string, possible values: "string", "number", "boolean", "email", "phone", "percent", "currency", "dateTime", "pick_list" — The custom field's data type. string number boolean email phone - E.164 format percent currency dateTime - unix timestamp pick_list
address_books

array — The address books associated with the custom field.

Items:
- address_book_id
  
  string — The address book's ID.
- address_book_name
  
  string — The address book's name.
custom_field_description

string — The custom field's description.
default_value

string — The custom field's default value.
pick_list_values

array — Specify the list of supported values for the picklist. This is only valid when `data_type` is `pick_list`.

Items:

string
show_in_inbound_notification

boolean — Controls whether or not to show the custom fields on the inbound engagement notification in the Zoom client.
show_in_profile_tab

boolean — Controls whether or not to show the custom fields on the profile tab in the Zoom client.
show_in_transferred_calls

boolean — Controls whether or not to show the custom fields in calls transferred to Zoom Phone.
use_as_external_url_parameter

boolean — Controls whether or not to use the `custom_field_name` in defining external URLs launched for each engagement. When set to true, the `custom_field_name` should not contain any spaces.
use_as_routing_profile_parameter

boolean — Controls whether or not to use the custom fields in the consumer routing profile.

Example:

{
  "custom_field_id": "7381d210-360e-4fbd-86e4-33eb7109b084",
  "custom_field_name": "Preferred Contact Method",
  "custom_field_description": "The custom field for contact method",
  "data_type": "pick_list",
  "default_value": "phone",
  "pick_list_values": [
    "phone"
  ],
  "address_books": [
    {
      "address_book_id": "X2e_jsLNRkCjI0sQg2kRQQ",
      "address_book_name": "Jill's address book"
    }
  ],
  "use_as_routing_profile_parameter": true,
  "use_as_external_url_parameter": false,
  "show_in_transferred_calls": true,
  "show_in_inbound_notification": true,
  "show_in_profile_tab": false
}

Status: 400 HTTP Status Code: `400` Bad Request Error Code: `300` Invalid field. Error Code: `2107` A custom field with this name already exists: $custom_field_name Error Code: `2108` The data type provided for the custom field is not supported. Error Code: `2109` The default value format does not match the data type. Error Code: `2110` Maximum limit of 4096 custom fields has been exceeded. Error Code: `2111` Custom field name cannot contain spaces when use_as_external_url_parameter is true. Error Code: `2115` Invalid default value. The provided value is not in the list of supported picklist values.

Status: 404 HTTP Status Code: `404` Not Found Error Code: `2006` Address books does not exist: $addressBookIds.

Status: 429 HTTP Status Code: `429` Too Many Requests. For more information, see [rate limits](/docs/api/rate-limits/).

Get an address book's custom field

Method: GET
Path: /contact_center/address_books/custom_fields/{customFieldId}
Tags: Address Books

Get information about an address book's custom field.

Scopes: contact_center_contact:read:admin

Granular Scopes: contact_center:read:address_book_custom_field:admin

Rate Limit Label: LIGHT

Responses

Status: 200 The address book's custom field is returned.

Content-Type: application/json

custom_field_id (required)

string — The custom field's ID.
custom_field_name (required)

string — The custom field's name.
data_type (required)

string, possible values: "string", "number", "boolean", "email", "phone", "percent", "currency", "dateTime", "pick_list" — The custom field's data type. string number boolean email phone - E.164 format percent currency dateTime - unix timestamp pick_list
address_books

array — The address books associated with the custom field.

Items:
- address_book_id
  
  string — The address book's ID.
- address_book_name
  
  string — The address book's name.
custom_field_description

string — The custom field's description.
default_value

string — The custom field's default value.
pick_list_values

array — Specify the list of supported values for the picklist. This is only valid when data_type is pick_list.

Items:

string
show_in_inbound_notification

boolean — Whether or not to show the custom fields on the inbound engagement notification in the Zoom client.
show_in_profile_tab

boolean — Whether or not to show the custom fields on the profile tab in the Zoom client.
show_in_transferred_calls

boolean — Whether or not to show the custom fields in calls transferred to Zoom Phone.
use_as_external_url_parameter

boolean — Whether or not to use the `custom_field_name` in defining external URLs launched for each engagement. When set to `true`, the `custom_field_name` should not contain any spaces.
use_as_routing_profile_parameter

boolean — Whether or not to use the custom fields in the consumer routing profile.

Example:

{
  "custom_field_id": "7381d210-360e-4fbd-86e4-33eb7109b084",
  "custom_field_name": "Preferred Contact Method",
  "custom_field_description": "Custom field for contact method",
  "data_type": "pick_list",
  "default_value": "phone",
  "pick_list_values": [
    "phone"
  ],
  "address_books": [
    {
      "address_book_id": "X2e_jsLNRkCjI0sQg2kRQQ",
      "address_book_name": "Jill's address book"
    }
  ],
  "use_as_routing_profile_parameter": true,
  "use_as_external_url_parameter": false,
  "show_in_transferred_calls": true,
  "show_in_inbound_notification": true,
  "show_in_profile_tab": false
}

Status: 400 HTTP Status Code: `400` Bad Request

Status: 404 HTTP Status Code: `404` Not Found Error Code: `2112` Custom field does not exist: $customFieldId

Status: 429 HTTP Status Code: `429` Too Many Requests. For more information, see [rate limits](https://developers.zoom.us/docs/api/rate-limits/).

Delete an address book custom field

Method: DELETE
Path: /contact_center/address_books/custom_fields/{customFieldId}
Tags: Address Books

Delete an address book custom field.

Scopes: contact_center_contact:write:admin

Granular Scopes: contact_center:delete:address_book_custom_field:admin

Rate Limit Label: LIGHT

Responses

Status: 204 Custom field deleted.

Status: 400 HTTP Status Code: `400` Bad Request

Status: 404 HTTP Status Code: `404` Not Found Error Code: `2112` Custom field does not exist: $customFieldId.

Status: 429 HTTP Status Code: `429` Too Many Requests. For more information, see [rate limits](/docs/api/rate-limits/).

Update an address book custom field

Method: PATCH
Path: /contact_center/address_books/custom_fields/{customFieldId}
Tags: Address Books

Update an address book custom field.

Scopes: contact_center_contact:write:admin

Granular Scopes: contact_center:update:address_book_custom_field:admin

Rate Limit Label: LIGHT

Request Body

Content-Type: application/json

custom_field_name (required)

string — The custom field's name.
data_type (required)

string, possible values: "string", "number", "boolean", "email", "phone", "percent", "currency", "dateTime", "pick_list" — The custom field's data type. string number boolean email phone - E.164 format percent currency dateTime - unix timestamp pick_list
address_book_ids

array — The address book IDs that should be associated with the custom field.

Items:

string — The address book's ID.
custom_field_description

string — The custom field's description.
default_value

string — The custom field's default value.
pick_list_values

array — Specify the list of supported values for the picklist. This is only valid when data_type is pick_list.

Items:

string
show_in_inbound_notification

boolean — Whether or not to show the custom fields on the inbound engagement notification in the Zoom client.
show_in_profile_tab

boolean — Whether or not to show the custom fields on the profile tab in the Zoom client.
show_in_transferred_calls

boolean — Whether or not to show the custom fields in calls transferred to Aoom Pnone.
use_as_external_url_parameter

boolean — Whether or not to use the `custom_field_name` in defining external URLs launched for each engagement. When set to true, the `custom_field_name` should not contain any spaces.
use_as_routing_profile_parameter

boolean — Whether or not to use the custom fields in the consumer routing profile.

Example:

{
  "custom_field_name": "Preferred Contact Method",
  "custom_field_description": "The custom field for contact method",
  "data_type": "pick_list",
  "default_value": "phone",
  "pick_list_values": [
    "phone"
  ],
  "address_book_ids": [
    "X2e_jsLNRkCjI0sQg2kRQQ"
  ],
  "use_as_routing_profile_parameter": true,
  "use_as_external_url_parameter": false,
  "show_in_transferred_calls": true,
  "show_in_inbound_notification": true,
  "show_in_profile_tab": false
}

Responses

Status: 204 Custom field updated.

Status: 400 HTTP Status Code: `400` Bad Request Error Code: `300` Invalid field. Error Code: `2107` A custom field with this name already exists: $custom_field_name. Error Code: `2108` The data type provided for the custom field is not supported. Error Code: `2109` The default value format does not match the data type. Error Code: `2111` Custom field name cannot contain spaces when `use_as_external_url_parameter` is `true`. Error Code: `2115` Invalid default value. The provided value is not in the list of supported picklist values.

Status: 404 HTTP Status Code: `404` Not Found Error Code: `2112` Custom field does not exist: $customFieldId. Error Code: `2006` Address books does not exist: $addressBookIds.

Status: 429 HTTP Status Code: `429` Too Many Requests. For more information, see [rate limits](/docs/api/rate-limits/).

List address book units

Method: GET
Path: /contact_center/address_books/units
Tags: Address Books

Return all address book units.

Scopes: contact_center_contact:read:admin

Granular Scopes: contact_center:read:list_address_book_units:admin

Rate Limit Label: MEDIUM

Responses

Status: 200 HTTP Status Code: `200` Units list returned.

Content-Type: application/json

next_page_token

string — The next page token is used to paginate through large result sets. A next page token will be returned whenever the set of available results exceeds the current page size. The expiration period for this token is 15 minutes.
page_size

integer, default: 30 — The number of records returned within a single API call.
total_records

integer — The total number of all the records available across pages.
units

array — Information about the address book units.

Items:
- unit_description
  
  string — The address book unit's description.
- unit_id
  
  string — The address book unit's ID.
- unit_name
  
  string — The address book unit's name.

Example:

{
  "next_page_token": "R4aF9Oj0fVM2hhezJTEmSKaBSkfesDwGy42",
  "page_size": 30,
  "total_records": 1,
  "units": [
    {
      "unit_id": "zeYjXoDOS_eV1QmTpj63PQ",
      "unit_name": "Example",
      "unit_description": "This is a unit description."
    }
  ]
}

Status: 400 HTTP Status Code: `400` Bad Request

Status: 429 HTTP Status Code: `429` Too Many Requests. For more information, see [rate limits](/docs/api/rest/rate-limits/).

Create an address book unit

Method: POST
Path: /contact_center/address_books/units
Tags: Address Books

Create an address book unit. Admins can use address book units to organize several address books.

Scopes: contact_center_contact:write:admin

Granular Scopes: contact_center:write:address_book_unit:admin

Rate Limit Label: LIGHT

Request Body

Content-Type: application/json

unit_description

string — The address book unit's description.
unit_name

string — The address book unit's name.

Example:

{
  "unit_name": "Example",
  "unit_description": "This is a unit."
}

Responses

Status: 201 HTTP Status Code: `201` Unit created.

Content-Type: application/json

unit_description

string — The address book unit's description.
unit_id

string — The address book unit's ID.
unit_name

string — The address book unit's name.

Example:

{
  "unit_id": "zeYjXoDOS_eV1QmTpj63PQ",
  "unit_name": "Example",
  "unit_description": "This is a unit."
}

Status: 400 HTTP Status Code: `400` Bad Request Error Code: `1904` Unit already exists.

Status: 429 HTTP Status Code: `429` Too Many Requests. For more information, see [rate limits](/docs/api/rest/rate-limits/).

Get an address book unit

Method: GET
Path: /contact_center/address_books/units/{unitId}
Tags: Address Books

Returns information about an address book unit.

Scopes: contact_center_contact:read:admin

Granular Scopes: contact_center:read:address_book_unit:admin

Rate Limit Label: LIGHT

Responses

Status: 200 HTTP Status Code: `200` Unit returned.

Content-Type: application/json

unit_description

string — The address book unit's description.
unit_id

string — The address book unit's ID.
unit_name

string — The address book unit's name.

Example:

{
  "unit_id": "zeYjXoDOS_eV1QmTpj63PQ",
  "unit_name": "Example",
  "unit_description": "This is a unit description."
}

Status: 400 HTTP Status Code: `400` Bad Request Error Code: `2008` More than one matching address book unit found.

Status: 401 HTTP Status Code: `401` Unauthorized

Status: 403 HTTP Status Code: `403` Forbidden

Status: 404 HTTP Status Code: `404` Not Found Error Code: `1901` Unit does not exist: $unitId.

Status: 429 HTTP Status Code: `429` Too Many Requests. For more information, see [rate limits](/docs/api/rest/rate-limits/).

Delete an address book unit

Method: DELETE
Path: /contact_center/address_books/units/{unitId}
Tags: Address Books

Delete an address book unit.

Scopes: contact_center_contact:write:admin

Granular Scopes: contact_center:delete:address_book_unit:admin

Rate Limit Label: LIGHT

Responses

Status: 204 HTTP Status Code: `204` Unit deleted.

Status: 400 HTTP Status Code: `400` Bad Request Error Code: `1905` Salesforce integration unit cannot be updated and deleted.

Status: 404 HTTP Status Code: `404` Not Found Error Code: `1901` Unit does not exist: $unitId.

Status: 429 HTTP Status Code: `429` Too Many Requests. For more information, see [rate limits](/docs/api/rest/rate-limits/).

Update an address book unit

Method: PATCH
Path: /contact_center/address_books/units/{unitId}
Tags: Address Books

Update an address book unit.

Scopes: contact_center_contact:write:admin

Granular Scopes: contact_center:update:address_book_unit:admin

Rate Limit Label: LIGHT

Request Body

Content-Type: application/json

unit_description

string — The address book unit's description.
unit_name

string — The address book unit's name.

Example:

{
  "unit_name": "example",
  "unit_description": "This is a Demo Unit."
}

Responses

Status: 204 HTTP Status Code: `204` Unit updated.

Status: 400 HTTP Status Code: `400` Bad Request Error Code: `1905` Salesforce integration unit cannot be updated or deleted.

Status: 404 HTTP Status Code: `404` Not Found Error Code: `1901` Unit does not exist: $unitId.

Status: 429 HTTP Status Code: `429` Too Many Requests. For more information, see [rate limits](/docs/api/rest/rate-limits/).

Get an address book

Method: GET
Path: /contact_center/address_books/{addressBookId}
Tags: Address Books

Returns information about an address book.

Scopes: contact_center_contact:read:admin

Granular Scopes: contact_center:read:address_book:admin

Rate Limit Label: LIGHT

Responses

Status: 200 HTTP Status Code: `200` Address book list returned.

Content-Type: application/json

address_book_description

string — The address book's description.
address_book_id

string — The address book's ID.
address_book_name

string — The address book's name.
queue_ids

array — The queue IDs that are accessible to an address book.

Items:

string — The Contact Center queue's ID or task queue id.
team_ids

array — The team IDs to that are accessible to an address book.

Items:

string — The team's ID.
total_contacts

integer — The address book's total number of contacts.
unit_id

string — The address book unit's ID.
unit_name

string — The address book unit's name.

Example:

{
  "address_book_id": "zeYjXoDOS_eV1QmTpj63PQ",
  "address_book_name": "Address Book",
  "address_book_description": "This is an address book.",
  "total_contacts": 30,
  "unit_id": "zeYjXoDOS_eV1QmTpj63PQ",
  "unit_name": "Unit",
  "queue_ids": [
    "beYjXoDOS_eV1QmTpj63PQ"
  ],
  "team_ids": [
    "neYjXoDOS_tV1QmTpj43PQ"
  ]
}

Status: 400 HTTP Status Code: `400` Bad Request Error Code: `2007` More than one matching address book found.

Status: 401 HTTP Status Code: `401` Unauthorized

Status: 403 HTTP Status Code: `403` Forbidden

Status: 404 HTTP Status Code: `404` Not Found Error Code: `2001` Address book does not exist: $addressBookId.

Status: 429 HTTP Status Code: `429` Too Many Requests. For more information, see [rate limits](/docs/api/rest/rate-limits/).

Delete an address book

Method: DELETE
Path: /contact_center/address_books/{addressBookId}
Tags: Address Books

Delete an address book.

Scopes: contact_center_contact:write:admin

Granular Scopes: contact_center:delete:address_book:admin

Rate Limit Label: LIGHT

Responses

Status: 204 HTTP Status Code: `204` Address Book deleted.

Status: 400 HTTP Status Code: `400` Bad Request

Status: 404 HTTP Status Code: `404` Not Found Error Code: `1201` Address book does not exist: $addressBookId

Status: 429 HTTP Status Code: `429` Too Many Requests. For more information, see [rate limits](/docs/api/rest/rate-limits/).

Update an address book

Method: PATCH
Path: /contact_center/address_books/{addressBookId}
Tags: Address Books

Update an address book's information.

Scopes: contact_center_contact:write:admin

Granular Scopes: contact_center:update:address_book:admin

Rate Limit Label: LIGHT

Request Body

Content-Type: application/json

address_book_description

string — The address book's description.
address_book_name

string — The address book's name.

Example:

{
  "address_book_name": "example",
  "address_book_description": "This is a Demo Address Book."
}

Responses

Status: 204 HTTP Status Code: `204` Address book updated.

Status: 400 HTTP Status Code: `400` Bad Request Error Code: `2004` Salesforce integration address book cannot be updated or deleted.

Status: 404 HTTP Status Code: `404` Not Found Error Code: `2001` Address book does not exist: $addressBookId.

Status: 429 HTTP Status Code: `429` Too Many Requests. For more information, see [rate limits](/docs/api/rest/rate-limits/).

List address book contacts

Method: GET
Path: /contact_center/address_books/{addressBookId}/contacts
Tags: Address Books

When the emails or phone_numbers query parameter is included, the address book returns a maximum of 10,000 contacts.

Scopes: contact_center_contact:read:admin

Granular Scopes: contact_center:read:list_address_book_contacts:admin

Rate Limit Label: MEDIUM

Responses

Status: 200 HTTP Status Code: `200` Contacts list returned.

Content-Type: application/json

contacts

array — Information about the contacts.

Items:
- contact_id (required)
  
  string — The contact's ID.
- display_name (required)
  
  string — The contact's name.
- phones (required)
  
  array — The contact's phone numbers.
  
  Items:
  - phone_number
    
    string — The phone number.
  - phone_type
    
    string, possible values: "main", "work", "home", "mobile", "other" — The phone number type.
- account_number
  
  string — The contact's account number.
- address_book_id
  
  string — The address book's ID.
- address_book_name
  
  string — The address book's name.
- company
  
  string — The contact's company.
- consumer_ids
  
  array — The consumer IDs associated with the contact.
  
  Items:
  
  string — The consumer's unique ID.
- custom_fields_url
  
  string — The URL to retrieve contact's custom field list, if the contact custom fields exists. \r\nFor security purposes, you must provide an OAuth access token in the authorization header to to retrieve contact's custom field list using this URL. Example:\r\ncurl --request GET \r\n --url {custom_fields_url} \r\n --header 'authorization: Bearer {access_token}' \r\n --header 'content-type: application/json'\r\n
- emails
  
  array — The contact's email addresses.
  
  Items:
  
  string, format: email
- first_name
  
  string — The contact's first name.
- last_name
  
  string — The contact's last name.
- location
  
  string — The contact's location.
- phone_numbers
  
  array — The contact's phone numbers.
  
  Items:
  
  string
- role
  
  string — The contact's role.
- timezone
  
  string — The contact's time zone. Refer to this list for supported [timezones](/docs/api/references/abbreviations/#timezones).
- variables
  
  array — Information about address book variables.
  
  Items:
  - data_type
    
    string, possible values: "string", "boolean" — The variable's data type.
  - variable_group_id
    
    string — The variable group's ID.
  - variable_id
    
    string — The variable's ID.
  - variable_name
    
    string — The variable's name.
  - variable_value
    
    string — The variable's value.
next_page_token

string — Use the next page token to paginate through large result sets. A next page token is returned whenever the set of available results exceeds the current page size. This token's expiration period is 15 minutes.
page_size

integer, default: 30 — The number of records returned in a single API call.
total_records

integer — The total number of all records available across pages.

Example:

{
  "next_page_token": "R4aF9Oj0fVM2hhezJTEmSKaBSkfesDwGy42",
  "page_size": 30,
  "total_records": 10,
  "contacts": [
    {
      "contact_id": "zeYjXoDOS_eV1QmTpj63PQ",
      "display_name": "Jill Chill",
      "first_name": "Jill",
      "last_name": "Chill",
      "phones": [
        {
          "phone_number": "+12048002447",
          "phone_type": "main"
        }
      ],
      "emails": [
        "user@example.com"
      ],
      "location": "San Jose",
      "timezone": "America/Los_Angeles",
      "account_number": "112233445566",
      "company": "Example",
      "role": "Agent",
      "address_book_id": "zeYjXoDOS_eV1QmTpj63PQ",
      "address_book_name": "Address Book",
      "variables": [
        {
          "variable_group_id": "afececcd-0c9f-48de-9d19-0c84e8bdfeca",
          "variable_id": "zeYjXoDOS_eV1QmTpj63PQ",
          "variable_name": "variable demo name",
          "data_type": "string",
          "variable_value": "variable value demo"
        }
      ],
      "consumer_ids": [
        "cvC2JxWkToWZsJUenBvNnw"
      ],
      "custom_fields_url": "https://api.zoom.us/v2/contact_center/address_books/custom_fields/contacts/zeYjXoDOS_eV1QmTpj63PQ"
    }
  ]
}

Status: 400 HTTP Status Code: `400` Bad Request Error Code: `300` Number of phone numbers exceeds max limit of 10 Error Code: `300` Number of emails exceeds max limit of 10 Error Code: `300` Invalid phone number Error Code: `300` Invalid email Error Code: `2007` More than one matching address book found.

Status: 401 HTTP Status Code: `401` Unauthorized

Status: 403 HTTP Status Code: `403` Forbidden

Status: 404 HTTP Status Code: `404` Not Found Error Code: `2001` Address book does not exist: $addressBookId.

Status: 429 HTTP Status Code: `429` Too Many Requests. For more information, see [rate limits](/docs/api/rate-limits/).

Create an address book contact

Method: POST
Path: /contact_center/address_books/{addressBookId}/contacts
Tags: Address Books

Create a new contact in an address book. During an active engagement, the Zoom desktop client displays information from the address book if that customer is a contact in the address book. If the consumer is not in the address book, agents can add a new contact and choose which address book the contact belongs to.

Scopes: contact_center_contact:write:admin

Granular Scopes: contact_center:write:address_book_contact:admin

Rate Limit Label: LIGHT

Request Body

Content-Type: application/json

display_name (required)

string — The contact's display name.
phone_numbers (required)

array — The contact's phone numbers. You must provide this field and/or the `email` field when you create a contact.

Items:

string
phones (required)

array — The contact's phone numbers.

Items:
- phone_number
  
  string — The phone number.
- phone_type
  
  string, possible values: "main", "work", "home", "mobile", "other" — The phone number type.
account_number

string — The contact's account number.
company

string — The contact's company.
consumer_ids

array — The consumer IDs to be associated with the contact.

Items:

string — The consumer's unique ID.
custom_fields

array — Information about address book's custom fields.

Items:
- custom_field_id (required)
  
  string — The custom field's ID.
- custom_field_value
  
  string — The custom field's value.
emails

array — The contact's email addresses. You must provide either this field or the `phone_numbers` field, or both, when you create a contact.

Items:

string, format: email
first_name

string — The contact's first name.
last_name

string — The contact's last name.
location

string — The contact's location.
role

string — The contact's role.
timezone

string — The contact's time zone. Refer to this list for supported [timezones](/docs/api/references/abbreviations/#timezones).
variables

array — Information about address book variables.

Items:
- variable_id
  
  string — The variable's ID.
- variable_value
  
  string — The variable's value.

Example:

{
  "display_name": "Jane Doe",
  "first_name": "Jane",
  "last_name": "Doe",
  "phones": [
    {
      "phone_number": "+12048002447",
      "phone_type": "main"
    }
  ],
  "emails": [
    "user@example.com"
  ],
  "location": "San Jose",
  "timezone": "America/Los_Angeles",
  "account_number": "112233445566",
  "company": "Example",
  "role": "Agent",
  "variables": [
    {
      "variable_id": "zeYjXoDOS_eV1QmTpj63PQ",
      "variable_value": "variable value demo"
    }
  ],
  "consumer_ids": [
    "cvC2JxWkToWZsJUenBvNnw"
  ],
  "custom_fields": [
    {
      "custom_field_id": "7381d210-360e-4fbd-86e4-33eb7109b084",
      "custom_field_value": "phone"
    }
  ]
}

Responses

Status: 201 HTTP Status Code: `201` Contact created.

Content-Type: application/json

display_name (required)

string — The contact's display name.
phone_numbers (required)

array — The contact's phone numbers.

Items:

string
phones (required)

array — The contact's phone numbers.

Items:
- phone_number
  
  string — The phone number.
- phone_type
  
  string, possible values: "main", "work", "home", "mobile", "other" — The phone number type.
account_number

string — The contact's account number.
address_book_id

string — The address book's ID.
address_book_name

string — The address book's name.
company

string — The contact's company.
consumer_ids

array — The consumer IDs associated with the contact.

Items:

string — The consumer's unique ID.
contact_id

string — The contact's ID.
custom_fields_url

string — The URL to retrieve contact's custom field list, if the contact custom fields exists. \r\nFor security purposes, you must provide an OAuth access token in the authorization header to to retrieve contact's custom field list using this URL. Example:\r\ncurl --request GET \r\n --url {custom_fields_url} \r\n --header 'authorization: Bearer {access_token}' \r\n --header 'content-type: application/json'\r\n
emails

array — The contact's email addresses.

Items:

string, format: email
first_name

string — The contact's first name.
last_name

string — The contact's last name.
location

string — The contact's location.
role

string — The contact's role.
timezone

string — The contact's time zone. Refer to this list for supported [timezones](/docs/api/references/abbreviations/#timezones).
variables

array — Information about address book variables.

Items:
- data_type
  
  string, possible values: "string", "boolean" — The variable's data type.
- variable_group_id
  
  string — The variable group's ID.
- variable_id
  
  string — The variable's ID.
- variable_name
  
  string — The variable's name.
- variable_value
  
  string — The variable's value.

Example:

{
  "contact_id": "zeYjXoDOS_eV1QmTpj63PQ",
  "display_name": "Jane Doe",
  "first_name": "Jane",
  "last_name": "Doe",
  "phones": [
    {
      "phone_number": "+12048002447",
      "phone_type": "main"
    }
  ],
  "emails": [
    "user@example.com"
  ],
  "location": "San Jose",
  "timezone": "America/Los_Angeles",
  "account_number": "112233445566",
  "company": "Example",
  "role": "Agent",
  "address_book_id": "jweQeTYDOS_eV1QmTpj63PQ",
  "address_book_name": "Address Book",
  "variables": [
    {
      "variable_group_id": "afececcd-0c9f-48de-9d19-0c84e8bdfeca",
      "variable_id": "zeYjXoDOS_eV1QmTpj63PQ",
      "variable_name": "variable demo name",
      "data_type": "string",
      "variable_value": "variable value demo"
    }
  ],
  "consumer_ids": [
    "cvC2JxWkToWZsJUenBvNnw"
  ],
  "custom_fields_url": "https://api.zoom.us/v2/contact_center/address_books/custom_fields/contacts/zeYjXoDOS_eV1QmTpj63PQ"
}

Status: 400 HTTP Status Code: `400` Bad Request Error Code: `2102` At least one of email's or phone's fields should be not empty. Error Code: `2104` The `display_name` field cannot be an empty value. Error Code: `2005` Salesforce integration contact can not be added, updated, or deleted. Error Code: `2106` Invalid consumer IDs: $consumerIds. Error Code: `2113` Contact custom field value `custom_field_value` format does not match the data type. Error Code: `2114` Custom field is invalid: $customFieldId Error Code: `2116` Invalid custom field value `custom_field_value`. The provided value is not in the list of supported picklist values. Error Code: `2117` Invalid time zone: $timezone. Error Code: `300` Invalid phone type. Error Code: `300` Only one main phone number is allowed. Error Code: `300` The maximum number of phones allowed is 5.

Status: 401 HTTP Status Code: `401` Unauthorized Error Code: `1002` The user associated with this access token was not found or is invalid. Error Code: `124` Invalid access token. Error Code: `124` Access token has expired.

Status: 403 HTTP Status Code: `403` Forbidden Error Code: `1021` User account is deactivated. Error Code: `1022` User does not have a Contact Center license. Error Code: `9001` The Contact Center user associated with this bearer token is missing privileges on their role required to operate this request.

Status: 404 HTTP Status Code: `404` Not Found Error Code: `2001` Address book does not exist: $addressBookId.

Status: 429 HTTP Status Code: `429` Too Many Requests. For more information, see [rate limits](/docs/api/rest/rate-limits/). Error Code: `4001` You have reached the maximum per-second rate limit for this API. Try again later.

Batch create address book contacts

Method: POST
Path: /contact_center/address_books/{addressBookId}/contacts/batch
Tags: Address Books

Batch create new contacts in an address book (https://support.zoom.us/hc/en-us/articles/4471544949389). Supports up to 10 contacts per request. Valid contacts are created while invalid contacts are rejected with detailed error messages. Returns 200 for all valid or partial success with invalid contact details, or 400 if all contacts are invalid.

Scopes: contact_center_contact:write:admin

Granular Scopes: contact_center:write:address_book_contact:admin

Rate Limit Label: MEDIUM

Request Body

Content-Type: application/json

contacts

array — Information about the contacts to create.

Items:
- display_name (required)
  
  string — The contact's display name.
- account_number
  
  string — The contact's account number.
- company
  
  string — The contact's company.
- consumer_ids
  
  array — The list of consumer IDs to associate with the contact.
  
  Items:
  
  string — The consumer's unique ID.
- custom_fields
  
  array — The custom field values for this contact.
  
  Items:
  - custom_field_id (required)
    
    string — The custom field's ID.
  - custom_field_value
    
    string — The custom field's value.
- emails
  
  array — The contact's email addresses.
  
  Items:
  
  string, format: email
- first_name
  
  string — The contact's first name.
- last_name
  
  string — The contact's last name.
- location
  
  string — The contact's location.
- phones
  
  array — The contact's phone numbers.
  
  Items:
  - phone_number (required)
    
    string — The phone number in E.164 format.
  - phone_type
    
    string, possible values: "main", "work", "home", "mobile", "other" — The type of phone number.
- role
  
  string — The contact's role.
- source_id
  
  string — The contact's source ID. This field is required for CRM address books.
- source_name
  
  string — The contact's source name.
- timezone
  
  string — The contact's time zone.

Example:

{
  "contacts": [
    {
      "display_name": "John Doe",
      "first_name": "John",
      "last_name": "Doe",
      "phones": [
        {
          "phone_number": "+12048002447",
          "phone_type": "main"
        }
      ],
      "emails": [
        "john.doe@example.com"
      ],
      "location": "New York",
      "timezone": "America/Los_Angeles",
      "account_number": "112233445566",
      "company": "Acme Corp",
      "role": "Agent",
      "consumer_ids": [
        "cvC2JxWkToWZsJUenBvNnw"
      ],
      "custom_fields": [
        {
          "custom_field_id": "7381d210-360e-4fbd-86e4-33eb7109b084",
          "custom_field_value": "priority"
        }
      ],
      "source_id": "R4aF9Oj0fVM2hhezJTEmSKaBSkfesDwGy42",
      "source_name": "salesforce"
    }
  ]
}

Responses

Status: 200 HTTP Status Code: `200` Contacts created. When some contacts fail validation, the response includes both `contacts` (successful) and `invalid_contacts` (failed with error details).

Content-Type: application/json

contacts

array — Information about the created contacts.

Items:
- account_number
  
  string — The contact's account number.
- address_book_id
  
  string — The address book's ID.
- address_book_name
  
  string — The address book's name.
- company
  
  string — The contact's company.
- consumer_ids
  
  array — The consumer IDs associated with the contact.
  
  Items:
  
  string
- contact_id
  
  string — The contact's ID.
- custom_fields_url
  
  string — The URL to retrieve the contact's custom field list.
- display_name
  
  string — The contact's name.
- emails
  
  array — The contact's email addresses.
  
  Items:
  
  string, format: email
- first_name
  
  string — The contact's first name.
- last_name
  
  string — The contact's last name.
- location
  
  string — The contact's location.
- phones
  
  array — The contact's phone numbers.
  
  Items:
  - phone_number
    
    string — The phone number in E.164 format.
  - phone_type
    
    string, possible values: "main", "work", "home", "mobile", "other" — The type of phone number. Allowed values are main, work, home, mobile, and other.
- role
  
  string — The contact's role.
- source_id
  
  string — The contact's source ID. This field is required for CRM address books.
- source_name
  
  string — The contact's source name.
- timezone
  
  string — The contact's time zone.
invalid_contacts

array — Contacts that failed validation. Only present when some contacts in the batch are invalid.

Items:
- display_name
  
  string — The contact's display name from the request.
- emails
  
  array — The email addresses from the request.
  
  Items:
  
  string — The email addresses from the request.
- error_messages
  
  array — Validation error messages for this contact.
  
  Items:
  
  string — Invalid phone number.
- phone_numbers
  
  array — The phone numbers from the request.
  
  Items:
  
  string — The phone numbers from the request.

Example:

{
  "contacts": [
    {
      "contact_id": "zeYjXoDOS_eV1QmTpj63PQ",
      "display_name": "John Doe",
      "first_name": "John",
      "last_name": "Doe",
      "phones": [
        {
          "phone_number": "+12048002447",
          "phone_type": "main"
        }
      ],
      "emails": [
        "john.doe@example.com"
      ],
      "location": "New York",
      "timezone": "America/Los_Angeles",
      "account_number": "112233445566",
      "company": "Acme Corp",
      "role": "Agent",
      "address_book_id": "jweQeTYDOS_eV1QmTpj63PQ",
      "address_book_name": "Corporate Address Book",
      "consumer_ids": [
        "cvC2JxWkToWZsJUenBvNnw"
      ],
      "custom_fields_url": "https://api.zoom.us/v2/contact_center/address_books/custom_fields/contacts/zeYjXoDOS_eV1QmTpj63PQ",
      "source_id": "R4aF9Oj0fVM2hhezJTEmSKaBSkfesDwGy42",
      "source_name": "external_system"
    }
  ],
  "invalid_contacts": [
    {
      "display_name": "Jane Doe",
      "phone_numbers": [
        "+12048002447"
      ],
      "emails": [
        "jane.doe@example.com"
      ],
      "error_messages": [
        "The phone numbers do not match the E.164 format."
      ]
    }
  ]
}

Status: 400 HTTP Status Code: `400` Bad Request Error Code: `2102` Either the `emails` or `phones` fields must have a value. Both of these fields cannot be empty.

Status: 401 HTTP Status Code: `401` Unauthorized Error Code: `124` Invalid access token. Error Code: `124` Access token has expired. Error Code: `1002` The user associated with this access token was not found or is invalid.

Status: 403 HTTP Status Code: `403` Forbidden Error Code: `1021` User account is deactivated. Error Code: `1022` User does not have a Contact Center license. Error Code: `9001` The Contact Center user associated with this bearer token is missing privileges on their role required to operate this request.

Status: 429 HTTP Status Code: `429` Too Many Requests. For more information, see [rate limits](https://developers.zoom.us/docs/api/rate-limits/). Error Code: `4001` You have reached the maximum per-second rate limit for this API. Try again later.

Batch delete address book contacts

Method: DELETE
Path: /contact_center/address_books/{addressBookId}/contacts/batch
Tags: Address Books

Batch delete contacts from an address book. Supports up to 50 contacts per request.

Scopes: contact_center_contact:write:admin

Granular Scopes: contact_center:delete:address_book_contact:admin

Rate Limit Label: MEDIUM

Request Body

Content-Type: application/json

contact_ids (required)

array — List of contact IDs to delete.

Items:

string — The contact's ID.

Example:

{
  "contact_ids": [
    "zeYjXoDOS_eV1QmTpj63PQ"
  ]
}

Responses

Status: 204 HTTP Status Code: `204` Contact deleted.

Status: 400 HTTP Status Code: `400` Bad Request Bad request. The `contact_ids` field is empty or exceeds the maximum limit.

Status: 404 HTTP Status Code: `404` Not Found Address book does not exist: {addressBookId}. Error Code: `2001` Address book does not exist: {addressBookId}.

Status: 429 HTTP Status Code: `429` Too Many Requests. For more information, see [rate limits](https://developers.zoom.us/docs/api/rate-limits/).

Batch update address book contacts

Method: PATCH
Path: /contact_center/address_books/{addressBookId}/contacts/batch
Tags: Address Books

Batch update contacts in an address book (https://support.zoom.us/hc/en-us/articles/4471544949389). Supports up to 50 contacts per request. Returns 200 for all valid or partial success with invalid contact details, or 400 if all contacts are invalid.

Scopes: contact_center_contact:write:admin

Granular Scopes: contact_center:update:address_book_contact:admin

Rate Limit Label: MEDIUM

Request Body

Content-Type: application/json

contacts

array — Information about the contacts.

Items:
- contact_id (required)
  
  string — The contact's ID.
- account_number
  
  string — The contact's account number.
- company
  
  string — The contact's company.
- consumer_ids
  
  array — The list of consumer IDs to associate with the contact.
  
  Items:
  
  string — The consumer's unique ID.
- custom_fields
  
  array — The custom field values for this contact.
  
  Items:
  - custom_field_id (required)
    
    string — The custom field's ID.
  - custom_field_value
    
    string — The custom field's value.
- display_name
  
  string — The contact's name.
- emails
  
  array — The contact's email addresses.
  
  Items:
  
  string
- first_name
  
  string — The contact's first name.
- last_name
  
  string — The contact's last name.
- location
  
  string — The contact's location.
- phones
  
  array — The contact's phone numbers. Supports up to five with explicit `phone_type`.
  
  Items:
  - phone_number (required)
    
    string — The phone number, in E.164 format.
  - phone_type
    
    string, possible values: "main", "work", "home", "mobile", "other", default: "main" — The type of phone number.
- role
  
  string — The contact's role.
- source_id
  
  string — The contact's source ID. This field is required for CRM address books.
- source_name
  
  string — The contact's source name.
- timezone
  
  string — The contact's time zone.

Example:

{
  "contacts": [
    {
      "contact_id": "zeYjXoDOS_eV1QmTpj63PQ",
      "display_name": "Jill Chill",
      "first_name": "Jill",
      "last_name": "Chill",
      "phones": [
        {
          "phone_number": "+12048002447",
          "phone_type": "main"
        }
      ],
      "emails": [
        "user@example.com"
      ],
      "location": "San Jose",
      "timezone": "America/Los_Angeles",
      "account_number": "112233445566",
      "company": "Acme Corp",
      "role": "Agent",
      "consumer_ids": [
        "cvC2JxWkToWZsJUenBvNnw"
      ],
      "custom_fields": [
        {
          "custom_field_id": "7381d210-360e-4fbd-86e4-33eb7109b084",
          "custom_field_value": "priority"
        }
      ],
      "source_id": "R4aF9Oj0fVM2hhezJTEmSKaBSkfesDwGy42",
      "source_name": "salesforce"
    }
  ]
}

Responses

Status: 200 HTTP Status Code: `200` Contacts created. When some contacts fail validation, the response includes both `contacts` (successful) and `invalid_contacts` (failed with error details).

Content-Type: application/json

contacts

array — Information about the created contacts.

Items:
- account_number
  
  string — The contact's account number.
- address_book_id
  
  string — The address book's ID.
- address_book_name
  
  string — The address book's name.
- company
  
  string — The contact's company.
- consumer_ids
  
  array — The consumer IDs associated with the contact.
  
  Items:
  
  string
- contact_id
  
  string — The contact's ID.
- custom_fields_url
  
  string — The URL to retrieve the contact's custom field list.
- display_name
  
  string — The contact's name.
- emails
  
  array — The contact's email addresses.
  
  Items:
  
  string, format: email
- first_name
  
  string — The contact's first name.
- last_name
  
  string — The contact's last name.
- location
  
  string — The contact's location.
- phones
  
  array — The contact's phone numbers.
  
  Items:
  - phone_number
    
    string — The phone number in E.164 format.
  - phone_type
    
    string, possible values: "main", "work", "home", "mobile", "other" — The type of phone number.
- role
  
  string — The contact's role.
- source_id
  
  string — The contact's source ID. This field is required for CRM address books.
- source_name
  
  string — The contact's source name.
- timezone
  
  string — The contact's time zone.
invalid_contacts

array — Contacts that failed validation. Only present when some contacts in the batch are invalid.

Items:
- display_name
  
  string — The contact's display name from the request.
- emails
  
  array — The email addresses from the request.
  
  Items:
  
  string — The email addresses from the request.
- error_messages
  
  array — Validation error messages for this contact.
  
  Items:
  
  string — Invalid phone number.
- phone_numbers
  
  array — The phone numbers from the request.
  
  Items:
  
  string — The phone numbers from the request.

Example:

{
  "contacts": [
    {
      "contact_id": "zeYjXoDOS_eV1QmTpj63PQ",
      "display_name": "John Doe",
      "first_name": "John",
      "last_name": "Doe",
      "phones": [
        {
          "phone_number": "+12048002447",
          "phone_type": "main"
        }
      ],
      "emails": [
        "john.doe@example.com"
      ],
      "location": "New York",
      "timezone": "America/Los_Angeles",
      "account_number": "112233445566",
      "company": "Acme Corp",
      "role": "Agent",
      "address_book_id": "jweQeTYDOS_eV1QmTpj63PQ",
      "address_book_name": "Corporate Address Book",
      "consumer_ids": [
        "cvC2JxWkToWZsJUenBvNnw"
      ],
      "custom_fields_url": "https://api.zoom.us/v2/contact_center/address_books/custom_fields/contacts/zeYjXoDOS_eV1QmTpj63PQ",
      "source_id": "R4aF9Oj0fVM2hhezJTEmSKaBSkfesDwGy42",
      "source_name": "external_system"
    }
  ],
  "invalid_contacts": [
    {
      "display_name": "Jane Doe",
      "phone_numbers": [
        "+12048002447"
      ],
      "emails": [
        "jane.doe@example.com"
      ],
      "error_messages": [
        "The phone numbers do not match the E.164 format."
      ]
    }
  ]
}

Status: 400 HTTP Status Code: `400` Bad Request Include `invalid_contacts` body when ALL fail. Error Code: `2102` Either the `email` or `phones` field must have a value. Both fields cannot be empty.

Status: 401 HTTP Status Code: `401` Unauthorized Invalid access token or the access token has expired. Error Code: `124` Invalid access token. Error Code: `124` Access token has expired. Error Code: `1002` The user associated with this access token was not found or is invalid.

Status: 403 HTTP Status Code: `403` Forbidden The user account is deactivated, does not have a Contact Center license, or is missing the required role privileges. Error Code: `1021` User account is deactivated. Error Code: `1022` User does not have a Contact Center license. Error Code: `9001` The Contact Center user associated with this bearer token is missing privileges on their role required to operate this request.

Status: 429 HTTP Status Code: `429` Too Many Requests. For more information, see [rate limits](https://developers.zoom.us/docs/api/rest/rate-limits/). Error Code: `4001` You have reached the maximum per-second rate limit for this API. Try again later.

Get an address book contact

Method: GET
Path: /contact_center/address_books/{addressBookId}/contacts/{contactId}
Tags: Address Books

Returns information about an address book's contact.

Scopes: contact_center_contact:read:admin

Granular Scopes: contact_center:read:address_book_contact:admin

Rate Limit Label: LIGHT

Responses

Status: 200 HTTP Status Code: `200` Contact returned.

Content-Type: application/json

contact_id (required)

string — The contact's ID.
display_name (required)

string — The contact's name.
phones (required)

array — The contact's phone numbers.

Items:
- phone_number
  
  string — The phone number.
- phone_type
  
  string, possible values: "main", "work", "home", "mobile", "other" — The phone number type.
account_number

string — The contact's account number.
address_book_id

string — The address book's ID.
address_book_name

string — The address book's name.
company

string — The contact's company.
consumer_ids

array — The consumer IDs associated with the contact.

Items:

string — The consumer's unique ID.
custom_fields_url

string — The URL to retrieve contact's custom field list, if the contact custom fields exists. \r\nFor security purposes, you must provide an OAuth access token in the authorization header to to retrieve contact's custom field list using this URL. Example:\r\ncurl --request GET \r\n --url {custom_fields_url} \r\n --header 'authorization: Bearer {access_token}' \r\n --header 'content-type: application/json'\r\n
emails

array — The contact's email addresses.

Items:

string, format: email
first_name

string — The contact's first name.
last_name

string — The contact's last name.
location

string — The contact's location.
phone_numbers

array — The contact's phone numbers.

Items:

string
role

string — The contact's role.
timezone

string — The contact's time zone. Refer to this list for supported [timezones](/docs/api/references/abbreviations/#timezones).
variables

array — Information about address book variables.

Items:
- data_type
  
  string, possible values: "string", "boolean" — The variable's data type.
- variable_group_id
  
  string — The variable group's ID.
- variable_id
  
  string — The variable's ID.
- variable_name
  
  string — The variable's name.
- variable_value
  
  string — The variable's value.

Example:

{
  "contact_id": "zeYjXoDOS_eV1QmTpj63PQ",
  "display_name": "Jill Chill",
  "first_name": "Jill",
  "last_name": "Chill",
  "phones": [
    {
      "phone_number": "+12048002447",
      "phone_type": "main"
    }
  ],
  "emails": [
    "user@example.com"
  ],
  "location": "San Jose",
  "timezone": "America/Los_Angeles",
  "account_number": "112233445566",
  "company": "Example",
  "role": "Agent",
  "address_book_id": "jweQeTYDOS_eV1QmTpj63PQ",
  "address_book_name": "Address Book",
  "variables": [
    {
      "variable_group_id": "afececcd-0c9f-48de-9d19-0c84e8bdfeca",
      "variable_id": "zeYjXoDOS_eV1QmTpj63PQ",
      "variable_name": "variable demo name",
      "data_type": "string",
      "variable_value": "variable value demo"
    }
  ],
  "consumer_ids": [
    "cvC2JxWkToWZsJUenBvNnw"
  ],
  "custom_fields_url": "https://api.zoom.us/v2/contact_center/address_books/custom_fields/contacts/zeYjXoDOS_eV1QmTpj63PQ"
}

Status: 400 HTTP Status Code: `400` Bad Request Error Code: `2007` More than one matching address book found.

Status: 401 HTTP Status Code: `401` Unauthorized

Status: 403 HTTP Status Code: `403` Forbidden

Status: 404 HTTP Status Code: `404` Not Found Error Code: `2101` Contact does not exist: $contactId. Error Code: `2001` Address book does not exist: $addressBookId.

Status: 429 HTTP Status Code: `429` Too Many Requests. For more information, see [rate limits](/docs/api/rate-limits/).

Delete an address book contact

Method: DELETE
Path: /contact_center/address_books/{addressBookId}/contacts/{contactId}
Tags: Address Books

Delete an contact from an address book.

Scopes: contact_center_contact:write:admin

Granular Scopes: contact_center:delete:address_book_contact:admin

Rate Limit Label: LIGHT

Responses

Status: 204 HTTP Status Code: `204` Contact deleted.

Status: 400 HTTP Status Code: `400` Bad Request Error Code: `2005` Salesforce integration contact can not be added, updated, or deleted.

Status: 404 HTTP Status Code: `404` Not Found Error Code: `2101` Contact does not exist: $contactId. Error Code: `2001` Address book does not exist: $addressBookId.

Status: 429 HTTP Status Code: `429` Too Many Requests. For more information, see [rate limits](/docs/api/rest/rate-limits/).

Update an address book contact

Method: PATCH
Path: /contact_center/address_books/{addressBookId}/contacts/{contactId}
Tags: Address Books

Update an address book's contact.

Scopes: contact_center_contact:write:admin

Granular Scopes: contact_center:update:address_book_contact:admin

Rate Limit Label: LIGHT

Request Body

Content-Type: application/json

phone_numbers (required)

array — The contact's phone numbers. You must provide this field and/or the `email` field when you create a contact.

Items:

string
phones (required)

array — The contact's phone numbers.

Items:
- phone_number
  
  string — The phone number.
- phone_type
  
  string, possible values: "main", "work", "home", "mobile", "other" — The phone number type.
account_number

string — The contact's account number.
company

string — The contact's company.
consumer_ids

array — The consumer IDs to be associated with the contact.

Items:

string — The consumer's unique ID.
custom_fields

array — Information about address book custom fields.

Items:
- custom_field_id
  
  string — The custom field's ID.
- custom_field_value
  
  string — The custom field's value.
display_name

string — The contact's display name.
emails

array — The contact's email addresses. You must provide this field and/or the `phone_numbers` field when you create a contact.

Items:

string, format: email
first_name

string — The contact's first name.
last_name

string — The contact's last name.
location

string — The contact's location.
role

string — The contact's role.
timezone

string — The contact's time zone. Refer to this list for supported [timezones](/docs/api/references/abbreviations/#timezones).
variables

array — Information about address book variables.

Items:
- variable_id
  
  string — The variable's ID.
- variable_value
  
  string — The variable's value.

Example:

{
  "display_name": "Jane Doe",
  "first_name": "Jane",
  "last_name": "Doe",
  "phones": [
    {
      "phone_number": "+12048002447",
      "phone_type": "main"
    }
  ],
  "emails": [
    "user@example.com"
  ],
  "location": "San Jose",
  "timezone": "America/Los_Angeles",
  "account_number": "112233445566",
  "company": "Example",
  "role": "Agent",
  "variables": [
    {
      "variable_id": "zeYjXoDOS_eV1QmTpj63PQ",
      "variable_value": "variable value demo"
    }
  ],
  "consumer_ids": [
    "cvC2JxWkToWZsJUenBvNnw"
  ],
  "custom_fields": [
    {
      "custom_field_id": "7381d210-360e-4fbd-86e4-33eb7109b084",
      "custom_field_value": "chat"
    }
  ]
}

Responses

Status: 204 HTTP Status Code: `204` Contact updated.

Status: 400 HTTP Status Code: `400` Bad Request Error Code: `2005` Salesforce integration contact cannot be added, updated, or deleted. Error Code: `2106` Invalid consumer Ids: $consumerIds. Error Code: `2113` Contact custom field value `custom_field_value` format does not match the data type. Error Code: `2114` Custom field is invalid: $customFieldId Error Code: `2116` Invalid custom field value `custom_field_value`. The provided value is not in the list of supported picklist values. Error Code: `2117` Invalid time zone: $timezone Error Code: `300` Invalid phone type. Error Code: `300` Only one main phone number is allowed. Error Code: `300` The maximum number of phones allowed is 5.

Status: 401 HTTP Status Code: `401` Unauthorized Error Code: `124` Invalid access token. Error Code: `124` Access token has expired. Error Code: `1002` The user associated with this access token was not found or is invalid.

Status: 403 HTTP Status Code: `403` Forbidden Error Code: `9001` The Contact Center user associated with this bearer token is missing privileges on their role required to operate this request. Error Code: `1021` User account is deactivated. Error Code: `1022` User does not have a Contact Center license.

Status: 404 HTTP Status Code: `404` Not Found Error Code: `2101` Contact does not exist: $contactId. Error Code: `2001` Address book does not exist: $addressBookId.

Status: 429 HTTP Status Code: `429` Too Many Requests. For more information, see [rate limits](/docs/api/rate-limits/). Error Code: `4001` You have reached the maximum per-second rate limit for this API. Try again later.

List system statuses

Method: GET
Path: /contact_center/system_statuses
Tags: Agent Statuses

Get a list of system statuses. Administrators can create system statuses, such as Maintenance.

Scopes: contact_center_preference:read:admin

Granular Scopes: contact_center:read:list_system_statues:admin

Rate Limit Label: MEDIUM

Responses

Status: 200 HTTP Status Code: `200` System statuses returned.

Content-Type: application/json

next_page_token

string — Use the next page token to paginate through large result sets. A next page token will be returned whenever the set of available results exceeds the current page size. This token's expiration period is 15 minutes.
page_size

integer, default: 30 — The number of records returned within a single API call.
statuses

array — Information about the statuses.

Items:
- enable
  
  boolean — Only applicable to a status with the `queue_opt_out_and_not_ready_status` category. If enabled, the agent can set the status as a sub-status for **Not Ready** or **Queue Opt Out**.
- status_assigned_queues
  
  array — Information about the queues that are using the 'Not Ready' or opt out of queue status.
  
  Items:
  - id
    
    string — Queue ID.
  - value
    
    string — Queue name.
- status_category
  
  string, possible values: "agent_status", "queue_opt_out_and_not_ready_status" — The status's category. * `agent_status` - User's system statuses. * `queue_opt_out_and_not_ready_status` - User's **Queue Opt-Out** and **Not Ready** reasons. **Not Ready** reasons are referenced by field `sub_status_name` in the Users APIs, such as [List users' profiles](https://developers.zoom.us/docs/contact-center/apis/#operation/users).
- status_id
  
  string — The status ID.
- status_name
  
  string, possible values: "Offline", "Ready", "Not Ready", "Occupied", "string" — The user's [availability status](https://support.zoom.us/hc/en-us/articles/4470584918541-Setting-availability-status). * Offline. * Ready. * Not Ready. * Occupied. * A custom user status, like **Lunch**.
- status_type
  
  string, possible values: "default", "custom" — The status's type, used to determine default or custom status.
total_records

integer — The total number of all the records available across pages.

Example:

{
  "next_page_token": "R4aF9Oj0fVM2hhezJTEmSKaBSkfesDwGy42",
  "page_size": 30,
  "total_records": 1,
  "statuses": [
    {
      "status_id": "1",
      "status_name": "Lunch",
      "status_type": "default",
      "status_category": "agent_status",
      "enable": true,
      "status_assigned_queues": [
        {
          "id": "123",
          "value": "customer queue"
        }
      ]
    }
  ]
}

Status: 400 HTTP Status Code: `400` Bad Request

Status: 429 HTTP Status Code: `429` Too Many Requests. For more information, see [rate limits](/docs/api/rest/rate-limits/).

Create a system status

Method: POST
Path: /contact_center/system_statuses
Tags: Agent Statuses

Create custom statuses for the agent_status and queue_opt_out_and_not_ready_status categories.

Scopes: contact_center_preference:write:admin

Granular Scopes: contact_center:write:system_status:admin

Rate Limit Label: LIGHT

Request Body

Content-Type: application/json

enable

boolean, default: true — Only applicable to a status with the `queue_opt_out_and_not_ready_status` category. If enabled, the agent can set a status as a sub-status for **Not Ready** or **Queue Opt Out**.
status_assigned_queues

array — Queues that the 'Not Ready' or opt out of queue status will be assigned to.

Items:
- id
  
  string — Queue ID.
status_category

string, possible values: "agent_status", "queue_opt_out_and_not_ready_status" — The status's category. * `agent_status` - User's system statuses. * `queue_opt_out_and_not_ready_status` - User's **Queue Opt-Out** and **Not Ready** reasons. **Not Ready** reasons are referenced by field `sub_status_name` in the **Users** APIs, such as [List users' profiles](https://developers.zoom.us/docs/contact-center/apis/#operation/users).
status_name

string — The status's name.

Example:

{
  "status_name": "Lunch",
  "status_category": "agent_status",
  "enable": true,
  "status_assigned_queues": [
    {
      "id": "123"
    }
  ]
}

Responses

Status: 201 System status successfully created.

Content-Type: application/json

enable

boolean — Only applicable to a status with the `queue_opt_out_and_not_ready_status` category. If enabled, the agent can set the status as a sub-status for **Not Ready** or **Queue Opt Out**.
status_category

string, possible values: "agent_status", "queue_opt_out_and_not_ready_status" — The status's category. * `agent_status` - User's system statuses. * `queue_opt_out_and_not_ready_status` - User's **Queue Opt-Out** and **Not Ready** reasons. **Not Ready** reasons are referenced by field `sub_status_name` in the **Users** APIs, such as [List users' profiles](https://developers.zoom.us/docs/contact-center/apis/#operation/users).
status_id

string — The status ID.
status_name

string, possible values: "Offline", "Ready", "Not Ready", "Occupied" — The user's [availability status](https://support.zoom.us/hc/en-us/articles/4470584918541-Setting-availability-status). * Offline * Ready * Not Ready * Occupied * A custom user status, like **Lunch**.
status_type

string, possible values: "default", "custom" — The status's type, used to determine default or custom status.

Example:

{
  "status_id": "1",
  "status_name": "Lunch",
  "status_type": "default",
  "status_category": "agent_status",
  "enable": true
}

Status: 400 HTTP Status Code: `400` Bad Request Error Code: `1105` Can't create more custom `agent_status` because there's a maximum of 15. Error Code: `1106` Can't create more custom `queue_opt_out_and_not_ready_status` because there's a maximum of 15. Error Code: `1107` Creating the status. Please wait a moment.

Status: 404 HTTP Status Code: `404` Not Found Error Code: `1104` Status category does not exist: $status_category.

Status: 429 HTTP Status Code: `429` Too Many Requests. For more information, see [rate limits](/docs/api/rest/rate-limits/).

Get a system status

Method: GET
Path: /contact_center/system_statuses/{statusId}
Tags: Agent Statuses

Get information about a system status.

Scopes: contact_center_preference:read:admin

Granular Scopes: contact_center:read:system_status:admin

Rate Limit Label: LIGHT

Responses

Status: 200 HTTP Status Code: `200` System status returned.

Content-Type: application/json

enable

boolean — Only applicable to a status with the `queue_opt_out_and_not_ready_status` category. If enabled, the agent can set the status as a sub-status for **Not Ready** or **Queue Opt Out**.
status_assigned_queues

array — Information about the queues that are using the 'Not Ready' or opt out of queue status.

Items:
- id
  
  string — Queue ID.
- value
  
  string — Queue name.
status_category

string, possible values: "agent_status", "queue_opt_out_and_not_ready_status" — The status's category. * `agent_status` - User's system statuses. * `queue_opt_out_and_not_ready_status` - User's **Queue Opt-Out** and **Not Ready** reasons. **Not Ready** reasons are referenced by field `sub_status_name` in the Users APIs, such as [List users' profiles](https://developers.zoom.us/docs/contact-center/apis/#operation/users).
status_id

string — The status ID.
status_name

string, possible values: "Offline", "Ready", "Not Ready", "Occupied" — The user's [availability status](https://support.zoom.us/hc/en-us/articles/4470584918541-Setting-availability-status). * Offline. * Ready. * Not Ready. * Occupied. * A custom user status, like **Lunch**.
status_type

string, possible values: "default", "custom" — The status's type, used to determine default or custom status.

Example:

{
  "status_id": "1",
  "status_name": "Lunch",
  "status_type": "default",
  "status_category": "agent_status",
  "enable": true,
  "status_assigned_queues": [
    {
      "id": "123",
      "value": "customer queue"
    }
  ]
}

Status: 400 HTTP Status Code: `400` Bad Request Error Code: `1116` More than one matching status found.

Status: 404 HTTP Status Code: `404` Not Found Error Code: `1101` Status does not exist: $statusId.

Status: 429 HTTP Status Code: `429` Too Many Requests. For more information, see [rate limits](https://developers.zoom.us/docs/api/rate-limits/).

Delete a system status

Method: DELETE
Path: /contact_center/system_statuses/{statusId}
Tags: Agent Statuses

Delete a custom status for the agent_status and queue_opt_out_and_not_ready_status categories.

Scopes: contact_center_preference:write:admin

Granular Scopes: contact_center:delete:system_status:admin

Rate Limit Label: LIGHT

Responses

Status: 204 HTTP Status Code: `204` System status deleted.

Status: 400 HTTP Status Code: `400` Bad Request Error Code: `1108` Status is default. Only custom statuses can be modified. Error Code: `1116` More than one matching status found.

Status: 404 HTTP Status Code: `404` Not Found Error Code: `1101` Status does not exist: $statusId.

Status: 429 HTTP Status Code: `429` Too Many Requests. For more information, see [rate limits](https://developers.zoom.us/docs/api/rate-limits/).

Update a system status

Method: PATCH
Path: /contact_center/system_statuses/{statusId}
Tags: Agent Statuses

Update a custom status for the agent_status and queue_opt_out_and_not_ready_status categories.

Scopes: contact_center_preference:write:admin

Granular Scopes: contact_center:update:system_status:admin

Rate Limit Label: LIGHT

Request Body

Content-Type: application/json

enable

boolean, default: true — Only applicable to a status with the `queue_opt_out_and_not_ready_status` category. If enabled, the agent can set the status as a sub-status for **Not Ready** or **Queue Opt Out**.
status_assigned_queues

array — Queues that the **Not Ready** or opt out of queue status will be assigned to.

Items:
- id
  
  string — Queue ID.
status_name

string — The status's name.

Example:

{
  "status_name": "Lunch",
  "enable": true,
  "status_assigned_queues": [
    {
      "id": "123"
    }
  ]
}

Responses

Status: 204 HTTP Status Code: `204` System status updated.

Status: 400 HTTP Status Code: `400` Bad Request Error Code: `300` Parameter `status_name` is required. Error Code: `1103` The system status already exists. Error Code: `1107` Updating status. Please wait a moment. Error Code: `1108` Status is default. Only custom statuses can be modified. Error Code: `1116` More than one matching status found.

Status: 404 HTTP Status Code: `404` Not Found Error Code: `1101` Status does not exist: $statusId.

Status: 429 HTTP Status Code: `429` Too Many Requests. For more information, see [rate limits](/docs/api/rest/rate-limits/).

List assets

Method: GET
Path: /contact_center/asset_library/assets
Tags: Asset Library

List Contact Center assets.

Scopes: contact_center_asset_library:read:admin

Granular Scopes: contact_center:read:asset_library:admin

Rate Limit Label: MEDIUM

Responses

Status: 200 HTTP Status Code: `200` Assets returned.

Content-Type: application/json

assets

array — Array of assets.

Items:
- asset_category_id
  
  string — The asset's category ID.
- asset_category_name
  
  string — The asset's category name.
- asset_description
  
  string — The asset's description.
- asset_id
  
  string — The asset's ID.
- asset_items_url
  
  string — If the query parameters include `asset_item_name`, this parameter returns the access URL of the matching asset item; otherwise, this field will return empty.
- asset_language_code
  
  string, possible values: "zh-CN", "zh-TW", "yue-CN", "cmn-CN", "da-DK", "nl-NL", "en-AU", "en-NZ", "en-GB", "en-US", "fr-CA", "fr-FR", "de-DE", "it-IT", "ja-JP", "ko-KR", "pl-PL", "pt-BR", "pt-PT", "ro-RO", "ru-RU", "es-ES", "es-MX", "es-US", "sv-SE", "tr-TR" — The asset's language code.
- asset_name
  
  string — The asset's name.
- asset_type
  
  string, possible values: "audio", "image", "script", "slides", "text", "video", "saved_reply" — The asset's type.
- last_modified_time
  
  string, format: date-time — The date and time when the asset was last modified.
- modified_by
  
  string — The ID of the user that last modified the asset.
next_page_token

string — Use the next page token to paginate through large result sets. A next page token is returned whenever the set of available results exceeds the current page size. This token's expiration period is 15 minutes.
page_size

integer, default: 30 — The number of records returned within a single API call.
total_records

integer — The total number of all the records available across pages.

Example:

{
  "next_page_token": "R4aF9Oj0fVM2hhezJTEmSKaBSkfesDwGy42",
  "page_size": 30,
  "total_records": 10,
  "assets": [
    {
      "asset_id": "zeYjXoDOS_eV1QmTpj63PQ",
      "asset_name": "My asset name.",
      "asset_description": "My asset description.",
      "asset_type": "image",
      "asset_category_id": "8ONs9XW4S9a2Lco9O0GdCw",
      "asset_category_name": "Sales Category",
      "asset_language_code": "zh-CN",
      "modified_by": "IGTRVt3gQ2i-WjoUIjeZxw",
      "last_modified_time": "2022-02-15T09:27:15Z",
      "asset_items_url": "https://api.zoom.us/v2/contact_center/asset_library/assets/zeYjXoDOS_eV1QmTpj63PQ?asset_item_name=english%20audio"
    }
  ]
}

Status: 400 HTTP Status Code: `400` Bad Request Error Code: `300` Validation failed.

Status: 429 HTTP Status Code: `429` Too Many Requests. For more information, see [rate limits](/docs/api/rate-limits/).

Create an asset

Method: POST
Path: /contact_center/asset_library/assets
Tags: Asset Library

Create an asset to store in the Contact Center Asset Library.

Scopes: contact_center_asset_library:write:admin

Granular Scopes: contact_center:write:asset_library:admin

Rate Limit Label: LIGHT

Request Body

Content-Type: multipart/form-data

asset_items (required)

array — A list of the asset's items. ### Restriction Each item must have a different `asset_item_language`, and only one item can have a `is_default` set to `true`.

Items:
- asset_item_content
 
 string — The asset item's content. Only works for `asset_type`s `text` and `saved_reply`.
- asset_item_language
 
 string, possible values: "zh-CN", "zh-TW", "yue-CN", "cmn-CN", "da-DK", "nl-NL", "en-AU", "en-NZ", "en-GB", "en-US", "fr-CA", "fr-FR", "de-DE", "it-IT", "ja-JP", "ko-KR", "pl-PL", "pt-BR", "pt-PT", "ro-RO", "ru-RU", "es-ES", "es-MX", "es-US", "sv-SE", "tr-TR" — The asset item's language code.
- asset_item_name
 
 string — The asset item's name.
- asset_item_voice
 
 string — The asset item's text-to-speech voice. It only works for the audio type. When you want to create a TTS asset item, need to fill in the `asset_item_file_url` and `asset_item_content`, but don't need to fill in the `upload_file` field. Not every language supports TTS, and each language has a different voice. | asset_item_language | asset_item_voice | |---------------------|------------------------------------------------------------------------------------------------------------------------------------------| | yue-CN | Hiujin | | cmn-CN | Zhiyu | | da-DK | Naja Sofie Mads | | nl-NL | Laura Ruben Lotte | | en-US | Joanna Stephen Kimberly Matthew Danielle Gregory Kevin Salli Kendra Justin Joey Ivy Ruth | | en-GB | Emma Brian Amy Arthur | | en-AU | Olivia Russell Nicole | | en-NZ | Aria | | fr-FR | Celine Lea Remi Mathieu | | fr-CA | Gabrielle Liam Chantal | | de-DE | Daniel Vicki Marlene Hans | | it-IT | Adriano Bianca Giorgio Carla | | ja-JP | Takumi Kazuha Tomoko Mizuki | | ko-KR | Seoyeon | | pl-PL | Ola Maja Jan Jacek Ewa | | pt-PT | Ines Cristiano | | pt-BR | Camila Thiago Vitoria Ricardo | | ro-RO | Carmen | | ru-RU | Maxim Tatyana | | es-US | Lupe Pedro Penelope Miguel | | es-MX | Mia Andres | | es-ES | Lucia Sergio Enrique Conchita | | sv-SE | Elin Astrid | | tr-TR | Filiz Burcu |
- is_default
 
 boolean — Whether this item is the default of the asset. Each asset can only have one `isDefault` set to `true`.
- upload_file
 
 string — The uploaded file in binary format. Only works for `asset_type`s `audio`, `image`, `video` and `slides`. This field is not required if you create a TTS item when creating or updating an audio asset. ### Allowed file extension - audio : mp3, wav - image : jpeg, jpg, jpe, jif, jfif, png, gif - slides : pdf - video : mp4, mov ### Maximum filesize support A single request can upload a maximum of 100MB. Single file maximum filesize: - audio : 10M - image : 10M - slides : 10M - video : 100M
asset_name (required)

string — The asset's name.
asset_type (required)

string, possible values: "audio", "image", "slides", "text", "video", "saved_reply" — The asset's type.
asset_description

string — The asset's description.
category_id

string — The asset category's ID.

Example:

{
  "asset_name": "asset name",
  "asset_description": "This is an audio asset.",
  "asset_type": "audio",
  "category_id": "bnGEj1yrRb6qlNMvyMK08g",
  "asset_items": [
    {
      "asset_item_name": "english audio",
      "asset_item_language": "en-US",
      "upload_file": "VkVST1EyRkhVa2hoUjFwclVucHNiVnBXWXpWTlYwNXdUMWN4YUZZemFITlVSekI0WkRBeE0xQlVNRDA9",
      "asset_item_content": "text asset content",
      "is_default": true,
      "asset_item_voice": "Joanna"
    }
  ]
}

Responses

Status: 201 HTTP Status Code: `201` Asset created.

Content-Type: application/json

archived

boolean — Whether the asset is archived.
archived_time

string, format: date-time — The time when this asset was archived.
asset_description

string — The asset's description.
asset_id

string — The asset's unique identifier.
asset_items

array — A list of the asset's items. **Restriction** Each item must have a different `asset_item_language`, and only one item can have a `is_default` set to `true`.

Items:
- asset_item_content
 
 string — The asset item's content. Only works for `asset_type`s `text` and `saved_reply`.
- asset_item_file_url
 
 string — The asset item's file URL. This data will only exist when the `asset_type` is one of `image`, `audio`, `video`, or `slides`.
- asset_item_id
 
 string — The asset item's ID. If it is used to update the asset item, carrying this field indicates an update. Otherwise, it indicates adding an asset item.
- asset_item_language
 
 string, possible values: "zh-CN", "zh-TW", "yue-CN", "cmn-CN", "da-DK", "nl-NL", "en-AU", "en-NZ", "en-GB", "en-US", "fr-CA", "fr-FR", "de-DE", "it-IT", "ja-JP", "ko-KR", "pl-PL", "pt-BR", "pt-PT", "ro-RO", "ru-RU", "es-ES", "es-MX", "es-US", "sv-SE", "tr-TR" — The asset item's language code.
- asset_item_name
 
 string — The asset item's name.
- asset_item_voice
 
 string — The asset item's text-to-speech voice. Only works for the `audio` type. To create a TTS asset item, fill in the `asset_item_file_url` and `asset_item_content`. You don't need to fill in the `upload_file` field. Not every language supports TTS, and each language has a different voice. | asset_item_language | asset_item_voice | |---------------------|------------------------------------------------------------------------------------------------------------------------------------------| | yue-CN | Hiujin | | cmn-CN | Zhiyu | | da-DK | Naja Sofie Mads | | nl-NL | Laura Ruben Lotte | | en-US | Joanna Stephen Kimberly Matthew Danielle Gregory Kevin Salli Kendra Justin Joey Ivy Ruth | | en-GB | Emma Brian Amy Arthur | | en-AU | Olivia Russell Nicole | | en-NZ | Aria | | fr-FR | Celine Lea Remi Mathieu | | fr-CA | Gabrielle Liam Chantal | | de-DE | Daniel Vicki Marlene Hans | | it-IT | Adriano Bianca Giorgio Carla | | ja-JP | Takumi Kazuha Tomoko Mizuki | | ko-KR | Seoyeon | | pl-PL | Ola Maja Jan Jacek Ewa | | pt-PT | Ines Cristiano | | pt-BR | Camila Thiago Vitoria Ricardo | | ro-RO | Carmen | | ru-RU | Maxim Tatyana | | es-US | Lupe Pedro Penelope Miguel | | es-MX | Mia Andres | | es-ES | Lucia Sergio Enrique Conchita | | sv-SE | Elin Astrid | | tr-TR | Filiz Burcu |
- is_default
 
 boolean — Whether this item is the asset's default. Each asset can only have one `isDefault` set to `true`.
asset_language_code

string, possible values: "zh-CN", "zh-TW", "yue-CN", "cmn-CN", "da-DK", "nl-NL", "en-AU", "en-NZ", "en-GB", "en-US", "fr-CA", "fr-FR", "de-DE", "it-IT", "ja-JP", "ko-KR", "pl-PL", "pt-BR", "pt-PT", "ro-RO", "ru-RU", "es-ES", "es-MX", "es-US", "sv-SE", "tr-TR" — The asset's default language code.
asset_name

string — The asset's name.
asset_type

string, possible values: "audio", "image", "slides", "text", "video", "saved_reply" — The asset's type.
category_id

string — The asset category's ID.
category_name

string — The asset category's name.
last_modified_time

string, format: date-time — The date and time when this data was last modified.
modified_by

string — The ID of the user that last modified this data.

Example:

{
  "asset_id": "WkdWelkzSnBjSEZwYjI0PQ11",
  "asset_name": "asset name",
  "asset_description": "This is an audio asset.",
  "asset_type": "audio",
  "modified_by": "IGTRVt3gQ2i-WjoUIjeZxw",
  "asset_items": [
    {
      "asset_item_id": "beYjXoDOS_eV1QmTpj63PQ",
      "asset_item_name": "english audio",
      "asset_item_language": "en-US",
      "is_default": true,
      "asset_item_content": "text asset content",
      "asset_item_file_url": "https://file.example.com/xxxx",
      "asset_item_voice": "Joanna"
    }
  ],
  "asset_language_code": "en-US",
  "category_id": "bnGEj1yrRb6qlNMvyMK08g",
  "category_name": "flows assets",
  "archived": false,
  "last_modified_time": "2022-02-15T09:27:15Z",
  "archived_time": "2023-08-29T06:12:33Z"
}

Status: 400 HTTP Status Code: `400` Bad Request Error Code: `10005` Asset name is too long. Error Code: `10006` The language is not supported. Error Code: `10007` Duplicate asset name Error Code: `10013` Asset description is too long. Error Code: `10018` Invalid asset type Error Code: `10020` Unable to create more.

Status: 401 HTTP Status Code: `401` Unauthorized Error Code: `124` Invalid access token. Error Code: `124` Access token has expired. Error Code: `1002` The user associated with this access token was not found or is invalid.

Status: 403 HTTP Status Code: `403` Forbidden Error Code: `1021` User account is deactivated. Error Code: `1022` User does not have a Contact Center license. Error Code: `9001` The Contact Center user associated with this bearer token is missing privileges on their role required to operate this request.

Status: 429 HTTP Status Code: `429` Too Many Requests. For more information, see [rate limits](/docs/api/rest/rate-limits/). Error Code: `4001` You have reached the maximum per-second rate limit for this API. Try again later.

Batch update asset items

Method: PATCH
Path: /contact_center/asset_library/assets/items
Tags: Asset Library

Batch updates asset items across multiple assets in a single request.

Scopes: contact_center_asset_library:write:admin

Granular Scopes: contact_center:update:asset_library:admin

Rate Limit Label: MEDIUM

Request Body

Content-Type: application/json

items (required)

array — The items to update. **Note** Ensure that the request body size does not exceed `100MB`.

Items:
- asset_id (required)
 
 string — The asset's unique identifier.
- asset_item_language (required)
 
 string, possible values: "zh-CN", "zh-TW", "yue-CN", "cmn-CN", "da-DK", "nl-NL", "en-AU", "en-NZ", "en-GB", "en-US", "fr-CA", "fr-FR", "de-DE", "it-IT", "ja-JP", "ko-KR", "pl-PL", "pt-BR", "pt-PT", "ro-RO", "ru-RU", "es-ES", "es-MX", "es-US", "sv-SE", "tr-TR" — The asset item's language code.
- asset_item_name
 
 string — The asset item's name.
- asset_item_voice
 
 string — The asset item's text-to-speech voice. This field only applies to the audio type. To update a TTS asset item, only fill in this field and `asset_item_content`. Do not fill in `upload_file_name` and `upload_file_content`. Not every language supports TTS, and each language has different available voices. | asset_item_language | asset_item_voice | |---------------------|------------------------------------------------------------------------------------------------------------------------------------------| | yue-CN | Hiujin | | cmn-CN | Zhiyu | | da-DK | Naja Sofie Mads | | nl-NL | Laura Ruben Lotte | | en-US | Joanna Stephen Kimberly Matthew Danielle Gregory Kevin Salli Kendra Justin Joey Ivy Ruth | | en-GB | Emma Brian Amy Arthur | | en-AU | Olivia Russell Nicole | | en-NZ | Aria | | fr-FR | Celine Lea Remi Mathieu | | fr-CA | Gabrielle Liam Chantal | | de-DE | Daniel Vicki Marlene Hans | | it-IT | Adriano Bianca Giorgio Carla | | ja-JP | Takumi Kazuha Tomoko Mizuki | | ko-KR | Seoyeon | | pl-PL | Ola Maja Jan Jacek Ewa | | pt-PT | Ines Cristiano | | pt-BR | Camila Thiago Vitoria Ricardo | | ro-RO | Carmen | | ru-RU | Maxim Tatyana | | es-US | Lupe Pedro Penelope Miguel | | es-MX | Mia Andres | | es-ES | Lucia Sergio Enrique Conchita | | sv-SE | Elin Astrid | | tr-TR | Filiz Burcu |
- upload_file_content
 
 string — The Base64-encoded file content. Required when `upload_file_name` is provided.
- upload_file_name
 
 string — The original file name. Required when `upload_file_content` is provided.
- use_shared
 
 boolean, default: false — When `true`, this item inherits the wrapper-level `shared_item.upload_file_content` and `shared_item.upload_file_name` if it omits its own per-item upload pair. When omitted, `null`, or `false`, this item does **not** inherit any shared upload pair; if it omits its own upload fields, the existing file on the asset item is preserved. Per-item upload fields, when present, always override the shared pair for that item regardless of `use_shared`. **Note:** Setting `use_shared` to `true` when `shared_item` is absent or empty does not raise an error; the item is treated as if it had no upload contribution from the shared pair, and the standard "at least one updatable field" validator decides whether the item is acceptable based on its remaining fields.
shared_item

object — Optional shared item that supplies an opt-in upload pair (`upload_file_content` and `upload_file_name`). The pair is only inherited by items that explicitly set `use_shared` to `true` and omit their own per-item upload fields; items that do not set `use_shared` (or set it to `false`) preserve their existing file regardless of whether `shared_item` is present. Per-item upload fields, when present, always override the shared pair for that item regardless of `use_shared`. **Same-source pairing rule:** Within `shared_item`, `upload_file_content` and `upload_file_name` must be provided together or both omitted. Sending one without the other causes the entire request to be rejected with HTTP 400. **Decoded once:** When provided, the shared Base64 content is decoded and validated exactly once per request and reused across items. Invalid Base64 in the shared content rejects the entire request (it is not a per-item failure). **Size limits:** The shared content is subject to the per-content limit (`10 MB`) and is counted exactly once toward the total request limit (`100 MB`), regardless of how many items fall back to it.
- upload_file_content
  
  string — The Base64-encoded file content. Required when `upload_file_name` is provided.
- upload_file_name
  
  string — The original file name. Required when `upload_file_content` is provided.

Example:

{
  "items": [
    {
      "asset_id": "WkdWelkzSnBjSEZwYjI0PQ11",
      "asset_item_language": "en-US",
      "asset_item_name": "english audio",
      "asset_item_voice": "Joanna",
      "upload_file_name": "hindi_aditi.wav",
      "upload_file_content": "UklGRiQAAABXQVZFZm10IBAAAA...(base64)",
      "use_shared": true
    }
  ],
  "shared_item": {
    "upload_file_content": "UklGRiQAAABXQVZFZm10IBAAAA...(base64)",
    "upload_file_name": "hindi_aditi.wav"
  }
}

Responses

Status: 200 HTTP Status Code: `200` Asset items updated.

Content-Type: application/json

failed_assets (required)

array — The assets that failed to update.

Items:
- asset_id (required)
  
  string — The asset's unique identifier.
- asset_item_language (required)
  
  string, possible values: "zh-CN", "zh-TW", "yue-CN", "cmn-CN", "da-DK", "nl-NL", "en-AU", "en-NZ", "en-GB", "en-US", "fr-CA", "fr-FR", "de-DE", "it-IT", "ja-JP", "ko-KR", "pl-PL", "pt-BR", "pt-PT", "ro-RO", "ru-RU", "es-ES", "es-MX", "es-US", "sv-SE", "tr-TR" — The asset item's language code.
- error_code (required)
  
  integer — The error code. * 10009 - Asset not found. * 10026 - Asset item not found.
- error_message (required)
  
  string — The error message describing the reason for the failure.
succeeded_assets (required)

array — The assets that were successfully updated.

Items:
- asset_id (required)
  
  string — The asset's unique identifier.
- asset_item_language (required)
  
  string, possible values: "zh-CN", "zh-TW", "yue-CN", "cmn-CN", "da-DK", "nl-NL", "en-AU", "en-NZ", "en-GB", "en-US", "fr-CA", "fr-FR", "de-DE", "it-IT", "ja-JP", "ko-KR", "pl-PL", "pt-BR", "pt-PT", "ro-RO", "ru-RU", "es-ES", "es-MX", "es-US", "sv-SE", "tr-TR" — The asset item's language code.

Example:

{
  "succeeded_assets": [
    {
      "asset_id": "WkdWelkzSnBjSEZwYjI0PQ11",
      "asset_item_language": "en-US"
    }
  ],
  "failed_assets": [
    {
      "asset_id": "WkdWelkzSnBjSEZwYjI0PQ11",
      "asset_item_language": "en-US",
      "error_code": 10026,
      "error_message": "Asset item not found."
    }
  ]
}

Status: 400 HTTP Status Code: `400` Bad Request Error Code: `303` Request array must not exceed 50 items.

Status: 401 HTTP Status Code: `401` Unauthorized Error Code: `124` Invalid access token. Error Code: `124` Access token has expired. Error Code: `1002` The user associated with this access token was not found or is invalid.

Status: 403 HTTP Status Code: `403` Forbidden Error Code: `1021` User account is deactivated. Error Code: `1022` User does not have a Contact Center license. Error Code: `9001` The Contact Center user associated with this bearer token is missing privileges on their role required to operate this request.

Status: 429 HTTP Status Code: `429` Too Many Requests. For more information, see [rate limits](https://developers.zoom.us/docs/api/rate-limits/). Error Code: `4001` You have reached the maximum per-second rate limit for this API. Try again later.

Get an asset

Method: GET
Path: /contact_center/asset_library/assets/{assetId}
Tags: Asset Library

Get information about an asset.

Scopes: contact_center_asset_library:read:admin

Granular Scopes: contact_center:read:asset_library:admin

Rate Limit Label: LIGHT

Responses

Status: 200 HTTP Status Code: `200` Asset returned.

Content-Type: application/json

archived

boolean — Whether the asset is archived.
archived_time

string, format: date-time — The time when this asset was archived.
asset_description

string — The asset's description.
asset_id

string — The asset's unique identifier.
asset_items

array — A list of the asset's items. **Restriction** Each item must have a different `asset_item_language`, and only one item can have a `is_default` set to `true`.

Items:
- asset_item_content
 
 string — The asset item's content. Only works for `asset_type`s `text` and `saved_reply`.
- asset_item_file_url
 
 string — The asset item's file URL. This data will only exist when the `asset_type` is one of `image`, `audio`, `video`, or `slides`.
- asset_item_id
 
 string — The asset item's ID. If it is used to update the asset item, carrying this field indicates an update. Otherwise, it indicates adding an asset item.
- asset_item_language
 
 string, possible values: "zh-CN", "zh-TW", "yue-CN", "cmn-CN", "da-DK", "nl-NL", "en-AU", "en-NZ", "en-GB", "en-US", "fr-CA", "fr-FR", "de-DE", "it-IT", "ja-JP", "ko-KR", "pl-PL", "pt-BR", "pt-PT", "ro-RO", "ru-RU", "es-ES", "es-MX", "es-US", "sv-SE", "tr-TR" — The asset item's language code.
- asset_item_name
 
 string — The asset item's name.
- asset_item_voice
 
 string — The asset item's text-to-speech voice. Only works for the `audio` type. To create a TTS asset item, fill in the `asset_item_file_url` and `asset_item_content`. You don't need to fill in the `upload_file` field. Not every language supports TTS, and each language has a different voice. | asset_item_language | asset_item_voice | |---------------------|------------------------------------------------------------------------------------------------------------------------------------------| | yue-CN | Hiujin | | cmn-CN | Zhiyu | | da-DK | Naja Sofie Mads | | nl-NL | Laura Ruben Lotte | | en-US | Joanna Stephen Kimberly Matthew Danielle Gregory Kevin Salli Kendra Justin Joey Ivy Ruth | | en-GB | Emma Brian Amy Arthur | | en-AU | Olivia Russell Nicole | | en-NZ | Aria | | fr-FR | Celine Lea Remi Mathieu | | fr-CA | Gabrielle Liam Chantal | | de-DE | Daniel Vicki Marlene Hans | | it-IT | Adriano Bianca Giorgio Carla | | ja-JP | Takumi Kazuha Tomoko Mizuki | | ko-KR | Seoyeon | | pl-PL | Ola Maja Jan Jacek Ewa | | pt-PT | Ines Cristiano | | pt-BR | Camila Thiago Vitoria Ricardo | | ro-RO | Carmen | | ru-RU | Maxim Tatyana | | es-US | Lupe Pedro Penelope Miguel | | es-MX | Mia Andres | | es-ES | Lucia Sergio Enrique Conchita | | sv-SE | Elin Astrid | | tr-TR | Filiz Burcu |
- is_default
 
 boolean — Whether this item is the asset's default. Each asset can only have one `isDefault` set to `true`.
asset_language_code

string, possible values: "zh-CN", "zh-TW", "yue-CN", "cmn-CN", "da-DK", "nl-NL", "en-AU", "en-NZ", "en-GB", "en-US", "fr-CA", "fr-FR", "de-DE", "it-IT", "ja-JP", "ko-KR", "pl-PL", "pt-BR", "pt-PT", "ro-RO", "ru-RU", "es-ES", "es-MX", "es-US", "sv-SE", "tr-TR" — The asset's default language code.
asset_name

string — The asset's name.
asset_type

string, possible values: "audio", "image", "slides", "text", "video", "saved_reply" — The asset's type.
category_id

string — The asset category's ID.
category_name

string — The asset category's name.
last_modified_time

string, format: date-time — The date and time when this data was last modified.
modified_by

string — The ID of the user that last modified this data.

Example:

{
  "asset_id": "WkdWelkzSnBjSEZwYjI0PQ11",
  "asset_name": "asset name",
  "asset_description": "This is an audio asset.",
  "asset_type": "audio",
  "modified_by": "IGTRVt3gQ2i-WjoUIjeZxw",
  "last_modified_time": "2022-02-15T09:27:15Z",
  "archived": false,
  "archived_time": "2023-08-29T06:12:33Z",
  "asset_items": [
    {
      "asset_item_id": "beYjXoDOS_eV1QmTpj63PQ",
      "asset_item_name": "english audio",
      "asset_item_language": "en-US",
      "is_default": true,
      "asset_item_content": "text asset content",
      "asset_item_file_url": "https://file.example.com/xxxx",
      "asset_item_voice": "Joanna"
    }
  ],
  "asset_language_code": "en-US",
  "category_id": "bnGEj1yrRb6qlNMvyMK08g",
  "category_name": "flows assets"
}

Status: 401 HTTP Status Code: `401` Unauthorized

Status: 403 HTTP Status Code: `403` Forbidden

Status: 404 HTTP Status Code: `404` Not Found Error Code: `10009` Asset not found.

Status: 429 HTTP Status Code: `429` Too Many Requests. For more information, see [rate limits](https://developers.zoom.us/docs/api/rate-limits/).

Delete an asset

Method: DELETE
Path: /contact_center/asset_library/assets/{assetId}
Tags: Asset Library

Delete or achive an existing asset. You can only operate assets that have not been assigned to other modules. Only assets in archived status can be deleted. Set the asset to archived through this API before deleting.

Scopes: contact_center_asset_library:write:admin

Granular Scopes: contact_center:delete:asset_library:admin

Rate Limit Label: LIGHT

Responses

Status: 204 HTTP Status Code: `204` Asset deleted or archived.

Status: 404 HTTP Status Code: `404` Not Found Error Code: `10009` Asset not found. Error Code: `10010` Unable to delete asset directly, archive it first. Error Code: `10002` This asset is being used.

Status: 429 HTTP Status Code: `429` Too Many Requests. For more information, see [rate limits](/docs/api/rest/rate-limits/).

Update an asset

Method: PATCH
Path: /contact_center/asset_library/assets/{assetId}
Tags: Asset Library

Update an asset.

Scopes: contact_center_asset_library:write:admin

Granular Scopes: contact_center:write:asset_library:admin

Rate Limit Label: LIGHT

Request Body

Content-Type: multipart/form-data

asset_description

string — The asset's description.
asset_items

array — A list of the asset's items. **Restriction** Each item must have a different `asset_item_language`, and only one item can have a `is_default` set to `true`. If this field is not filled in, it means no modifications will be made to the asset items. If this field is filled in, the provided data will overwrite the current asset items. To update an existing asset item, fill in the `asset_item_id`. Otherwise, it will be considered adding a new asset item. This API can only update or add asset items, not delete them.

Items:
- asset_item_content
 
 string — The asset item's content. Only works for `asset_type`s `text` and `saved_reply`.
- asset_item_id
 
 string — The asset item's ID. If it is used to update the asset item, carrying this field indicates an update; otherwise, it indicates adding an asset item.
- asset_item_language
 
 string, possible values: "zh-CN", "zh-TW", "yue-CN", "cmn-CN", "da-DK", "nl-NL", "en-AU", "en-NZ", "en-GB", "en-US", "fr-CA", "fr-FR", "de-DE", "it-IT", "ja-JP", "ko-KR", "pl-PL", "pt-BR", "pt-PT", "ro-RO", "ru-RU", "es-ES", "es-MX", "es-US", "sv-SE", "tr-TR" — The asset item's language code.
- asset_item_name
 
 string — The asset item's name.
- asset_item_voice
 
 string — The asset item's text-to-speech voice. It only works for the audio type. When you want to create a TTS asset item, need to fill in the `asset_item_file_url` and `asset_item_content`, but don't need to fill in the `upload_file` field. Not every language supports TTS, and each language has a different voice. | asset_item_language | asset_item_voice | |---------------------|------------------------------------------------------------------------------------------------------------------------------------------| | yue-CN | Hiujin | | cmn-CN | Zhiyu | | da-DK | Naja Sofie Mads | | nl-NL | Laura Ruben Lotte | | en-US | Joanna Stephen Kimberly Matthew Danielle Gregory Kevin Salli Kendra Justin Joey Ivy Ruth | | en-GB | Emma Brian Amy Arthur | | en-AU | Olivia Russell Nicole | | en-NZ | Aria | | fr-FR | Celine Lea Remi Mathieu | | fr-CA | Gabrielle Liam Chantal | | de-DE | Daniel Vicki Marlene Hans | | it-IT | Adriano Bianca Giorgio Carla | | ja-JP | Takumi Kazuha Tomoko Mizuki | | ko-KR | Seoyeon | | pl-PL | Ola Maja Jan Jacek Ewa | | pt-PT | Ines Cristiano | | pt-BR | Camila Thiago Vitoria Ricardo | | ro-RO | Carmen | | ru-RU | Maxim Tatyana | | es-US | Lupe Pedro Penelope Miguel | | es-MX | Mia Andres | | es-ES | Lucia Sergio Enrique Conchita | | sv-SE | Elin Astrid | | tr-TR | Filiz Burcu |
- is_default
 
 boolean — Whether this item is the default of the asset. Each asset can only have one `isDefault` set to `true`.
- upload_file
 
 string — The uploaded file, in binary format. Only works for `asset_type`s `audio`, `image`, `video` and `slides`. This field is not required if you create a TTS item when creating or updating an audio asset. **Allowed file extensions** * audio - mp3, wav * image - jpeg, jpg, jpe, jif, jfif, png, gif * slides - pdf * video - mp4, mov **Maximum supported filesize** A single request can upload a maximum of 100MB. **Single file maximum filesize** * audio - 10M * image - 10M * slides - 10M * video - 100M
asset_name

string — The asset's name.
category_id

string — The asset category's ID.
restore

boolean — Whether this asset should be restored. Only assets in archived status can be restored. Take care to avoid name duplication with current assets. If there is a conflict, the name of this asset needs to be changed as well. If this field is `true`, this request will ignore updates to other fields apart from the initial `asset_name`.

Example:

{
  "asset_description": "This is an audio asset.",
  "asset_name": "asset name",
  "category_id": "bnGEj1yrRb6qlNMvyMK08g",
  "asset_items": [
    {
      "asset_item_id": "beYjXoDOS_eV1QmTpj63PQ",
      "asset_item_name": "english audio",
      "upload_file": "Vm10V1UxUXhSWGxTYTJoV1lUSm9iMVZxUm5kamJGWjFZMGhPYVZadVFsaFhXSEJYVkd4WmQwNVlaRlZOVjA0MFdWVmFXbVZ0UmtsVWJGWlRaV3RKTUZkclVrSmxSVEI0VVd4V1RsSkVRVGs9",
      "asset_item_content": "text asset content",
      "is_default": true,
      "asset_item_voice": "Joanna",
      "asset_item_language": "en-US"
    }
  ],
  "restore": true
}

Responses

Status: 204 HTTP Status Code: `204` Asset updated

Status: 400 HTTP Status Code: `400` Bad Request Error Code: `10005` Asset name is too long. Error Code: `10007` Duplicate asset name Error Code: `10013` Asset description is too long.

Status: 404 HTTP Status Code: `404` Not Found Error Code: `10009` Asset not found.

Status: 429 HTTP Status Code: `429` Too Many Requests. For more information, see [rate limits](/docs/api/rest/rate-limits/).

Duplicate an asset

Method: POST
Path: /contact_center/asset_library/assets/{assetId}/duplicate
Tags: Asset Library

Creates new assets based on an existing asset.

Scopes: contact_center_asset_library:write:admin

Granular Scopes: contact_center:write:asset_library:admin

Rate Limit Label: MEDIUM

Request Body

Content-Type: application/json

assets (required)

array — List of new asset information to be created.

Items:
- asset_name (required)
  
  string — The asset's name.
- asset_description
  
  string — The asset's description.

Example:

{
  "assets": [
    {
      "asset_name": "asset name",
      "asset_description": "This is an audio asset."
    }
  ]
}

Responses

Status: 201 HTTP Status Code: `201` Asset duplicated.

Content-Type: application/json

results (required)

array — Array containing the duplication results for each asset.

Items:
- status (required)
  
  string, possible values: "success", "failed" — The duplication status of the asset.
- asset_id
  
  string — The asset's unique identifier.
- asset_name
  
  string — The asset's name.
- error
  
  string — The reason for duplication failure. This field is returned only when duplication fails.

Example:

{
  "results": [
    {
      "asset_id": "WkdWelkzSnBjSEZwYjI0PQ11",
      "asset_name": "asset name",
      "status": "success",
      "error": "Asset name is too long."
    }
  ]
}

Status: 400 HTTP Status Code: `400` Bad Request

Status: 401 HTTP Status Code: `401` Unauthorized Error Code: `124` Invalid access token. Error Code: `124` Access token has expired. Error Code: `1002` The user associated with this access token was not found or is invalid.

Status: 403 HTTP Status Code: `403` Forbidden Error Code: `1021` User account is deactivated. Error Code: `1022` User does not have a Contact Center license. Error Code: `9001` The Contact Center user associated with this bearer token is missing privileges on their role required to operate this request.

Status: 404 HTTP Status Code: `404` Not Found Error Code: `10009` Asset not found. If the source asset you input does not exist or is in an archived state, this error will occur.

Status: 429 HTTP Status Code: `429` Too Many Requests. For more information, see [rate limits](https://developers.zoom.us/docs/api/rate-limits/). Error Code: `4001` You have reached the maximum per-second rate limit for this API. Try again later.

Delete asset items

Method: DELETE
Path: /contact_center/asset_library/assets/{assetId}/items
Tags: Asset Library

Delete specific asset items. The default asset item can't be deleted.

Scopes: contact_center_asset_library:write:admin

Granular Scopes: contact_center:write:asset_library:admin

Rate Limit Label: LIGHT

Request Body

Content-Type: application/json

asset_item_ids

array — The list of asset item IDs.

Items:

string — The asset item's ID.

Example:

{
  "asset_item_ids": [
    "BeSjXoDOS_eV1QmTpj63PQ"
  ]
}

Responses

Status: 204 HTTP Status Code: `204` Asset items deleted.

Status: 401 HTTP Status Code: `401` Unauthorized

Status: 403 HTTP Status Code: `403` Forbidden

Status: 404 HTTP Status Code: `404` Not Found Error Code: `10009` Asset not found.

Status: 429 HTTP Status Code: `429` Too Many Requests. For more information, see [rate limits](https://developers.zoom.us/docs/api/rate-limits/).

List asset categories

Method: GET
Path: /contact_center/asset_library/categories
Tags: Asset Library

List asset categories.

Scopes: contact_center_asset_library:read:admin

Granular Scopes: contact_center:read:asset_library:admin

Rate Limit Label: MEDIUM

Responses

Status: 200 HTTP Status Code: `200` Asset categories returned.

Content-Type: application/json

categories

array — Array of assets categories.

Items:
- category_id
  
  string — The asset category's ID.
- category_name
  
  string — The asset category's name.
- category_scope
  
  string, possible values: "system", "agent" — The asset category's scope.
next_page_token

string — Use the next page token to paginate through large result sets. A next page token is returned whenever the set of available results exceeds the current page size. This token's expiration period is 15 minutes.
page_size

integer, default: 30 — The number of records returned within a single API call.
total_records

integer — The total number of all the records available across pages.

Example:

{
  "next_page_token": "R4aF9Oj0fVM2hhezJTEmSKaBSkfesDwGy42",
  "page_size": 30,
  "total_records": 10,
  "categories": [
    {
      "category_id": "bnGEj1yrRb6qlNMvyMK08g",
      "category_name": "flows assets",
      "category_scope": "system"
    }
  ]
}

Status: 429 HTTP Status Code: `429` Too Many Requests. For more information, see [rate limits](/docs/api/rate-limits/).

Create an asset category

Method: POST
Path: /contact_center/asset_library/categories
Tags: Asset Library

Create an asset category.

Scopes: contact_center_asset_library:write:admin

Granular Scopes: contact_center:write:asset_library:admin

Rate Limit Label: LIGHT

Request Body

Content-Type: application/json

category_name (required)

string — The asset category's name.
category_scope (required)

string, possible values: "system", "agent" — The asset category's scope.

Example:

{
  "category_name": "flows assets",
  "category_scope": "system"
}

Responses

Status: 201 HTTP Status Code: `201` Assets category created.

Content-Type: application/json

category_id

string — The asset category's ID.
category_name

string — The asset category's name.
category_scope

string, possible values: "system", "agent" — The asset category's scope.

Example:

{
  "category_id": "bnGEj1yrRb6qlNMvyMK08g",
  "category_name": "flows assets",
  "category_scope": "system"
}

Status: 400 HTTP Status Code: `400` Bad Request Error Code: `10015` Duplicate category name. Error Code: `10020` Unable to create more.

Status: 429 HTTP Status Code: `429` Too Many Requests. For more information, see [rate limits](/docs/api/rest/rate-limits/).

Get an asset category

Method: GET
Path: /contact_center/asset_library/categories/{categoryId}
Tags: Asset Library

Get an asset category.

Scopes: contact_center_asset_library:read:admin

Granular Scopes: contact_center:read:asset_library:admin

Rate Limit Label: LIGHT

Responses

Status: 200 HTTP Status Code: `200` Assets category returned.

Content-Type: application/json

category_id

string — The asset category's ID.
category_name

string — The asset category's name.
category_scope

string, possible values: "system", "agent" — The asset category's scope.

Example:

{
  "category_id": "bnGEj1yrRb6qlNMvyMK08g",
  "category_name": "flows assets",
  "category_scope": "system"
}

Status: 401 HTTP Status Code: `401` Unauthorized

Status: 403 HTTP Status Code: `403` Forbidden

Status: 404 HTTP Status Code: `404` Not Found Error Code: `10023` Asset category not found.

Status: 429 HTTP Status Code: `429` Too Many Requests. For more information, see [rate limits](https://developers.zoom.us/docs/api/rate-limits/).

Delete an asset category

Method: DELETE
Path: /contact_center/asset_library/categories/{categoryId}
Tags: Asset Library

Delete an existing asset category.

Scopes: contact_center_asset_library:write:admin

Granular Scopes: contact_center:delete:asset_library:admin

Rate Limit Label: LIGHT

Responses

Status: 204 HTTP Status Code: `204` Asset deleted.

Status: 404 HTTP Status Code: `404` Not Found Error Code: `10023` Asset category not found. Error Code: `10019` This asset category is being used.

Status: 429 HTTP Status Code: `429` Too Many Requests. For more information, see [rate limits](/docs/api/rest/rate-limits/).

Update an asset category

Method: PATCH
Path: /contact_center/asset_library/categories/{categoryId}
Tags: Asset Library

Update an asset category.

Scopes: contact_center_asset_library:write:admin

Granular Scopes: contact_center:write:asset_library:admin

Rate Limit Label: LIGHT

Request Body

Content-Type: application/json

category_name

string — The asset category's name.

Example:

{
  "category_name": "flows assets"
}

Responses

Status: 204 HTTP Status Code: `204` The assets category updated

Status: 400 HTTP Status Code: `400` Bad Request Error Code: `10015` Duplicate category name.

Status: 404 HTTP Status Code: `404` Not Found Error Code: `10023` Asset category not found.

Status: 429 HTTP Status Code: `429` Too Many Requests. For more information, see [rate limits](/docs/api/rest/rate-limits/).

List block list rules for IP addresses

Method: GET
Path: /contact_center/block_list_rules/ip_addresses
Tags: Block List Rules

List block list rules for IP addresses.

Scopes: contact_center_block_list_rules:read:admin

Granular Scopes: contact_center:read:block_list_rules:admin

Rate Limit Label: MEDIUM

Responses

Status: 200 Block list rules of IP addresses returned.

Content-Type: application/json

ip_address_block_list_rules

array — Information about the block list rules of IP addresses.

Items:
- created_time (required)
  
  string, format: date-time — The date and time when the block list rule was created.
- ip_address (required)
  
  string — The IP address the block list rule applies to.
- ip_address_block_list_rule_id (required)
  
  string — The block list rule's unique identifier.
- last_modified_time (required)
  
  string, format: date-time — The date and time when the block list rule was last modified.
- match_type (required)
  
  string, possible values: "ip_address" — The block list rule's match type. * `ip_address` — Matches a specific IP address.
- status (required)
  
  string, possible values: "active", "inactive" — The block list rule's status.
- comment
  
  string — The comment about the block list rule.
next_page_token

string — Use the next page token to paginate through large result sets. A next page token is returned whenever the set of available results exceeds the current page size. This token's expiration period is 15 minutes.
page_size

integer, default: 10 — The number of records returned within a single API call.
total_records

integer — The total number of all records available across pages.

Example:

{
  "next_page_token": "R4aF9Oj0fVM2hhezJTEmSKaBSkfesDwGy42",
  "page_size": 10,
  "total_records": 10,
  "ip_address_block_list_rules": [
    {
      "ip_address_block_list_rule_id": "zeYjXoDOS_eV1QmTpj63PQ",
      "ip_address": "192.168.1.100",
      "match_type": "ip_address",
      "status": "active",
      "comment": "Suspicious activity detected",
      "created_time": "2022-02-15T09:27:15Z",
      "last_modified_time": "2022-02-15T09:27:15Z"
    }
  ]
}

Status: 400 HTTP Status Code: `400` Bad Request Error Code: `300` Validation failed. Error Code: `1019` Feature OP flag is not enabled. Error Code: `300` Invalid `match_type`. Error Code: `300` Invalid `ip_address`. Error Code: `300` Invalid `status`.

Status: 401 HTTP Status Code: `401` Unauthorized Error Code: `124` Invalid access token. Error Code: `124` Access token has expired. Error Code: `1002` The user associated with this access token was not found or is invalid.

Status: 403 HTTP Status Code: `403` Forbidden Error Code: `1021` User account is deactivated. Error Code: `1022` User does not have a Contact Center license. Error Code: `9001` The Contact Center user associated with this bearer token is missing privileges on their role required to operate this request.

Status: 429 HTTP Status Code: `429` Too Many Requests. For more information, see [rate limits](https://developers.zoom.us/docs/api/rate-limits/). Error Code: `4001` You have reached the maximum per-second rate limit for this API. Try again later.

Status: 500 HTTP Status Code: `500` Internal Server Error

Create block list rules for IP addresses

Method: POST
Path: /contact_center/block_list_rules/ip_addresses
Tags: Block List Rules

Create block list rules for IP addresses. Supports up to 20 block list rules per request. Valid block list rules are created while invalid block list rules are rejected with detailed error messages. Returns 201 if all are valid, 207 for partial success, or 400 if all are invalid.

Scopes: contact_center_block_list_rules:write:admin

Granular Scopes: contact_center:write:block_list_rules:admin

Rate Limit Label: MEDIUM

Request Body

Content-Type: application/json

ip_address_block_list_rules (required)

array — Information about the block list rules for IP addresses. You can create a maximum number of 20 rules.

Items:
- ip_address (required)
  
  string — The IP address the block list rule applies to.
- match_type (required)
  
  string, possible values: "ip_address" — The block list rule's match type. * `ip_address` - Matches a specific IP address.
- status (required)
  
  string, possible values: "active", "inactive" — The block list rule's status.
- comment
  
  string — The comment about the block list rule.

Example:

{
  "ip_address_block_list_rules": [
    {
      "status": "active",
      "match_type": "ip_address",
      "ip_address": "192.168.1.100",
      "comment": "Suspicious activity detected"
    }
  ]
}

Responses

Status: 201 HTTP Status Code: `201` All block list rules of IP addresses successfully created. HTTP Status Code: `207` Block list rules of IP addresses partially created. Valid block list rules are created while invalid block list rules are rejected with detailed error messages.

Content-Type: application/json

ip_address_block_list_rules (required)

array — Information about the created block list rules.

Items:
- ip_address (required)
  
  string — The IP address the block list rule applies to.
- ip_address_block_list_rule_id (required)
  
  string — The block list rule's unique identifier.
- match_type (required)
  
  string, possible values: "ip_address" — The block list rule's match type. * `ip_address` - Matches a specific IP address.
- status (required)
  
  string, possible values: "active", "inactive" — The status of the block list rule.
- comment
  
  string — The comment about the block list rule.
- created_time
  
  string, format: date-time — The date and time when the block list rule was created.
- last_modified_time
  
  string, format: date-time — The date and time when the block list rule was last modified.

Example:

{
  "ip_address_block_list_rules": [
    {
      "ip_address_block_list_rule_id": "zeYjXoDOS_eV1QmTpj63PQ",
      "status": "active",
      "match_type": "ip_address",
      "ip_address": "192.168.1.100",
      "comment": "Suspicious activity detected",
      "created_time": "2022-02-15T09:27:15Z",
      "last_modified_time": "2022-02-15T09:27:15Z"
    }
  ]
}

Status: 400 HTTP Status Code: `400` Bad Request Error Code: `300` Validation failed. Error Code: `1508` Invalid IP address. Error Code: `1507` Duplicated block list rule.

Status: 401 HTTP Status Code: `401` Unauthorized Error Code: `124` Invalid access token. Error Code: `124` Access token has expired. Error Code: `1002` The user associated with this access token was not found or is invalid.

Status: 403 HTTP Status Code: `403` Forbidden Error Code: `1021` User account is deactivated. Error Code: `1022` User does not have a Contact Center license. Error Code: `9001` The Contact Center user associated with this bearer token is missing privileges on their role required to operate this request.

Status: 429 HTTP Status Code: `429` Too Many Requests. For more information, see [rate limits](https://developers.zoom.us/docs/api/rate-limits/). Error Code: `4001` You have reached the maximum per-second rate limit for this API. Try again later.

Delete IP addresses' block list rules

Method: DELETE
Path: /contact_center/block_list_rules/ip_addresses
Tags: Block List Rules

Delete block list rules of IP addresses. Supports up to 20 block list rules per request. No block list rules are deleted unless all IDs in the request are valid.

Scopes: contact_center_block_list_rules:write:admin

Granular Scopes: contact_center:delete:block_list_rules:admin

Rate Limit Label: MEDIUM

Request Body

Content-Type: application/json

ip_address_block_list_rule_ids (required)

array — A list of block list rule IDs to delete.

Items:

string

Example:

{
  "ip_address_block_list_rule_ids": [
    "zeYjXoDOS_eV1QmTpj63PQ",
    "abCdEfGhI_jKlMnOpQrStU"
  ]
}

Responses

Status: 204 All IP address block list rules were successfully deleted.

Status: 400 HTTP Status Code: `400` Bad Request Error Code: `1019` Feature OP flag is not enabled. Error Code: `300` `ip_address_block_list_rule_ids` is required. Error Code: `300` Block list rule supports a maximum of 20.

Status: 401 HTTP Status Code: `401` Unauthorized Error Code: `124` Invalid access token. Error Code: `124` Access token has expired. Error Code: `1002` The user associated with this access token was not found or is invalid.

Status: 403 HTTP Status Code: `403` Forbidden Error Code: `1021` User account is deactivated. Error Code: `1022` User does not have a Contact Center license. Error Code: `9001` The Contact Center user associated with this bearer token is missing privileges on their role required to operate this request.

Status: 404 HTTP Status Code: `404` Not Found Error Code: `1505` Block list rules do not exist: `ipAddressBlockListRuleId1`, `ipAddressBlockListRuleId2`.

Status: 429 HTTP Status Code: `429` Too Many Requests. For more information, see [rate limits](https://developers.zoom.us/docs/api/rate-limits/). Error Code: `4001` You have reached the maximum per-second rate limit for this API. Try again later.

Status: 500 HTTP Status Code: `500` Internal Server Error

Get a block list rule of IP addresses

Method: GET
Path: /contact_center/block_list_rules/ip_addresses/{ipAddressBlockListRuleId}
Tags: Block List Rules

Get a block list rule of IP addresses.

Scopes: contact_center_block_list_rules:read:admin

Granular Scopes: contact_center:read:block_list_rules:admin

Rate Limit Label: LIGHT

Responses

Status: 200 Block list rule of IP addresses returned.

Content-Type: application/json

created_time (required)

string, format: date-time — The date and time when the block list rule was created.
ip_address (required)

string — The IP address the block list rule applies to.
ip_address_block_list_rule_id (required)

string — The ID of the block list rule.
last_modified_time (required)

string, format: date-time — The date and time when the block list rule was last modified.
match_type (required)

string, possible values: "ip_address" — The match type of the block list rule. * `ip_address` — Matches a specific IP address
status (required)

string, possible values: "active", "inactive" — The status of the block list rule.
comment

string — The comment about the block list rule.

Example:

{
  "ip_address_block_list_rule_id": "zeYjXoDOS_eV1QmTpj63PQ",
  "ip_address": "192.168.1.100",
  "match_type": "ip_address",
  "status": "active",
  "comment": "Suspicious activity detected",
  "created_time": "2022-02-15T09:27:15Z",
  "last_modified_time": "2022-02-15T09:27:15Z"
}

Status: 400 HTTP Status Code: `400` Bad Request Error Code: `1019` Feature OP flag is not enabled.

Status: 401 HTTP Status Code: `401` Unauthorized

Status: 403 HTTP Status Code: `403` Forbidden

Status: 404 HTTP Status Code: `404` Not Found Error Code: `1505` Block list rule does not exist: {ipAddressBlockListRuleId}.

Status: 429 HTTP Status Code: `429` Too Many Requests. For more information, see [rate limits](https://developers.zoom.us/docs/api/rate-limits/).

Status: 500 HTTP Status Code: `500` Internal Server Error

List block list rules of phone numbers

Method: GET
Path: /contact_center/block_list_rules/phone_numbers
Tags: Block List Rules

List block list rules of phone numbers.

Scopes: contact_center_block_list_rules:read:admin

Granular Scopes: contact_center:read:block_list_rules:admin

Rate Limit Label: MEDIUM

Responses

Status: 200 Block list rules of phone numbers returned.

Content-Type: application/json

next_page_token

string — Use the next page token to paginate through large result sets. A next page token is returned whenever the set of available results exceeds the current page size. This token's expiration period is 15 minutes.
page_size

integer, default: 30 — The number of records returned in a single API call.
phone_block_list_rules

array — Information about the block list rules of phone numbers.

Items:
- channel (required)
  
  array — The channel the block list rule applies to.
  
  Items:
  
  string, possible values: "voice", "sms"
- country_iso_code (required)
  
  string — The [ISO country code](/docs/api/references/abbreviations/#countries).
- created_time (required)
  
  string, format: date-time — The date and time when the block list rule was created.
- direction (required)
  
  array — The call direction the block list rule applies to.
  
  Items:
  
  string, possible values: "inbound", "outbound"
- last_modified_time (required)
  
  string, format: date-time — The date and time when the block list rule was last modified.
- match_type (required)
  
  string, possible values: "phone_number", "prefix" — The block list rule's match type. * `phone_number` - A specific phone number. * `prefix` - All numbers starting with the specified digits.
- phone_block_list_rule_id (required)
  
  string — The block list rule's ID.
- phone_number (required)
  
  string — The phone number or prefix the block list rule applies to.
- status (required)
  
  string, possible values: "active", "inactive" — The block list rule's status.
- comment
  
  string — The comment about the block list rule.
- exceptions
  
  array — The phone numbers excluded from the block list rule. Only applies to `prefix` match type.
  
  Items:
  
  string
total_records

integer — The total number of all records available across pages.

Example:

{
  "next_page_token": "R4aF9Oj0fVM2hhezJTEmSKaBSkfesDwGy42",
  "page_size": 30,
  "total_records": 10,
  "phone_block_list_rules": [
    {
      "phone_block_list_rule_id": "zeYjXoDOS_eV1QmTpj63PQ",
      "status": "active",
      "match_type": "prefix",
      "country_iso_code": "US",
      "phone_number": "1800",
      "exceptions": [
        "8005550101"
      ],
      "direction": [
        "inbound"
      ],
      "channel": [
        "voice"
      ],
      "comment": "Spam caller",
      "created_time": "2022-02-15T09:27:15Z",
      "last_modified_time": "2022-02-15T09:27:15Z"
    }
  ]
}

Status: 400 HTTP Status Code: `400` Bad Request Error Code: `300` Invalid `match_type`. Error Code: `300` Invalid `status`. Error Code: `300` Invalid `direction`. Error Code: `300` Invalid `channel`. Error Code: `1019` Feature OP flag is not enabled. Error Code: `300` Invalid phone number.

Status: 401 HTTP Status Code: `401` Unauthorized Error Code: `124` Invalid access token. Error Code: `124` Access token has expired. Error Code: `1002` The user associated with this access token was not found or is invalid.

Status: 429 HTTP Status Code: `429` Too Many Requests. For more information, see [rate limits](https://developers.zoom.us/docs/api/rate-limits/). Error Code: `4001` You have reached the maximum per-second rate limit for this API. Try again later.

Status: 500 HTTP Status Code: `500` Internal Server Error

Create block list rules for phone numbers

Method: POST
Path: /contact_center/block_list_rules/phone_numbers
Tags: Block List Rules

Create block list rules for phone numbers. Supports up to 20 block list rules per request. Valid block list rules are created while invalid block list rules are rejected with detailed error messages. Returns 201 if all are valid, 207 for partial success, or 400 if all are invalid.

Scopes: contact_center_block_list_rules:write:admin

Granular Scopes: contact_center:write:block_list_rules:admin

Rate Limit Label: MEDIUM

Request Body

Content-Type: application/json

phone_block_list_rules (required)

array — Information about the block list rules for phone numbers. You can create a maximum of 20 rules.

Items:
- channel (required)
  
  array — The channel the block list rule applies to.
  
  Items:
  
  string, possible values: "voice", "sms"
- country_iso_code (required)
  
  string — The [ISO country code](/docs/api/rest/other-references/abbreviation-lists/#countries).
- direction (required)
  
  array — The call direction the block list rule applies to.
  
  Items:
  
  string, possible values: "inbound", "outbound"
- match_type (required)
  
  string, possible values: "phone_number", "prefix" — The block list rule's match type. * `phone_number` - Matches a specific phone number. * `prefix` - Matches all numbers starting with the specified digits.
- phone_number (required)
  
  string — The phone number or prefix the block list rule applies to.
- status (required)
  
  string, possible values: "active", "inactive" — The block list rule's status.
- comment
  
  string — The comment about the block list rule.
- exceptions
  
  array — The phone numbers excluded from the block list rule. Only applies to `prefix` match type. **Note:** * Must start with the prefix. * Do not include the country code. * Phone numbers are digits only.
  
  Items:
  
  string

Example:

{
  "phone_block_list_rules": [
    {
      "status": "active",
      "match_type": "prefix",
      "country_iso_code": "US",
      "phone_number": "1800",
      "exceptions": [
        "8005550101",
        "8005550102"
      ],
      "direction": [
        "inbound"
      ],
      "channel": [
        "voice"
      ],
      "comment": "Spam caller"
    }
  ]
}

Responses

Status: 201 HTTP Status Code: `201` All block list rules of phone numbers successfully created. HTTP Status Code: `207` Block list rules of phone number partially created. Valid block list rules are created while invalid block list rules are rejected with detailed error messages.

Content-Type: application/json

phone_block_list_rules (required)

array — Information about the created block list rules.

Items:
- channel (required)
  
  array — The channel the block list rule applies to.
  
  Items:
  
  string, possible values: "voice", "sms"
- country_iso_code (required)
  
  string — The [ISO country code](/docs/api/rest/other-references/abbreviation-lists/#countries).
- direction (required)
  
  array — The call direction the block list rule applies to.
  
  Items:
  
  string, possible values: "inbound", "outbound"
- match_type (required)
  
  string, possible values: "phone_number", "prefix" — The block list rule's match type. * `phone_number` - Matches a specific phone number. * `prefix` - Matches all numbers starting with the specified digits.
- phone_block_list_rule_id (required)
  
  string — The block list rule's unique identifier.
- phone_number (required)
  
  string — The phone number or prefix the block list rule applies to.
- status (required)
  
  string, possible values: "active", "inactive" — The block list rule's status.
- comment
  
  string — The comment about the block list rule.
- created_time
  
  string, format: date-time — The date and time when the block list rule was created.
- exceptions
  
  array — The phone numbers excluded from the block list rule. Only applies to `prefix` match type.
  
  Items:
  
  string
- last_modified_time
  
  string, format: date-time — The date and time when the block list rule was last modified.

Example:

{
  "phone_block_list_rules": [
    {
      "phone_block_list_rule_id": "zeYjXoDOS_eV1QmTpj63PQ",
      "status": "active",
      "match_type": "prefix",
      "country_iso_code": "US",
      "phone_number": "1800",
      "exceptions": [
        "8005550101",
        "8005550102"
      ],
      "direction": [
        "inbound"
      ],
      "channel": [
        "voice"
      ],
      "comment": "Spam caller",
      "created_time": "2022-02-15T09:27:15Z",
      "last_modified_time": "2022-02-15T09:27:15Z"
    }
  ]
}

Status: 400 HTTP Status Code: `400` Bad Request Error Code: `1019` Feature OP flag is not enabled. Error Code: `300` `phone_block_list_rules` is required. Error Code: `300` Block list rule supports a maximum of 20.

Status: 401 HTTP Status Code: `401` Unauthorized Error Code: `124` Invalid access token. Error Code: `124` Access token has expired. Error Code: `1002` The user associated with this access token was not found or is invalid.

Status: 403 HTTP Status Code: `403` Forbidden Error Code: `1021` User account is deactivated. Error Code: `1022` User does not have a Contact Center license. Error Code: `9001` The Contact Center user associated with this bearer token is missing privileges on their role required to operate this request.

Status: 429 HTTP Status Code: `429` Too Many Requests. For more information, see [rate limits](https://developers.zoom.us/docs/api/rate-limits/). Error Code: `4001` You have reached the maximum per-second rate limit for this API. Try again later.

Status: 500 HTTP Status Code: `500` Internal Server Error

Delete phone numbers' block list rules

Method: DELETE
Path: /contact_center/block_list_rules/phone_numbers
Tags: Block List Rules

Delete block list rules of phone numbers. Supports up to 20 block list rules per request. No block list rules are deleted unless all IDs in the request are valid.

Scopes: contact_center_block_list_rules:write:admin

Granular Scopes: contact_center:delete:block_list_rules:admin

Rate Limit Label: MEDIUM

Request Body

Content-Type: application/json

phone_block_list_rule_ids (required)

array — A list of IDs of block list rules to delete.

Items:

string

Example:

{
  "phone_block_list_rule_ids": [
    "zeYjXoDOS_eV1QmTpj63PQ",
    "abCdEfGhI_jKlMnOpQrStU"
  ]
}

Responses

Status: 204 All block list rules of phone numbers successfully deleted.

Status: 400 HTTP Status Code: `400` Bad Request Error Code: `1019` Feature OP flag is not enabled. Error Code: `300` `phone_block_list_rule_ids` is required. Error Code: `300` Block list rule supports a maximum of 20.

Status: 401 HTTP Status Code: `401` Unauthorized Error Code: `124` Invalid access token. Error Code: `124` Access token has expired. Error Code: `1002` The user associated with this access token was not found or is invalid.

Status: 403 HTTP Status Code: `403` Forbidden Error Code: `1021` User account is deactivated. Error Code: `1022` User does not have a Contact Center license. Error Code: `9001` The Contact Center user associated with this bearer token is missing privileges on their role required to operate this request.

Status: 404 HTTP Status Code: `404` Not Found Error Code: `1505` Block list rules do not exist: `phoneBlockListRuleId1`, `phoneBlockListRuleId2`.

Status: 429 HTTP Status Code: `429` Too Many Requests. For more information, see [rate limits](https://developers.zoom.us/docs/api/rate-limits/). Error Code: `4001` You have reached the maximum per-second rate limit for this API. Try again later.

Status: 500 HTTP Status Code: `500` Internal Server Error

Get a block list rule of phone numbers

Method: GET
Path: /contact_center/block_list_rules/phone_numbers/{phoneBlockListRuleId}
Tags: Block List Rules

Get a block list rule of phone numbers.

Scopes: contact_center_block_list_rules:read:admin

Granular Scopes: contact_center:read:block_list_rules:admin

Rate Limit Label: LIGHT

Responses

Status: 200 Block list rule of phone numbers returned.

Content-Type: application/json

channel (required)

array — The channel the block list rule applies to.

Items:

string, possible values: "voice", "sms"
country_iso_code (required)

string — The [ISO country code](/docs/api/rest/other-references/abbreviation-lists/#countries).
created_time (required)

string, format: date-time — The date and time when the block list rule was created.
direction (required)

array — The call direction the block list rule applies to.

Items:

string, possible values: "inbound", "outbound"
last_modified_time (required)

string, format: date-time — The date and time when the block list rule was last modified.
match_type (required)

string, possible values: "phone_number", "prefix" — The block list rule's match type. * `phone_number` — A specific phone number. * `prefix` — All numbers starting with the specified digits.
phone_block_list_rule_id (required)

string — The block list rule's ID.
phone_number (required)

string — The phone number or prefix the block list rule applies to.
status (required)

string, possible values: "active", "inactive" — The block list rule's status.
comment

string — The comment about the block list rule.
exceptions

array — The phone numbers excluded from the block list rule. Only applies to `prefix` match type.

Items:

string

Example:

{
  "phone_block_list_rule_id": "zeYjXoDOS_eV1QmTpj63PQ",
  "status": "active",
  "match_type": "prefix",
  "country_iso_code": "US",
  "phone_number": "1800",
  "exceptions": [
    "8005550101"
  ],
  "direction": [
    "inbound"
  ],
  "channel": [
    "voice"
  ],
  "comment": "Spam caller",
  "created_time": "2022-02-15T09:27:15Z",
  "last_modified_time": "2022-02-15T09:27:15Z"
}

Status: 400 HTTP Status Code: `400` Bad Request Error Code: `1019` Feature OP flag is not enabled.

Status: 401 HTTP Status Code: `401` Unauthorized Error Code: `124` Invalid access token. Error Code: `124` Access token has expired. Error Code: `1002` The user associated with this access token was not found or is invalid.

Status: 403 HTTP Status Code: `403` Forbidden Error Code: `1021` User account is deactivated. Error Code: `1022` User does not have a Contact Center license. Error Code: `9001` The Contact Center user associated with this bearer token is missing privileges on their role required to operate this request.

Status: 404 HTTP Status Code: `404` Not Found Error Code: `1505` Blocklist rule does not exist: {phoneBlockListRuleId}.

Status: 429 HTTP Status Code: `429` Too Many Requests. For more information, see [rate limits](https://developers.zoom.us/docs/api/rate-limits/). Error Code: `4001` You have reached the maximum per-second rate limit for this API. Try again later.

Status: 500 HTTP Status Code: `500` Internal Server Error

Control an engagement's recording

Method: PUT
Path: /contact_center/engagements/{engagementId}/recording/{command}
Tags: Call Control

Controls the recording state for an engagement.

This request is only valid for video and voice engagements. Calling this API for other channel types is invalid.

Acceptance of a request and response of HTTP 204 No Content only ensures there were no validation errors with the request.

Note: The Control an engagement's recording API only works with third-party apps if the account admin has enabled the Allow Open API to pause and resume automatic call recording setting. For more details, refer to this support article.

Scopes: contact_center_engagement:write:admin

Granular Scopes: contact_center:update:engagement_recording_control:admin

Rate Limit Label: LIGHT

Responses

Status: 204 HTTP Status: `204` No Content Request accepted for processing with no validation errors. This does not imply successful execution of the command.

Status: 400 HTTP Status Code: `400` Bad Request Error Code: `2814` Cannot use this recording control command with this engagement's channel type. Error Code: `2815` The engagement is not assigned to an agent. It is not being recorded. Error Code: `2818` Cannot change recording state from {current_state} to {command_state}. Error Code: `2819` Recording is stopped. Error Code: `2808` Recording is in progress. There is no need to open it again. Error Code: `2809` Start recording first. Cannot be converted to {state}. Error Code: `2810` No need to repeat the operation. The current state is already {state}. Error Code: `2812` The recording control's current state is {current_state}, and it cannot be converted to {command_state}. Error Code: `300` Invalid request.

Status: 404 HTTP Status Code: `404` Not Found Error Code: `20006` Account not found. Error Code: `2816` The system could not find the session for the engagement. Error Code: `2817` There is no recording for this engagement. Error Code: `2901` Engagement does not exist: {0}. Error Code: `2906` There are no agents on the call.

Status: 409 HTTP Status Code: `409` Conflict Error Code: `2907` There was a problem processing the recording control request. Error Code: `2908` The operation was partially completed. Try again. Error Code: `2909` There was a problem processing the recording control request.

Status: 429 HTTP Status Code: `429` Too Many Requests. For more information, see [rate limits](/docs/api/rate-limits/).

Command control of a user

Method: POST
Path: /contact_center/users/{userId}/commands
Tags: Call Control

Issue a command to trigger an action for a Contact Center user.

command - make_call initiates an outbound voice engagement.

Scopes: contact_center_user:write:admin

Granular Scopes: contact_center:write:user_control:admin

Rate Limit Label: LIGHT

Request Body

Content-Type: application/json

channel (required)

string, possible values: "voice" — The channel type. Currently only supports `voice`.
command (required)

string, possible values: "make_call", "answer_call", "hold_call", "unhold_call", "end_call", "conference_warm_invite" — Control commands. - `make_call` - The `cc_queue_id` field is required.
params

object — The parameters.
- cc_queue_id
  
  string — The Contact Center queue identifier.
- consumer_display_name
  
  string — The consumer's name. Only valid and `Optional` when `command` is `make_call`.
- consumer_number
  
  string — The customer's phone number. Only valid and `Required` when `command` is `make_call`.
- device_id
  
  string — The device ID. Only valid and `Required` when `channel` is `voice`.
- engagement_id
  
  string — The engagement's ID. Only valid and `Required` when `command` is `hold_call`, `unhold_call`, or `end_call` or `conference_warm_invite`.
- invitee_id
  
  string — The invitee's ID. When `invitee_type` is `0`, it represents the agent's ID. When `invitee_type` is `1`, it represents the queue's ID. When `invitee_type` is `2`, it represents the DID number. Only valid and `Required` when `command` is `conference_warm_invite`.
- invitee_type
  
  integer, possible values: 0, 1, 2 — The invitee's type. - 0= Contact Center agent - 1= queue - 2= Direct Inward Dialing Number (DID number) Only valid and `Required` when `command` is `conference_warm_invite`.
- queue_caller_id_number
  
  string — The queue's caller ID number, in E.164 format, configured inside the queue. Only valid and `Optional` when `command` is `make_call`.
- reservation_id
  
  string — The reservation's ID. Only valid and `Required` when `command` is `answer_call`.

Example:

{
  "command": "make_call",
  "channel": "voice",
  "params": {
    "device_id": "ZoomClient-CCITab-Tnxa76dLQ_SZwxmCP3bIOA",
    "cc_queue_id": "a4lCNeq2SzKbgkcDVbjCZQ",
    "queue_caller_id_number": "+14155552641",
    "consumer_number": "+14155552641",
    "consumer_display_name": "Jill Chill",
    "reservation_id": "ZWRB4E457925500218F7883FC12D151AA9F",
    "engagement_id": "TTv5RIhDRWS6Kb-OZfTYtg",
    "invitee_type": 0,
    "invitee_id": "NMYuY-8aThej4Fm3GTww4Q"
  }
}

Responses

Status: 201 HTTP Status: `201` Created Request created for processing with no validation errors. This does not imply successful execution of the command.

Content-Type: application/json

request_id (required)

string — The request ID to correlate the asynchronous response. For `make_call` commands, the webhook event containing the `request_id` is [`contact_center.call_control_make_call_executed`](/docs/api/contact-center/events/#tag/contact_center/postcontact_center.call_control_make_call_executed).

Example:

{
  "request_id": "alU302FoDe-dCq9QAFeZhw"
}

Status: 400 HTTP Status Code: `400` Bad Request Error Code: `9002` User is currently `Occupied`. Error Code: `300` Invalid request. Error Code: `1018` User device not found. Error Code: `1211` User is not assigned to queue. Error Code: `1212` Caller ID not found or not assigned to queue. Error Code: `9003` The CTI device is not supported.

Status: 401 HTTP Status Code: `401` Unauthorized Error Code: `124` Invalid access token. Error Code: `124` Access token has expired. Error Code: `1002` The user associated with this access token was not found or is invalid.

Status: 403 HTTP Status Code: `403` Forbidden Error Code: `9001` The Contact Center user associated with this bearer token is missing privileges on their role required to operate this request. Error Code: `1021` User account is deactivated. Error Code: `1022` User does not have a Contact Center license.

Status: 429 HTTP Status Code: `429` Too Many Requests. For more information, see [rate limits](https://developers.zoom.us/docs/api/rate-limits/). Error Code: `4001` You have reached the maximum per-second rate limit for this API. Try again later.

List user's devices

Method: GET
Path: /contact_center/users/{userId}/devices
Tags: Call Control

List a Contact Center user's device information.

Scopes: contact_center_user:read:admin

Granular Scopes: contact_center:read:user_device:admin

Rate Limit Label: LIGHT

Responses

Status: 200 User device list returned.

Content-Type: application/json

devices

array — The device information.

Items:
- device_id
  
  string — User login device ID.
- device_type
  
  string, possible values: "pwa", "client", "cti" — Device type.
- device_version
  
  string — Client version.
- sip_registration_information
  
  object — The SIP registration information.
  - registration_success
    
    boolean — Registration successful.
next_page_token

string — Use the next page token to paginate through large result sets. A next page token is returned whenever the set of available results exceeds the current page size. This token's expiration period is 15 minutes.
page_size

integer, default: 10 — The number of records returned within a single API call.
total_records

integer — The total number of all records available across pages.

Example:

{
  "next_page_token": "R4aF9Oj0fVM2hhezJTEmSKaBSkfesDwGy42",
  "page_size": 10,
  "total_records": 10,
  "devices": [
    {
      "device_id": "ZoomClient-CCITab-Tnxa76dLQ_SZwxmCP3bIOA",
      "device_version": "6.2.3.40682",
      "sip_registration_information": {
        "registration_success": true
      },
      "device_type": "pwa"
    }
  ]
}

Status: 400 HTTP Status Code: `400` Bad Request

Status: 401 HTTP Status Code: `401` Unauthorized Error Code: `124` Invalid access token. Error Code: `124` Access token has expired. Error Code: `1002` The user associated with this access token was not found or is invalid.

Status: 403 HTTP Status Code: `403` Forbidden Error Code: `1021` User account is deactivated. Error Code: `1022` User does not have a Contact Center license. Error Code: `9001` The Contact Center user associated with this bearer token is missing privileges on their role required to operate this request.

Status: 404 HTTP Status Code: `404` Not Found Error Code: `1001` User does not exist: {userId}.

Status: 429 HTTP Status Code: `429` Too Many Requests. For more information, see [rate limits](/docs/api/rate-limits/). Error Code: `4001` You have reached the maximum per-second rate limit for this API. Try again later.

List outbound campaigns

Method: GET
Path: /contact_center/outbound_campaign/campaigns
Tags: Campaigns

List Contact Center outbound campaigns.

Scopes: contact_center_outbound_campaign:read:admin

Granular Scopes: contact_center:read:outbound_campaign:admin

Rate Limit Label: MEDIUM

Responses

Status: 200 Outbound campaigns are returned successfully.

Content-Type: application/json

next_page_token

string — Use the next page token to paginate through large result sets. A next page token is returned whenever the set of available results exceeds the current page size. This token's expiration period is 15 minutes.
outbound_campaign_items

array — Array of outbound campaigns.

Items:
- outbound_campaign_description
  
  string — The campaign's description.
- outbound_campaign_id
  
  string — The outbound campaign ID.
- outbound_campaign_name
  
  string — The campaign's name. The name is a unique key among all outbound campaigns.
- outbound_campaign_status
  
  string, possible values: "draft", "ready", "running", "paused", "completed", "not_running" — The campaign's status.
page_size

integer, default: 10 — The number of records returned within a single API call.
total_records

integer — The total number of all records available across pages.

Example:

{
  "page_size": 10,
  "total_records": 10,
  "next_page_token": "R4aF9Oj0fVM2hhezJTEmSKaBSkfesDwGy42",
  "outbound_campaign_items": [
    {
      "outbound_campaign_id": "TY_XsJuWR9ehXrsf1DSIAQ",
      "outbound_campaign_name": "My outbound campaign",
      "outbound_campaign_description": "My outbound campaign description",
      "outbound_campaign_status": "paused"
    }
  ]
}

Status: 400 HTTP Status Code: `400` Bad Request Error Code: `5012` Campaign status enum is invalid. Error Code: `300` Validation failed.

Status: 401 HTTP Status Code: `401` Unauthorized Error Code: `124` Invalid access token. Error Code: `124` Access token has expired. Error Code: `1002` The user associated with this access token was not found or is invalid.

Status: 403 HTTP Status Code: `403` Forbidden Error Code: `1021` User account is deactivated. Error Code: `1022` User does not have a Contact Center license. Error Code: `9001` The Contact Center user associated with this bearer token is missing privileges on their role required to operate this request.

Status: 429 HTTP Status Code: `429` Too Many Requests. For more information, see [rate limits](https://developers.zoom.us/docs/api/rate-limits/). Error Code: `4001` You have reached the maximum per-second rate limit for this API. Try again later.

Create an outbound campaign

Method: POST
Path: /contact_center/outbound_campaign/campaigns
Tags: Campaigns

Create an outbound Contact Center campaign.

Scopes: contact_center_outbound_campaign:write:admin

Granular Scopes: contact_center:write:outbound_campaign:admin

Rate Limit Label: LIGHT

Request Body

Content-Type: application/json

dialing_method (required)

string, possible values: "progressive", "preview", "agentless", default: "progressive" — Determine how contacts in this campaign will be dialed. - `progressive` - engagement details are displayed to the agent **after** they are connected with the consumer. - `preview` - engagement details are displayed to the agent **before** they are connected with the consumer. - `agentless` - automated dialing without agent involvement.
dialing_method_settings (required)

object — One of either progressive, preview, or agentless dialing.
outbound_campaign_name (required)

string — The campaign's name. Names are a unique key among all outbound campaigns.
phone_number_id (required)

string — The reference ID for the Contact Center phone number. This number is displayed to consumers for outbound calls.
queue_id (required)

string — The queue ID. 1 - Only voice queues configured for outbound engagements with at least one user from Zoom Contact Center Premium or Elite packages are available for selection. 2 - Queue distribution cannot be configured to Simultaneous or Do Not Distribute.
assign_type

string, possible values: "queue", "default", "customer", default: "queue" — Caller ID assignment type. This assignment type needs to match with `phone_number_id`.
attempts_use_same_period

boolean, default: false — Whether attempts use the same period.
business_hour_id

string — The Contact Center business hours ID. The campaign will only dial during these hours. [Create business hours API.](/docs/contact-center/apis/#operation/businessHourCreate)
business_hour_source

string, possible values: "queue", "campaign", default: "queue" — The Contact Center business hour source. Select `queue` to use the outbound queue's business hours, and `campaign` to set custom hours. Defaults to `queue`.
campaign_contact_list_ids

array — Contacts will be dialed in alphabetical order. If a contact has more than one phone number, the numbers will be dialed in the order they are listed until a call is connected or all numbers have been tried. A list of contact list ids to dial with this campaign. Multiple contact lists can be input here.

Items:

string — Contact list IDs. These can be retrieved using the [List campaign contact lists API.](/docs/api/contact-center/#tag/campaign/GET/contact_center/outbound_campaign/contact_lists)
campaign_do_not_contact_list_ids

array — Contacts will not be dialed in.

Items:

string — Do mot contact list IDs.
closure_set_id

string — The Contact Center closure hours ID. [Create closure hours API.](/docs/contact-center/apis/#operation/closuresSetCreate)
contact_phone_order

string — Contact phone order. 1 means main, 2 means work, 3 means home, 4 means mobile, 5 means other
contact_timezone_source

string, possible values: "none", "area_code", "timezone", default: "none" — Determine the source used to establish the contact's timezone for deciding appropriate calling hours, like 9 AM to 5 PM. **Valid values** `none` - Disables timezone-based calling restrictions. Calls can be made at any time. `timezone` - Uses the contact's explicit timezone attribute to determine calling eligibility. `area_code` - Derives the timezone based on the area code of the contact's highest priority phone number according to the dial order.
dial_sequence

string, possible values: "list_dial", "contact_dial", "contact_with_lock", default: "list_dial" — Controls the dialing sequence and failure-handling behavior. - `LIST_DIAL` (Current Mode) - Upon a dial failure, the system immediately abandons the current contact and tries the next contact in the list or queue. - `CONTACT_DIAL` (New Mode) - Upon a dial failure for a phone number, the system tries the next available phone number for the same contact before moving to the next contact. - `CONTACT_WITH_LOCK` - Functions as `CONTACT_DIAL`, but also applies an exclusive agent lock to the contact upon retrieval to prevent simultaneous access by other agents.
enable_always_running

boolean, default: false — Enable always running.
enable_closure_hour

boolean, default: false — Toggle closure hours on or off. Outbound calls are not started during closure hours.
enable_diagnostics

boolean, default: false — Enable diagnostics.
enable_max_ring_time

boolean, default: true — Disconnect unanswered calls after a set period of time has elapsed.
exclusion_logic

string, possible values: "and", "or", default: "and" — Exclusion logic for contact lists.
max_attempts_per_contact

integer — Maximum attempts per contact.
max_ring_time

integer, default: 60 — Use with `enable_max_ring_time`. A call is considered unanswered after the maximum ring time has elapsed. Maximum ring time must be between 15 and 120 seconds.
other_attempt_period

integer — Other attempt period. Could be in seconds, minutes, hours, and days.
outbound_campaign_description

string — The campaign's description.
outbound_campaign_priority

integer, default: 5 — The campaign priority.
retry_period

integer — Retry period. Could be in seconds, minutes, hours, and days.
retry_period_unit

string, possible values: "seconds", "minutes", "hours", "days", default: "hours" — Unit for retry period.
second_attempt_period

integer, default: 30 — Second attempt period. Could be in seconds, minutes, hours, and days.
third_attempt_period

integer, default: 60 — Third attempt period. Could be in seconds, minutes, hours, and days.

Example:

{
  "outbound_campaign_name": "My outbound campaign name",
  "outbound_campaign_description": "My outbound campaign description",
  "queue_id": "TY_XsJuWR9ehXrsf1DSIAQ",
  "phone_number_id": "XfTPrZjyR5W6QgNARdtGlw",
  "assign_type": "queue",
  "dialing_method": "progressive",
  "dialing_method_settings": {
    "enable_amd": false,
    "amd_settings": {
      "greeting_asset_id": "zNWo_1M5ScCuKnBb2Z-sfw",
      "answering_machine_asset_id": "z8XtiytyQammquBRlVPiWw"
    },
    "enable_abandonment_timeout": false,
    "abandonment_timeout": 5,
    "abandonment_message_asset_id": "z8XtiytyQammquBRlVPiWw"
  },
  "outbound_campaign_priority": 5,
  "campaign_contact_list_ids": [
    "MN2Dtcb2T-yT5CU3clN-AA"
  ],
  "campaign_do_not_contact_list_ids": [
    "Lp7Wzxf4Q-pA9RX6bhO-XX"
  ],
  "exclusion_logic": "and",
  "max_attempts_per_contact": 3,
  "attempts_use_same_period": false,
  "second_attempt_period": 30,
  "third_attempt_period": 60,
  "other_attempt_period": 120,
  "retry_period": 60,
  "retry_period_unit": "hours",
  "dial_sequence": "list_dial",
  "enable_max_ring_time": true,
  "max_ring_time": 60,
  "business_hour_source": "campaign",
  "business_hour_id": "h7XtiytFTammquBRlTRiWZ",
  "enable_closure_hour": false,
  "closure_set_id": "y9XtiytyQammquBRlTPiWw",
  "contact_timezone_source": "area_code",
  "contact_phone_order": "1,2,3,4,5",
  "enable_always_running": false,
  "enable_diagnostics": false
}

Responses

Status: 201 HTTP Status Code: `201` Outbound campaign is created.

Content-Type: application/json

assign_type

string, possible values: "queue", "default", "customer", default: "queue" — Caller ID assignment type.
attempts_use_same_period

boolean — Whether attempts use the same period.
business_hour_id

string — The Contact Center business hours ID. The campaign will only dial during these hours. [Create business hours API.](/docs/contact-center/apis/#operation/businessHourCreate)
business_hour_source

string, possible values: "queue", "campaign", default: "queue" — The Contact Center business hour source. Select `queue` to use the outbound queue's business hours, and `campaign` to set custom hours. Defaults to `queue`. When this value is `queue`, the operating hours are not provided in the API response. [Use the Get Queue Operating Hours API.](/docs/contact-center/apis/#operation/getAQueueOperatingHours)
campaign_contact_list

array — Contacts will be dialed in alphabetical order. If a contact has more than one phone number, the numbers will be dialed in the order they are listed until a call is connected or all numbers have been tried. A list of contact list ids to dial with this campaign. Multiple contact lists can be input here. **Leave this blank to use this campaign with the outbound dialer API.**

Items:
- contact_list_id (required)
  
  string — The campaign contact list's ID.
- contact_list_name (required)
  
  string — The campaign contact list's name.
- contact_list_description
  
  string — The campaign contact list's description.
- contacts_count
  
  string — Number of contacts in the contact list.
campaign_do_not_contact_list_ids

array — Contacts will be not dialed.

Items:
- contact_list_id (required)
  
  string — The campaign contact list's ID.
- contact_list_name (required)
  
  string — The campaign contact list's name.
- contact_list_description
  
  string — The campaign contact list's description.
- contacts_count
  
  string — Number of contacts in the contact list.
closure_set_id

string — The Contact Center closure hours ID. [Create closure hours API.](/docs/contact-center/apis/#operation/closuresSetCreate)
contact_order

integer — Contact order.
contact_phone_order

string — Contact phone order.
contact_timezone_source

string, possible values: "none", "timezone", "area_code", default: "none" — Determine the source used to establish the contact's timezone for deciding appropriate calling hours, like 9 AM to 5 PM. **Valid values** `none` - Disables timezone-based calling restrictions; calls can be made at any time. `timezone` - Uses the contact's explicit timezone attribute to determine calling eligibility. `area_code` - Derives the timezone based on the area code of the contact's highest priority phone number according to the dial order.
dial_sequence

string — Dial sequence mode.
dialing_method

string, possible values: "progressive", "preview", "agentless" — Determine how contacts in this campaign will be dialed.\nProgressive - engagement details are displayed to the agent **after** they are connected with the consumer.\nPreview - engagement details are displayed to the agent **before** they are connected with the consumer.\nAgentless - automated dialing without agent involvement.
dialing_method_settings

object — One of either progressive, pPreview, or agentless dialing.
enable_always_running

boolean, default: false — Whether always running is enabled.
enable_closure_hour

boolean — Toggle closure hours on or off. Outbound calls are not started during closure hours.
enable_diagnostics

boolean — Whether diagnostics is enabled.
enable_max_ring_time

boolean — Enabled if `max_ring_time` is set.
exclusion_logic

string — Exclusion logic for contact lists.
max_attempts_per_contact

integer — Maximum attempts per contact.
max_ring_time

integer — Use with `max_ring_time_enabled`. A call is considered unanswered after the maximum ring time has elapsed. Maximum ring time must be between 15 and 120 seconds.
other_attempt_period

integer — Other attempt period. Could be in seconds, minutes, hours, and days.
outbound_campaign_description

string — The campaign's description.
outbound_campaign_id

string — The outbound campaign ID.
outbound_campaign_name

string — The campaign's name. Names are a unique key among all outbound campaigns.
outbound_campaign_priority

integer, default: 5 — The campaign priority.
outbound_campaign_status

string, possible values: "draft", "ready", "running", "paused", "completed", "not_running" — The campaign's status.
phone_number_id

string — The reference ID for the Contact Center phone number. This number is displayed to consumers for outbound calls.
queue_id

string — The queue ID. 1 - Only voice queues configured for outbound engagements with at least one user from Zoom Contact Center Premium or Elite packages are available for selection. 2 - Queue distribution cannot be configured to Simultaneous or Do Not Distribute.
queue_name

string — The Contact Center queue name.
retry_period

integer — Retry period. Could be in seconds, minutes, hours, and days.
retry_period_unit

string, possible values: "seconds", "minutes", "hours", "days" — Unit for retry period.
second_attempt_period

integer — Second attempt period. Could be in seconds, minutes, hours, and days.
third_attempt_period

integer — Third attempt period. Could be in seconds, minutes, hours, and days.

Example:

{
  "outbound_campaign_id": "TY_XsJuWR9ehXrsf1DSIAQ",
  "outbound_campaign_name": "My outbound campaign",
  "outbound_campaign_description": "My outbound campaign description",
  "queue_id": "TY_XsJuWR9ehXrsf1DSIAQ",
  "queue_name": "Voice - Customer Support",
  "phone_number_id": "XfTPrZjyR5W6QgNARdtGlw",
  "assign_type": "queue",
  "outbound_campaign_status": "draft",
  "dialing_method": "progressive",
  "dialing_method_settings": {
    "enable_amd": true,
    "amd_settings": {
      "greeting_asset_id": "zNWo_1M5ScCuKnBb2Z-sfw",
      "answering_machine_asset_id": "z8XtiytyQammquBRlVPiWw"
    },
    "enable_abandonment_timeout": false,
    "abandonment_timeout": 5,
    "abandonment_message_asset_id": "z8XtiytyQammquBRlVPiWw"
  },
  "outbound_campaign_priority": 5,
  "campaign_contact_list": [
    {
      "contact_list_id": "MN2Dtcb2T-yT5CU3clN-AA",
      "contact_list_name": "Contact List",
      "contact_list_description": "Description",
      "contacts_count": "1"
    }
  ],
  "campaign_do_not_contact_list_ids": [
    {
      "contact_list_id": "Lp7Wzxf4Q-pA9RX6bhO-XX",
      "contact_list_name": "Do-not-contact list",
      "contact_list_description": "Description",
      "contacts_count": "1"
    }
  ],
  "exclusion_logic": "AND",
  "max_attempts_per_contact": 3,
  "attempts_use_same_period": false,
  "second_attempt_period": 30,
  "third_attempt_period": 60,
  "other_attempt_period": 120,
  "retry_period": 60,
  "retry_period_unit": "hours",
  "dial_sequence": "LIST_DIAL",
  "max_ring_time": 15,
  "enable_max_ring_time": true,
  "business_hour_source": "queue",
  "business_hour_id": "h7XtiytFTammquBRlTRiWZ",
  "enable_closure_hour": true,
  "closure_set_id": "y9XtiytyQammquBRlTPiWw",
  "contact_timezone_source": "area_code",
  "contact_phone_order": "ascending",
  "enable_always_running": false,
  "contact_order": 1,
  "enable_diagnostics": false
}

Status: 400 HTTP Status Code: `400` Bad Request Error Code: `5008` Campaign phone number not found. Please check that the phone number exists in Contact Center Preferences and that the ID is correct. Error Code: `5009` Campaign greeting asset not found. Please check that the asset exists in Contact Center Asset Library and that the ID is correct. Error Code: `5010` Campaign AMD asset not found. Please check that the asset exists in Contact Center Asset Library and that the ID is correct. Error Code: `300` Validation failed. Error Code: `302` Invalid enum value. Error Code: `5011` Campaign Business Hour not found. Please check that the Operating Hour exists in Contact Center Preferences and that the ID is correct. Error Code: `5012` Campaign Closure Hour Set not found. Please check that the Operating Hour exists in Contact Center Preferences and that the ID is correct. Error Code: `5016` The maximum number of contacts assigned to a campaign cannot exceed 100000.

Status: 429 HTTP Status Code: `429` Too Many Requests. For more information, see [rate limits](/docs/api/rate-limits/).

Get an outbound campaign

Method: GET
Path: /contact_center/outbound_campaign/campaigns/{campaignId}
Tags: Campaigns

Get a Contact Center outbound campaign.

Scopes: contact_center_outbound_campaign:read:admin

Granular Scopes: contact_center:read:outbound_campaign:admin

Rate Limit Label: LIGHT

Responses

Status: 200 Outbound campaign object.

Content-Type: application/json

assign_type

string, possible values: "queue", "default", "customer", default: "queue" — Caller ID assignment type.
attempts_use_same_period

boolean, default: false — Whether attempts use the same period.
business_hour_id

string — The Contact Center business hours ID. The campaign will only dial during these hours. [Create business hours API.](/docs/contact-center/apis/#operation/businessHourCreate)
business_hour_source

string, possible values: "queue", "campaign", default: "queue" — The Contact Center business hour source. Select `queue` to use the outbound queue's business hours, and `campaign` to set custom hours. Defaults to `queue`.
campaign_contact_list

array — Contacts will be dialed in alphabetical order. If a contact has more than one phone number, the numbers will be dialed in the order they are listed until a call is connected or all numbers have been tried. A list of contact list ids to dial with this campaign. Multiple contact lists can be input here. **Leave this blank to use this campaign with the outbound dialer API.**

Items:
- contact_list_id (required)
  
  string — The campaign contact list's ID.
- contact_list_name (required)
  
  string — The campaign contact list's name.
- contact_list_description
  
  string — The campaign contact list's description.
- contacts_count
  
  string — Number of contacts in the contact list.
campaign_do_not_contact_list

array — Do not contact lists for the campaign.

Items:
- contact_list_description
  
  string — The do not contact list's description.
- contact_list_id
  
  string — The do not contact list's ID.
- contact_list_name
  
  string — The do not contact list's name.
- contacts_count
  
  string — Number of contacts in the do not contact list.
closure_set_id

string — The Contact Center closure hours ID. [Create closure hours API.](/docs/contact-center/apis/#operation/closuresSetCreate)
contact_order

integer — The order for processing contacts.
contact_phone_order

string — Contact phone order.
contact_timezone_source

string, possible values: "none", "timezone", "area_code", default: "none" — Determines the source used to establish the contact's timezone for deciding appropriate calling hours, such as "9 AM to 5 PM". **Valid values** `none` - Disables timezone-based calling restrictions. Calls can be made at any time. `timezone` - Uses the contact's explicit timezone attribute to determine calling eligibility. `area_code` - Derives the timezone based on the area code of the contact's highest priority phone number according to the dial order.
dial_sequence

string, possible values: "list_dial", "contact_dial", "contact_with_lock", default: "list_dial" — Controls the dialing sequence and failure-handling behavior. - `LIST_DIAL (Current Mode)` - Upon a dial failure, the system immediately abandons the current contact and tries the next contact in the list or queue. - `CONTACT_DIAL (New Mode)` - Upon a dial failure for a phone number, the system tries the next available phone number for the*same contact before moving to the next contact. - `CONTACT_WITH_LOCK` - Functions as `CONTACT_DIAL`, but also applies an exclusive agent lock to the contact upon retrieval to prevent simultaneous access by other agents.
dialing_method

string, possible values: "progressive", "preview", "agentless" — Determine how contacts in this campaign will be dialed.\nProgressive - display engagement details to the agent **after** they are connected with the consumer.\nPreview - display engagement details to the agent **before** they are connected with the consumer.\nAgentless - automated dialing without agent involvement.
dialing_method_settings

object — Settings for the selected dialing method.
enable_always_running

boolean, default: false — Enable always running.
enable_closure_hour

boolean, default: false — Toggle closure hours on or off. Outbound calls are not started during closure hours.
enable_diagnostics

boolean, default: false — Enable diagnostics.
enable_max_ring_time

boolean, default: true — Disconnect unanswered calls after a set period of time has elapsed.
exclusion_logic

string, possible values: "and", "or", default: "and" — Exclusion logic for contact lists.
max_attempts_per_contact

integer — Maximum attempts per contact.
max_ring_time

integer, default: 60 — Use with `max_ring_time_enabled`. A call is considered unanswered after the maximum ring time has elapsed. Maximum ring time must be between 15 and 120 seconds.
other_attempt_period

integer — Other attempt period. Could be in seconds, minutes, hours, and days.
outbound_campaign_description

string — The campaign's description.
outbound_campaign_id

string — The outbound campaign ID.
outbound_campaign_name

string — The campaign's name. Names are a unique key among all outbound campaigns.
outbound_campaign_priority

integer, default: 5 — The campaign priority.
outbound_campaign_status

string, possible values: "draft", "ready", "running", "paused", "completed", "not_running" — The campaign's status.
phone_number_id

string — The reference ID for the Contact Center phone number. This number is displayed to consumers for outbound calls.
queue_id

string — 1 - Only voice queues configured for outbound engagements with at least one user from Zoom Contact Center Premium or Elite packages are available for selection.\n2 - Queue distribution cannot be configured to Simultaneous or Do Not Distribute.
queue_name

string — The queue's name.
retry_period

integer — Retry period. Could be in seconds, minutes, hours, and days.
retry_period_unit

string, possible values: "seconds", "minutes", "hours", "days", default: "hours" — Unit for the retry period.
second_attempt_period

integer, default: 30 — Second attempt period. Could be in seconds, minutes, hours, and days.
third_attempt_period

integer, default: 60 — Third attempt period. Could be in seconds, minutes, hours, and days.

Example:

{
  "outbound_campaign_id": "TY_XsJuWR9ehXrsf1DSIAQ",
  "outbound_campaign_name": "My outbound campaign",
  "outbound_campaign_description": "My outbound campaign description",
  "queue_id": "TY_XsJuWR9ehXrsf1DSIAQ",
  "queue_name": "My queue name",
  "phone_number_id": "XfTPrZjyR5W6QgNARdtGlw",
  "assign_type": "queue",
  "outbound_campaign_status": "draft",
  "dialing_method": "progressive",
  "dialing_method_settings": {
    "enable_amd": false,
    "amd_settings": {
      "greeting_asset_id": "zNWo_1M5ScCuKnBb2Z-sfw",
      "answering_machine_asset_id": "z8XtiytyQammquBRlVPiWw"
    },
    "enable_abandonment_timeout": false,
    "abandonment_timeout": 5,
    "abandonment_message_asset_id": "z8XtiytyQammquBRlVPiWw"
  },
  "outbound_campaign_priority": 5,
  "campaign_contact_list": [
    {
      "contact_list_id": "MN2Dtcb2T-yT5CU3clN-AA",
      "contact_list_name": "Contact List",
      "contact_list_description": "Description",
      "contacts_count": "1"
    }
  ],
  "campaign_do_not_contact_list": [
    {
      "contact_list_id": "Lp7Wzxf4Q-pA9RX6bhO-XX",
      "contact_list_name": "DNC List",
      "contact_list_description": "DNC Description",
      "contacts_count": "1"
    }
  ],
  "exclusion_logic": "and",
  "max_attempts_per_contact": 3,
  "attempts_use_same_period": false,
  "second_attempt_period": 30,
  "third_attempt_period": 60,
  "other_attempt_period": 120,
  "retry_period": 60,
  "retry_period_unit": "hours",
  "dial_sequence": "list_dial",
  "enable_max_ring_time": true,
  "max_ring_time": 60,
  "contact_phone_order": "ascending",
  "enable_always_running": false,
  "contact_order": 1,
  "enable_diagnostics": false,
  "business_hour_source": "queue",
  "business_hour_id": "h7XtiytFTammquBRlTRiWZ",
  "enable_closure_hour": false,
  "closure_set_id": "y9XtiytyQammquBRlTPiWw",
  "contact_timezone_source": "area_code"
}

Status: 400 HTTP Status Code: `400` Bad Request

Status: 401 HTTP Status Code: `401` Unauthorized

Status: 403 HTTP Status Code: `403` Forbidden

Status: 404 HTTP Status Code: `404` Not Found Error Code: `5005` Campaign not found.

Status: 429 HTTP Status Code: `429` Too Many Requests. For more information, see [rate limits](https://developers.zoom.us/docs/api/rate-limits/).

Delete an outbound campaign

Method: DELETE
Path: /contact_center/outbound_campaign/campaigns/{campaignId}
Tags: Campaigns

Delete a Contact Center's outbound campaign.

Scopes: contact_center_outbound_campaign:delete:admin

Granular Scopes: contact_center:delete:outbound_campaign:admin

Rate Limit Label: LIGHT

Responses

Status: 204 HTTP Status Code: `204` Outbound campaign is removed.

Status: 404 HTTP Status Code: `404` Not Found Error Code: `5005` Campaign not found.

Status: 429 HTTP Status Code: `429` Too Many Requests. For more information, see [rate limits](/docs/api/rate-limits/).

Update an outbound campaign

Method: PATCH
Path: /contact_center/outbound_campaign/campaigns/{campaignId}
Tags: Campaigns

Update an outbound Contact Center campaign.

Scopes: contact_center_outbound_campaign:update:admin

Granular Scopes: contact_center:update:outbound_campaign:admin

Rate Limit Label: LIGHT

Request Body

Content-Type: application/json

abandonment_message_asset_id

string — Use with `enable_abandonment_timeout`. The Contact Center Asset Library asset to play when a call is abandoned due to agent unavailability.
abandonment_timeout

integer, default: 5 — Use with `enable_abandonment_timeout`. If `enable_abandonment_timeout` is `false`, this is set to null. A call connected to a consumer will be abandoned if an agent does not connect before the abandonment timeout elapses. Abandonment timeout must be between 2 and 30 seconds.
agentless_amd_off_action

string, possible values: "use_flow", "hang_up", "play_media" — Action when agentless AMD is off.
agentless_amd_off_resource_id

string — Resource ID when agentless AMD is off.
allow_retry_preview_dialer

boolean, default: false — Allow retry for preview dialer.
assign_type

string, possible values: "queue", "default", "customer", default: "queue" — Caller ID assignment type.
attempts_use_same_period

boolean — Whether attempts use the same period.
business_hour_id

string — The Contact Center business hours ID. The campaign will only dial during these hours. [Create business hours API.](/docs/contact-center/apis/#operation/businessHourCreate)
business_hour_source

string, possible values: "queue", "campaign", default: "queue" — The Contact Center business hour source. Select `queue` to use the outbound queue's business hours, and `campaign` to set custom hours. Defaults to `queue`.
campaign_do_not_contact_list_ids

array — Contacts will not be dialed in.

Items:

string — Do Not Contact list IDs.
closure_set_id

string — The Contact Center closure hours ID. [Create closure hours API.](/docs/contact-center/apis/#operation/closuresSetCreate)
contact_order

integer — The order for contacts.
contact_phone_order

string — The order for contact phone numbers.
contact_timezone_source

string, possible values: "none", "timezone", "area_code", default: "none" — Determines the source used to establish the contact's timezone for deciding appropriate calling hours (9 AM to 5 PM). **Valid values** `none` - Disables timezone-based calling restrictions. Calls can be made at any time. `timezone` - Uses the contact's explicit timezone attribute to determine calling eligibility. `area_code` - Derives the timezone based on the area code of the contact's highest priority phone number according to the dial order.
dial_sequence

string, possible values: "list_dial", "contact_dial", "contact_with_lock" — Control the dialing sequence and failure-handling behavior. - `LIST_DIAL` (Current Mode) - Upon a dial failure, the system immediately abandons the current contact and tries the next contact in the list or queue. - `CONTACT_DIAL` (New Mode)** - Upon a dial failure for a phone number, the system tries the next available phone number for the same contact before moving to the next contact. - `CONTACT_WITH_LOCK` - Functions as `CONTACT_DIAL`, but also applies an exclusive agent lock to the contact upon retrieval to prevent simultaneous access by other agents.
enable_abandonment_timeout

boolean, default: false — Abandon answered calls if an agent does not connect within a set period of time.
enable_always_running

boolean, default: false — Enable always running.
enable_closure_hour

boolean, default: false — Toggle closure hours on or off. Outbound calls are not started during closure hours.
enable_diagnostics

boolean, default: false — Enable diagnostics.
enable_max_ring_time

boolean — Disconnect unanswered calls after a set period of time has elapsed.
enable_skip

boolean, default: true — Preview dialing method only. Allow agent to skip outbound engagements.
exclusion_logic

string, possible values: "and", "or", default: "and" — Exclusion logic for contact lists. When choose and as strategy, contacts with additional phone numbers will still be included in the campaign. When choose or strategy, the contacts will be excluded from the campaign if one or more phone number matches the DNC list.
max_attempts_per_contact

integer — Maximum number of attempts per contact.
max_concurrent_calls

integer — The maximum concurrent calls for the agentless dialer.
max_ring_time

integer — Use with `max_ring_time_enabled`. A call is considered unanswered after the maximum ring time has elapsed. Maximum ring time must be between 15 and 120 seconds.
max_skips

integer, default: 1 — Preview dialing method only. Configure skip reasons under **Contact Center Preferences**.
new_flow_id

string — The agentless dialer's new flow ID.
old_flow_id

string — The agentless dialer's old flow ID.
other_attempt_period

integer — Other attempt period. Could be in seconds, minutes, hours, and days.
outbound_campaign_description

string — The campaign's description.
outbound_campaign_name

string — The campaign's name. Names are a unique key among all outbound campaigns.
outbound_campaign_priority

integer, default: 5 — The campaign priority.
phone_number_id

string — The reference ID for the Contact Center phone number. This number is displayed to consumers for outbound calls.
retry_period

integer — Retry period. Could be in seconds, minutes, hours, and days.
retry_period_unit

string, possible values: "seconds", "minutes", "hours", "days", default: "hours" — Unit for retry period.
second_attempt_period

integer, default: 30 — Second attempt period. Could be in seconds, minutes, hours, and days.
third_attempt_period

integer, default: 60 — Third attempt period. Could be in seconds, minutes, hours, and days.

Example:

{
  "outbound_campaign_name": "My outbound campaign name",
  "outbound_campaign_description": "My outbound campaign description",
  "phone_number_id": "XfTPrZjyR5W6QgNARdtGlw",
  "assign_type": "queue",
  "outbound_campaign_priority": 5,
  "enable_max_ring_time": true,
  "max_ring_time": 15,
  "campaign_do_not_contact_list_ids": [
    "Lp7Wzxf4Q-pA9RX6bhO-XX"
  ],
  "exclusion_logic": "and",
  "max_attempts_per_contact": 3,
  "attempts_use_same_period": true,
  "second_attempt_period": 30,
  "third_attempt_period": 60,
  "other_attempt_period": 120,
  "retry_period": 60,
  "retry_period_unit": "hours",
  "dial_sequence": "list_dial",
  "enable_abandonment_timeout": false,
  "abandonment_timeout": 5,
  "abandonment_message_asset_id": "z8XtiytyQammquBRlVPiWw",
  "enable_skip": true,
  "max_skips": 1,
  "business_hour_source": "campaign",
  "business_hour_id": "rYyRJRjGQhi8gFNP9G7pSw",
  "enable_closure_hour": false,
  "closure_set_id": "IlSdt6YUQES8nkOqSehKJg",
  "contact_timezone_source": "area_code",
  "contact_phone_order": "mobile,home,work",
  "enable_always_running": false,
  "contact_order": 1,
  "enable_diagnostics": false,
  "allow_retry_preview_dialer": false,
  "max_concurrent_calls": 5,
  "old_flow_id": "_2npVp3juQWO2g9pt2rqSKg",
  "new_flow_id": "_3npVp3juQWO2g9pt2rqSKg",
  "agentless_amd_off_action": "use_flow",
  "agentless_amd_off_resource_id": "z8XtiytyQammquBRlVPiWw"
}

Responses

Status: 204 HTTP Status Code: `204` Outbound Campaign is updated.

Status: 400 HTTP Status Code: `400` Bad Request Error Code: `300` Validation failed. Error Code: `302` Invalid enum value. Error Code: `5008` Campaign phone number not found. Please check that the phone number exists in Contact Center Preferences and that the ID is correct. Error Code: `5011` Campaign business hour not found. Please check that the operating hours exist in Contact Center Preferences and that the ID is correct. Error Code: `5012` Campaign closure hour set not found. Please check that the operating hours exist in Contact Center Preferences and that the ID is correct.

Status: 404 HTTP Status Code: `404` Not Found Error Code: `5005` Campaign is not found.

Status: 429 HTTP Status Code: `429` Too Many Requests. For more information, see [rate limits](/docs/api/rate-limits/).

Update an outbound campaign status

Method: PATCH
Path: /contact_center/outbound_campaign/campaigns/{campaignId}/status
Tags: Campaigns

Update an outbound campaign status.

Scopes: contact_center_outbound_campaign:write:admin

Granular Scopes: contact_center:update:outbound_campaign:admin

Rate Limit Label: LIGHT

Request Body

Content-Type: application/json

status

string, possible values: "Draft", "Ready", "Paused", "Running", default: "Draft" — An outbound campaign status.

Example:

{
  "status": "Draft"
}

Responses

Status: 204 HTTP Status Code: `204` Outbound Campaign Status is updated.

Status: 400 HTTP Status Code: `400` Bad Request Error Code: `302` Invalid enum value. Error Code: `300` Validation failed.

Status: 429 HTTP Status Code: `429` Too Many Requests. For more information, see [rate limits](https://developers.zoom.us/docs/api/rate-limits/).

List campaign contact lists' custom fields

Method: GET
Path: /contact_center/outbound_campaign/contact_list_custom_fields
Tags: Campaigns

Retrieve all custom fields defined for campaign contact lists.

Scopes: contact_center_outbound_campaign_contactlist:read:admin

Granular Scopes: contact_center:read:outbound_campaign_contactlist:admin

Rate Limit Label: MEDIUM

Responses

Status: 200 The campaign contact list's custom fields list is returned.

Content-Type: application/json

custom_fields

array — Information about custom fields in campaign contact lists.

Items:
- custom_field_id (required)
  
  string — The custom field's ID.
- custom_field_name (required)
  
  string — The custom field's name.
- data_type (required)
  
  string, possible values: "string", "number", "boolean", "email", "phone", "percent", "currency", "date_time", "pick_list" — The custom field's data type. - `string` - Any text value. - `number` - Numeric value. Supports integers or decimals like `123.45`. Valid range is -9999999999 to 9999999999. - `percent` - Numeric value between 0 and 100. May include decimals. - `currency` - Decimal value ≥ 0 with up to two decimal places. When `data_type` is `pick_list`, `pick_list_values` specifies the allowed options.
- allow_third_party_access
  
  boolean — Whether the custom field can be accessed by third party apps.
- contact_list_ids
  
  array — The contact list IDs associated with the custom field.
  
  Items:
  
  string — The contact list's ID.
- default_value
  
  string — The custom field's default value.
- pick_list_values
  
  array — The picklist's supported values. This is only valid when `data_type` is `pick_list`.
  
  Items:
  
  string
- show_in_inbound_notification
  
  boolean — Whether the custom field is shown on the inbound engagement notification in the Zoom client.
- show_in_profile_tab
  
  boolean — Whether the custom field is shown on the profile tab in the Zoom client.
- show_in_transferred_calls
  
  boolean — Whether the custom field is shown in calls transferred to Zoom Phone.
- use_as_external_url_parameter
  
  boolean — Whether the `custom_field_name` is used in defining external URLs launched for each engagement. When set to `true`, the `custom_field_name` should not contain any spaces.
- use_as_routing_profile_parameter
  
  boolean — Whether the custom field is used in the consumer routing profile.
next_page_token

string — Use the next page token to paginate through large result sets. A next page token is returned whenever the set of available results exceeds the current page size. This token's expiration period is 15 minutes.
page_size

integer, default: 30 — The number of records returned in a single API call.
total_records

integer — The total number of all records available across pages.

Example:

{
  "next_page_token": "R4aF9Oj0fVM2hhezJTEmSKaBSkfesDwGy42",
  "page_size": 30,
  "total_records": 10,
  "custom_fields": [
    {
      "custom_field_id": "7381d210 Contact Method",
      "custom_field_name": "Preferred Contact Method",
      "data_type": "string",
      "default_value": "phone",
      "pick_list_values": [
        "phone"
      ],
      "contact_list_ids": [
        "suk0leXNTye2JjIm6v0yCQ"
      ],
      "use_as_routing_profile_parameter": true,
      "use_as_external_url_parameter": false,
      "show_in_transferred_calls": true,
      "allow_third_party_access": true,
      "show_in_inbound_notification": true,
      "show_in_profile_tab": false
    }
  ]
}

Status: 400 HTTP Status Code: `400` Bad Request

Status: 401 HTTP Status Code: `401` Unauthorized Error Code: `124` Invalid access token. Error Code: `124` Access token has expired. Error Code: `1002` The user associated with this access token was not found or is invalid.

Status: 403 HTTP Status Code: `403` Forbidden Error Code: `1021` User account is deactivated. Error Code: `1022` User does not have a Contact Center license. Error Code: `9001` The Contact Center user associated with this bearer token is missing privileges on their role required to operate this request.

Status: 429 HTTP Status Code: `429` Too Many Requests. For more information, see [rate limits](/docs/api/rate-limits/). Error Code: `4001` You have reached the maximum per-second rate limit for this API. Try again later.

Create a campaign contact list's custom field

Method: POST
Path: /contact_center/outbound_campaign/contact_list_custom_fields
Tags: Campaigns

Create a custom field for a campaign contact list.

Scopes: contact_center_outbound_campaign_contactlist:write:admin

Granular Scopes: contact_center:write:outbound_campaign_contactlist:admin

Rate Limit Label: LIGHT

Request Body

Content-Type: application/json

custom_field_name (required)

string — The custom field's name. When `use_as_external_url_parameter` is set to `true`, `custom_field_name` must not contain spaces.
data_type (required)

string, possible values: "string", "number", "boolean", "email", "phone", "percent", "currency", "date_time", "pick_list" — The custom field's data type. - `string` - Any text value. - `number` - Numeric value. Supports integers or decimals like 123.45. Valid range is -9999999999 to 9999999999. - `percent` - Numeric value between 0 and 100. May include decimals. - `currency` - Decimal value ≥ 0 with up to two decimal places. When `data_type` is `pick_list`, `pick_list_values` specifies the allowed options.
allow_third_party_access

boolean — Whether the custom field can be accessed by third party apps.
contact_list_ids

array — The IDs of contact lists associated with the custom field. Retrieve available contact list IDs using the [**List campaign contact lists**](/docs/api/contact-center/#tag/campaigns/get/contact_center/outbound_campaign/contact_lists) API.

Items:

string — The contact list's ID.
default_value

string — The custom field's default value. When `data_type` is `pick_list`, the default value must be one of the `pick_list_values`.
pick_list_values

array — The list of supported values for the picklist. This field is required when `data_type` is `pick_list`.

Items:

string
show_in_inbound_notification

boolean — Whether the custom field is shown on the inbound engagement notification in the Zoom client.
show_in_profile_tab

boolean — Whether the custom field is shown on the profile tab in the Zoom client.
show_in_transferred_calls

boolean — Whether the custom field is shown in calls transferred to Zoom Phone.
use_as_external_url_parameter

boolean — Whether the `custom_field_name` is used in defining external URLs launched for each engagement. When set to t`rue`, the `custom_field_name` should not contain any spaces.
use_as_routing_profile_parameter

boolean — Whether the custom field is used in the consumer routing profile.

Example:

{
  "custom_field_name": "contact_field_demo",
  "data_type": "string",
  "default_value": "option_a",
  "pick_list_values": [
    "option_a"
  ],
  "contact_list_ids": [
    "suk0leXNTye2JjIm6v0yCQ"
  ],
  "use_as_routing_profile_parameter": true,
  "use_as_external_url_parameter": false,
  "show_in_transferred_calls": true,
  "allow_third_party_access": true,
  "show_in_inbound_notification": true,
  "show_in_profile_tab": false
}

Responses

Status: 201 Custom field created.

Content-Type: application/json

custom_field_id (required)

string — The custom field's ID.
custom_field_name (required)

string — The custom field's name. When `use_as_external_url_parameter` is set to `true`, `custom_field_name` must not contain spaces.
data_type (required)

string, possible values: "string", "number", "boolean", "email", "phone", "percent", "currency", "date_time", "pick_list" — The custom field's data type. - `string` - Any text value. - `number` - Numeric value. Supports integers or decimals like 123.45. Valid range is -9999999999 to 9999999999. - `percent` - Numeric value between 0 and 100. May include decimals. - `currency` - Decimal value ≥ 0 with up to two decimal places. When `data_type` is `pick_list`, `pick_list_values` specifies the allowed options.
allow_third_party_access

boolean — Whether the custom field can be accessed by third party apps.
contact_list_ids

array — The IDs of contact lists associated with the custom field. Retrieve available contact list IDs using the [**List campaign contact lists**](/docs/api/contact-center/#tag/campaigns/get/contact_center/outbound_campaign/contact_lists) API.

Items:

string — The contact list's ID.
default_value

string — The custom field's default value. When `data_type` is `pick_list`, the default value must be one of the `pick_list_values`.
pick_list_values

array — The list of supported values for the picklist. This field is required when `data_type` is `pick_list`.

Items:

string
show_in_inbound_notification

boolean — Whether the custom field is shown on the inbound engagement notification in the Zoom client.
show_in_profile_tab

boolean — Whether the custom field is shown on the profile tab in the Zoom client.
show_in_transferred_calls

boolean — Whether the custom field is shown in calls transferred to Zoom Phone.
use_as_external_url_parameter

boolean — Whether the `custom_field_name` is used in defining external URLs launched for each engagement. When set to true, the `custom_field_name` should not contain any spaces.
use_as_routing_profile_parameter

boolean — Whether the custom field is used in the consumer routing profile.

Example:

{
  "custom_field_id": "7381d210-360e-4fbd-86e4-33eb7109b084",
  "custom_field_name": "contact_field_demo",
  "data_type": "string",
  "default_value": "option_a",
  "pick_list_values": [
    "option_a"
  ],
  "contact_list_ids": [
    "suk0leXNTye2JjIm6v0yCQ"
  ],
  "use_as_routing_profile_parameter": true,
  "use_as_external_url_parameter": false,
  "show_in_transferred_calls": true,
  "allow_third_party_access": true,
  "show_in_inbound_notification": true,
  "show_in_profile_tab": false
}

Status: 400 HTTP Status Code: `400` Bad Request Error Code: `300` Invalid field. Error Code: `2107` A custom field with this name already exists: {0}. Error Code: `2108` The data type provided for the custom field is not supported. Error Code: `2109` The default value format does not match the data type. Error Code: `2110` You've exceeded the maximum limit of 4096 custom fields. Error Code: `2111` Custom field name cannot contain spaces when `use_as_external_url_parameter` is `true`. Field name cannot contain spaces when `use_as_external_url_parameter` is `true`.

Status: 401 HTTP Status Code: `401` Unauthorized

Status: 403 HTTP Status Code: `403` Forbidden

Status: 404 HTTP Status Code: `404` Not Found Error Code: `5001` Contact list not found.

Status: 429 HTTP Status Code: `429` Too Many Requests. For more information, see [rate limits](/docs/api/rate-limits/).

Get a campaign contact list's custom field

Method: GET
Path: /contact_center/outbound_campaign/contact_list_custom_fields/{customFieldId}
Tags: Campaigns

Retrieve information about a campaign contact list custom field.

Scopes: contact_center_outbound_campaign_contactlist:read:admin

Granular Scopes: contact_center:read:outbound_campaign_contactlist:admin

Rate Limit Label: LIGHT

Responses

Status: 200 The campaign contact list's custom field is returned.

Content-Type: application/json

custom_field_id (required)

string — The custom field's ID.
custom_field_name (required)

string — The custom field's name.
data_type (required)

string, possible values: "string", "number", "boolean", "email", "phone", "percent", "currency", "date_time", "pick_list" — The custom field's data type. - `string` - Any text value. - `number` - Numeric value. Supports integers or decimals, like `123.45`. Valid range is -9999999999 to 9999999999. - `percent` - Numeric value between 0 and 100. May include decimals. - `currency` - Decimal value ≥ 0 with up to two decimal places. When `data_type` is `pick_list`, `pick_list_values` specifies the allowed options.
allow_third_party_access

boolean — Whether the custom field can be accessed by third party apps.
contact_list_ids

array — The IDs of contact lists associated with the custom field.

Items:

string — The contact list's ID.
default_value

string — The custom field's default value.
pick_list_values

array — The list of supported values for the picklist. This is only valid when `data_type` is `pick_list`.

Items:

string
show_in_inbound_notification

boolean — Whether the custom field is shown on the inbound engagement notification in the Zoom client.
show_in_profile_tab

boolean — Whether the custom field is shown on the profile tab in the Zoom client.
show_in_transferred_calls

boolean — Whether the custom field is shown in calls transferred to Zoom Phone.
use_as_external_url_parameter

boolean — Whether the `custom_field_name` is used in defining external URLs launched for each engagement. When set to `true`, the `custom_field_name` should not contain any spaces.
use_as_routing_profile_parameter

boolean — Whether the custom field is used in the consumer routing profile.

Example:

{
  "custom_field_id": "7381d210-360e-4fbd-86e4-33eb7109b084",
  "custom_field_name": "Preferred Contact Method",
  "data_type": "string",
  "default_value": "phone",
  "pick_list_values": [
    "phone"
  ],
  "contact_list_ids": [
    "suk0leXNTye2JjIm6v0yCQ"
  ],
  "use_as_routing_profile_parameter": true,
  "use_as_external_url_parameter": false,
  "show_in_transferred_calls": true,
  "allow_third_party_access": true,
  "show_in_inbound_notification": true,
  "show_in_profile_tab": false
}

Status: 400 HTTP Status Code: `400` Bad Request

Status: 401 HTTP Status Code: `401` Unauthorized

Status: 403 HTTP Status Code: `403` Forbidden

Status: 404 HTTP Status Code: `404` Not Found Error Code: `2112` Custom field does not exist: {0}.

Status: 429 HTTP Status Code: `429` Too Many Requests. For more information, see [rate limits](/docs/api/rate-limits/).

Delete a campaign contact list's custom field

Method: DELETE
Path: /contact_center/outbound_campaign/contact_list_custom_fields/{customFieldId}
Tags: Campaigns

Delete a custom field in a campaign contact list.

Scopes: contact_center_outbound_campaign_contactlist:write:admin

Granular Scopes: contact_center:delete:outbound_campaign_contactlist:admin

Rate Limit Label: LIGHT

Responses

Status: 204 Custom field deleted.

Status: 400 HTTP Status Code: `400` Bad Request

Status: 401 HTTP Status Code: `401` Unauthorized

Status: 403 HTTP Status Code: `403` Forbidden

Status: 404 HTTP Status Code: `404` Not Found Error Code: `2112` Custom field does not exist: {0}.

Status: 429 HTTP Status Code: `429` Too Many Requests. For more information, see [rate limits](/docs/api/rate-limits/).

Update a campaign contact list's custom field

Method: PATCH
Path: /contact_center/outbound_campaign/contact_list_custom_fields/{customFieldId}
Tags: Campaigns

Update details of a campaign contact list's custom field.

Scopes: contact_center_outbound_campaign_contactlist:write:admin

Granular Scopes: contact_center:update:outbound_campaign_contactlist:admin

Rate Limit Label: LIGHT

Request Body

Content-Type: application/json

allow_third_party_access

boolean — Whether the custom field can be accessed by third party apps.
contact_list_ids

array — The list of contact list IDs that should be associated with the custom field. When updating this array, the operation performs a **full replacement** of the existing list rather than an additive merge. This means that any previously associated contact list IDs not included in the update request will be removed from the association. If a contact list that is currently associated with this custom field is deleted or becomes unavailable, the corresponding value in that field becomes invalid and should be handled appropriately by the client application. Ensure that updated contact list IDs reference valid and existing contact lists to avoid invalid references or data integrity issues.

Items:

string — The unique identifier of a contact list associated with the custom field.
custom_field_name

string — The custom field's name.
data_type

string, possible values: "string", "number", "boolean", "email", "phone", "percent", "currency", "date_time", "pick_list" — The custom field's data type. - `string`- Any text value. - `number` - Numeric value. Supports integers or decimals, like `123.45`. Valid range is -9999999999 to 9999999999. - `percent` - Numeric value between 0 and 100. May include decimals. - `currency` - Decimal value ≥ 0 with up to two decimal places. When `data_type` is `pick_list`, `pick_list_values` specifies the allowed options. **Note** Modifying the `data_type` will invalidate all previously configured related variables.
default_value

string — The custom field's default value.
pick_list_values

array — The list of the picklist's supported values. This is only valid when `data_type` is `pick_list`. When updating this array, the update operation performs a full replacement of the existing list rather than a merge. Removing values from the list does not affect any existing contacts that already use those values. They remain valid for those contacts. Values currently in use can still be removed from the picklist definition.

Items:

string
show_in_inbound_notification

boolean — Whether the custom field is shown on the inbound engagement notification in the Zoom client.
show_in_profile_tab

boolean — Whether the custom field is shown on the profile tab in the Zoom client.
show_in_transferred_calls

boolean — Whether the custom field is shown in calls transferred to Zoom Phone.
use_as_external_url_parameter

boolean — Whether the `custom_field_name` is used in defining external URLs launched for each engagement. When set to `true`, the `custom_field_name` should not contain any spaces.
use_as_routing_profile_parameter

boolean — Whether the custom field is used in the consumer routing profile.

Example:

{
  "custom_field_name": "Preferred Contact Method",
  "data_type": "string",
  "default_value": "phone",
  "pick_list_values": [
    "phone"
  ],
  "contact_list_ids": [
    "X2e_jsLNRkCjI0sQg2kRQQ"
  ],
  "use_as_routing_profile_parameter": true,
  "use_as_external_url_parameter": false,
  "show_in_transferred_calls": true,
  "allow_third_party_access": true,
  "show_in_inbound_notification": true,
  "show_in_profile_tab": false
}

Responses

Status: 204 Custom field updated.

Status: 400 HTTP Status Code: `400` Bad Request Error Code: `300` Invalid field. Error Code: `2107` A custom field with this name already exists: {0}. Error Code: `2108` The data type provided for the custom field is not supported. Error Code: `2109` The default value format does not match the data type. Error Code: `2111` Custom field name cannot contain spaces when use_as_external_url_parameter is true.

Status: 401 HTTP Status Code: `401` Unauthorized

Status: 403 HTTP Status Code: `403` Forbidden

Status: 404 HTTP Status Code: `404` Not Found Error Code: `2112` Custom field does not exist: {0}. Error Code: `5001` Contact list not found.

Status: 429 HTTP Status Code: `429` Too Many Requests. For more information, see [rate limits](/docs/api/rate-limits/).

List campaign contact lists

Method: GET
Path: /contact_center/outbound_campaign/contact_lists
Tags: Campaigns

List campaign contact lists.

Scopes: contact_center_outbound_campaign_contactlist:read:admin

Granular Scopes: contact_center:read:outbound_campaign_contactlist:admin

Rate Limit Label: MEDIUM

Responses

Status: 200 HTTP Status Code: `200` Campaign contact lists or do not contact lists are returned.

Content-Type: application/json

contact_lists

array — Array of contact lists or DNC lists

Items:
- contact_list_id (required)
  
  string — The campaign contact list's ID or DNC list's ID.
- contact_list_name (required)
  
  string — The campaign contact list's name or DNC list's name.
- contact_list_description
  
  string — The campaign contact list's description or DNC list's description.
- contacts_count
  
  integer — Number of contacts in the contact list or DNC list.
next_page_token

string — Use the next page token to paginate through large result sets. A next page token is returned whenever the set of available results exceeds the current page size. This token's expiration period is 15 minutes.
page_size

integer, default: 30 — The number of records returned within a single API call.
total_records

integer — The total number of all records available across pages.

Example:

{
  "next_page_token": "R4aF9Oj0fVM2hhezJTEmSKaBSkfesDwGy42",
  "page_size": 30,
  "total_records": 10,
  "contact_lists": [
    {
      "contact_list_id": "MN2Dtcb2T-yT5CU3clN-AA",
      "contact_list_name": "Contact List",
      "contact_list_description": "Description",
      "contacts_count": 1
    }
  ]
}

Status: 400 HTTP Status Code: `400` Bad Request

Status: 429 HTTP Status Code: `429` Too Many Requests. For more information, see [rate limits](/docs/api/rest/rate-limits/).

Create a campaign contact list

Method: POST
Path: /contact_center/outbound_campaign/contact_lists
Tags: Campaigns

Create a campaign contact list.

Scopes: contact_center_outbound_campaign_contactlist:write:admin

Granular Scopes: contact_center:write:outbound_campaign_contactlist:admin

Rate Limit Label: LIGHT

Request Body

Content-Type: application/json

contact_list_name (required)

string — The contact list's name.
contact_list_description

string — The contact list's description.
contact_list_type

string, possible values: "contact", "do_not_contact", default: "contact" — The contact list's type.

Example:

{
  "contact_list_name": "Contact List",
  "contact_list_description": "This is a description",
  "contact_list_type": "contact"
}

Responses

Status: 201 HTTP Status Code: `201` Campaign contact list is created.

Content-Type: application/json

contact_list_description

string — The contact list's description.
contact_list_id

string — The newly created contact list's ID.
contact_list_name

string — The contact list's name.
contact_list_type

string — The contact list's type.
contacts_count

integer — Number of contacts.

Example:

{
  "contact_list_id": "rfMoVPVYS3yjWJAzdOOlWA",
  "contact_list_name": "Contact List",
  "contact_list_description": "Description",
  "contacts_count": 0,
  "contact_list_type": "contact"
}

Status: 400 HTTP Status Code: `400` Bad Request Error Code: `300` Validation failed.

Status: 429 HTTP Status Code: `429` Too Many Requests. For more information, see [rate limits](https://developers.zoom.us/docs/api/rate-limits/).

Batch update campaign contact lists

Method: PATCH
Path: /contact_center/outbound_campaign/contact_lists
Tags: Campaigns

Batch update campaign contact lists.

Scopes: contact_center_outbound_campaign_contactlist:write:admin

Granular Scopes: contact_center:update:outbound_campaign_contactlist:admin

Rate Limit Label: MEDIUM

Request Body

Content-Type: application/json

contact_list_id (required)

string — Campaign contact list ID.
contact_list_description

string — The campaign contact list's description.
contact_list_name

string — The campaign contact list's name.

Example:

{
  "contact_list_id": "07UQHRzvQ02R_o-l9pBB4w",
  "contact_list_name": "New Name",
  "contact_list_description": "New Description"
}

Responses

Status: 200 HTTP Status Code: `200` Campaign contact lists are updated.

Content-Type: application/json

failed_contact_lists

array — List of contact lists that failed to patch.

Items:
- contact_list_id
  
  string — The contact list's ID.
- error
  
  string — The failure reason.

Example:

{
  "failed_contact_lists": [
    {
      "contact_list_id": "07UQHRzvQ02R_o-l9pBB4w",
      "error": "Contact list not found"
    }
  ]
}

Status: 400 HTTP Status Code: `400` Bad Request Error Code: `300` Validation failed.

Status: 429 HTTP Status Code: `429` Too Many Requests. For more information, see [rate limits](https://developers.zoom.us/docs/api/rate-limits/).

Get a campaign contact list

Method: GET
Path: /contact_center/outbound_campaign/contact_lists/{contactListId}
Tags: Campaigns

Get a campaign contact list.

Scopes: contact_center_outbound_campaign_contactlist:read:admin

Granular Scopes: contact_center:read:outbound_campaign_contactlist:admin

Rate Limit Label: LIGHT

Responses

Status: 200 HTTP Status Code: `200` Campaign contact list is returned.

Content-Type: application/json

contact_list_id (required)

string — The campaign contact list's ID.
contact_list_name (required)

string — The campaign contact list's name.
contact_list_description

string — The campaign contact list's description.
contact_list_type

string, possible values: "contact", "do_not_contact" — Contact list type.
contacts_count

integer — Number of contacts in the contact list.

Example:

{
  "contact_list_id": "MN2Dtcb2T-yT5CU3clN-AA",
  "contact_list_name": "Contact List",
  "contact_list_description": "Description",
  "contacts_count": 1,
  "contact_list_type": "contact"
}

Status: 401 HTTP Status Code: `401` Unauthorized

Status: 403 HTTP Status Code: `403` Forbidden

Status: 404 HTTP Status Code: `404` Not Found Error Code: `5001` Contact list is not found

Status: 429 HTTP Status Code: `429` Too Many Requests. For more information, see [rate limits](https://developers.zoom.us/docs/api/rate-limits/).

Remove a campaign contact list

Method: DELETE
Path: /contact_center/outbound_campaign/contact_lists/{contactListId}
Tags: Campaigns

Delete a campaign contact list

Scopes: contact_center_outbound_campaign_contactlist:write:admin

Granular Scopes: contact_center:delete:outbound_campaign_contactlist:admin

Rate Limit Label: LIGHT

Responses

Status: 204 HTTP Status Code: `204` Campaign contact list is removed.

Status: 404 HTTP Status Code: `404` Not Found Error Code: `5001` Contact list not found.

Status: 429 HTTP Status Code: `429` Too Many Requests. For more information, see [rate limits](/docs/api/rate-limits/).

Update a campaign contact list

Method: PATCH
Path: /contact_center/outbound_campaign/contact_lists/{contactListId}
Tags: Campaigns

Update a campaign contact list

Scopes: contact_center_outbound_campaign_contactlist:write:admin

Granular Scopes: contact_center:update:outbound_campaign_contactlist:admin

Rate Limit Label: LIGHT

Request Body

Content-Type: application/json

contact_list_description

string — Description for the campaign contact list
contact_list_name

string — The name of the campaign contact list

Example:

{
  "contact_list_name": "New Name",
  "contact_list_description": "New Description"
}

Responses

Status: 204 HTTP Status Code: `204` Campaign contact list is updated.

Status: 400 HTTP Status Code: `400` Bad Request Error Code: `300` Validation failed.

Status: 404 HTTP Status Code: `404` Not Found Error Code: `5001` Contact list not found.

Status: 429 HTTP Status Code: `429` Too Many Requests. For more information, see [rate limits](/docs/api/rate-limits/).

List a campaign contact list's contacts

Method: GET
Path: /contact_center/outbound_campaign/contact_lists/{contactListId}/contacts
Tags: Campaigns

List contacts on a campaign contact list.

Scopes: contact_center_outbound_campaign_contacts:read:admin

Granular Scopes: contact_center:read:outbound_campaign_contacts:admin

Rate Limit Label: MEDIUM

Responses

Status: 200 Campaign contacts of contact list are returned.

Content-Type: application/json

contacts

array — Array of contacts.

Items:
- contact_display_name (required)
  
  string — The contact's display name.
- contact_id (required)
  
  string — The contact ID.
- contact_phones (required)
  
  array — The contact's phone numbers.
  
  Items:
  - contact_phone_number (required)
    
    string — Phone number, in E164 format.
  - contact_phone_type (required)
    
    string, possible values: "Main", "Home", "Work", "Mobile", "Other" — The phone's type.
- contact_account_number
  
  string — The contact's account number.
- contact_company
  
  string — The contact's company.
- contact_emails
  
  array — Array of emails.
  
  Items:
  
  string, format: email — The contact's email.
- contact_first_name
  
  string — The contact's first name.
- contact_last_name
  
  string — The contact's last name.
- contact_location
  
  string — The contact's location.
- contact_role
  
  string — The contact's role.
- custom_fields
  
  array — Custom fields associated with the current contact.
  
  Items:
  - custom_field_id (required)
    
    string — The custom field's ID. Required - must not be null or empty.
  - custom_field_value (required)
    
    string — The custom field's value. All custom field values are represented as `strings`, regardless of their logical data type specified in `data_type`. The API consumer should provide the value in the correct format according to the `data_type`. - `string` - Any text content. - `number` - Numeric string representing integer or decimal values, such as '123.45'. Valid range is -9999999999 to 9999999999. - `boolean - 'true' or 'false'. - `email` - Valid email address format. - `phone` - Phone number string including country code, like `+1-202-555-0147`. - `percent` - Numeric string between 0 and 100, like `85.5`. - `currency` - Decimal string ≥ 0 with up to two decimal places. - `date_time` - ISO 8601 formatted string, like `2026-01-28T08:00:00Z`. - `pick_list` - One of the allowed option values defined in `pick_list_values`. Input validation should follow these rules based on the `data_type`.
next_page_token

string — Use the next page token to paginate through large result sets. A next page token is returned whenever the set of available results exceeds the current page size. This token's expiration period is 15 minutes.
page_size

integer, default: 30 — The number of records returned within a single API call.
total_records

integer — The total number of all records available across pages.

Example:

{
  "next_page_token": "R4aF9Oj0fVM2hhezJTEmSKaBSkfesDwGy42",
  "page_size": 30,
  "total_records": 10,
  "contacts": [
    {
      "contact_id": "07UQHRzvQ02R_o-l9pBB4w",
      "contact_display_name": "Jill Chill",
      "contact_first_name": "Jill",
      "contact_last_name": "Chill",
      "contact_phones": [
        {
          "contact_phone_number": "+12345551100",
          "contact_phone_type": "Main"
        }
      ],
      "contact_emails": [
        "test@example.com"
      ],
      "contact_location": "Location",
      "contact_account_number": "123",
      "contact_company": "Zoom",
      "contact_role": "developer",
      "custom_fields": [
        {
          "custom_field_id": "suk0leXNTye2JjIm6v0yCQ",
          "custom_field_value": "+1-202-555-0147"
        }
      ]
    }
  ]
}

Status: 400 HTTP Status Code: `400` Bad Request Error Code: `5017` More than one matching contact list found.

Status: 401 HTTP Status Code: `401` Unauthorized Error Code: `124` Invalid access token. Error Code: `124` Access token has expired. Error Code: `1002` The user associated with this access token was not found or is invalid.

Status: 403 HTTP Status Code: `403` Forbidden Error Code: `1021` User account is deactivated. Error Code: `1022` User does not have a Contact Center license. Error Code: `9001` The Contact Center user associated with this bearer token is missing privileges on their role required to operate this request.

Status: 429 HTTP Status Code: `429` Too Many Requests. For more information, see [rate limits](/docs/api/rate-limits/). Error Code: `4001` You have reached the maximum per-second rate limit for this API. Try again later.

Create a campaign contact list's contact

Method: POST
Path: /contact_center/outbound_campaign/contact_lists/{contactListId}/contacts
Tags: Campaigns

Add a new contact to a campaign contact list.

Scopes: contact_center_outbound_campaign_contacts:write:admin

Granular Scopes: contact_center:write:outbound_campaign_contacts:admin

Rate Limit Label: LIGHT

Request Body

Content-Type: application/json

contact_display_name (required)

string — The contact's display name.
contact_phones (required)

array — Supports up to 5 phone numbers. Only one main or primary phone number is supported.

Items:
- contact_phone_number (required)
  
  string — Phone number in E164 format.
- contact_phone_type (required)
  
  string, possible values: "Main", "Work", "Home", "Mobile", "Other" — The phone's type.
contact_account_number

string — The contact's account number.
contact_company

string — The contact's company.
contact_emails

array — Supports up to 4 emails, with a maximum of 1100 characters total.

Items:

string — Email address
contact_first_name

string — The contact's first name.
contact_last_name

string — The contact's last name.
contact_location

string — The contact's location.
contact_role

string — The contact's role.
contact_timezone

string — [TZDB identifier](/docs/api/references/abbreviations/#timezones) time zone.
custom_fields

array — Custom fields associated with the current contact.

Items:
- custom_field_id (required)
  
  string — The custom field's ID. Required, must not be null or empty)
- custom_field_value (required)
  
  string — The custom field's value. All custom field values are represented as **strings**, regardless of their logical data type specified in `data_type`. The API consumer should provide the value in the correct format according to the `data_type`. - **string** - Any text content. - **number** - Numeric string representing integer or decimal values, like '123.45'. Valid range is -9999999999 to 9999999999. - **boolean** - 'true' or 'false'. - **email** - Valid email address format, like 'user@example.com'. - **phone** - Phone number string including country code, like '+1-202-555-0147'. - **percent** - Numeric string between 0 and 100, like '85.5'. - **currency** - Decimal string ≥ 0 with up to two decimal places, like '199.99'. - **date_time** - ISO 8601 formatted string, such as '2026-01-28T08:00:00Z'. - **pick_list** - One of the allowed option values defined in `pick_list_values`. Input validation should follow these rules based on the `data_type`.

Example:

{
  "contact_display_name": "Display Name",
  "contact_first_name": "First Name",
  "contact_last_name": "Last Name",
  "contact_phones": [
    {
      "contact_phone_number": "+12345551100",
      "contact_phone_type": "Main"
    }
  ],
  "contact_emails": [
    "test@example.com"
  ],
  "contact_location": "Location",
  "contact_account_number": "111",
  "contact_company": "zoom",
  "contact_role": "developer",
  "contact_timezone": "America/Los_Angeles",
  "custom_fields": [
    {
      "custom_field_id": "suk0leXNTye2JjIm6v0yCQ",
      "custom_field_value": "+1-202-555-0147"
    }
  ]
}

Responses

Status: 201 HTTP Status Code: `201` New contact has been created.

Content-Type: application/json

contact_display_name (required)

string — The contact's display name.
contact_id (required)

string — The contact's ID.
contact_phones (required)

array — Contact emails

Items:
- contact_phone_number (required)
  
  string — The phone number, in E164 format.
- contact_phone_type (required)
  
  string, possible values: "Main", "Work", "Home", "Mobile", "Other" — Phone type
contact_account_number

string — Account number.
contact_company

string — Contact company.
contact_emails

array — The contact's email addresses.

Items:

string, format: email — Email address
contact_first_name

string — The contact's first name.
contact_last_name

string — The contact's last name.
contact_location

string — The contact's location.
contact_role

string — Contact role
contact_timezone

string — [TZDB identifier](/docs/api/references/abbreviations/#timezones) time zone.
custom_fields

array — Custom fields associated with the current contact.

Items:
- custom_field_id (required)
  
  string — The custom field's ID. Required - must not be null or empty.
- custom_field_value (required)
  
  string — The value of the custom field. All custom field values are represented as **strings**, regardless of their logical data type specified in `data_type`. The API consumer should provide the value in the correct format according to the `data_type`. - **string** - Any text content. - **number** - Numeric string representing integer or decimal values, like '123.45'. Valid range is -9999999999 to 9999999999. - **boolean** - 'true' or 'false'. - **email** - Valid email address format, like 'user@example.com'. - **phone** - Phone number string including country code, like '+1-202-555-0147'. - **percent** - Numeric string between 0 and 100, like '85.5'. - **currency** - Decimal string ≥ 0 with up to two decimal places, such as '199.99'. - **date_time** - ISO 8601 formatted string, like'2026-01-28T08:00:00Z'. - **pick_list** - One of the allowed option values defined in `pick_list_values`. Input validation should follow these rules based on the `data_type`.

Example:

{
  "contact_id": "GgAOGeRFQOqJlphf3gqhqg",
  "contact_display_name": "Jill Chill",
  "contact_first_name": "Jill",
  "contact_last_name": "Chill",
  "contact_phones": [
    {
      "contact_phone_number": "+12345551100",
      "contact_phone_type": "Main"
    }
  ],
  "contact_emails": [
    "jillchill@example.com"
  ],
  "contact_location": "Location",
  "contact_account_number": "111",
  "contact_company": "zoom",
  "contact_role": "developer",
  "contact_timezone": "America/Los_Angeles",
  "custom_fields": [
    {
      "custom_field_id": "suk0leXNTye2JjIm6v0yCQ",
      "custom_field_value": "+1-202-555-0147"
    }
  ]
}

Status: 400 HTTP Status Code: `400` Bad Request Error Code: `300` Validation failed. Error Code: `5003` Contact already exists. Error Code: `5004` Reached the limit of contacts per contact list.

Status: 401 HTTP Status Code: `401` Unauthorized

Status: 403 HTTP Status Code: `403` Forbidden

Status: 404 HTTP Status Code: `404` Not Found Error Code: `5001` Contact list not found.

Status: 429 HTTP Status Code: `429` Too Many Requests. For more information, see [rate limits](/docs/api/rate-limits/).

Update a batch of contacts on a campaign contact list

Method: PATCH
Path: /contact_center/outbound_campaign/contact_lists/{contactListId}/contacts
Tags: Campaigns

Batch update contacts on a campaign contact list.

Scopes: contact_center_outbound_campaign_contacts:write:admin

Granular Scopes: contact_center:update:outbound_campaign_contacts:admin

Rate Limit Label: MEDIUM

Request Body

Content-Type: application/json

contacts

array — Array of contacts to patch.

Items:
- contact_id (required)
  
  string — The contact's ID.
- contact_account_number
  
  string — The contact's account number.
- contact_company
  
  string — The contact's company.
- contact_display_name
  
  string — The contact's display name.
- contact_emails
  
  array — Supports up to 4 emails, up to a maximum of 1100 characters.
  
  Items:
  
  string, format: email — Email address.
- contact_first_name
  
  string — The contact's first name.
- contact_last_name
  
  string — The contact's last name.
- contact_location
  
  string — The contact's location.
- contact_phones
  
  array — Supports up to 5 numbers. Only one main or primar phone number is supported.
  
  Items:
  - contact_phone_number
    
    string — Phone number, in E164 format.
  - contact_phone_type
    
    string, possible values: "Main", "Work", "Home", "Mobile", "Other" — The phone's type.
- contact_role
  
  string — The contact's role.
- contact_timezone
  
  string — [TZDB identifier](/docs/api/references/abbreviations/#timezones) time zone.
- custom_fields
  
  array — Custom fields associated with the current contact. If omitted, existing custom fields remain unchanged. If provided as an empty array, all existing custom fields for the contact will be removed. If provided as null, the field is ignored and no changes are made.
  
  Items:
  - custom_field_id (required)
    
    string — The custom field's ID. Required. Must not be null or empty.
  - custom_field_value (required)
    
    string — The value of the custom field. All custom field values are represented as **strings**, regardless of their logical data type specified in `data_type`. The API consumer should provide the value in the correct format according to the `data_type`: - **string**: Any text content. - **number**: Numeric string representing integer or decimal values (e.g., '123.45'). Valid range: -9999999999 to 9999999999. - **boolean**: 'true' or 'false'. - **email**: Valid email address format (e.g., 'user@example.com'). - **phone**: Phone number string including country code (e.g., '+1-202-555-0147'). - **percent**: Numeric string between 0 and 100 (e.g., '85.5'). - **currency**: Decimal string ≥ 0 with up to two decimal places (e.g., '199.99'). - **date_time**: ISO 8601 formatted string (e.g., '2026-01-28T08:00:00Z'). - **pick_list**: One of the allowed option values defined in `pick_list_values`. Input validation should follow these rules based on the `data_type`.

Example:

{
  "contacts": [
    {
      "contact_id": "MN2Dtcb2T-yT5CU3clN-AA",
      "contact_display_name": "Jill Chill",
      "contact_first_name": "Jill",
      "contact_last_name": "Chill",
      "contact_phones": [
        {
          "contact_phone_number": "+12345551100",
          "contact_phone_type": "Main"
        }
      ],
      "contact_emails": [
        "jillchill@example.com"
      ],
      "contact_location": "Zurich",
      "contact_account_number": "111",
      "contact_company": "Zoom",
      "contact_role": "developer",
      "contact_timezone": "America/Los_Angeles",
      "custom_fields": [
        {
          "custom_field_id": "suk0leXNTye2JjIm6v0yCQ",
          "custom_field_value": "+1-202-555-0147"
        }
      ]
    }
  ]
}

Responses

Status: 200 HTTP Status Code: `200` Contact list is updated.

Content-Type: application/json

failed_contacts

array — List of contacts that failed to patch.

Items:
- contact_id
  
  string — The contact's ID.
- error
  
  string — The reason for failure.

Example:

{
  "failed_contacts": [
    {
      "contact_id": "MN2Dtcb2T-yT5CU3clN-AA",
      "error": "Contact not found"
    }
  ]
}

Status: 400 HTTP Status Code: `400` Bad Request Error Code: `300` Validation failed.

Status: 401 HTTP Status Code: `401` Unauthorized

Status: 403 HTTP Status Code: `403` Forbidden

Status: 429 HTTP Status Code: `429` Too Many Requests. For more information, see [rate limits](https://developers.zoom.us/docs/api/rate-limits/).

Insert a batch of contacts into a campaign contact list

Method: POST
Path: /contact_center/outbound_campaign/contact_lists/{contactListId}/contacts/batch
Tags: Campaigns

Batch insert contacts into a campaign contact list.

Scopes: contact_center_outbound_campaign_contacts:write:admin

Granular Scopes: contact_center:write:outbound_campaign_contacts:admin

Rate Limit Label: MEDIUM

Request Body

Content-Type: application/json

contacts

array — Array of contacts to insert.

Items:
- contact_display_name (required)
  
  string — The contact's display name.
- contact_phones (required)
  
  array — Supports up to 5 numbers. Only one main or primary phone number is supported.
  
  Items:
  - contact_phone_number (required)
    
    string — The phone number, in E164 format.
  - contact_phone_type (required)
    
    string, possible values: "Main", "Work", "Home", "Mobile", "Other" — The phone's type.
- contact_account_number
  
  string — The contact's account number.
- contact_company
  
  string — The contact's company.
- contact_emails
  
  array — Supports up to 4 emails.
  
  Items:
  
  string, format: email — Email address.
- contact_first_name
  
  string — The contact's first name.
- contact_last_name
  
  string — The contact's last name.
- contact_location
  
  string — The contact's location.
- contact_role
  
  string — The contact's role.
- contact_timezone
  
  string — [TZDB identifier](/docs/api/references/abbreviations/#timezones) time zone.

Example:

{
  "contacts": [
    {
      "contact_display_name": "Jane Doe",
      "contact_first_name": "Jane",
      "contact_last_name": "Doe",
      "contact_phones": [
        {
          "contact_phone_number": "+12345551100",
          "contact_phone_type": "Main"
        }
      ],
      "contact_emails": [
        "jdoe@example.com"
      ],
      "contact_location": "Los_Angeles",
      "contact_account_number": "73510482",
      "contact_company": "Zoom",
      "contact_role": "Developer",
      "contact_timezone": "America/Los_Angeles"
    }
  ]
}

Responses

Status: 200 HTTP Status Code: `200` The request was processed successfully. Check the `failed_contacts` array for any contacts that could not be created.

Content-Type: application/json

failed_contacts

array — List of contacts that failed to be created.

Items:
- contact_index
  
  string — The contact's index from the input list, zero-based.
- error
  
  string — The error message describing why the contact failed to be created.

Example:

{
  "failed_contacts": [
    {
      "contact_index": "3",
      "error": "Invalid Email"
    }
  ]
}

Status: 400 HTTP Status Code: `400` Bad Request Error Code: `300` Validation failed.

Status: 401 HTTP Status Code: `401` Unauthorized Error Code: `124` Invalid access token. Error Code: `124` Access token has expired. Error Code: `1002` The user associated with this access token was not found or is invalid.

Status: 403 HTTP Status Code: `403` Forbidden Error Code: `9001` The Contact Center user associated with this bearer token is missing privileges on their role required to operate this request. Error Code: `1021` User account is deactivated. Error Code: `1022` User does not have a Contact Center license.

Status: 429 HTTP Status Code: `429` Too Many Requests. For more information, see [rate limits](https://developers.zoom.us/docs/api/rate-limits/). Error Code: `4001` You have reached the maximum per-second rate limit for this API. Try again later.

Get a campaign contact list's contact

Method: GET
Path: /contact_center/outbound_campaign/contact_lists/{contactListId}/contacts/{contactId}
Tags: Campaigns

Get a contact on a campaign contact list.

Scopes: contact_center_outbound_campaign_contacts:read:admin

Granular Scopes: contact_center:read:outbound_campaign_contacts:admin

Rate Limit Label: LIGHT

Responses

Status: 200 HTTP Status Code: `200` Campaign contact list contact is returned.

Content-Type: application/json

contact_display_name (required)

string — The contact's display name
contact_id (required)

string — Campaign contact list contact ID.
contact_phones (required)

array — Array of phones.

Items:
- contact_phone_number (required)
  
  string — Phone number, in E164 format.
- contact_phone_type (required)
  
  string, possible values: "Main", "Home", "Work", "Mobile", "Other" — The phone's type.
contact_account_number

string — The contact's account number.
contact_company

string — The contact's company.
contact_emails

array — Array of emails.

Items:

string, format: email — The contact's email.
contact_first_name

string — The contact's first name.
contact_last_name

string — The contact's last name.
contact_location

string — The contact's location.
contact_role

string — The contact's role.
contact_timezone

string — [TZDB identifier](/docs/api/references/abbreviations/#timezones) time zone.
custom_fields

array — Custom fields associated with the current contact.

Items:
- custom_field_id (required)
  
  string — The custom field's ID. Required. Must not be null or empty.
- custom_field_value (required)
  
  string — The custom field's value. All custom field values are represented as **strings**, regardless of their logical data type specified in `data_type`. The API consumer should provide the value in the correct format according to the `data_type`: - **string**: Any text content. - **number**: Numeric string representing integer or decimal values (e.g., '123.45'). Valid range: -9999999999 to 9999999999. - **boolean**: 'true' or 'false'. - **email**: Valid email address format (e.g., 'user@example.com'). - **phone**: Phone number string including country code (e.g., '+1-202-555-0147'). - **percent**: Numeric string between 0 and 100 (e.g., '85.5'). - **currency**: Decimal string ≥ 0 with up to two decimal places (e.g., '199.99'). - **date_time**: ISO 8601 formatted string (e.g., '2026-01-28T08:00:00Z'). - **pick_list**: One of the allowed option values defined in `pick_list_values`. Input validation should follow these rules based on the `data_type`.

Example:

{
  "contact_id": "07UQHRzvQ02R_o-l9pBB4w",
  "contact_display_name": "Joe Chill",
  "contact_first_name": "Joe",
  "contact_last_name": "Chill",
  "contact_phones": [
    {
      "contact_phone_number": "+12345551100",
      "contact_phone_type": "Main"
    }
  ],
  "contact_emails": [
    "test@example.com"
  ],
  "contact_location": "Location",
  "contact_account_number": "123",
  "contact_company": "zoom",
  "contact_role": "developer",
  "contact_timezone": "America/Los_Angeles",
  "custom_fields": [
    {
      "custom_field_id": "suk0leXNTye2JjIm6v0yCQ",
      "custom_field_value": "+1-202-555-0147"
    }
  ]
}

Status: 400 HTTP Status Code: `400` Bad Request Error Code: `5017` More than one matching contact list found.

Status: 401 HTTP Status Code: `401` Unauthorized

Status: 403 HTTP Status Code: `403` Forbidden

Status: 404 HTTP Status Code: `404` Not Found Error Code: `5001` Contact list not found. Error Code: `5002` Contact not found.

Status: 429 HTTP Status Code: `429` Too Many Requests. For more information, see [rate limits](https://developers.zoom.us/docs/api/rate-limits/).

Remove campaign contact list's contact

Method: DELETE
Path: /contact_center/outbound_campaign/contact_lists/{contactListId}/contacts/{contactId}
Tags: Campaigns

Remove a contact by ID from a campaign contact list.

Scopes: contact_center_outbound_campaign_contacts:write:admin

Granular Scopes: contact_center:delete:outbound_campaign_contacts:admin

Rate Limit Label: LIGHT

Responses

Status: 204 HTTP Status Code: `204` Contact is deleted.

Status: 404 HTTP Status Code: `404` Not Found Error Code: `5001` Contact list is not found. Error Code: `5002` Contact is not found.

Status: 429 HTTP Status Code: `429` Too Many Requests. For more information, see [rate limits](/docs/api/rate-limits/).

Update contact on a campaign contact list

Method: PATCH
Path: /contact_center/outbound_campaign/contact_lists/{contactListId}/contacts/{contactId}
Tags: Campaigns

Update a contact on a campaign contact list.

Scopes: contact_center_outbound_campaign_contacts:write:admin

Granular Scopes: contact_center:update:outbound_campaign_contacts:admin

Rate Limit Label: LIGHT

Request Body

Content-Type: application/json

contact_account_number

string — The contact's account number.
contact_company

string — The contact's company.
contact_display_name

string — The contact's display name.
contact_emails

array — Supports up to 4 emails, a maximum of 1100 characters in total.

Items:

string — Email address.
contact_first_name

string — The contact's first name.
contact_last_name

string — The contact's last name.
contact_location

string — The contact's location.
contact_phones

array — Supports up to 5 numbers. Only one main or primar phone number is supported.

Items:
- contact_phone_number
  
  string — Phone number, in E164 format.
- contact_phone_type
  
  string, possible values: "Main", "Work", "Home", "Mobile", "Other" — The phone's type.
contact_role

string — The contact's role.
contact_timezone

string — [TZDB identifier](/docs/api/references/abbreviations/#timezones) time zone.
custom_fields

array — Custom fields associated with the current contact. If omitted, existing custom fields remain unchanged. If provided as an empty array, all existing custom fields for the contact will be removed. If provided as null, the field is ignored and no changes are made.

Items:
- custom_field_id (required)
  
  string — The custom field's ID. Required. Must not be null or empty.
- custom_field_value (required)
  
  string — The custom field's value. All custom field values are represented as **strings**, regardless of their logical data type specified in `data_type`. The API consumer should provide the value in the correct format according to the `data_type`. - **string** - Any text content. - **number** - Numeric string representing integer or decimal values such as '123.45'. Valid range is -9999999999 to 9999999999. - **boolean** - 'true' or 'false'. - **email** - Valid email address format, like 'user@example.com'. - **phone** - Phone number string including country code, like '+1-202-555-0147'. - **percent** - Numeric string between 0 and 100, like '85.5'. - **currency** - Decimal string ≥ 0 with up to two decimal places such as '199.99'. - **date_time** - ISO 8601 formatted string, like '2026-01-28T08:00:00Z'. - **pick_list** - One of the allowed option values defined in `pick_list_values`. Input validation should follow these rules based on the `data_type`.

Example:

{
  "contact_display_name": "Jill Chill",
  "contact_first_name": "Jill",
  "contact_last_name": "Chill",
  "contact_phones": [
    {
      "contact_phone_number": "+12345551100",
      "contact_phone_type": "Main"
    }
  ],
  "contact_emails": [
    "jillchill@example.com"
  ],
  "contact_location": "Zurich",
  "contact_account_number": "111",
  "contact_company": "Zoom",
  "contact_role": "developer",
  "contact_timezone": "America/Los_Angeles",
  "custom_fields": [
    {
      "custom_field_id": "suk0leXNTye2JjIm6v0yCQ",
      "custom_field_value": "+1-202-555-0147"
    }
  ]
}

Responses

Status: 204 HTTP Status Code: `204` Contact is updated.

Status: 400 HTTP Status Code: `400` Bad Request Error Code: `300` Validation failed.

Status: 401 HTTP Status Code: `401` Unauthorized

Status: 403 HTTP Status Code: `403` Forbidden

Status: 404 HTTP Status Code: `404` Not Found Error Code: `5001` Contact list not found. Error Code: `5002` Contact not found.

Status: 429 HTTP Status Code: `429` Too Many Requests. For more information, see [rate limits](/docs/api/rate-limits/).

List a campaign contact's custom fields

Method: GET
Path: /contact_center/outbound_campaign/contacts/{contactId}/custom_fields
Tags: Campaigns

Retrieve all custom fields associated with a contact.

Scopes: contact_center_outbound_campaign_contactlist:read:admin

Granular Scopes: contact_center:read:outbound_campaign_contactlist:admin

Rate Limit Label: MEDIUM

Responses

Status: 200 Contact custom fields are returned.

Content-Type: application/json

custom_fields

array — A list of custom fields associated with the contact.

Items:
- custom_field_id (required)
  
  string — The custom field's ID.
- custom_field_name (required)
  
  string — The custom field's name.
- data_type (required)
  
  string, possible values: "string", "number", "boolean", "email", "phone", "percent", "currency", "date_time", "pick_list" — The custom field's data type. - `string` - Any text value. - `number` - Numeric value. Supports integers or decimals, like `123.45`. Valid range is -9999999999 to 9999999999. - `percent` - Numeric value between 0 and 100. May include decimals. - `currency` - Decimal value ≥ 0 with up to two decimal places. When `data_type` is `pick_list`, `pick_list_values` specifies the allowed options.
- custom_field_value
  
  string — The contact's custom field value.
next_page_token

string — Use the next page token to paginate through large result sets. A next page token is returned whenever the set of available results exceeds the current page size. This token's expiration period is 15 minutes.
page_size

integer, default: 30 — The number of records returned in a single API call.
total_records

integer — The total number of all records available across pages.

Example:

{
  "next_page_token": "R4aF9Oj0fVM2hhezJTEmSKaBSkfesDwGy42",
  "page_size": 30,
  "total_records": 10,
  "custom_fields": [
    {
      "custom_field_id": "7381d210-360e-4fbd-86e4-33eb7109b084",
      "custom_field_name": "Preferred Contact Method",
      "data_type": "string",
      "custom_field_value": "phone"
    }
  ]
}

Status: 400 HTTP Status Code: `400` Bad Request

Status: 401 HTTP Status Code: `401` Unauthorized

Status: 403 HTTP Status Code: `403` Forbidden

Status: 404 HTTP Status Code: `404` Not Found Error Code: `2101` Contact does not exist.

Status: 429 HTTP Status Code: `429` Too Many Requests. For more information, see [rate limits](/docs/api/rate-limits/).

List campaign DNC phone numbers

Method: GET
Path: /contact_center/outbound_campaign/dnc_lists/{dncListId}/phones
Tags: Campaigns

List phone numbers on a campaign DNC (Do Not Call) list.

Scopes: contact_center_outbound_campaign_dnc_list_phones:read:admin

Granular Scopes: contact_center:read:outbound_campaign_dnc_list_phones:admin

Rate Limit Label: MEDIUM

Responses

Status: 200 HTTP Status Code: `200` Phone numbers of DNC list are returned.

Content-Type: application/json

dnc_list_phones

array — Array of phone numbers in the DNC list.

Items:
- phone_id (required)
  
  string — The phone record ID.
- phone_number (required)
  
  string — Phone number, in E164 format.
next_page_token

string — Use the next page token to paginate through large result sets. A next page token is returned whenever the set of available results exceeds the current page size. This token's expiration period is 15 minutes.
page_size

integer, default: 10 — The number of records returned within a single API call.
total_records

integer — The total number of all records available across pages.

Example:

{
  "next_page_token": "R4aF9Oj0fVM2hhezJTEmSKaBSkfesDwGy42",
  "page_size": 10,
  "total_records": 10,
  "dnc_list_phones": [
    {
      "phone_id": "07UQHRzvQ02R_o-l9pBB4w",
      "phone_number": "+12345551100"
    }
  ]
}

Status: 400 HTTP Status Code: `400` Bad Request

Status: 404 HTTP Status Code: `404` Not Found Error Code: `5020` DNC list is not found.

Status: 429 HTTP Status Code: `429` Too Many Requests. For more information, see [rate limits](https://developers.zoom.us/docs/api/rate-limits/).

Batch create a campaign DNC list's phones

Method: POST
Path: /contact_center/outbound_campaign/dnc_lists/{dncListId}/phones
Tags: Campaigns

Batch add phone numbers to a Do Not Call (DNC) list.

Scopes: contact_center_outbound_campaign_dnc_list_phones:write:admin

Granular Scopes: contact_center:write:outbound_campaign_dnc_list_phones:admin

Rate Limit Label: LIGHT

Request Body

Content-Type: application/json

phone_numbers (required)

array — Phone numbers to be added to the DNC list.

Items:

string — Phone number of the phone to be added.

Example:

{
  "phone_numbers": [
    "+12095551212"
  ]
}

Responses

Status: 201 HTTP Status Code: `201` Phone numbers successfully added.

Status: 404 HTTP Status Code: `404` Not Found Error Code: `5020` DNC list is not found.

Status: 429 HTTP Status Code: `429` Too Many Requests. For more information, see [rate limits](https://developers.zoom.us/docs/api/rate-limits/).

Batch delete a campaign DNC list's phones

Method: DELETE
Path: /contact_center/outbound_campaign/dnc_lists/{dncListId}/phones
Tags: Campaigns

Batch delete phone numbers from a Do Not Call (DNC) list.

Scopes: contact_center_outbound_campaign_dnc_list_phones:write:admin

Granular Scopes: contact_center:delete:outbound_campaign_dnc_list_phones:admin

Rate Limit Label: LIGHT

Request Body

Content-Type: application/json

phone_ids

array — IDs of the phones to be deleted.

Items:

string — ID of the phone to be deleted.

Example:

{
  "phone_ids": [
    "pJ_DCxrmQMevo0MUJvEUAA"
  ]
}

Responses

Status: 204 HTTP Status Code: `204` Phones are deleted.

Status: 404 HTTP Status Code: `404` Not Found Error Code: `5020` DNC list is not found.

Status: 429 HTTP Status Code: `429` Too Many Requests. For more information, see [rate limits](https://developers.zoom.us/docs/api/rate-limits/).

List dispositions

Method: GET
Path: /contact_center/dispositions
Tags: Dispositions

Return a list of available dispositions.

Scopes: contact_center_disposition:read:admin

Granular Scopes: contact_center:read:list_dispositions:admin

Rate Limit Label: MEDIUM

Responses

Status: 200 HTTP Status Code: `200` Dispositions returned.

Content-Type: application/json

dispositions

array — Information about the disposition.

Items:
- disposition_description
  
  string — The disposition's description.
- disposition_id
  
  string — The disposition's ID.
- disposition_name
  
  string — The disposition's name.
- disposition_type
  
  string, possible values: "single", "multi_level" — The disposition type.
- last_modified_time
  
  string, format: date-time — The date and time when this data was last modified.
- modified_by
  
  string — The ID of the user that last modified this data.
- queue_count
  
  integer — The number of queues associated with the disposition.
- status
  
  string, possible values: "inactive", "active" — The disposition's active status. * `inactive` - Deactivated. * `active` - Activated.
next_page_token

string — Use the next page token to paginate through large result sets. A next page token is returned whenever the set of available results exceeds the current page size. This token's expiration period is 15 minutes.
page_size

integer, default: 30 — The number of records returned within a single API call.
total_records

integer — The total number of all the records available across pages.

Example:

{
  "next_page_token": "R4aF9Oj0fVM2hhezJTEmSKaBSkfesDwGy42",
  "page_size": 30,
  "total_records": 10,
  "dispositions": [
    {
      "disposition_id": "W_VATTk_Q5aW6z5rZtBxAQ",
      "disposition_name": "Inquiry",
      "disposition_description": "Inquiry dispositions.",
      "status": "inactive",
      "queue_count": 0,
      "last_modified_time": "2022-02-15T09:27:15Z",
      "modified_by": "IGTRVt3gQ2i-WjoUIjeZxw",
      "disposition_type": "single"
    }
  ]
}

Status: 400 HTTP Status Code: `400` Bad Request

Status: 401 HTTP Status Code: `401` Unauthorized

Status: 403 HTTP Status Code: `403` Forbidden

Status: 429 HTTP Status Code: `429` Too Many Requests. For more information, see [rate limits](https://developers.zoom.us/docs/api/rest/rate-limits/).

Create a disposition

Method: POST
Path: /contact_center/dispositions
Tags: Dispositions

Create a new disposition. Dispositions let agents assign an outcome or topic to each engagement. After creating dispositions, you can add them to queues.

Scopes: contact_center_disposition:write:admin

Granular Scopes: contact_center:write:disposition:admin

Rate Limit Label: LIGHT

Request Body

Content-Type: application/json

disposition_name (required)

string — The disposition's name.
disposition_description

string — The disposition's description.
disposition_type

string, possible values: "single", "multi_level", default: "single" — The disposition's type.
status

string, possible values: "inactive", "active", default: "inactive" — The disposition's active status. * `inactive` - Deactivated. * `active` - Activated.
sub_dispositions

array — For `single` dispositions, this field can be ignored. For `multi_level` dispositions, there must be at least one subdisposition. There can be up to 500, and each parent node can have up to 20 child nodes. Child nodes can only have up to 4 levels.

Items:
- current_index (required)
  
  number — The subdisposition's unique identifier.
- parent_index (required)
  
  number — The index of the parent node that the current node belongs to. If it is `0`, it means that the current node belongs to the root node. If the parent index does not exist, the node will be discarded.
- sub_disposition_name (required)
  
  string — The subdisposition's name.

Example:

{
  "status": "inactive",
  "disposition_name": "Inquiry",
  "disposition_description": "Inquiry dispositions.",
  "disposition_type": "multi_level",
  "sub_dispositions": [
    {
      "sub_disposition_name": "Subdisposition A",
      "current_index": 1,
      "parent_index": 0
    }
  ]
}

Responses

Status: 201 HTTP Status Code: `201` Disposition created.

Content-Type: application/json

disposition_description

string — The disposition's description.
disposition_id

string — The disposition's ID.
disposition_name

string — The disposition's name.
disposition_type

string, possible values: "single", "multi_level" — The disposition's type.
last_modified_time

string, format: date-time — The date and time when this data was last modified.
modified_by

string — The ID of the user that last modified this data.
status

string, possible values: "inactive", "active" — The disposition's active status. * `inactive` - Deactivated. * `active` - Activated.

Example:

{
  "disposition_id": "W_VATTk_Q5aW6z5rZtBxAQ",
  "disposition_name": "Inquiry",
  "disposition_description": "Inquiry dispositions.",
  "status": "inactive",
  "last_modified_time": "2022-02-15T09:27:15Z",
  "modified_by": "IGTRVt3gQ2i-WjoUIjeZxw",
  "disposition_type": "multi_level"
}

Status: 400 HTTP Status Code: `400` Bad Request Error Code: `2402` That disposition name already exists. Use a different name. Error Code: `2504` Sub dispositions total size should be less than or equal to 500. Error Code: `2505` Sub Disposition current index repeated. Error Code: `2507` Multi_level disposition no sub dispositions. Error Code: `2508` Duplicate sub disposition name on the same tier. Error Code: `2509` Sub disposition tier size should be more than 0 and less than 5. Error Code: `2512` The number of sub dispositions on the same tier should less than or equal to 20. Error Code: `2514` Sub Disposition current_index is required. Error Code: `2515` Sub Disposition parent_index is required.

Status: 401 HTTP Status Code: `401` Unauthorized

Status: 403 HTTP Status Code: `403` Forbidden

Status: 429 HTTP Status Code: `429` Too Many Requests. For more information, see [rate limits](/docs/api/rest/rate-limits/).

List disposition sets

Method: GET
Path: /contact_center/dispositions/sets
Tags: Dispositions

Return a list of available disposition sets. Use sets to organize dispositions into groups.

Scopes: contact_center_disposition:read:admin

Granular Scopes: contact_center:read:list_disposition_sets:admin

Rate Limit Label: MEDIUM

Responses

Status: 200 HTTP Status Code: `200` Disposition sets returned.

Content-Type: application/json

disposition_sets

array — Information about the disposition set.

Items:
- disposition_set_description
  
  string — The set's description.
- disposition_set_id
  
  string — The set's ID.
- disposition_set_name
  
  string — The set's name.
- dispositions_count
  
  integer — The number of dispositions associated with the disposition set.
- last_modified_time
  
  string, format: date-time — The date and time when this data was last modified.
- modified_by
  
  string — The ID of the user that last modified this data.
- queues_count
  
  integer — The number of queues associated with the disposition set.
- status
  
  string, possible values: "inactive", "active" — The set's active status. * `inactive` - Deactivated. * `active` - Activated.
next_page_token

string — Use the next page token to paginate through large result sets. A next page token is returned whenever the set of available results exceeds the current page size. This token's expiration period is 15 minutes.
page_size

integer, default: 30 — The number of records returned within a single API call.
total_records

integer — The total number of all the records available across pages.

Example:

{
  "next_page_token": "R4aF9Oj0fVM2hhezJTEmSKaBSkfesDwGy42",
  "page_size": 30,
  "total_records": 10,
  "disposition_sets": [
    {
      "disposition_set_id": "saaHWgVMGQU69soco456oNA",
      "disposition_set_name": "Lead created",
      "disposition_set_description": "New leads generated.",
      "status": "inactive",
      "last_modified_time": "2022-02-15T09:27:15Z",
      "modified_by": "IGTRVt3gQ2i-WjoUIjeZxw",
      "dispositions_count": 0,
      "queues_count": 0
    }
  ]
}

Status: 400 HTTP Status Code: `400` Bad Request

Status: 401 HTTP Status Code: `401` Unauthorized

Status: 403 HTTP Status Code: `403` Forbidden

Status: 429 HTTP Status Code: `429` Too Many Requests. For more information, see [rate limits](https://developers.zoom.us/docs/api/rest/rate-limits/).

Create a disposition set

Method: POST
Path: /contact_center/dispositions/sets
Tags: Dispositions

Create a new disposition set.

Scopes: contact_center_disposition:write:admin

Granular Scopes: contact_center:write:disposition_set:admin

Rate Limit Label: LIGHT

Request Body

Content-Type: application/json

disposition_set_name (required)

string — The set's name.
disposition_ids

array — Information about the set's assigned dispositions.

Items:

string — The disposition's ID.
disposition_set_description

string — The set's description.
status

string, possible values: "inactive", "active", default: "inactive" — The set's active status. * `inactive` - Deactivated. * `active` - Activated.

Example:

{
  "status": "inactive",
  "disposition_set_name": "Lead created",
  "disposition_set_description": "New leads generated.",
  "disposition_ids": [
    "W_VATTk_Q5aW6z5rZtBxAQ"
  ]
}

Responses

Status: 201 HTTP Status Code: `201` Disposition set created.

Content-Type: application/json

disposition_set_description

string — The set's description.
disposition_set_id

string — The set's ID.
disposition_set_name

string — The set's name.
dispositions

array — Information about the set's assigned dispositions.

Items:
- disposition_id
  
  string — The disposition's ID.
- disposition_name
  
  string — The disposition's name.
last_modified_time

string, format: date-time — The date and time when this data was last modified.
modified_by

string — The ID of the user that last modified this data.
status

string, possible values: "inactive", "active" — The set's active status. * `inactive` - Deactivated. * `active` - Activated.

Example:

{
  "disposition_set_id": "saaHWgVMGQU69soco456oNA",
  "disposition_set_name": "Lead created",
  "disposition_set_description": "New leads generated.",
  "status": "inactive",
  "last_modified_time": "2022-02-15T09:27:15Z",
  "modified_by": "IGTRVt3gQ2i-WjoUIjeZxw",
  "dispositions": [
    {
      "disposition_id": "W_VATTk_Q5aW6z5rZtBxAQ",
      "disposition_name": "Inquiry"
    }
  ]
}

Status: 400 HTTP Status Code: `400` Bad Request Error Code: `2502` That set name already exists. Use a different name.

Status: 401 HTTP Status Code: `401` Unauthorized

Status: 403 HTTP Status Code: `403` Forbidden

Status: 404 HTTP Status Code: `404` Not Found Error Code: `2403` Disposition does not exist: $disposition_ids.

Status: 429 HTTP Status Code: `429` Too Many Requests. For more information, see [rate limits](/docs/api/rest/rate-limits/).

Get a disposition set

Method: GET
Path: /contact_center/dispositions/sets/{dispositionSetId}
Tags: Dispositions

Retrieve information about a disposition set.

Scopes: contact_center_disposition:read:admin

Granular Scopes: contact_center:read:disposition_set:admin

Rate Limit Label: LIGHT

Responses

Status: 200 HTTP Status Code: `200` Set returned.

Content-Type: application/json

disposition_set_description

string — The set's description.
disposition_set_id

string — The set's ID.
disposition_set_name

string — The set's name.
dispositions

array — Information about the set's assigned dispositions.

Items:
- disposition_id
  
  string — The disposition's ID.
- disposition_name
  
  string — The disposition's name.
last_modified_time

string, format: date-time — The date and time when this data was last modified.
modified_by

string — The ID of the user that last modified this data.
queues

array — Information about the set's assigned queue.

Items:
- cc_queue_id
  
  string — The Contact Center queue's ID.
- queue_id
  
  string — The queue's ID.
- queue_name
  
  string — The queue's name.
status

string, possible values: "inactive", "active" — The set's active status. * `inactive` — Deactivated. * `active` — Activated.

Example:

{
  "disposition_set_id": "saaHWgVMGQU69soco456oNA",
  "disposition_set_name": "Lead created",
  "disposition_set_description": "New leads generated.",
  "status": "inactive",
  "last_modified_time": "2022-02-15T09:27:15Z",
  "modified_by": "IGTRVt3gQ2i-WjoUIjeZxw",
  "dispositions": [
    {
      "disposition_id": "W_VATTk_Q5aW6z5rZtBxAQ",
      "disposition_name": "Inquiry"
    }
  ],
  "queues": [
    {
      "cc_queue_id": "d95avl1eRJ-H162PZUJ-qg",
      "queue_name": "Sales"
    }
  ]
}

Status: 400 HTTP Status Code: `400` Bad Request Error Code: `2513` More than one matching disposition set found.

Status: 401 HTTP Status Code: `401` Unauthorized

Status: 403 HTTP Status Code: `403` Forbidden

Status: 404 HTTP Status Code: `404` Not Found Error Code: `2501` Disposition Set does not exist: $setId.

Status: 429 HTTP Status Code: `429` Too Many Requests. For more information, see [rate limits](https://developers.zoom.us/docs/api/rate-limits/).

Delete a disposition set

Method: DELETE
Path: /contact_center/dispositions/sets/{dispositionSetId}
Tags: Dispositions

Delete a disposition set.

Scopes: contact_center_disposition:write:admin

Granular Scopes: contact_center:delete:disposition_set:admin

Rate Limit Label: LIGHT

Responses

Status: 204 HTTP Status Code: `204 ` Disposition Set deleted.

Status: 400 HTTP Status Code: `400` Bad Request

Status: 401 HTTP Status Code: `401` Unauthorized

Status: 403 HTTP Status Code: `403` Forbidden

Status: 404 HTTP Status Code: `404` Not Found Error Code: `2501` Set does not exist: $setId.

Status: 429 HTTP Status Code: `429` Too Many Requests. For more information, see [rate limits](https://developers.zoom.us/docs/api/rest/rate-limits/).

Update a disposition set

Method: PATCH
Path: /contact_center/dispositions/sets/{dispositionSetId}
Tags: Dispositions

Update an existing disposition set.

Scopes: contact_center_disposition:write:admin

Granular Scopes: contact_center:update:disposition_set:admin

Rate Limit Label: LIGHT

Request Body

Content-Type: application/json

disposition_ids

array — A list of disposition IDs to add to the set.

Items:

string — The disposition's ID.
disposition_set_description

string — The set's description.
disposition_set_name

string — The set's name.
status

string, possible values: "inactive", "active" — The set's active status. * `inactive` — Deactivated. * `active` — Activated.

Example:

{
  "disposition_set_name": "Lead created",
  "disposition_set_description": "New leads generated.",
  "status": "inactive",
  "disposition_ids": [
    "W_VATTk_Q5aW6z5rZtBxAQ"
  ]
}

Responses

Status: 204 HTTP Status Code: `204` Set updated.

Status: 400 HTTP Status Code: `400` Bad Request Error Code: `2502` That set name already exists. Use a different name.

Status: 401 HTTP Status Code: `401` Unauthorized

Status: 403 HTTP Status Code: `403` Forbidden

Status: 404 HTTP Status Code: `404` Not Found Error Code: `2501` Set does not exist: $dispositionSetId. Error Code: `2403` Dispositions do not exist: $disposition_ids.

Status: 429 HTTP Status Code: `429` Too Many Requests. For more information, see [rate limits](/docs/api/rest/rate-limits/).

Get a disposition

Method: GET
Path: /contact_center/dispositions/{dispositionId}
Tags: Dispositions

Retrieve information about a disposition.

Scopes: contact_center_disposition:read:admin

Granular Scopes: contact_center:read:disposition:admin

Rate Limit Label: LIGHT

Responses

Status: 200 HTTP Status Code: `200` Disposition returned.

Content-Type: application/json

disposition_description

string — The disposition's description.
disposition_id

string — The disposition's ID.
disposition_name

string — The disposition's name.
disposition_type

string, possible values: "single", "multi_level" — The disposition's type.
last_modified_time

string, format: date-time — The date and time when this data was last modified.
modified_by

string — The ID of the user that last modified this data.
queue_count

integer — The number of queues associated with the disposition.
status

string, possible values: "inactive", "active" — The disposition's active status. * `inactive` - Deactivated. * `active` - Activated.
sub_dispositions

array — The list of sub-dispositions.

Items:
- current_index
  
  number — The sub-disposition's unique identifier.
- parent_index
  
  number — The index of the parent node that the current sub-disposition belongs to. `parent_index` - `0` means that the parent node of the current node is the root node.
- sub_disposition_id
  
  string — The sub-disposition's ID.
- sub_disposition_name
  
  string — The sub-disposition's name.

Example:

{
  "disposition_id": "W_VATTk_Q5aW6z5rZtBxAQ",
  "disposition_name": "Inquiry",
  "disposition_description": "Inquiry dispositions.",
  "status": "inactive",
  "queue_count": 0,
  "last_modified_time": "2022-02-15T09:27:15Z",
  "modified_by": "IGTRVt3gQ2i-WjoUIjeZxw",
  "disposition_type": "multi_level",
  "sub_dispositions": [
    {
      "sub_disposition_id": "OYTRVt3gQ2iAGjoUIjeZxq",
      "sub_disposition_name": "Sub-Disposition A",
      "current_index": 1,
      "parent_index": 1
    }
  ]
}

Status: 400 HTTP Status Code: `400` Bad Request Error Code: `2404` More than one matching disposition found.

Status: 401 HTTP Status Code: `401` Unauthorized

Status: 403 HTTP Status Code: `403` Forbidden

Status: 404 HTTP Status Code: `404` Not Found Error Code: `2401` Disposition does not exist: $dispositionId.

Status: 429 HTTP Status Code: `429` Too Many Requests. For more information, see [rate limits](https://developers.zoom.us/docs/api/rate-limits/).

Delete a disposition

Method: DELETE
Path: /contact_center/dispositions/{dispositionId}
Tags: Dispositions

Delete an existing disposition.

Scopes: contact_center_disposition:write:admin

Granular Scopes: contact_center:delete:disposition:admin

Rate Limit Label: LIGHT

Responses

Status: 204 HTTP Status Code: `204 ` Disposition deleted.

Status: 400 HTTP Status Code: `400` Bad Request

Status: 401 HTTP Status Code: `401` Unauthorized

Status: 403 HTTP Status Code: `403` Forbidden

Status: 404 HTTP Status Code: `404` Not Found Error Code: `2401` Disposition does not exist: $dispositionId.

Status: 429 HTTP Status Code: `429` Too Many Requests. For more information, see [rate limits](https://developers.zoom.us/docs/api/rest/rate-limits/).

Update a disposition

Method: PATCH
Path: /contact_center/dispositions/{dispositionId}
Tags: Dispositions

Update an existing disposition.

Scopes: contact_center_disposition:write:admin

Granular Scopes: contact_center:update:disposition:admin

Rate Limit Label: LIGHT

Request Body

Content-Type: application/json

disposition_description

string — The disposition's description.
disposition_name

string — The disposition's name.
disposition_type

string, possible values: "single", "multi_level", default: "single" — The disposition's type.
status

string, possible values: "inactive", "active" — The disposition's active status. * `inactive` — Deactivated. * `active` — Activated.
sub_dispositions

array — For `single` dispositions, this field can be ignored. For `multi_level` dispositions, there must be at least one subdispositions, there can be up to 500, and each parent node can have up to 20 child nodes. At the same time, child nodes can only have up to 4 levels.

Items:
- current_index (required)
  
  number — The subdisposition's unique identifier.
- parent_index (required)
  
  number — The index of the parent node to which the current node belongs. If it is `0`, it means that the current node belongs to the root node. If the parent index does not exist, the node will be discarded.
- sub_disposition_name (required)
  
  string — The subdisposition's name.
- sub_disposition_id
  
  string — The subdisposition's ID.

Example:

{
  "disposition_name": "Inquiry",
  "status": "inactive",
  "disposition_description": "Inquiry dispositions.",
  "disposition_type": "multi_level",
  "sub_dispositions": [
    {
      "sub_disposition_id": "HDLHFK_gdhgfajhsedfhg",
      "sub_disposition_name": "Subdisposition A",
      "current_index": 1,
      "parent_index": 0
    }
  ]
}

Responses

Status: 204 HTTP Status Code: `204` Disposition updated.

Status: 400 HTTP Status Code: `400` Bad Request Error Code: `2402` That disposition name already exists. Use a different name. Error Code: `2504` Sub disposition's total size should be less than or equal to 500. Error Code: `2507` Multi_level disposition no subdispositions. Error Code: `2508` Duplicate subdisposition name on the same tier. Error Code: `2509` Sub disposition tier size should be more than 0 and less than 5. Error Code: `2510` Can not update `multi_level` to single. Error Code: `2512` The number of sub dispositions on the same tier should less than or equal to 20. Error Code: `2505` Sub Disposition current index repeated. Error Code: `2514` Sub Disposition current_index is required. Error Code: `2515` Sub Disposition parent_index is required.

Status: 401 HTTP Status Code: `401` Unauthorized

Status: 403 HTTP Status Code: `403` Forbidden

Status: 404 HTTP Status Code: `404` Not Found Error Code: `2401` Disposition does not exist: $dispositionId.

Status: 429 HTTP Status Code: `429` Too Many Requests. For more information, see [rate limits](/docs/api/rate-limits/).

Start an engagement

Method: POST
Path: /contact_center/engagement
Tags: Engagements

Start an engagement. Currently only supports the Work Item channel.

Note When creating a work item, variable conflicts are resolved using these guidelines.

If a key exists in both consumerInfo and variableList, the value from consumerInfo takes precedence.
If duplicate keys are provided within variableList, only the first occurrence is used.
If a key appears only once in variableList, the provided value is applied.

Scopes: contact_center_engagement:write:admin

Granular Scopes: contact_center:write:engagement:admin

Rate Limit Label: LIGHT

Request Body

Content-Type: application/json

channels

array — The task's channels. It contains only one element when starting an engagement.

Items:
- channel (required)
  
  string, possible values: "work_item" — The channel you want to start. Currently only supports `work_item`.
- channel_source (required)
  
  string, possible values: "API" — The channel source you want to start. Currently only supports `API`.
consumers

array — Consumer information. Contains only one element when starting an engagement.

Items:
- consumer_display_name (required)
  
  string — The consumer's name.
- consumer_email
  
  string — The consumer's email.
- consumer_external_id
  
  string — A unique identifier for the consumer initiating the conversation.
- consumer_number
  
  string — The consumer's phone number, in E.164 format. Maximum length is 15 characters.
flow

object — The flow info required to start a new engagement.
- flow_entry_id (required)
  
  string — The `flow_entry_id`, which should be bound to a Contact Center flow.
language_code

string — Equivalent to setting the `global_system.Engagement.language` variable. Default value is `en-US`. |Language | Value| | - | - | | Chinese (Simplified) | zh-CN | | Chinese (Traditional) | zh-TW | | Chinese Cantonese | yue-CN | | Chinese Mandarin | cmn-CN | | Danish (Denmark) |da-DK| | Dutch (Netherlands) | nl-NL | | English (Australia) | en-AU | | English (New Zealand) | en-NZ | | English (UK) | en-GB | | English (US) | en-US | | French (Canada) | fr-CA | | French (France) | fr-FR | |German (Germany) | de-DE | | Italian (Italy) | it-IT | | Japanese (Japan) |ja-JP | | Korean (Korea) | ko-KR | | Polish (Poland) | pl-PL | | Portuguese (Brazil) | pt-BR | | Portuguese (Portugal) |pt-PT | |Romanian (Romania) | ro-RO | | Russian (Russia) | ru-RU| | Spanish (European) | es-ES | |Spanish (Mexico) | es-MX | |Spanish (US) | es-US | | Swedish (Sweden) | sv-SE| | Turkish (Turkey) | tr-TR|
variables

array — Global variables.\nFor more information, see [Variables](/docs/api/contact-center/#tag/variables).

Items:
- name (required)
  
  string — The variable's name.
- value (required)
  
  string — The variable's value.
work_item_variables

object — The variables required to initiate a work item engagement.
- work_item_name (required)
  
  string — Each work item's name or title.
- work_item_desc
  
  string — The work item's description.
- work_item_due_date
  
  string — The work item's due date in `YYYY-MM-DDTHH:mm:ssZ` format. Time zone is `UTC`.
- work_item_hyperlink
  
  string — The link to the work item's detail.
- work_item_id
  
  string — The request's unique identifier, used to ensure idempotency. We recommended using a UUID format.
- work_item_origin
  
  string — Where or how each work item was created.
- work_item_priority
  
  integer — The work item's priority.
- work_item_transcript_url
  
  string — Ingest and store an external transcript in the Contact Center. When provided, the associated transcript becomes accessible to agents directly from the work item while they are handling it.
- work_item_type
  
  string — This field is automatically populated during engagement creation based on the configured settings. It will also be included in the response payload.
- work_item_type_id
  
  string — The work item source type's ID. Find the work item type ID in the Contact Center's **Preferences**.

Example:

{
  "work_item_variables": {
    "work_item_id": "24fwet23525",
    "work_item_name": "Research the market performance of competing companies.",
    "work_item_desc": "Conduct an in-depth analysis of key competitors' overall performance in the target market, including but not limited to market share, sales trends, product positioning, pricing strategies, distribution channels, and recent market activities.",
    "work_item_type_id": "w3pOm-CLRHmugqYIiByYHg",
    "work_item_due_date": "2025-10-01T00:00:00Z",
    "work_item_origin": "chat system",
    "work_item_priority": 1,
    "work_item_transcript_url": "https://api.example.com/v2/transcripts/download/yJAEEra27v4InERTcm77LQ",
    "work_item_hyperlink": "www.example.com/ticket123"
  },
  "flow": {
    "flow_entry_id": "4ad5A8qLTIunwdlpzSS4lg"
  },
  "language_code": "en-US",
  "channels": [
    {
      "channel": "work_item",
      "channel_source": "API"
    }
  ],
  "consumers": [
    {
      "consumer_external_id": "yJAEEra27v4InERTcm77LQ",
      "consumer_display_name": "Jill Doe",
      "consumer_email": "JillDoe@example.com",
      "consumer_number": "+1234561212"
    }
  ],
  "variables": [
    {
      "name": "global_custom.user.name",
      "value": "123"
    }
  ]
}

Responses

Status: 201 Engagement information.

Content-Type: application/json

engagement_id (required)

string — Engagement ID.
start_time (required)

string — Engagement start time in `YYYY-MM-DDThh:mm:ssZ` format. Time zone is `UTC`.
channels

array — The task's channels. It contains only one element when starting an engagement.

Items:
- channel
  
  string, possible values: "work_item" — The channel you want to start. Currently only supports `work_item`.
- channel_source
  
  string, possible values: "API" — The channel source you want to start. Currently only supports `API`.
consumers

array — A list of consumer information. It contains only one element when starting an engagement.

Items:
- consumer_display_name
  
  string — The consumer's name.
- consumer_email
  
  string — The consumer's email.
- consumer_external_id
  
  string — A unique identifier for the consumer initiating the conversation.
- consumer_id
  
  string — The consumer's ID.
- consumer_number
  
  string — The user's phone number in E.164 format. Maximum length is 15 characters.
flows

array — Information about the engagement's flows.

Items:
- flow_entry_id
  
  string — The `flow_entry_id` bound to a Contact Center flow.
- flow_id
  
  string — The flow's ID.
- flow_name
  
  string — The flow's name.
- flow_version
  
  string — The flow's version.
language_code

string — Engagement language code.
session_id

string — Session ID.
variables

array — Global variables. For more information, see [Variables](/docs/api/contact-center/#tag/variables)

Items:
- name
  
  string — The variable's name.
- value
  
  string — The variable's value.
work_item_variables

object
- work_item_desc
  
  string — The work item's description.
- work_item_due_date
  
  string — The work item's due date in `YYYY-MM-DDTHH:mm:ss` format. Time zone is `UTC`.
- work_item_hyperlink
  
  string — The link to the work item's detail.
- work_item_id
  
  string — The request's unique identifier, used to ensure idempotency. We recommend using UUID format.
- work_item_name
  
  string — The work item's name or title.
- work_item_origin
  
  string — Where or how the work item was created.
- work_item_priority
  
  string — The work item's priority.
- work_item_source_id
  
  string — Same as work item type's ID.
- work_item_transcript_url
  
  string — Ingest and store an external transcript in the Contact Center. When provided, the associated transcript becomes accessible to agents directly from the work item while they are handling it.
- work_item_type
  
  string — The work item type's name.
- work_item_type_id
  
  string — The work item source type's ID. **Note** This field is not yet supported.

Example:

{
  "work_item_variables": {
    "work_item_name": "Research the market performance of competing companies.",
    "work_item_desc": "Conduct an in-depth analysis of key competitors' overall performance in the target market, including but not limited to market share, sales trends, product positioning, pricing strategies, distribution channels, and recent market activities.",
    "work_item_type": "ticket",
    "work_item_id": "24fwet23525",
    "work_item_due_date": "2025-10-01T00:00:00",
    "work_item_origin": "chat system",
    "work_item_priority": "1",
    "work_item_transcript_url": "https://api.example.com/v2/transcripts/download/yJAEEra27v4InERTcm77LQ",
    "work_item_hyperlink": "www.example.com/ticket123",
    "work_item_type_id": "w3pOm-CLRHmugqYIiByYHg"
  },
  "flows": [
    {
      "flow_entry_id": "4ad5A8qLTIunwdlpzSS4lg",
      "flow_id": "zeYjXoDOS_eV1QmTpj63PQ",
      "flow_name": "Demo",
      "flow_version": "5"
    }
  ],
  "session_id": "z7bc2vC5TPSliVBO4dhaoQ",
  "engagement_id": "vj9yy02ZTsyK22boIf2dww",
  "language_code": "en-US",
  "channels": [
    {
      "channel": "work_item",
      "channel_source": "API"
    }
  ],
  "start_time": "2025-09-01T00:00:00Z",
  "consumers": [
    {
      "consumer_id": "zeYjXoDOS_eV1QmTpj63PQ",
      "consumer_external_id": "yJAEEra27v4InERTcm77LQ",
      "consumer_display_name": "Jill Doe",
      "consumer_email": "JillDoe@example.com",
      "consumer_number": "+1234561212"
    }
  ],
  "variables": [
    {
      "name": "global_custom.user.name",
      "value": "123"
    }
  ]
}

Status: 400 HTTP Status Code: `400` Bad Request

Status: 401 HTTP Status Code: `401` Unauthorized Error Code: `124` Invalid access token. Error Code: `124` Access token has expired. Error Code: `1002` The user associated with this access token was not found or is invalid.

Status: 403 HTTP Status Code: `403` Forbidden Error Code: `1021` User account is deactivated. Error Code: `1022` User does not have a Contact Center license. Error Code: `9001` The Contact Center user associated with this bearer token is missing privileges on their role required to operate this request.

Status: 409 HTTP Status Code: `409` Conflict Error Code: `8000007` Repeated request. Error Code: `8000017` Lock failed.

Status: 429 HTTP Status Code: `429` Too Many Requests. For more information, see [rate limits](https://developers.zoom.us/docs/api/rate-limits/). Error Code: `4001` You have reached the maximum per-second rate limit for this API. Try again later.

List engagements

Method: GET
Path: /contact_center/engagements
Tags: Engagements

Return a list of engagement detail objects. Engagements are available via API once they have completed processing, not immediately after they end.

You may retry this request for up to 1 minute to get engagement details for a specific engagement, if querying shortly after an engagement_ended webhook event. Consider using a backoff between retries, to avoid rate limiting.

Scopes: contact_center_report:read:admin

Granular Scopes: contact_center:read:list_engagements:admin

Rate Limit Label: HEAVY

Responses

Status: 200 HTTP Status Code: `200` Engagements returned.

Content-Type: application/json

engagements

array — A list of engagement detail objects.

Items:
- agents
  
  array — Information about the engagement's agents.
  
  Items:
  - display_name
    
    string — The user's display name.
  - user_id
    
    string — The Meetings user identifier.
- callback_voice_messages
  
  array — The callback voice messages.
  
  Items:
  - callback_voice_message_transcript_url
    
    string — The URL to download the callback voice message transcript, if the transcript text file exists. For security purposes, you **must** provide an OAuth access token in the authorization header to download the transcript file using this URL.
  - callback_voice_message_url
    
    string — The URL to download the callback voice recording, if the recording file exists. For security purposes, you **must** provide an OAuth access token in the authorization header to download the recording file using this URL.
- channel_types
  
  array — The channel's type.
  
  Items:
  
  string, possible values: "voice", "sms", "chat", "video", "kiosk", "in_app_chat", "in_app_video"
- channels
  
  array — The engagement's channels.
  
  Items:
  - channel
    
    string, possible values: "voice", "video", "messaging", "email" — The engagement's channel.
  - channel_source
    
    string, possible values: "in_app_video", "kiosk_video", "web_video", "web_chat", "in_app_chat", "sms", "facebook_messenger", "whatsapp", "email_address" — The channel's source. * `in_app_video` - Only applies to video channel. * `kiosk_video` - Only applies to video channel. * `web_video` - Only applies to video channel. * `in_app_chat` - Only applies to messaging channel. * `web_chat` - Only applies to messaging channel. * `sms` - Only applies to messaging channel. * `facebook_messenger` - Only applies to messaging channel. * `whatsapp` - Only applies to messaging channel. * `email_address` - Only applies to email channel.
- consumers
  
  array — Information about the consumers.
  
  Items:
  - consumer_display_name
    
    string — The consumer's name.
  - consumer_id
    
    string — The consumer's ID.
  - consumer_number
    
    string — The consumer's phone number.
- direction
  
  string — The engagement's direction.
- dispositions
  
  array — Information about the dispositions.
  
  Items:
  - disposition_id
    
    string — The disposition's ID.
  - disposition_name
    
    string — The disposition's name.
- duration
  
  integer, format: int64 — The engagement's duration, in seconds.
- end_time
  
  string, format: date-time — The date and time when the engagement ended. Format is either `yyyy-MM-dd'T'HH:mm:ss'Z'` or `yyyy-MM-dd'T'HH:mm:ss±HH:mm`, matching the input format when a timezone offset was provided in the `from`/`to` parameters. Time is adjusted to the specified timezone.
- engagement_id
  
  string — The engagement's ID.
- flow_duration
  
  integer, format: int64 — The engagement's flow duration, in seconds.
- flows
  
  array — Information about the engagement's flows.
  
  Items:
  - flow_id
    
    string — The flow's ID.
  - flow_name
    
    string — The flow's name.
  - flow_version
    
    string — The flow's version.
- handling_duration
  
  integer, format: int64 — The engagement's handling duration, in seconds.
- notes
  
  array — Information about the notes.
  
  Items:
  - last_modified_time
    
    string, format: date-time — The date and time when this data was last modified.
  - note
    
    string — The note's content.
  - note_id
    
    string — The note's ID.
  - user_id
    
    string — The Meetings user identifier.
- queue_wait_type
  
  string, possible values: "live_waiting", "callback" — The engagement's queue wait type.
- queues
  
  array — Information about the engagement's queues.
  
  Items:
  - cc_queue_id
    
    string — The Contact Center queue identifier.
  - queue_id
    
    string — The task queue's identifier. **Deprecated** - use the `cc_queue_id` field to reference the Contact Center queue.
  - queue_name
    
    string — The Contact Center queue name.
- start_time
  
  string, format: date-time — The date and time when the engagement started. Format is either `yyyy-MM-dd'T'HH:mm:ss'Z'` or `yyyy-MM-dd'T'HH:mm:ss±HH:mm`, matching the input format when a timezone offset was provided in the `from`/`to` parameters. Time is adjusted to the specified timezone.
- survey_id
  
  string — The survey's ID.
- talk_duration
  
  integer, format: int64 — The engagement's talk duration, in seconds.
- transcript_url
  
  string — The URL to download the messaging transcript, if the transcript text file exists. This field is only used for messaging engagements. For voice and video engagement recordings, see the List engagement recordings API. For security purposes, you **must** provide an OAuth access token in the authorization header to download the transcript file using this URL. The app used to generate the token must have the granular scope `contact_center:read:engagement:admin` or the classic scope `contact_center_report:read:admin`. Example: ``` curl --request GET \ --url {transcript_url} \ --header 'Authorization: Bearer {access_token}' \ --header 'Content-Type: application/json' ```
- transfer_count
  
  integer, format: int32 — The engagement's transfer count.
- transferCount
  
  integer, format: int32 — The engagement's transfer count.
- voice_mail
  
  integer, format: int32 — The number of voicemails for the engagement.
- waiting_duration
  
  integer, format: int64 — The engagement's waiting duration, in seconds.
- wrap_up_duration
  
  integer, format: int64 — The engagement's wrap-up duration, in seconds.
from

string, format: date-time — The start time and date. If the input was `yyyy-MM-dd`, it is expanded to `yyyy-MM-ddT00:00:00Z`. Otherwise, the input format is preserved as either `yyyy-MM-dd'T'HH:mm:ss'Z'` or `yyyy-MM-dd'T'HH:mm:ss±HH:mm`.
next_page_token

string — Use the next page token to paginate through large result sets. A next page token is returned whenever the set of available results exceeds the current page size. This token's expiration period is 15 minutes.
page_size

integer, default: 10 — The number of records returned within a single API call.
timezone

string — The engagement's [timezone ID](/docs/api/references/abbreviations/#timezones). The default is UTC.
to

string, format: date-time — The end time and date. If the input was `yyyy-MM-dd`, it is expanded to `yyyy-MM-ddT23:59:59Z`. Otherwise, the input format is preserved as either `yyyy-MM-dd'T'HH:mm:ss'Z'` or `yyyy-MM-dd'T'HH:mm:ss±HH:mm`.
total_records

integer — The total number of all records available across pages.

Example:

{
  "next_page_token": "R4aF9Oj0fVM2hhezJTEmSKaBSkfesDwGy42",
  "page_size": 10,
  "total_records": 10,
  "timezone": "America/Los_Angeles",
  "from": "2021-12-10T00:00:00Z",
  "to": "2021-12-10T23:59:59Z",
  "engagements": [
    {
      "start_time": "2021-12-03T13:07:46Z",
      "end_time": "2021-12-03T13:07:46Z",
      "duration": 3600,
      "engagement_id": "W_VATTk_Q5aW6z5rZtBxAQ",
      "direction": "inbound",
      "channels": [
        {
          "channel": "messaging",
          "channel_source": "in_app_chat"
        }
      ],
      "consumers": [
        {
          "consumer_id": "zeYjXoDOS_eV1QmTpj63PQ",
          "consumer_display_name": "Jill",
          "consumer_number": "+12058945728"
        }
      ],
      "flows": [
        {
          "flow_id": "zeYjXoDOS_eV1QmTpj63PQ",
          "flow_name": "Demo",
          "flow_version": "5"
        }
      ],
      "queues": [
        {
          "cc_queue_id": "a4lCNeq2SzKbgkcDVbjCZQ",
          "queue_name": "Voice - Customer Support"
        }
      ],
      "agents": [
        {
          "user_id": "IGTRVt3gQ2i-WjoUIjeZxw",
          "display_name": "Jane Doe"
        }
      ],
      "talk_duration": 10,
      "flow_duration": 10,
      "waiting_duration": 10,
      "handling_duration": 0,
      "wrap_up_duration": 10,
      "transfer_count": 10,
      "dispositions": [
        {
          "disposition_id": "W_VATTk_Q5aW6z5rZtBxAQ",
          "disposition_name": "Inquiry"
        }
      ],
      "notes": [
        {
          "user_id": "IGTRVt3gQ2i-WjoUIjeZxw",
          "note_id": "W_VATTk_Q5aW6z5rZtBxAQ",
          "note": "This is the content of the note.",
          "last_modified_time": "2022-02-15T09:27:15Z"
        }
      ],
      "transcript_url": "https://api.example.com/v2/contact_center/engagements/transcripts/download/W_VATTk_Q5aW6z5rZtBxAQ",
      "survey_id": "2yWjT4awTumcFKIrvcf4OA",
      "voice_mail": 1,
      "queue_wait_type": "live_waiting",
      "callback_voice_messages": [
        {
          "callback_voice_message_url": "https://api.zoom.us/v2/contact_center/consumer_callback/voice_messages/4Q0ILNMfTA2nJolNxhg0Rw/download",
          "callback_voice_message_transcript_url": "https://api.zoom.us/v2/contact_center/consumer_callback/voice_messages/4Q0ILNMfTA2nJolNxhg0Rw/transcript"
        }
      ]
    }
  ]
}

Status: 400 HTTP Status Code: `400` Bad Request Error Code: `300` Invalid field. Error Code: `124` Invalid access token. Error Code: `300` The requested report exceeds the 1-month limit. Error Code: `300` The time and date must be in yyyy-mm-dd or ISO 8601 format (yyyy-MM-dd'T'HH:mm:ss'Z' or yyyy-MM-dd'T'HH:mm:ss'TZD'). Error Code: `300` Timezone does not exist: {timezone}.

Status: 401 HTTP Status Code: `401` Unauthorized Error Code: `1001` The user associated with this access token was not found or is invalid. Error Code: `1601` Access denied. Invalid or insufficient permissions.

Status: 403 HTTP Status Code: `403` Forbidden Error Code: `9001` The Contact Center user associated with this bearer token is missing privileges on their role required to operate this request.

Status: 404 HTTP Status Code: `404` Not Found Error Code: `1201` Queue does not exist: {queueId}. Error Code: `1001` User does not exist: {userId}.

Status: 429 HTTP Status Code: `429` Too Many Requests. For more information, see [rate limits](https://developers.zoom.us/docs/api/rest/rate-limits/). Error Code: `4001` You have reached the maximum per-second rate limit for this API. Try again later.

Get an engagement

Method: GET
Path: /contact_center/engagements/{engagementId}
Tags: Engagements

Retrieve information about an engagement. Engagements are available via API once they have completed processing, not immediately after they end. This API may return an empty response while the data is persisting.

You may need to retry this request for up to 1 minute to get engagement details, if querying shortly after an engagement_ended webhook event. Consider using a backoff between retries to avoid rate limiting.

Scopes: contact_center_report:read:admin

Granular Scopes: contact_center:read:engagement:admin

Rate Limit Label: LIGHT

Responses

Status: 200 HTTP Status Code: `200` Engagement information returned.

Content-Type: application/json

agents

array — Information about the engagement's agents.

Items:
- display_name
  
  string — The agent's name.
- user_id
  
  string — The agent's ID.
callback_voice_messages

array — The callback voice messages.

Items:
- callback_voice_message_transcript_url
  
  string — The URL to download the callback voice message transcript, if the transcript text file exists. For security purposes, you **must** provide an OAuth access token in the authorization header to download the transcript file using this URL.
- callback_voice_message_url
  
  string — The URL to download the callback voice recording, if the recording file exists. For security purposes, you **must** provide an OAuth access token in the authorization header to download the recording file using this URL.
channel_types

array — The channel's type. * voice * SMS * chat * video * kiosk * in_app_chat * in_app_video

Items:

string, possible values: "voice", "sms", "chat", "video", "kiosk", "in_app_chat", "in_app_video"
channels

array — The task's channels.

Items:
- channel
  
  string, possible values: "voice", "video", "messaging", "email" — The task's channel. * `voice` * `video` * `messaging` * `email`
- channel_source
  
  string, possible values: "in_app_video", "kiosk_video", "web_video", "web_chat", "in_app_chat", "sms", "facebook_messenger", "whatsapp", "email_address" — The channel's source. * `in_app_video` - Only applies to video channel. * `kiosk_video` - Only applies to video channel. * `web_video` - Only applies to video channel. * `in_app_chat` - Only applies to messaging channel. * `web_chat` - Only applies to messaging channel. * `sms` - Only applies to messaging channel. * `facebook_messenger` - Only applies to messaging channel. * `whatsapp` - Only applies to messaging channel. * `email_address` - Only applies to email channel.
consumers

array — Information about the customers.

Items:
- consumer_display_name
  
  string — The customer's name.
- consumer_id
  
  string — The customer's ID.
- consumer_number
  
  string — The customer's phone number.
direction

string, possible values: "inbound", "outbound" — The session's direction. `inbound` | `outbound`.
dispositions

array — Information about the dispositions.

Items:
- disposition_id
  
  string — The disposition's ID.
- disposition_name
  
  string — The disposition's name.
duration

integer, format: int64 — The engagement's duration, in seconds.
end_time

string, format: date-time — The date and time when the engagement ended. Always returned in `yyyy-MM-dd'T'HH:mm:ss'Z'` format (UTC).
engagement_id

string — The engagement's ID.
events

array — Information about the events.

Items:
- accept_type
  
  string, possible values: "manual", "auto" — The router's accept type. `manual` | `auto`.
- cc_queue_id
  
  string — The Contact Center queue's ID.
- channel
  
  string, possible values: "voice", "video", "messaging", "email" — The task's channel. * `voice` * `video` * `messaging` * `email`
- channel_source
  
  string, possible values: "in_app_video", "kiosk_video", "web_video", "web_chat", "in_app_chat", "sms", "email_address" — The channel's source. * `in_app_video` - Only applies to video channel. * `kiosk_video` - Only applies to video channel. * `web_video` - Only applies to video channel. * `in_app_chat` - Only applies to messaging channel. * `web_chat` - Only applies to messaging channel. * `sms` - Only applies to messaging channel. * `email_address` - Only applies to email channel.
- channel_type
  
  string, possible values: "voice", "sms", "chat", "video", "in_app_chat", "kiosk", "in_app_chat", "in_app_video" — The channel's type. * voice * SMS * chat * video * kiosk * in_app_chat * in_app_video
- conference_type
  
  string, possible values: "cold", "warm" — The conference's type.
- consumer_display_name
  
  string — The customer's name.
- consumer_id
  
  string — The consumer's ID.
- crm_call_status
  
  string, possible values: "ringing", "answer", "hangup", "miss" — The CRM's call status.
- crm_type
  
  string — The CRM's type.
- direction
  
  string, possible values: "inbound", "outbound" — The session's direction. `inbound` | `outbound`.
- duration
  
  integer, format: int64 — The event's duration.
- email_reply_bcc
  
  array — BCC recipients' information when replying to an email.
  
  Items:
  - email_address
    
    string — Email address
  - email_name
    
    string — Email name
- email_reply_cc
  
  array — CC recipients' information when replying to emails.
  
  Items:
  - email_address
    
    string — Email address
  - email_name
    
    string — Email name
- email_reply_to
  
  array — Recipient's information when replying to an email.
  
  Items:
  - email_address
    
    string — Email address
  - email_name
    
    string — Email name
- event_type
  
  string — The event's type.
- flow_id
  
  string — The flow's ID.
- flow_name
  
  string — The flow's name.
- inbox_id
  
  string — The inbox's ID.
- inbox_name
  
  string — The inbox's name.
- invitee
  
  string — The conference's invitee.
- invitee_type
  
  string, possible values: "Agent", "Queue", "PSTN number" — The conference invitee's type.
- queue_id
  
  string — The queue's ID.
- queue_name
  
  string — The queue's name.
- skills
  
  array — Information about the skills.
  
  Items:
  - skill_category_id
    
    string — The skill category's ID.
  - skill_category_name
    
    string — The skill category's name.
  - skill_id
    
    string — The skill's ID.
  - skill_name
    
    string — The skill's name.
  - skill_proficiency_level
    
    integer, format: int32 — The skill's proficiency level. Only proficiency-based skill will have proficiency level.
- start_time
  
  string, format: date-time — The date and time when the event started. Always returned in `yyyy-MM-dd'T'HH:mm:ss'Z'` format (UTC).
- supervisor_display_name
  
  string — The supervisor's name.
- supervisor_id
  
  string — The supervisor's ID.
- transfer_count
  
  integer, format: int32 — The number of transfers during the engagement.
- transfer_to_cc_queue_id
  
  string — The target queue's ID.
- transfer_to_flow_id
  
  string — The target flow's ID.
- transfer_to_flow_name
  
  string — The target flow's name.
- transfer_to_number
  
  string — The transfer's number.
- transfer_to_queue_id
  
  string — The target queue's ID.
- transfer_to_queue_name
  
  string — The target flow's ID.
- transfer_to_user_display_name
  
  string — The target agent's name.
- transfer_to_user_id
  
  string — The target agent's ID.
- transfer_type
  
  string, possible values: "cold", "warm" — The transfer's type.
- upgraded_to_channel_type
  
  string, possible values: "video" — The target upgraded channel's type.
- user_display_name
  
  string — The agent's name.
- user_id
  
  string — The agent's ID.
flow_duration

integer, format: int64 — The engagement's flow duration, in seconds.
flows

array — Information about the engagement's flows.

Items:
- flow_id
  
  string — The flow's ID.
- flow_name
  
  string — The flow's name.
- flow_version
  
  string — The flow's version.
handling_duration

integer, format: int64 — The handling duration, in seconds. This setting applies to voice channels.
notes

array — Information about the notes.

Items:
- last_modified_time
  
  string, format: date-time — The date and time when this data was last modified.
- note
  
  string — The note's content.
- note_id
  
  string — The note's ID.
- user_id
  
  string — The agent's ID.
queue_wait_type

string, possible values: "live_waiting", "callback" — The queue's wait type.
queues

array — Information about the engagement's queues.

Items:
- cc_queue_id
  
  string — The Contact Center queue's ID.
- queue_id
  
  string — The queue's ID.
- queue_name
  
  string — The queue's name.
start_time

string, format: date-time — The date and time when the engagement started. Always returned in `yyyy-MM-dd'T'HH:mm:ss'Z'` format (UTC).
survey_id

string — The survey's ID.
talk_duration

integer, format: int64 — The engagement's talk duration, in seconds.
transcript_url

string — The URL to download the messaging transcript, if the transcript text file exists. This field is only used for messaging engagements. For voice and video engagement recordings, see the `List engagement recordings` API. For security purposes, you **must** provide an OAuth access token in the authorization header to download the transcript file using this URL. **Example**:\r\n```curl --request GET \r\n --url {transcript_url} \r\n --header 'authorization: Bearer {access_token}' \r\n --header 'content-type: application/json'\r\n```
voice_mail

integer, format: int32 — The voicemail count.
waiting_duration

integer, format: int64 — The engagement's waiting duration, in seconds.
wrap_up_duration

integer, format: int64 — The engagement's wrap-up duration, in seconds.

Example:

{
  "start_time": "2021-12-03T13:07:46Z",
  "end_time": "2021-12-03T13:07:46Z",
  "duration": 3600,
  "engagement_id": "W_VATTk_Q5aW6z5rZtBxAQ",
  "channels": [
    {
      "channel": "video",
      "channel_source": "in_app_video"
    }
  ],
  "consumers": [
    {
      "consumer_id": "zeYjXoDOS_eV1QmTpj63PQ",
      "consumer_display_name": "Jill",
      "consumer_number": "+12058945728"
    }
  ],
  "direction": "inbound",
  "flows": [
    {
      "flow_id": "zeYjXoDOS_eV1QmTpj63PQ",
      "flow_name": "Demo",
      "flow_version": "5"
    }
  ],
  "queues": [
    {
      "cc_queue_id": "d95avl1eRJ-H162PZUJ-qg",
      "queue_name": "agentQueue"
    }
  ],
  "agents": [
    {
      "user_id": "ukAAkZKfROKMSw1bj_RDFQ",
      "display_name": "Jilly"
    }
  ],
  "queue_wait_type": "live_waiting",
  "talk_duration": 10,
  "flow_duration": 10,
  "waiting_duration": 10,
  "handling_duration": 0,
  "wrap_up_duration": 10,
  "voice_mail": 10,
  "dispositions": [
    {
      "disposition_id": "W_VATTk_Q5aW6z5rZtBxAQ",
      "disposition_name": "Inquiry"
    }
  ],
  "notes": [
    {
      "user_id": "ukAAkZKfROKMSw1bj_RDFQ",
      "note_id": "W_VATTk_Q5aW6z5rZtBxAQ",
      "note": "This is the content of the note.",
      "last_modified_time": "2022-02-15T09:27:15Z"
    }
  ],
  "events": [
    {
      "start_time": "2021-12-03T13:07:46Z",
      "duration": 3600,
      "channel": "video",
      "channel_source": "in_app_video",
      "event_type": "Agent Ringing",
      "direction": "inbound",
      "flow_id": "zwKiV80hQ7CwRg9BEm0Bvw",
      "flow_name": "Demo",
      "cc_queue_id": "d95avl1eRJ-H162PZUJ-qg",
      "queue_name": "Sales",
      "user_id": "ukAAkZKfROKMSw1bj_RDFQ",
      "user_display_name": "Jilly",
      "accept_type": "manual",
      "transfer_to_flow_id": "zwKiV80hQ7CwRg9BEm0Bvw",
      "transfer_to_flow_name": "Demo",
      "transfer_to_cc_queue_id": "d95avl1eRJ-H162PZUJ-qg",
      "transfer_to_queue_name": "Sales",
      "transfer_to_user_id": "zwKiV80hQ7CwRg9BEm0Bvw",
      "transfer_to_user_display_name": "Jilly",
      "transfer_to_number": "+12059300920",
      "transfer_type": "cold",
      "transfer_count": 2,
      "upgraded_to_channel_type": "video",
      "crm_type": "salesforce",
      "crm_call_status": "ringing",
      "supervisor_id": "kRQpbWO5TV6E7wxEYOKFWw",
      "supervisor_display_name": "Jilly",
      "consumer_id": "zeYjXoDOS_eV1QmTpj63PQ",
      "consumer_display_name": "Jill",
      "inbox_id": "W_VATTk_Q5aW6z5rZtBxAQ",
      "inbox_name": "example",
      "conference_type": "cold",
      "invitee_type": "PSTN number",
      "invitee": "+14244108479",
      "skills": [
        {
          "skill_category_id": "Mu_IEZZHQZGMY9avK74kwA",
          "skill_category_name": "Languages",
          "skill_id": "saaHWgVMGQU69soco456oNA",
          "skill_name": "French",
          "skill_proficiency_level": 3
        }
      ],
      "email_reply_to": [
        {
          "email_address": "jill.chill@example.com",
          "email_name": "Jill Chill"
        }
      ],
      "email_reply_cc": [
        {
          "email_address": "jill.chill@example.com",
          "email_name": "Jill Chill"
        }
      ],
      "email_reply_bcc": [
        {
          "email_address": "jill.chill@example.com",
          "email_name": "Jill Chill"
        }
      ]
    }
  ],
  "transcript_url": "https://api.zoom.us/v2/contact_center/engagements/transcripts/download/W_VATTk_Q5aW6z5rZtBxAQ",
  "survey_id": "2yWjT4awTumcFKIrvcf4OA",
  "callback_voice_messages": [
    {
      "callback_voice_message_url": "https://api.zoom.us/v2/contact_center/consumer_callback/voice_messages/4Q0ILNMfTA2nJolNxhg0Rw/download",
      "callback_voice_message_transcript_url": "https://api.zoom.us/v2/contact_center/consumer_callback/voice_messages/4Q0ILNMfTA2nJolNxhg0Rw/transcript"
    }
  ]
}

Status: 400 HTTP Status Code: `400` Bad Request Error Code: `124` Invalid access token.

Status: 401 HTTP Status Code: `401` Unauthorized Error Code: `1002` The user associated with this access token was not found or is invalid.

Status: 403 HTTP Status Code: `403` Forbidden Error Code: `9001` The Contact Center user associated with this bearer token is missing privileges on their role required to operate this request.

Status: 404 HTTP Status Code: `404` Not Found Error Code: `2901` Engagement does not exist: $engagementId.

Status: 429 HTTP Status Code: `429` Too Many Requests. For more information, see [rate limits](/docs/api/rest/rate-limits/). Error Code: `4001` You have reached the maximum per-second rate limit for this API. Try again later.

Update an engagement

Method: PATCH
Path: /contact_center/engagements/{engagementId}
Tags: Engagements

Allows performing an action on an engagement

Scopes: contact_center_engagement:write:admin

Granular Scopes: contact_center:update:engagement:admin

Rate Limit Label: LIGHT

Request Body

Content-Type: application/json

engagement_action (required)

string, possible values: "transfer to queue", "transfer to agent", "transfer to flow", "release", "end", "activate", "deactivate" — Action to apply to the engagement. The **activate/deactivate** option is only supported for work item channels.
engagement_status

string, possible values: "end", "activate", "deactivate" — The new status to set for the engagement. The **activate/deactivate** option is only supported for work item channels.
target_agent_id

string — The target agent ID for transfer. Required when the action is `transfer to agent`.
target_flow_id

string — The target flow ID for transfer. Required when the action is `transfer to flow`.
target_queue_id

string — The target queue ID for transfer. Required when the action is `transfer to queue`.

Example:

{
  "engagement_action": "transfer to queue",
  "target_queue_id": "aok8Zi4GQUyZ6HjR_nZl1A",
  "target_agent_id": "eBUOIxoDSrSTUht2USpoUQ",
  "target_flow_id": "QCCP5nfbTVqXOsUZxkWsJw"
}

Responses

Status: 204 HTTP 204 No Content — The engagement was successfully updated. No content is returned in the response body.

Status: 400 HTTP Status Code: `400` Bad Request Error Code: `2907` Invalid `engagement_status`. Error Code: `2908` Invalid `engagement_action`.

Status: 401 HTTP Status Code: `401` Unauthorized

Status: 403 HTTP Status Code: `403` Forbidden

Status: 429 HTTP Status Code: `429` Too Many Requests. For more information, see [rate limits](https://developers.zoom.us/docs/api/rate-limits/).

Get an engagement's attachments

Method: GET
Path: /contact_center/engagements/{engagementId}/attachments
Tags: Engagements

Retrieve a list of attachments for a specified engagement.

Scopes: contact_center_attachment:read:admin

Granular Scopes: contact_center:read:attachment:admin

Rate Limit Label: MEDIUM

Responses

Status: 200 Engagement attachment list returned.

Content-Type: application/json

attachments

array — Information about the attachments.

Items:
- attachment_alias
  
  string — The attachment's alias.
- attachment_id
  
  string — The attachment's ID.
- attachment_name
  
  string — The attachment's name.
- attachment_size
  
  number — The attachment's file size, in bytes.
- attachment_type
  
  string — The attachment's file type.
- attachment_url
  
  string — The URL to download the attachment. For security purposes, you **must** provide an OAuth access token in the authorization header to download the attachment using this URL. Example:\n```curl --request GET \n --url {attachment_url} \n --header 'authorization: Bearer {access_token}' \n --header 'content-type: application/json'\n```
- engagement_id
  
  string — The engagement's ID.
next_page_token

string — Use the next page token to paginate through large result sets. A next page token is returned whenever the set of available results exceeds the current page size. This token's expiration period is 15 minutes.
page_size

integer, default: 30 — The number of records returned within a single API call.
total_records

integer — The total number of all the records available across pages.

Example:

{
  "next_page_token": "R4aF9Oj0fVM2hhezJTEmSKaBSkfesDwGy42",
  "page_size": 30,
  "total_records": 10,
  "attachments": [
    {
      "attachment_id": "0AYFv9ePSsmPUSJYHorUWQ",
      "engagement_id": "3XilEfOvQEKRIWMWhX1jDg",
      "attachment_name": "GMT20251015-95414_296_lbMMg_boRtaWyHqA87cUuQ_VideoScreenshot.png",
      "attachment_url": "https://api.zoom.us/v2/contact_center/attachments/0AYFv9ePSsmPUSJYHorUWQ/download?type=screenshot",
      "attachment_alias": "Screenshot 1.png",
      "attachment_size": 197238,
      "attachment_type": "image"
    }
  ]
}

Status: 400 HTTP Status Code: `400` Bad Request

Status: 404 HTTP Status Code: `404` Not Found Error Code: `2901` Engagement does not exist: $engagementId.

Status: 429 HTTP Status Code: `429` Too Many Requests. For more information, see [rate limits](https://developers.zoom.us/docs/api/rate-limits/).

Get an engagement's events

Method: GET
Path: /contact_center/engagements/{engagementId}/events
Tags: Engagements

Retrieve information about an engagement's events.

Scopes: contact_center_report:read:admin

Granular Scopes: contact_center:read:engagement:admin

Rate Limit Label: LIGHT

Responses

Status: 200 HTTP Status Code: `200` Engagement's events information returned.

Content-Type: application/json

engagement_id

string — The engagement's ID.
events

array — Information about the events.

Items:
- channel
  
  string, possible values: "voice", "video" — The task's channel. Currently supports only voice and video channels.
- channel_source
  
  string, possible values: "voice", "in_app_video", "kiosk_video", "web_video" — The channel's source. Currently only returns voice and video channel sources. * `voice` - Only applies to voice channel. * `in_app_video` - Only applies to video channel. * `kiosk_video` - Only applies to video channel. * `web_video` - Only applies to video channel.
- event_content
  
  string — Currently, only voice channel events are supported. Other channel events will be supported in the future. Deserializes [engagement events](https://support.zoom.com/hc/en/article?id=zm_kb&sysparm_article=KB0059105).
- event_name
  
  string — The event's name, [Engagement events](https://support.zoom.com/hc/en/article?id=zm_kb&sysparm_article=KB0059105&_ga=2.188292840.1595505736.1717553252-540387373.1700551325#h_01GCW1GKA8NFE21SNAN3VR3K4P)
- start_time
  
  string, format: date-time — The date and time when the event started. Always returned in `yyyy-MM-dd'T'HH:mm:ss'Z'` format (UTC).

Example:

{
  "engagement_id": "W_VATTk_Q5aW6z5rZtBxAQ",
  "events": [
    {
      "start_time": "2021-12-03T13:07:46Z",
      "event_name": "Start",
      "channel": "video",
      "channel_source": "in_app_video",
      "event_content": "{\"flow_id\": \"zwKiV80hQ7CwRg9BEm0Bvw\",\"flow_name\": \"Demo\"}"
    }
  ]
}

Status: 400 HTTP Status Code: `400` Bad Request Error Code: `7001` Only voice and video channels are currently supported.

Status: 404 HTTP Status Code: `404` Not Found Error Code: `2901` Engagement does not exist: $engagementId.

Status: 429 HTTP Status Code: `429` Too Many Requests. For more information, see [rate limits](https://developers.zoom.us/docs/api/rest/rate-limits/).

Poll an engagement recording's status

Method: GET
Path: /contact_center/engagements/{engagementId}/recordings/status
Tags: Engagements

Polls a video or voice engagement's recordings' status.

Scopes: contact_center_engagement:read:admin

Granular Scopes: contact_center:read:engagement_recording_status:admin

Rate Limit Label: LIGHT

Responses

Status: 200 HTTP Status: `200` OK

Content-Type: application/json

channel

string, possible values: "voice", "video" — The recording's channel type. * `voice` - Voice recording. * `video` - Video recording.
channel_source

string, possible values: "in_app_video", "kiosk_video", "web_video" — The channel's source. * `in_app_chat` - Only applies to messaging channel. * `web_chat` - Only applies to messaging channel. * `sms` - Only applies to messaging channel.
engagement_id

string — The engagement's ID.
statuses

array — The list of statuses.

Items:
- last_modified_time
  
  string — The date and time when the recording was last modified.
- status
  
  string, possible values: "pause", "resume", "start", "stop" — The recording status. If the recording status change failed, it does not explicitly show in this API response. If the recording status does not change within 5 seconds of an expected change, assume that the recording status did not successfully transition to the expected status. If used with the recording control API, the control API request can be re-attempted.

Example:

{
  "statuses": [
    {
      "status": "pause",
      "last_modified_time": "2023-01-01T00:00:00Z"
    }
  ],
  "engagement_id": "W_VATTk_Q5aW6z5rZtBxAQ",
  "channel": "video",
  "channel_source": "live_video"
}

Status: 400 HTTP Status Code: `400` Bad Request Error Code: `2814` The engagement's channel type is invalid for this recording control command. Error Code: `2815` The engagement is not assigned to an agent. It is not being recorded. Error Code: `300` Invalid request.

Status: 404 HTTP Status Code: `404` Not Found Error Code: `2901` Engagement does not exist: {0}. Error Code: `20006` Account not found. Error Code: `2817` There is no recording for this engagement. Error Code: `2906` There are not any agents on the call.

Status: 429 HTTP Status Code: `429` Too Many Requests. For more information, see [rate limits](https://developers.zoom.us/docs/api/rest/rate-limits/).

Get an engagement's survey

Method: GET
Path: /contact_center/engagements/{engagementId}/survey
Tags: Engagements

Get an engagement's survey

Scopes: contact_center_engagement:read:admin

Granular Scopes: contact_center:read:engagement:admin

Rate Limit Label: LIGHT

Responses

Status: 200 HTTP Status Code: `200` Survey returned.

Content-Type: application/json

engagement_id

string — The engagement's ID.
flow_id

string — The `flow_id` or `flow_name` is returned if the survey is tied to a flow.
flow_name

string — The `flow_id` or `flow_name` is returned if the survey is tied to a flow.
queue_id

string — The `queue_id` or `queue_name` is returned if the survey is tied to a queue.
queue_name

string — The `queue_id` or `queue_name` is returned if the survey is tied to a queue.
survey_id

string — The survey's ID.
survey_name

string — The survey's name.
survey_results

array — The survey's answers, to a maximum of 10 items.

Items:
- answer
  
  string — The user's given answer.
- date_time
  
  string — The date and time of the customer's response. Format is ISO 8601 with milliseconds and timezone offset.
- file_url
  
  string — The answer as a recording URL.
- numeric_answer
  
  integer — The user's given numeric answer.
- question_id
  
  string — The question's ID.
- question_name
  
  string — The question's name.
- question_order
  
  integer — The question's order.
- question_type
  
  integer, possible values: 0, 5, 7 — The question's type. * `0` - Single choice. * `5` - Long answer. * `7` - Rating scale (NPS).
survey_trigger_level

integer, possible values: 0, 1 — The survey's trigger level. * `0` - queue. * `1` - flow.

Example:

{
  "survey_id": "2yWjT4awTumcFKIrvcf4OA",
  "survey_name": "web chat survey",
  "engagement_id": "I9kVGZJZS5u796LxrKSWWg",
  "queue_id": "2N13_yMTaeYUSYUKqupQQ",
  "queue_name": "queue-chat",
  "flow_id": "--N6BCoPQveeGJSyni57jw",
  "flow_name": "flow-chat",
  "survey_trigger_level": 0,
  "survey_results": [
    {
      "question_id": "JocDev1cT-mIHREwDtMTVw",
      "question_name": "What is your suggestion?",
      "question_type": 0,
      "question_order": 10,
      "date_time": "2024-07-02T01:10:22.000+00:00",
      "answer": "this is my answer",
      "numeric_answer": 10,
      "file_url": "https://file.example.com/file/pvlGl_b5Q8KxSBp2vaAKXA?jwt=eyJ6bV9za20iOiJ6bV9vMm0iLCJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJhdWQiOiJhc3luY2ZpbGUiLCJ0b2tlbklkIjoiNVIyNjBGYW9RaUdFTE44alJneS0zUSIsImFwcE5hbWUiOiJhcHBfd2ViIiwiaXNzIjoiYXBwX3dlYiIsInBlcm1pc3Npb24iOiJtQ1l3ME9mM3N5Wm41alZFM25qYW40MXFMWUo4aWh1dGp3SmFYamd0Z1NrYUJxaEp4NjAtcXR2WEVoejBWVVFOOVl1Y3NrRlVwUUtxbVViS1o5TnpJQ2YxZHVaVUxjMkpVanlrOHZpXzFIWVNfdDhWeHluZ1VUdWpIbHFDTjRqY3p3Tnppdy5JbnhMMmZlVTVsZzU3cnZ3IiwiZXhwIjoxNzIwMTkwNjc0LCJ0b2tlblR5cGUiOiJwcmVzaWduVG9rZW4iLCJpYXQiOjE3MjAwODI2NzR9.tJ2Nq9f_veVMv6-60bKGcVZfIzPf2WshnOECg9Lkhxw&mode=play&with_domain=true"
    }
  ]
}

Status: 401 HTTP Status Code: `401` Unauthorized

Status: 403 HTTP Status Code: `403` Forbidden

Status: 404 HTTP Status Code: `404` Not Found Error Code: `404` The engagement does not trigger survey.

Status: 429 HTTP Status Code: `429` Too Many Requests. For more information, see [rate limits](/docs/api/rest/rate-limits/).

Status: 444 HTTP Status Code: `444` No Response Error Code: `444` The survey for this engagement has no answer.

Get available transfer flows

Method: GET
Path: /contact_center/engagements/{engagementId}/transfer/flows
Tags: Engagements

Retrieve a list of flows that are available for transfer.

Scopes: contact_center_flow:read:admin

Granular Scopes: contact_center:read:flow:admin

Rate Limit Label: LIGHT

Responses

Status: 200 HTTP Status Code: `200` Successfully retrieved the list of available transfer flows.

Content-Type: application/json

flows

array

Items:
- flow_id (required)
  
  string — The flow's ID.
- flow_description
  
  string — The flow's description.
- flow_name
  
  string — The flow's name.
next_page_token

string — Use the next page token to paginate through large result sets. A next page token is returned whenever the set of available results exceeds the current page size. This token's expiration period is 15 minutes.
page_size

integer, default: 10 — The number of records returned within a single API call.
total_records

integer — The total number of all records available across pages.

Example:

{
  "next_page_token": "R4aF9Oj0fVM2hhezJTEmSKaBSkfesDwGy42",
  "page_size": 10,
  "total_records": 10,
  "flows": [
    {
      "flow_id": "1QEhGTxFRmqKKLrZIm18CQ",
      "flow_name": "SMS",
      "flow_description": "SMS flow"
    }
  ]
}

Status: 400 HTTP Status Code: `400` Bad Request Error Code: `7001` Invalid channel or `channel_source`.

Status: 401 HTTP Status Code: `401` Unauthorized Error Code: `1002` The user associated with this access token was not found or is invalid. Error Code: `124` Invalid access token. Error Code: `124` Access token has expired.

Status: 403 HTTP Status Code: `403` Forbidden Error Code: `9001` The Contact Center user associated with this bearer token is missing privileges on their role required to operate this request. Error Code: `1021` User account is deactivated. Error Code: `1022` User does not have a Contact Center license.

Status: 404 HTTP Status Code: `404` Not Found Error Code: `2901` Engagement does not exist: $engagementId.

Status: 429 HTTP Status Code: `429` Too Many Requests. For more information, see [rate limits](https://developers.zoom.us/docs/api/rate-limits/). Error Code: `4001` You have reached the maximum per-second rate limit for this API. Try again later.

Get available transfer queues

Method: GET
Path: /contact_center/engagements/{engagementId}/transfer/queues
Tags: Engagements

Return a list of queues that are available for transfer.

Scopes: contact_center_queue:read:admin

Granular Scopes: contact_center:read:list_queues:admin

Rate Limit Label: LIGHT

Responses

Status: 200 HTTP Status Code: `200` OK Queue information returned.

Content-Type: application/json

next_page_token

string — Use the next page token to paginate through large result sets. A next page token is returned whenever the set of available results exceeds the current page size. This token's expiration period is 15 minutes.
page_size

integer, default: 10 — The number of records returned within a single API call.
queues

array

Items:
- queue_id (required)
  
  string — The queue's ID.
- queue_description
  
  string — The queue's description.
- queue_name
  
  string — The queue's name.
total_records

integer — The total number of all records available across pages.

Example:

{
  "next_page_token": "R4aF9Oj0fVM2hhezJTEmSKaBSkfesDwGy42",
  "page_size": 10,
  "total_records": 10,
  "queues": [
    {
      "queue_id": "1QEhGTxFRmqKKLrZIm18CQ",
      "queue_name": "SMS",
      "queue_description": "SMS Queue"
    }
  ]
}

Status: 400 HTTP Status Code: `400` Bad Request Error Code: `7001` Invalid channel or `channel_source`.

Status: 401 HTTP Status Code: `401` Unauthorized Error Code: `1002` The user associated with this access token was not found or is invalid. Error Code: `124` Invalid access token. Error Code: `124` Access token has expired.

Status: 403 HTTP Status Code: `403` Forbidden Error Code: `9001` The Contact Center user associated with this bearer token is missing privileges on their role required to operate this request. Error Code: `1021` User account is deactivated. Error Code: `1022` User does not have a Contact Center license.

Status: 404 HTTP Status Code: `404` Not Found Error Code: `2901` Engagement does not exist: $engagementId.

Status: 429 HTTP Status Code: `429` Too Many Requests. For more information, see [rate limits](https://developers.zoom.us/docs/api/rate-limits/). Error Code: `4001` You have reached the maximum per-second rate limit for this API. Try again later.

Get available transfer users

Method: GET
Path: /contact_center/engagements/{engagementId}/transfer/users
Tags: Engagements

Retrieve a list of available transfer users.

Scopes: contact_center_user:read:admin

Granular Scopes: contact_center:read:list_users:admin

Rate Limit Label: LIGHT

Responses

Status: 200 HTTP Status Code: `200` Agent information returned.

Content-Type: application/json

next_page_token

string — Use the next page token to paginate through large result sets. A next page token is returned whenever the set of available results exceeds the current page size. This token's expiration period is 15 minutes.
page_size

integer, default: 10 — The number of records returned within a single API call.
total_records

integer — The total number of all records available across pages.
users

array

Items:
- cc_user_id (required)
  
  string — The Contact Center user identifier.
- user_status (required)
  
  string, possible values: "offline", "available", "unavailable", "occupied", "break", "meal", "training", "meeting", "end_shift", "forced", "disabling", "in_meeting", "on_call" — The user's current status.
- queue_count
  
  integer — The number of queues assigned to the user.
- queues
  
  array — The list of queues assigned to the user.
  
  Items:
  - queue_id
    
    string — The queue's ID.
  - queue_name
    
    string — The queue's name.
- user_display_name
  
  string — The user's display name.
- user_email
  
  string, format: email — The user's email address.
- user_first_name
  
  string — The user's first name.
- user_id
  
  string — The Meetings user identifier.
- user_last_name
  
  string — The user's last name.
- user_personal_profile_avatar
  
  string — The URL of the user's personal profile avatar.
- user_profile_picture_background_color
  
  string — The background color of the user's profile picture.
- user_profile_picture_file_id
  
  string — The file ID of the user's profile picture.
- user_profile_picture_type
  
  string — The type of the user's profile picture.

Example:

{
  "next_page_token": "R4aF9Oj0fVM2hhezJTEmSKaBSkfesDwGy42",
  "page_size": 10,
  "total_records": 10,
  "users": [
    {
      "cc_user_id": "hKuMAiDdRlSwMkBxR5we7g",
      "user_id": "IGTRVt3gQ2i-WjoUIjeZxw",
      "user_display_name": "Jane Doe",
      "user_email": "jchill@example.com",
      "user_status": "available",
      "user_first_name": "John",
      "user_last_name": "Doe",
      "user_profile_picture_background_color": "#4A90E2",
      "user_profile_picture_file_id": "file_abc123xyz",
      "user_profile_picture_type": "uploaded",
      "user_personal_profile_avatar": "https://example.com/avatar.png",
      "queue_count": 5,
      "queues": [
        {
          "queue_id": "RpKKZwpVxNq1aQtMIODHq",
          "queue_name": "Support Queue"
        }
      ]
    }
  ]
}

Status: 400 HTTP Status Code: `400` Bad Request

Status: 401 HTTP Status Code: `401` Unauthorized Error Code: `1002` The user associated with this access token was not found or is invalid. Error Code: `124` Invalid access token. Error Code: `124` Access token has expired.

Status: 403 HTTP Status Code: `403` Forbidden Error Code: `9001` The Contact Center user associated with this bearer token is missing privileges on their role required to operate this request. Error Code: `1021` User account is deactivated. Error Code: `1022` User does not have a Contact Center license.

Status: 404 HTTP Status Code: `404` Not Found Error Code: `2901` Engagement does not exist: $engagementId.

Status: 429 HTTP Status Code: `429` Too Many Requests. For more information, see [rate limits](https://developers.zoom.us/docs/api/rate-limits/). Error Code: `4001` You have reached the maximum per-second rate limit for this API. Try again later.

List flows

Method: GET
Path: /contact_center/flows
Tags: Flows

Return a list of flows.

Scopes: contact_center_flow:read:admin

Granular Scopes: contact_center:read:list_flows:admin

Rate Limit Label: MEDIUM

Responses

Status: 200 HTTP Status Code: `200` Flow list returned.

Content-Type: application/json

flows

array — Information about the flows.

Items:
- channel
  
  string, possible values: "voice", "video", "messaging", "email", "work_item" — The flow's channel.
- channel_source
  
  string, possible values: "web_chat", "in_app_chat", "sms", "facebook_messenger", "whatsapp", "email_address", "api" — The channel's source. * `in_app_chat` - Only applies to messaging channel. * `web_chat` - Only applies to messaging channel. * `sms` - Only applies to messaging channel. * `facebook_messenger` - Only applies to messaging channel. * `whatsapp` - Only applies to messaging channel. * `email_address` - Only applies to email channel. * `api` - Only applies to work_item channel.
- channel_type
  
  string, possible values: "voice", "chat", "sms", "video", "in_app_chat" — The flow's channel type.
- entry_points
  
  array — The flow's entry points.
  
  Items:
  - email_address
    
    string — The flow's entry point email address, applicable to email.
  - entry_id
    
    string — The flow's entry point ID.
  - entry_language
    
    string — The flow's entry point engagement language.
  - entry_name
    
    string — The flow's entry point name, applicable to Video, Web Chat and In-App Chat.
  - entry_number
    
    string — The flow's entry point number, applicable to voice and SMS.
- flow_description
  
  string — The flow's description.
- flow_id
  
  string — The flow's ID.
- flow_name
  
  string — The flow's name.
- flow_versions
  
  array — The flow's versions.
  
  Items:
  - flow_version
    
    integer — The flow's version.
  - flow_version_description
    
    string — The flow's version description.
  - flow_version_id
    
    string — The flow's studio version ID.
  - flow_version_last_modified_time
    
    string — The date and time when this flow version was last modified.
  - flow_version_modified_by
    
    string — The parent ID of the user who modified the flow version.
  - flow_version_status
    
    string, possible values: "draft", "published", "archived", "debugging" — The flow version's status.
- last_modified_time
  
  string, format: date-time — The date and time when this data was last modified.
- modified_by
  
  string — The ID of the user that last modified this data.
- status
  
  string, possible values: "draft", "published", "archived", "debugging" — This flow's status.
next_page_token

string — Use the next page token to paginate through large result sets. A next page token is returned whenever the set of available results exceeds the current page size. This token's expiration period is 15 minutes.
page_size

integer, default: 30 — The number of records returned within a single API call.
total_records

integer — The total number of all the records available across pages.

Example:

{
  "next_page_token": "R4aF9Oj0fVM2hhezJTEmSKaBSkfesDwGy42",
  "page_size": 30,
  "total_records": 10,
  "flows": [
    {
      "flow_id": "zwKiV80hQ7CwRg9BEm0Bvw",
      "flow_name": "Video Test",
      "flow_description": "A testing flow.",
      "channel": "messaging",
      "channel_source": "web_chat",
      "status": "published",
      "modified_by": "IGTRVt3gQ2i-WjoUIjeZxw",
      "last_modified_time": "2022-02-15T09:27:15Z",
      "entry_points": [
        {
          "entry_id": "x_h7uCj3TtScXWOBnQnKrw",
          "entry_name": "Test video",
          "entry_number": "+16052052430",
          "entry_language": "en-US",
          "email_address": "xxxx@zoom.us"
        }
      ],
      "flow_versions": [
        {
          "flow_version_id": "EWg5URJZRXKwfbLJpeJWyA",
          "flow_version_description": "Version 1",
          "flow_version_status": "draft",
          "flow_version": 2,
          "flow_version_modified_by": "jdhgdhghk376453hjdf",
          "flow_version_last_modified_time": "2022-08-05T01:55:52Z"
        }
      ]
    }
  ]
}

Status: 429 HTTP Status Code: `429` Too Many Requests. For more information, see [rate limits](/docs/api/rest/rate-limits/).

Import a flow

Method: POST
Path: /contact_center/flows
Tags: Flows

Import and create a flow, using content from another flow's exported JSON.

Scopes: contact_center_flow:write:admin

Granular Scopes: contact_center:write:flow:admin

Rate Limit Label: MEDIUM

Request Body

Content-Type: multipart/form-data

flow_file (required)

string — * View - The uploaded file is in binary format. * Allowed file extensions - `xxx.json` * Maximum file size supported - 10 MB
flow_name (required)

string — The flow name. Must be unique within a division.
import_mode (required)

string, possible values: "new", "version" — "new" (default) or "version" - "new" creates a brand new flow. - "version" checks for existing flow by name + channel and imports as new version.
flow_description

string — The flow description.
flow_version_description

string — The flow version description. The flow is imported and created with Version 1 automatically.

Example:

{
  "flow_name": "my flow",
  "flow_description": "my description",
  "flow_version_description": "my version description",
  "flow_file": "Vm0wd2QyUXlVWGxWV0d4V1YwZDRWMVl3WkRSWFJteFZVMjA1VjAxV2JETlhhMk0xVmpKS1NHVkVRbUZXVmxsM1ZtcEJlRll5U2tWVWJHaG9UVlZ3VlZacVFtRlRNbEpJVm10a1dHSkdjSEJXYTFwaFpWWmFkRTFVVWxSTmF6RTFWa2QwYzJGc1NuUmhSemxWVmpOT00xcFZXbUZrUjA1R1UyMTRVMkpXU2twV2JURXdWakZXZEZOc1dsaGlSMmhZV1d4b2IyVnNVbFZTYlVaclVqQTFSMVV5TVRSVk1rcElaSHBHVjFaRmIzZFdha1poVjBaT2NtRkhhRk5sYlhoWFZtMXdUMVF3TUhoalJscFlZbFZhY2xWc1VrZFdiRnBZWlVoa1YwMUVSa1pWYkZKSFZqSkZlVlZZWkZkaGExcFhXbFphVDJOdFNrZFRiV2hzWWxob1dWWXhaRFJpTWtsM1RVaG9hbEp0VWxsWmJHaFRWMFpTVjFwR1RteGlSbXcxVkZaU1UxWnJNWEpqUld4aFUwaENTRlpxU2tabFZsWlpXa1p3YkdFelFrbFdWM0JIVkRKU1YxWnVUbGhpVjNoVVdWUk9RMlJzV25STldHUlZUVlpXTkZVeGFHOWhiRXB6WTBac1dtSkhhRlJXTUZwVFZqRndSVkZyT1dsU00yaFlWbXBKZUZJeFdsaFRhMXBxVWxkb1dGUlhOVU5YUmxweFVtdDBhazFyTlVoWlZWcHJZVWRGZWxGcmJGZFdSVXBvVjFaa1UxWXhUblZVYkZKcFVqRktWVlpHVWtKa01ERlNVRlF3UFE9PQ==",
  "import_mode": "new"
}

Responses

Status: 201 HTTP Status Code: `201` Import and create a flow.

Content-Type: application/json

channel

string, possible values: "voice", "video", "messaging", "email", "work_item" — The flow's channel.
channel_source

string, possible values: "video", "voice", "sms", "web_chat", "in_app_chat", "facebook_messenger", "whatsapp", "instagram", "team_chat", "email_address", "api" — The channel's source. `in_app_chat` - Only applies to messaging channel. `web_chat` - Only applies to messaging channel. `sms` - Only applies to messaging channel. `facebook_messenger` - Only applies to messaging channel. `whatsapp` - Only applies to messaging channel. `web_chat` - Only applies to messaging channel. `email_address` - Only applies to email channel. `api` - Only applies to work_item channel.
entry_points

array — The flow's entry points.

Items:
- email_address
  
  string — The flow's entry point email address. Applicable to email.
- entry_id
  
  string — The flow's entry point ID.
- entry_language
  
  string — The flow's entry point engagement language.
- entry_name
  
  string — The flow's entry point name. Applicable to video, web chat, and in-app chat.
- entry_number
  
  string — The flow's entry point number. Applicable to voice and SMS.
flow_description

string — The flow description.
flow_id

string — The flow ID.
flow_name

string — The flow name.
flow_versions

array — The flow version.

Items:
- flow_version
  
  integer — The flow's version.
- flow_version_description
  
  string — The flow version's description.
- flow_version_id
  
  string — The flow's entry point ID.
- flow_version_last_modified_time
  
  string — The date and time when this flow version was last modified.
- flow_version_modified_by
  
  string — The parent ID of the user who modified the flow version.
- flow_version_status
  
  string, possible values: "draft", "published", "archieved" — The flow version's status.
last_modified_time

string, format: date-time — The date and time when this data was last modified.
modified_by

string — The ID of the user that last modified this data.
status

string, possible values: "draft", "published" — The flow's status.

Example:

{
  "flow_id": "zwKiV80hQ7CwRg9BEm0Bvw",
  "flow_name": "test_flow",
  "flow_description": "test_flow",
  "channel": "messaging",
  "channel_source": "web_chat",
  "status": "draft",
  "modified_by": "IGTRVt3gQ2i-WjoUIjeZxw",
  "last_modified_time": "2022-02-15T09:27:15Z",
  "entry_points": [
    {
      "entry_id": "x_h7uCj3TtScXWOBnQnKrw",
      "entry_name": "my_entry",
      "entry_number": "+16052052430",
      "entry_language": "en-US",
      "email_address": "address@company.com"
    }
  ],
  "flow_versions": [
    {
      "flow_version_id": "EWg5URJZRXKwfbLJpeJWyA",
      "flow_version_description": "My Version Description",
      "flow_version_status": "draft",
      "flow_version": 2,
      "flow_version_modified_by": "jdhgdhghk376453hjdf",
      "flow_version_last_modified_time": "2023-01-01T00:00:00-04:00"
    }
  ]
}

Status: 400 HTTP Status Code: `400` Bad Request Error Code: `3202` The flow name already exists. Error Code: `3203` The flow is invalid.

Status: 404 HTTP Status Code: `404` Not Found

Status: 429 HTTP Status Code: `429` Too Many Requests. For more information, see [rate limits](/docs/api/rate-limits/).

Get a flow

Method: GET
Path: /contact_center/flows/{flowId}
Tags: Flows

Get information about a flow.

Scopes: contact_center_flow:read:admin

Granular Scopes: contact_center:read:flow:admin

Rate Limit Label: LIGHT

Responses

Status: 200 HTTP Status Code: `200` Flow returned.

Content-Type: application/json

channel

string, possible values: "voice", "video", "messaging", "email", "work_item" — The flow's channel.
channel_source

string, possible values: "web_chat", "in_app_chat", "sms", "facebook_messenger", "whatsapp", "email_address", "api" — The channel's source. * `in_app_chat` - Only applies to messaging channel. * `web_chat` - Only applies to messaging channel. * `sms` - Only applies to messaging channel. * `facebook_messenger` - Only applies to messaging channel. * `whatsapp` - Only applies to messaging channel. * `web_chat` - Only applies to messaging channel. * `sms` - Only applies to messaging channel. * `facebook_messenger` - Only applies to messaging channel. * `email_address` - Only applies to email channel. * `api` - Only applies to work_item channel.
channel_type

string, possible values: "voice", "chat", "sms", "video", "in_app_chat" — The flow's channel type.
entry_points

array — The flow's entry points.

Items:
- email_address
  
  string — The flow's entry point email address. Applicable to email.
- entry_id
  
  string — The flow's entry point ID.
- entry_language
  
  string — The flow's entry point engagement language.
- entry_name
  
  string — The flow's entry point name, applicable to Video, Web Chat and In-App Chat.
- entry_number
  
  string — The flow's entry point number, applicable to voice and SMS.
flow_description

string — The flow's description.
flow_id

string — The flow's ID.
flow_name

string — The flow's name.
flow_versions

array — The flow's versions.

Items:
- flow_version
  
  integer — The flow's version.
- flow_version_description
  
  string — The flow's version description.
- flow_version_id
  
  string — The flow's studio version ID.
- flow_version_last_modified_time
  
  string — The date and time when this flow version was last modified.
- flow_version_modified_by
  
  string — The parent ID of the user who modified the flow version.
- flow_version_status
  
  string, possible values: "draft", "published", "archived", "debugging" — The flow version's status.
last_modified_time

string — The date and time when this flow was last modified.
modified_by

string — The parent ID of the user who modified the flow.
status

string, possible values: "draft", "published", "archived", "debugging" — This flow's status.

Example:

{
  "flow_id": "zwKiV80hQ7CwRg9BEm0Bvw",
  "flow_name": "Video Test",
  "flow_description": "A testing flow.",
  "channel": "messaging",
  "channel_source": "web_chat",
  "status": "published",
  "modified_by": "jdhgdhghk376453hjdf",
  "last_modified_time": "2022-08-05T01:55:52Z",
  "entry_points": [
    {
      "entry_id": "x_h7uCj3TtScXWOBnQnKrw",
      "entry_name": "Test video",
      "entry_number": "+16052052430",
      "entry_language": "en-US",
      "email_address": "xxxx@zoom.us"
    }
  ],
  "flow_versions": [
    {
      "flow_version_id": "EWg5URJZRXKwfbLJpeJWyA",
      "flow_version_description": "Version 1",
      "flow_version_status": "draft",
      "flow_version": 2,
      "flow_version_modified_by": "jdhgdhghk376453hjdf",
      "flow_version_last_modified_time": "2022-08-05T01:55:52Z"
    }
  ]
}

Status: 400 HTTP Status Code: `400` Bad Request

Status: 401 HTTP Status Code: `401` Unauthorized

Status: 403 HTTP Status Code: `403` Forbidden

Status: 404 HTTP Status Code: `404` Not Found Error Code: `3201` Flow does not exist: $flowId.

Status: 429 HTTP Status Code: `429` Too Many Requests. For more information, see [rate limits](https://developers.zoom.us/docs/api/rate-limits/).

Delete a flow

Method: DELETE
Path: /contact_center/flows/{flowId}
Tags: Flows

Delete a flow.

Scopes: contact_center_flow:write:admin

Granular Scopes: contact_center:delete:flow:admin

Rate Limit Label: LIGHT

Responses

Status: 204 HTTP Status Code: `204` Delete a flow.

Status: 400 HTTP Status Code: `400` Bad Request Error Code: `3209` Message: Current flow is in use for the following areas and can’t be deleted. Please remove the flow from the listed areas before proceeding. Errors: - Related Flows (Flow information associated with the current flow): ```json "related_flows": [ { "flow_name": "xxx", "flow_id": "xxx" } ] ``` - Related Queues (Queue information associated with the current flow): ```json "related_queues": [ { "queue_name": "xxx", "queue_id": "xxx" } ] ``` - Related Campaigns (Queue information associated with the current flow): ```json "related_campaigns": [ { "campaign_id": "xxx", "campaign_name": "xxx" } ] ```

Status: 404 HTTP Status Code: `404` Not Found Error Code: `3201` Flow does not exist.

Status: 429 HTTP Status Code: `429` Too Many Requests. For more information, see [rate limits](https://developers.zoom.us/docs/api/rate-limits/).

Edit a flow

Method: PATCH
Path: /contact_center/flows/{flowId}
Tags: Flows

Edit a flow's attributes.

Scopes: contact_center_flow:write:admin

Granular Scopes: contact_center:update:flow:admin

Rate Limit Label: LIGHT

Request Body

Content-Type: application/json

flow_version (required)

integer — The flow version.
flow_description

string — The flow's description.
flow_name

string — The flow's name.
flow_version_description

string — The flow version description.

Example:

{
  "flow_name": "my flow name",
  "flow_description": "my_flow_desc",
  "flow_version_description": "my_flow_version_desc",
  "flow_version": 1
}

Responses

Status: 204 HTTP Status Code: `204` Edit a flow's attributes.

Status: 400 HTTP Status Code: `400` Bad Request Error Code: `3202` Flow name already exists.

Status: 404 HTTP Status Code: `404` Not Found Error Code: `3201` Flow does not exist.

Status: 429 HTTP Status Code: `429` Too Many Requests. For more information, see [rate limits](/docs/api/rate-limits/).

List flow's entry points

Method: GET
Path: /contact_center/flows/{flowId}/entry_points
Tags: Flows

Retrieve a list of the entry points bound to the current flow.

Scopes: contact_center_flow:read:admin

Granular Scopes: contact_center:read:flow:admin

Rate Limit Label: MEDIUM

Responses

Status: 200 HTTP Status Code: `200` List the entry points bound to the current flow

Content-Type: application/json

channel

string, possible values: "voice", "video", "messaging", "email", "work_item" — The flow's channel.
channel_source

string, possible values: "sms", "web_chat", "in_app_chat", "team_chat", "email_address", "instagram", "facebook_messenger", "whatsapp", "api" — The channel's source. `in_app_chat` - Only applies to messaging channel. `web_chat` - Only applies to messaging channel. `sms` - Only applies to messaging channel. `team_chat` - Only applies to messaging channel. `instagram` - Only applies to messaging channel. `facebook_messenger` - Only applies to messaging channel. `whatsapp` - Only applies to messaging channel. `web_chat` - Only applies to messaging channel. `email_address` - Only applies to email channel. `video` - Only applies to video channel. `voice` - Only applies to voice channel. `api` - Only applies to work_item channel.
enable_detect_language

boolean — **Channel limitation** - This field is only required when `channel` = email. **Default value** = `false` **Note** - The detected language will automatically set the global variable `engagement language`.
entry_points

array — The entry point list.

Items:
- entry_id (required)
  
  string — The entry's ID.
- customer_identity_source
  
  string, possible values: "from", "reply_to", default: "from" — Which email header the Contact Center uses to identify the customer for an inbound email engagement at this email entry point. This field is only applicable to the **Email** channel. - `from` - Use the inbound email `From` header as the customer identity. - `reply_to` - Prefer the inbound email `Reply-To` header as the customer identity. If the `Reply-To` header is missing, the system falls back to using the `From` header.
- entry_email
  
  string — The email address. Only supports `channel_source` = email.
- entry_language
  
  string — **Only supports `channel` = voice** The language you choose sets the engagement's language and which language based assets are used. **Channel limitation** - This field is only needed when `channel` = voice. **Default value** - `en_US` **Language List** | Language | Value | |---------------------------|----------| | Chinese (Simplified) | zh-CN | | Chinese (Traditional) | zh-TW | | Chinese Cantonese | yue-CN | | Chinese Mandarin | cmn-CN | | Danish (Denmark) | da-DK | | Dutch (Netherlands) | nl-NL | | English (Australia) | en-AU | | English (New Zealand) | en-NZ | | English (UK) | en-GB | | English (US) | en-US | | French (Canada) | fr-CA | | French (France) | fr-FR | | German (Germany) | de-DE | | Italian (Italy) | it-IT | | Japanese (Japan) | ja-JP | | Korean (Korea) | ko-KR | | Polish (Poland) | pl-PL | | Portuguese (Brazil) | pt-BR | | Portuguese (Portugal) | pt-PT | | Romanian (Romania) | ro-RO | | Russian (Russia) | ru-RU | | Spanish (European) | es-ES | | Spanish (Mexico) | es-MX | | Spanish (US) | es-US | | Swedish (Sweden) | sv-SE | | Turkish (Turkey) | tr-TR |
- entry_name
  
  string — entry name
- entry_number
  
  string — The phone number. Only supports `channel` = voice or `channel` = messaging and `channel_source` = sms.
- entry_number_area_code
  
  string — The number's area code. Only supports `channel` = voice or `channel` = messaging and `channel_source` = sms.
- entry_number_country_code
  
  string — **Note** Number country. Only supports `channel` = voice or `channel` = messaging and `channel_source` = sms. See [Country Abbreviations](/docs/api/references/abbreviations/#countries) for more details.
- entry_number_type
  
  integer, possible values: 2, 3, 5 — Only supports `channel_source` = voice or sms. 2- Toll-free. 3- Virtual. 5- Mobile.

Example:

{
  "entry_points": [
    {
      "entry_id": "xxxxxxxxxx",
      "entry_number": "+1209144732",
      "entry_email": "xxx@example.com",
      "entry_name": "test entry",
      "entry_number_type": 2,
      "entry_number_country_code": "US",
      "entry_number_area_code": "209",
      "entry_language": "en-US",
      "customer_identity_source": "from"
    }
  ],
  "enable_detect_language": true,
  "channel": "messaging",
  "channel_source": "web_chat"
}

Status: 400 HTTP Status Code: `400` Bad Request

Status: 401 HTTP Status Code: `401` Unauthorized

Status: 403 HTTP Status Code: `403` Forbidden

Status: 404 HTTP Status Code: `404` Not Found Error Code: `3201` Flow does not exist.

Status: 429 HTTP Status Code: `429` Too Many Requests. For more information, see [rate limits](https://developers.zoom.us/docs/api/rate-limits/).

Add flow entry points

Method: POST
Path: /contact_center/flows/{flowId}/entry_points
Tags: Flows

Add entry points to a flow.

Scopes: contact_center_flow:write:admin

Granular Scopes: contact_center:write:flow:admin

Rate Limit Label: LIGHT

Request Body

Content-Type: application/json

enable_detect_language

boolean — **Channel Limitation** - This field is only required when `channel=email`. - Default Value- `false` **Note** The detected language will automatically set the global variable `engagement language`.
entry_points

array — The entry ID list.

Items:
- entry_id (required)
  
  string — The entry ID.
- customer_identity_source
  
  string, possible values: "from", "reply_to", default: "from" — Determines which email header Contact Center uses to identify the customer for an inbound email engagement at this email entry point. This field is only applicable to the **Email** channel. - `from` - Use the inbound email `From` header as the customer identity. - `reply_to` - Prefer the inbound email `Reply-To` header as the customer identity. If the `Reply-To` header is missing, the system falls back to using the `From` header.
- entry_language
  
  string — **Channel Limitation*- only channel=voice need this field. Default value - `en_US` **Language list** - | Language | Value | |---------------------------|----------| | Chinese (Simplified) | zh-CN | | Chinese (Traditional) | zh-TW | | Chinese Cantonese | yue-CN | | Chinese Mandarin | cmn-CN | | Danish (Denmark) | da-DK | | Dutch (Netherlands) | nl-NL | | English (Australia) | en-AU | | English (New Zealand) | en-NZ | | English (UK) | en-GB | | English (US) | en-US | | French (Canada) | fr-CA | | French (France) | fr-FR | | German (Germany) | de-DE | | Italian (Italy) | it-IT | | Japanese (Japan) | ja-JP | | Korean (Korea) | ko-KR | | Polish (Poland) | pl-PL | | Portuguese (Brazil) | pt-BR | | Portuguese (Portugal) | pt-PT | | Romanian (Romania) | ro-RO | | Russian (Russia) | ru-RU | | Spanish (European) | es-ES | | Spanish (Mexico) | es-MX | | Spanish (US) | es-US | | Swedish (Sweden) | sv-SE | | Turkish (Turkey) | tr-TR |

Example:

{
  "entry_points": [
    {
      "entry_id": "Nn3aO8lOSm6aYYW6l8brSQ",
      "entry_language": "en-US",
      "customer_identity_source": "from"
    }
  ],
  "enable_detect_language": false
}

Responses

Status: 201 HTTP Status Code: `201` Flow entry points added.

Content-Type: application/json

channel (required)

string, possible values: "voice", "video", "messaging", "email", "work_item" — The flow channel.
channel_source (required)

string, possible values: "sms", "web_chat", "in_app_chat", "team_chat", "email", "instagram", "facebook_messenger", "whatsapp", "api" — The channel's source. - `in_app_chat` - Only applies to messaging channel. - `web_chat` - Only applies to messaging channel. - `sms` - Only applies to messaging channel. - `team_chat` - Only applies to messaging channel. - `instagram` - Only applies to messaging channel. - `facebook_messenger` - Only applies to messaging channel. `whatsapp` - Only applies to messaging channel. - `web_chat` - Only applies to messaging channel. - `email_address` - Only applies to email channel. - `api` - Only applies to work_item channel.
entry_points (required)

array

Items:
- entry_id (required)
  
  string — The entry ID.
- customer_identity_source
  
  string, possible values: "from", "reply_to" — Determines which email header Contact Center uses to identify the customer for an inbound email engagement at this email entry point. This field is only applicable to the **Email channel**. - **from**: Use the inbound email `From` header as the customer identity. - **reply_to**: Prefer the inbound email `Reply-To` header as the customer identity. If the `Reply-To` header is missing, the system falls back to using the `From` header.
- entry_language
  
  string — This value only returns when `channel` = voice.
enable_detect_language

boolean — This field is meaningful only when `channel` = email.

Example:

{
  "entry_points": [
    {
      "entry_id": "Nn3aO8lOSm6aYYW6l8brSQ",
      "entry_language": "en_US",
      "customer_identity_source": "from"
    }
  ],
  "channel_source": "web_chat",
  "channel": "messaging",
  "enable_detect_language": false
}

Status: 400 HTTP Status Code: `400` Bad Request Error Code: `3208` The flow entry point has reached the maximum limit.

Status: 401 HTTP Status Code: `401` Unauthorized Error Code: `124` Invalid access token. Error Code: `124` Access token has expired. Error Code: `1002` The user associated with this access token was not found or is invalid.

Status: 403 HTTP Status Code: `403` Forbidden Error Code: `1021` User account is deactivated. Error Code: `1022` User does not have a Contact Center license. Error Code: `9001` The Contact Center user associated with this bearer token is missing privileges on their role required to operate this request.

Status: 404 HTTP Status Code: `404` Not Found Error Code: `3201` Flow does not exist.

Status: 429 HTTP Status Code: `429` Too Many Requests. For more information, see [rate limits](https://developers.zoom.us/docs/api/rate-limits/). Error Code: `4001` You have reached the maximum per-second rate limit for this API. Try again later.

Remove flow entry points

Method: DELETE
Path: /contact_center/flows/{flowId}/entry_points
Tags: Flows

Remove entry points from a flow.

Scopes: contact_center_flow:write:admin

Granular Scopes: contact_center:delete:flow:admin

Rate Limit Label: LIGHT

Request Body

Content-Type: application/json

entry_ids

array — Identifiers for the entry points to remove. For voice and SMS flows each value may be either the phone number ID or the phone number in E.164 format such as +17083362211. For chat-based flows pass the channel-specific identifier.

Items:

string — The entry ID.

Example:

{
  "entry_ids": [
    "zwKiV80hQ7CwRg9BEm0Bvw"
  ]
}

Responses

Status: 204 HTTP Status Code: `204` Entry points are deleted

Status: 400 HTTP Status Code: `400` Bad Request

Status: 401 HTTP Status Code: `401` Unauthorized Error Code: `124` Error Code: `124` Error Code: `1002` The user associated with this access token was not found or is invalid.

Status: 403 HTTP Status Code: `403` Forbidden Error Code: `1021` User account is deactivated. Error Code: `1022` User does not have a Contact Center license. Error Code: `9001` The Contact Center user associated with this bearer token is missing privileges on their role required to operate this request.

Status: 404 HTTP Status Code: `404` Not Found Error Code: `3201` Flow does not exist: $flowId.

Status: 429 HTTP Status Code: `429` Too Many Requests. For more information, see [rate limits](/docs/api/rate-limits/). Error Code: `4001` You have reached the maximum per-second rate limit for this API. Try again later.

Export a flow

Method: GET
Path: /contact_center/flows/{flowId}/export
Tags: Flows

Export a flow's content as JSON.

Scopes: contact_center_flow:read:admin

Granular Scopes: contact_center:read:flow:admin

Rate Limit Label: LIGHT

Responses

Status: 200 HTTP Status Code: `200` Export flow as JSON. You will get a downloadable file.

Status: 400 HTTP Status Code: `400` Bad Request Error Code: `3201` Flow does not exist: $flowId $flowVersion.

Status: 401 HTTP Status Code: `401` Unauthorized

Status: 403 HTTP Status Code: `403` Forbidden

Status: 429 HTTP Status Code: `429` Too Many Requests. For more information, see [rate limits](https://developers.zoom.us/docs/api/rate-limits/).

Publish a flow

Method: PUT
Path: /contact_center/flows/{flowId}/publish
Tags: Flows

Publish a flow version. Any other published version of the flow will be replaced with the one specified in this request.

Scopes: contact_center_flow:write:admin

Granular Scopes: contact_center:update:flow:admin

Rate Limit Label: LIGHT

Responses

Status: 204 HTTP Status Code: `204` Publish a flow.

Status: 400 HTTP Status Code: `400` Bad Request

Status: 404 HTTP Status Code: `404` Not Found Error Code: `3201` Flow does not exist.

Status: 429 HTTP Status Code: `429` Too Many Requests. For more information, see [rate limits](/docs/api/rate-limits/).

List entry points

Method: GET
Path: /contact_center/flows_entry_points
Tags: Flows

Retrieve a list of entry points.

Scopes: contact_center_flow:read:admin

Granular Scopes: contact_center:read:flow:admin

Rate Limit Label: MEDIUM

Responses

Status: 200 HTTP Status Code: `200` List current channel available entry id list

Content-Type: application/json

entry_points

array — The entry point list.

Items:
- channel
  
  string, possible values: "voice", "video", "messaging", "email", "work_item" — The flow's channel.
- channel_source
  
  string, possible values: "sms", "web_chat", "in_app_chat", "team_chat", "email_address", "instagram", "facebook_messenger", "whatsapp", "api" — The channel's source. - `in_app_chat` - Only applies to the messaging channel. - `web_chat` - Only applies to the messaging channel. - `sms` - Only applies to **messaging** channel - `team_chat` – Only applies to **messaging** channel - `instagram` – Only applies to **messaging** channel - `facebook_messenger` – Only applies to **messaging** channel - `whatsapp` – Only applies to **messaging** channel - `email_address` – Only applies to **email** channel - `api` - Only applies to work_item channel.
- entry_email
  
  string — Email address. Only supported when `channel = email`.
- entry_id
  
  string — The entry ID.
- entry_name
  
  string — The entry name.
- entry_number
  
  string — **Note** Phone number only supports `channel = voice` or `channel = messaging` with `channel_source = sms`.
- entry_number_area_code
  
  string — The number's area code.
- entry_number_country_code
  
  string — **Note** Number country only supports `channel = voice` or `channel = messaging & channel_source = sms`. See [Zoom API Country Abbreviations](/docs/api/references/abbreviations/#countries) for more details.
- entry_number_type
  
  integer, possible values: 2, 3, 5 — **Note** Only supports `channel = voice` or `channel = messaging & channel_source = sms` Supported number types Toll-Free Virtual Mobile
next_page_token

string — Use the next page token to paginate through large result sets. A next page token is returned whenever the set of available results exceeds the current page size. This token's expiration period is 15 minutes.
page_size

integer, default: 30 — The number of records returned within a single API call.
total_records

integer — The total number of all the records available across pages.

Example:

{
  "next_page_token": "R4aF9Oj0fVM2hhezJTEmSKaBSkfesDwGy42",
  "page_size": 30,
  "total_records": 10,
  "entry_points": [
    {
      "entry_id": "rDjD-6bvTKyvc7jWuKJOxg",
      "entry_number": "+1209144732",
      "entry_name": "test entry",
      "entry_email": "xxx@example.com",
      "entry_number_type": 2,
      "entry_number_country_code": "US",
      "entry_number_area_code": "209",
      "channel": "messaging",
      "channel_source": "web_chat"
    }
  ]
}

Status: 400 HTTP Status Code: `400` Bad Request Error Code: `3210` Channel or `channel_source` is illegal.

Status: 404 HTTP Status Code: `404` Not Found

Status: 429 HTTP Status Code: `429` Too Many Requests. For more information, see [rate limits](/docs/api/rate-limits/).

List engagement follow-up tasks

Method: GET
Path: /contact_center/engagements/{engagementId}/follow_up_tasks
Tags: Follow-up Tasks

Returns a list of follow-up tasks under an engagement.

Scopes: contact_center_follow_up_task:read:admin

Granular Scopes: contact_center:read:list_follow_up_tasks:admin

Rate Limit Label: MEDIUM

Responses

Status: 200 HTTP Status Code: `200` Engagement follow-up task list returned

Content-Type: application/json

follow_up_tasks

array — Information about the follow-up tasks.

Items:
- content
  
  string — The follow-up task's content.
- create_time
  
  string — The follow-up task's creation time.
- engagement_id
  
  string — The engagement event's unique ID.
- task_id
  
  string — The follow-up task's unique ID.
- update_time
  
  string — The follow-up task's last modification time.
- user_id
  
  string — The ID of the user who created the task.

Example:

{
  "follow_up_tasks": [
    {
      "task_id": "W_VATTk_Q5aW6z5rZtBxAQ",
      "engagement_id": "Xh79Eq6gQhy8I1vM-r8P-w",
      "content": "The agent will check the customer's order status and provide an update.",
      "user_id": "DLv4511QThOGTMTWHn7oGw",
      "create_time": "2022-05-23T14:15:57Z",
      "update_time": "2022-05-23T14:15:57Z"
    }
  ]
}

Status: 400 HTTP Status Code: `400` Bad Request

Status: 401 HTTP Status Code: `401` Unauthorized Error Code: `124` Invalid access token. Error Code: `124` Access token has expired. Error Code: `1002` The user associated with this access token was not found or is invalid.

Status: 403 HTTP Status Code: `403` Forbidden Error Code: `1021` User account is deactivated. Error Code: `1022` User does not have a Contact Center license. Error Code: `9001` The Contact Center user associated with this bearer token is missing privileges on their role required to operate this request.

Status: 429 HTTP Status Code: `429` Too Many Requests. For more information, see [rate limits](https://developers.zoom.us/docs/api/rate-limits/). Error Code: `4001` You have reached the maximum per-second rate limit for this API. Try again later.

Get a follow-up task

Method: GET
Path: /contact_center/engagements/{engagementId}/follow_up_tasks/{taskId}
Tags: Follow-up Tasks

Returns a single follow-up task by engagement and task ID.

Scopes: contact_center_follow_up_task:read:admin

Granular Scopes: contact_center:read:follow_up_task:admin

Rate Limit Label: LIGHT

Responses

Status: 200 HTTP Status Code: `200` Follow-up task returned.

Content-Type: application/json

content (required)

string — The follow-up task's content.
create_time (required)

string — The follow-up task's creation time.
engagement_id (required)

string — The engagement event's unique ID.
task_id (required)

string — The follow-up task's unique ID.
update_time (required)

string — The follow-up task's last modification time.
user_id

string — The ID of the user who created the task.

Example:

{
  "task_id": "W_VATTk_Q5aW6z5rZtBxAQ",
  "engagement_id": "Xh79Eq6gQhy8I1vM-r8P-w",
  "content": "The agent will check the customer's order status and provide an update.",
  "user_id": "DLv4511QThOGTMTWHn7oGw",
  "create_time": "2022-05-23T14:15:57Z",
  "update_time": "2022-05-23T14:15:57Z"
}

Status: 401 HTTP Status Code: `401` Unauthorized Error Code: `124` Invalid access token. Error Code: `124` Access token has expired. Error Code: `1002` The user associated with this access token was not found or is invalid.

Status: 403 HTTP Status Code: `403` Forbidden Error Code: `1021` User account is deactivated. Error Code: `1022` User does not have a Contact Center license. Error Code: `9001` The Contact Center user associated with this bearer token is missing privileges on their role required to operate this request.

Status: 404 HTTP Status Code: `404` Not Found Error Code: `13002` Follow-up task does not exist: $taskId

Status: 429 HTTP Status Code: `429` Too Many Requests. For more information, see [rate limits](https://developers.zoom.us/docs/api/rate-limits/). Error Code: `4001` You have reached the maximum per-second rate limit for this API. Try again later.

Update a follow-up task

Method: PATCH
Path: /contact_center/engagements/{engagementId}/follow_up_tasks/{taskId}
Tags: Follow-up Tasks

Updates a single follow-up task.

Scopes: contact_center_follow_up_task:write

Granular Scopes: contact_center:update:follow_up_task

Rate Limit Label: LIGHT

Request Body

Content-Type: application/json

content (required)

string — The follow-up task's content.

Example:

{
  "content": "The agent will check the customer's order status and provide an update."
}

Responses

Status: 204 HTTP Status Code: `204` Follow-up task updated

Status: 400 HTTP Status Code: `400` Bad Request Error Code: `13003` Follow-up task can not be updated. You can only update the task that belongs to you.

Status: 404 HTTP Status Code: `404` Not Found Error Code: `13002` Follow-up task does not exist: $taskId

Status: 429 HTTP Status Code: `429` Too Many Requests. For more information, see [rate limits](https://developers.zoom.us/docs/api/rate-limits/).

List inboxes

Method: GET
Path: /contact_center/inboxes
Tags: Inboxes

Return a list of inboxes.

Scopes: contact_center_inbox:read:admin

Granular Scopes: contact_center:read:list_inboxes:admin

Rate Limit Label: MEDIUM

Responses

Status: 200 HTTP Status Code: `200` Inbox list returned.

Content-Type: application/json

inboxes

array — Information about the notes.

Items:
- access_queue_count
  
  integer — The inbox access queue count.
- access_user_count
  
  integer — The inbox access user count.
- inbox_id
  
  string — The inbox's unique ID.
- inbox_name
  
  string — The inbox's name.
- inbox_type
  
  string, possible values: "voicemail" — The inbox type. * voicemail
- last_modified_time
  
  string, format: date-time — The date and time when this data was last modified.
- modified_by
  
  string — The ID of the user that last modified this data.
next_page_token

string — Use the next page token to paginate through large result sets. A next page token is returned whenever the set of available results exceeds the current page size. This token's expiration period is 15 minutes.
page_size

integer, default: 30 — The number of records returned in a single API call.
total_records

integer — The total number of all records available across pages.

Example:

{
  "next_page_token": "R4aF9Oj0fVM2hhezJTEmSKaBSkfesDwGy42",
  "page_size": 30,
  "total_records": 10,
  "inboxes": [
    {
      "inbox_id": "W_VATTk_Q5aW6z5rZtBxAQ",
      "inbox_name": "example",
      "inbox_type": "voicemail",
      "access_user_count": 5,
      "access_queue_count": 5,
      "last_modified_time": "2022-02-15T09:27:15Z",
      "modified_by": "IGTRVt3gQ2i-WjoUIjeZxw"
    }
  ]
}

Status: 401 HTTP Status Code: `401` Unauthorized Error Code: `124` Invalid access token. Error Code: `124` Access token has expired. Error Code: `1002` The user associated with this access token was not found or is invalid.

Status: 403 HTTP Status Code: `403` Forbidden Error Code: `1021` User account is deactivated. Error Code: `1022` User does not have a Contact Center license. Error Code: `9001` The Contact Center user associated with this bearer token is missing privileges on their role required to operate this request.

Status: 429 HTTP Status Code: `429` Too Many Requests. For more information, see [rate limits](/docs/api/rate-limits/). Error Code: `4001` You have reached the maximum per-second rate limit for this API. Try again later.

Create an inbox

Method: POST
Path: /contact_center/inboxes
Tags: Inboxes

Create a new inbox.

Scopes: contact_center_inbox:write:admin

Granular Scopes: contact_center:write:inbox:admin

Rate Limit Label: LIGHT

Request Body

Content-Type: application/json

inbox_content_storage_location

string, possible values: "US", "AU", "BR", "CA", "DE", "JP", "SG" — The inbox content's physical storage location, using a two-letter country code. US: `United States` AU: `Australia` BR: `Brazil` CA: `Canada` DE: `Germany` JP: `Japan` SG: `Singapore`
inbox_description

string — The inbox's description.
inbox_name

string — The inbox's name.
inbox_type

string, possible values: "voicemail" — The inbox type. * voicemail
voicemail

object — The voicemail settings.
- delete_voicemail_days_limit
  
  integer — Delete voicemail after a specified number of days.
- soft_delete
  
  boolean — Enable soft deletion for the inbox.
- soft_delete_days_limit
  
  integer — When a voicemail is deleted, it is initially soft-deleted and can be restored within the admin-specified timeframe, which is up to 30 days. After that time, the voicemail is permanently deleted.
- voicemail_notification_by_email
  
  object — The voicemail notification by email.
  - emails
    
    array — Forward voicemail to an email list.
    
    Items:
    
    string
  - enable
    
    boolean — Enable voicemail notification by email.
  - forward_voicemail_to_emails
    
    boolean — Enable forward voicemail to emails.
  - include_voicemail_file
    
    boolean — Whether to include voicemail file.
  - include_voicemail_transcription
    
    boolean — Whether to include voicemail transcription.
- voicemail_time_limit
  
  integer — The voicemail time limit in minutes.
- voicemail_transcription
  
  boolean — The voicemail enable transcription.

Example:

{
  "inbox_name": "example",
  "inbox_description": "This is a inbox.",
  "inbox_type": "voicemail",
  "inbox_content_storage_location": "US",
  "voicemail": {
    "soft_delete": true,
    "soft_delete_days_limit": 20,
    "voicemail_time_limit": 5,
    "delete_voicemail_days_limit": 30,
    "voicemail_transcription": false,
    "voicemail_notification_by_email": {
      "enable": false,
      "include_voicemail_file": false,
      "include_voicemail_transcription": false,
      "forward_voicemail_to_emails": false,
      "emails": [
        "jchill@example.com"
      ]
    }
  }
}

Responses

Status: 201 HTTP Status Code: `201` Inbox created.

Content-Type: application/json

inbox_content_storage_location

string, possible values: "US", "AU", "BR", "CA", "DE", "JP", "SG" — The inbox content's physical storage location, using a two-letter country code. US: `United States` AU: `Australia` BR: `Brazil` CA: `Canada` DE: `Germany` JP: `Japan` SG: `Singapore`
inbox_description

string — The inbox's description.
inbox_id

string — The inbox's unique ID.
inbox_name

string — The inbox's name.
inbox_type

string, possible values: "voicemail" — The inbox type. * voicemail
last_modified_time

string, format: date-time — The date and time when this data was last modified.
modified_by

string — The ID of the user that last modified this data.
voicemail

object — The voicemail settings.
- delete_voicemail_days_limit
  
  integer — Delete voicemail after a specified number of days.
- soft_delete
  
  boolean — Enable soft deletion for the inbox.
- soft_delete_days_limit
  
  integer — When a voicemail is deleted, it is initially soft-deleted and can be restored within the admin-specified timeframe, which is up to 30 days. After that time, the voicemail is permanently deleted.
- voicemail_auto_assignment
  
  object — Voicemail auto assignment settings.
  - enable
    
    boolean — Enable voicemail auto assignment.
  - voicemail_auto_assignment_content_id
    
    string — The voicemail auto assignment operation object's ID. Can be `userId`, `queueId` or `teamId`. This field is only effective when `voicemail_auto_assignment_type` is `1`, `3`, or `4`.
  - voicemail_auto_assignment_during_active_work_session
    
    integer, format: int32, possible values: 0, 1 — The person assigned the voicemail auto assignment is during an active work session.The value can only be `0` inactive or `1` active. This field is only effective when `voicemail_auto_assignment_type` is `2`, `3`, `4`, or `5`.
  - voicemail_auto_assignment_routine_profile_id
    
    string — Routine profile ID used by voicemail auto assignment. This field only takes effect when `voicemail_auto_assignment_type` is `2`, `3`, `4,` or `5`, and the user has set a routine profile.
  - voicemail_auto_assignment_type
    
    integer, format: int32, possible values: 1, 2, 3, 4, 5 — Voicemail auto assignment type. The value can only be one of these values. *1 - user *2 - access list *3 - queue *4 - team *5 - rotation
- voicemail_notification_by_email
  
  object — The voicemail notification by email.
  - emails
    
    array — Forward voicemail to an email list.
    
    Items:
    
    string
  - enable
    
    boolean — The voicemail enable notification by email.
  - forward_voicemail_to_emails
    
    boolean — Enable forwarding voicemail to emails.
  - include_voicemail_file
    
    boolean — Whether to include voicemail file.
  - include_voicemail_transcription
    
    boolean — Whether to include voicemail transcription.
- voicemail_send_reminders_for_unresolved
  
  object — Reminder policy for unresolved voicemails.
  - enable
    
    boolean — Enable a reminder policy for unresolved voicemails.
  - send_alert_for_unresolved_voicemail_timeout
    
    integer — Timeout for unresolved voicemail reminders, in minutes. The range is from 1 to 10080.
- voicemail_time_limit
  
  integer — The voicemail time limit in minutes.
- voicemail_transcription
  
  boolean — Enable voicemail transcription.

Example:

{
  "inbox_id": "W_VATTk_Q5aW6z5rZtBxAQ",
  "inbox_name": "example",
  "inbox_description": "This is a inbox.",
  "inbox_type": "voicemail",
  "inbox_content_storage_location": "US",
  "last_modified_time": "2022-02-15T09:27:15Z",
  "modified_by": "IGTRVt3gQ2i-WjoUIjeZxw",
  "voicemail": {
    "soft_delete": true,
    "soft_delete_days_limit": 20,
    "voicemail_time_limit": 5,
    "delete_voicemail_days_limit": 30,
    "voicemail_transcription": false,
    "voicemail_notification_by_email": {
      "enable": false,
      "include_voicemail_file": false,
      "include_voicemail_transcription": false,
      "forward_voicemail_to_emails": false,
      "emails": [
        "jchill@example.com"
      ]
    },
    "voicemail_auto_assignment": {
      "enable": false,
      "voicemail_auto_assignment_type": 1,
      "voicemail_auto_assignment_during_active_work_session": 0,
      "voicemail_auto_assignment_content_id": "testUserId",
      "voicemail_auto_assignment_routine_profile_id": "testRoutineProfileId"
    },
    "voicemail_send_reminders_for_unresolved": {
      "enable": false,
      "send_alert_for_unresolved_voicemail_timeout": 30
    }
  }
}

Status: 400 HTTP Status Code: `400` Bad Request

Status: 401 HTTP Status Code: `401` Unauthorized

Status: 403 HTTP Status Code: `403` Forbidden

Status: 429 HTTP Status Code: `429` Too Many Requests. For more information, see [rate limits](/docs/api/rate-limits/).

Delete inboxes

Method: DELETE
Path: /contact_center/inboxes
Tags: Inboxes

Delete one or more inboxes.

Scopes: contact_center_inbox:write:admin

Granular Scopes: contact_center:delete:inbox:admin

Rate Limit Label: MEDIUM

Responses

Status: 204 HTTP Status Code: `204` Inboxes deleted.

Status: 400 HTTP Status Code: `400` Bad Request

Status: 401 HTTP Status Code: `401` Unauthorized Error Code: `124` Invalid access token. Error Code: `124` Access token has expired. Error Code: `1002` The user associated with this access token was not found or is invalid.

Status: 403 HTTP Status Code: `403` Forbidden Error Code: `1021` User account is deactivated. Error Code: `1022` User does not have a Contact Center license. Error Code: `9001` The Contact Center user associated with this bearer token is missing privileges on their role required to operate this request.

Status: 404 HTTP Status Code: `404` Not Found Error Code: `3001` Inbox does not exist: $inboxId.

Status: 429 HTTP Status Code: `429` Too Many Requests. For more information, see [rate limits](/docs/api/rate-limits/). Error Code: `4001` You have reached the maximum per-second rate limit for this API. Try again later.

List an account's inbox messages

Method: GET
Path: /contact_center/inboxes/messages
Tags: Inboxes

Return all messages in an inbox.

Scopes: contact_center_inbox:read:admin

Granular Scopes: contact_center:read:inbox_messages:admin

Rate Limit Label: MEDIUM

Responses

Status: 200 HTTP Status Code: `200` Inbox messages returned.

Content-Type: application/json

messages

array — Information about the inbox message.

Items:
- cci_queue_id
  
  string — The Contact Center queue ID of the inbox message routed by the queue.
- consumer_display_name
  
  string — The consumer's name.
- consumer_id
  
  string — The consumer's ID.
- consumer_number
  
  string — The consumer's phone number.
- created_at
  
  string, format: date-time — The inbox message's creation time.
- download_url
  
  string — The URL to download the inbox message. For security purposes, you **must** provide an OAuth access token in the authorization header to download the inbox message file using this URL. Example: ```curl --request GET --url {download_url} --header 'authorization: Bearer {access_token}' --header 'content-type: application/json' ```
- engagement_id
  
  string — The engagement's ID.
- flow_id
  
  string — The flow's ID.
- flow_name
  
  string — The flow's name.
- inbox_id
  
  string — The inbox's unique ID.
- inbox_name
  
  string — The inbox's name.
- message_duration
  
  integer — The inbox message's duration in seconds.
- message_id
  
  string — The inbox message's ID.
- message_type
  
  string, possible values: "voicemail" — The inbox message's type. * voicemail
- playback_url
  
  string — The URL to playback the inbox message. For security purposes, you **must** provide an OAuth access token in the authorization header to playback the inbox message file using this URL. Example: ```curl --request GET --url {playback_url} --header 'authorization: Bearer {access_token}' --header 'content-type: application/json' ```
- queue_id
  
  string — The queue ID of the inbox message routed by the queue.
- queue_name
  
  string — The queue name of the inbox message routed by the queue.
- status
  
  string, possible values: "normal", "deleted" — The inbox message soft delete flag. * normal * deleted
- transcript_url
  
  string — The URL to download the inbox message transcript. For security purposes, you **must** provide an OAuth access token in the authorization header to download the recording transcript file using this URL. Example: ```curl --request GET --url {transcript_url} --header 'authorization: Bearer {access_token}' --header 'content-type: application/json' ```
next_page_token

string — Use the next page token to paginate through large result sets. A next page token returns when the set of available results exceeds the current page size. This token's expiration period is 15 minutes.
page_size

integer, default: 30 — The number of records returned in a single API call.
total_records

integer — The total number of all the records available across pages.

Example:

{
  "next_page_token": "R4aF9Oj0fVM2hhezJTEmSKaBSkfesDwGy42",
  "page_size": 30,
  "total_records": 1,
  "messages": [
    {
      "message_id": "4Q0ILNMfTA2nJolNxhg0Rw",
      "inbox_id": "W_VATTk_Q5aW6z5rZtBxAQ",
      "inbox_name": "example",
      "engagement_id": "xRk0eHNNTGygFDPrWqR9FA",
      "created_at": "2022-05-23T14:15:57Z",
      "flow_id": "1wGgU3HQR8u1wWjPFNXOyA",
      "flow_name": "inbox_message_flow",
      "cci_queue_id": "LB937Z8oQP2mJxeNj3GxJQ",
      "queue_name": "inbox_message_queue",
      "message_type": "voicemail",
      "download_url": "https://api.zoom.us/v2/contact_center/inbox/message/download/4Q0ILNMfTA2nJolNxhg0Rw?type=voicemail",
      "playback_url": "https://api.zoom.us/v2/contact_center/inbox/message/playback/4Q0ILNMfTA2nJolNxhg0Rw?type=voicemail",
      "transcript_url": "https://api.zoom.us/v2/contact_center/inbox/message/transcripts/download/4Q0ILNMfTA2nJolNxhg0Rw",
      "message_duration": 150,
      "consumer_number": "+12058945728",
      "consumer_id": "fsdfere78fserhgfyjb",
      "consumer_display_name": "Jill",
      "status": "normal"
    }
  ]
}

Status: 429 HTTP Status Code: `429` Too Many Requests. For more information, see [rate limits](https://developers.zoom.us/docs/api/rest/rate-limits/).

Delete inbox messages

Method: DELETE
Path: /contact_center/inboxes/messages
Tags: Inboxes

Delete messages.

Scopes: contact_center_inbox:write:admin

Granular Scopes: contact_center:delete:inbox_messages:admin

Rate Limit Label: LIGHT

Responses

Status: 204 HTTP Status Code: `204` Inbox messages deleted.

Status: 400 HTTP Status Code: `400` Bad Request

Status: 429 HTTP Status Code: `429` Too Many Requests. For more information, see [rate limits](https://developers.zoom.us/docs/api/rest/rate-limits/).

Get an inbox

Method: GET
Path: /contact_center/inboxes/{inboxId}
Tags: Inboxes

Retrieve an inbox.

Scopes: contact_center_inbox:read:admin

Granular Scopes: contact_center:read:inbox:admin

Rate Limit Label: LIGHT

Responses

Status: 200 HTTP Status Code: `200` Inbox returned.

Content-Type: application/json

inbox_content_storage_location

string, possible values: "US", "AU", "BR", "CA", "DE", "JP", "SG" — The inbox content's physical storage location, using a two-letter country code. US: `United States` AU: `Australia` BR: `Brazil` CA: `Canada` DE: `Germany` JP: `Japan` SG: `Singapore`
inbox_description

string — The inbox's description.
inbox_id

string — The inbox's unique ID.
inbox_name

string — The inbox's name.
inbox_type

string, possible values: "voicemail" — The inbox type.
last_modified_time

string, format: date-time — The date and time when this data was last modified.
modified_by

string — The ID of last user to modify the inbox.
voicemail

object — The voicemail settings.
- delete_voicemail_days_limit
  
  integer — Delete voicemail after a specified number of days.
- greeting_audio_asset_id
  
  string — Greeting audio asset ID used for voicemail.
- soft_delete
  
  boolean — Enable soft deletion for the inbox.
- soft_delete_days_limit
  
  integer — When a voicemail is deleted, it is initially soft-deleted and can be restored within the admin-specified timeframe, which is up to 30 days. After that time, the voicemail is permanently deleted.
- voicemail_auto_assignment
  
  object — Voicemail auto assignment settings.
  - enable
    
    boolean — Enable voicemail auto assignment.
  - voicemail_auto_assignment_content_id
    
    string — The voicemail auto assignment operation object's ID. Can be `userId`, `queueId`, or `teamId`. This field is only effective when `voicemail_auto_assignment_type` is `1`, `3`, or `4`.
  - voicemail_auto_assignment_during_active_work_session
    
    integer, format: int32, possible values: 0, 1 — The person assigned the voicemail auto assignment is during an active work session. The value can only be `0` or `1`, 0 - inactive, 1 - active. This field is only effective when `voicemail_auto_assignment_type` is `2`, `3`, `4`, or `5`.
  - voicemail_auto_assignment_routine_profile_id
    
    string — Routine profile ID used by voicemail auto assignment. This field only takes effect when `voicemail_auto_assignment_type` is `2`, `3`, `4`, or `5`, and the user has set a routine profile.
  - voicemail_auto_assignment_type
    
    integer, format: int32, possible values: 1, 2, 3, 4, 5 — Voicemail auto assignment type. The value can be any one of these options. *1 - user *2 - access list *3 - queue *4 - team *5 - rotation
- voicemail_notification_by_email
  
  object — The voicemail notification by email.
  - emails
    
    array — Forward voicemail to email list.
    
    Items:
    
    string
  - enable
    
    boolean — The voicemail enable notification by email.
  - forward_voicemail_to_emails
    
    boolean — Enable forwarding voicemail to emails.
  - include_voicemail_file
    
    boolean — Whether to include voicemail file.
  - include_voicemail_transcription
    
    boolean — Whether to include voicemail transcription.
- voicemail_send_reminders_for_unresolved
  
  object — Reminder policy for unresolved voicemails.
  - enable
    
    boolean — Enable a reminder policy for unresolved voicemails.
  - send_alert_for_unresolved_voicemail_timeout
    
    integer — Timeout for unresolved voicemail reminders, in minutes. The range is from 1 to 10080.
- voicemail_time_limit
  
  integer — The voicemail time limit in minutes.
- voicemail_transcription
  
  boolean — Enable voicemail transcription.

Example:

{
  "inbox_id": "W_VATTk_Q5aW6z5rZtBxAQ",
  "inbox_name": "example",
  "inbox_description": "This is a inbox.",
  "inbox_type": "voicemail",
  "inbox_content_storage_location": "US",
  "last_modified_time": "2022-02-15T09:27:15Z",
  "modified_by": "IGTRVt3gQ2i-WjoUIjeZxw",
  "voicemail": {
    "soft_delete": true,
    "soft_delete_days_limit": 20,
    "voicemail_time_limit": 5,
    "delete_voicemail_days_limit": 30,
    "voicemail_transcription": false,
    "voicemail_notification_by_email": {
      "enable": false,
      "include_voicemail_file": false,
      "include_voicemail_transcription": false,
      "forward_voicemail_to_emails": false,
      "emails": [
        "jchill@example.com"
      ]
    },
    "greeting_audio_asset_id": "testAssetId",
    "voicemail_auto_assignment": {
      "enable": false,
      "voicemail_auto_assignment_type": 1,
      "voicemail_auto_assignment_during_active_work_session": 0,
      "voicemail_auto_assignment_content_id": "testUserId",
      "voicemail_auto_assignment_routine_profile_id": "testRoutineProfileId"
    },
    "voicemail_send_reminders_for_unresolved": {
      "enable": false,
      "send_alert_for_unresolved_voicemail_timeout": 30
    }
  }
}

Status: 400 HTTP Status Code: `400` Bad Request Error Code: `3010` More than one matching inbox found.

Status: 404 HTTP Status Code: `404` Not Found Error Code: `3001` Inbox does not exist: $inboxId.

Status: 429 HTTP Status Code: `429` Too Many Requests. For more information, see [rate limits](https://developers.zoom.us/docs/api/rate-limits/).

Update an inbox

Method: PATCH
Path: /contact_center/inboxes/{inboxId}
Tags: Inboxes

Update an inbox.

Scopes: contact_center_inbox:write:admin

Granular Scopes: contact_center:update:inbox:admin

Rate Limit Label: LIGHT

Request Body

Content-Type: application/json

inbox_content_storage_location

string, possible values: "US", "AU", "BR", "CA", "DE", "JP", "SG" — The inbox content's physical storage location, using a two-letter country code. US: `United States` AU: `Australia` BR: `Brazil` CA: `Canada` DE: `Germany` JP: `Japan` SG: `Singapore`
inbox_description

string — The inbox's description.
inbox_name

string — The inbox's name.
voicemail

object — The voicemail settings.
- delete_voicemail_days_limit
  
  integer — Delete voicemail after a specified number of days.
- greeting_audio_asset_id
  
  string — Greeting audio asset ID used for voicemail.
- soft_delete
  
  boolean — Enable soft deletion for the inbox.
- soft_delete_days_limit
  
  integer — When a voicemail is deleted, it is initially soft-deleted and can be restored within the admin-specified timeframe, which is up to 30 days. After that time, the voicemail is permanently deleted.
- voicemail_auto_assignment
  
  object — Voicemail auto assignment settings.
  - enable
    
    boolean — Enable voicemail auto assignment.
  - voicemail_auto_assignment_content_id
    
    string — The voicemail auto assignment operation object's ID. Can be `userId`, `queueId` or `teamId`. This field is only effective when `voicemail_auto_assignment_type` is `1`, `3`, or `4`.
  - voicemail_auto_assignment_during_active_work_session
    
    integer, format: int32, possible values: 0, 1 — The person assigned the voicemail auto assignment is during an active work session.The value can only be `0` inactive or `1` active. This field is only effective when `voicemail_auto_assignment_type` is `2`, `3`, `4`, or `5`.
  - voicemail_auto_assignment_routine_profile_id
    
    string — Routine profile ID used by voicemail auto assignment. This field only takes effect when `voicemail_auto_assignment_type` is `2`, `3`, `4,` or `5`, and the user has set a routine profile.
  - voicemail_auto_assignment_type
    
    integer, format: int32, possible values: 1, 2, 3, 4, 5 — Voicemail auto assignment type. The value can only be one of these values. *1 - user *2 - access list *3 - queue *4 - team *5 - rotation
- voicemail_notification_by_email
  
  object — The voicemail notification by email.
  - emails
    
    array — Forward voicemail to email list.
    
    Items:
    
    string
  - enable
    
    boolean — The voicemail enable notification by email.
  - forward_voicemail_to_emails
    
    boolean — Enable forwarding voicemail to emails.
  - include_voicemail_file
    
    boolean — Whether to include voicemail file.
  - include_voicemail_transcription
    
    boolean — Whether to include voicemail transcription.
- voicemail_send_reminders_for_unresolved
  
  object — Reminder policy for unresolved voicemails.
  - enable
    
    boolean — Enable a reminder policy for unresolved voicemails.
  - send_alert_for_unresolved_voicemail_timeout
    
    integer — Timeout for unresolved voicemail reminders, in minutes. The range is from 1 to 10080.
- voicemail_time_limit
  
  integer — The voicemail time limit in minutes.
- voicemail_transcription
  
  boolean — Enable voicemail transcription.

Example:

{
  "inbox_name": "example",
  "inbox_description": "This is a inbox.",
  "inbox_content_storage_location": "US",
  "voicemail": {
    "soft_delete": true,
    "soft_delete_days_limit": 20,
    "voicemail_time_limit": 5,
    "delete_voicemail_days_limit": 30,
    "voicemail_transcription": false,
    "voicemail_notification_by_email": {
      "enable": false,
      "include_voicemail_file": false,
      "include_voicemail_transcription": false,
      "forward_voicemail_to_emails": false,
      "emails": [
        "jchill@example.com"
      ]
    },
    "greeting_audio_asset_id": "testAssetId",
    "voicemail_auto_assignment": {
      "enable": false,
      "voicemail_auto_assignment_type": 1,
      "voicemail_auto_assignment_during_active_work_session": 0,
      "voicemail_auto_assignment_content_id": "testUserId",
      "voicemail_auto_assignment_routine_profile_id": "testRoutineProfileId"
    },
    "voicemail_send_reminders_for_unresolved": {
      "enable": false,
      "send_alert_for_unresolved_voicemail_timeout": 30
    }
  }
}

Responses

Status: 204 HTTP Status Code: `204` Inbox updated.

Status: 400 HTTP Status Code: `400` Bad Request

Status: 404 HTTP Status Code: `404` Not Found Error Code: `3001` Inbox does not exist: $inboxId.

Status: 429 HTTP Status Code: `429` Too Many Requests. For more information, see [rate limits](/docs/api/rate-limits/).

Update an inbox's email notification setting

Method: PATCH
Path: /contact_center/inboxes/{inboxId}/email_notification
Tags: Inboxes

Update an inbox's email notification setting for a given user.

Scopes: contact_center_inbox:write:admin

Granular Scopes: contact_center:update:inbox:admin

Rate Limit Label: LIGHT

Request Body

Content-Type: application/json

user_id (required)

string — The email, Meetings user ID, or Contact Center id used to identify the user. This value will not be modified.
email_notification

boolean — Enable email notification. Defaults to `false`.

Example:

{
  "user_id": "IGTRVt3gQ2i-WjoUIjeZxw",
  "email_notification": true
}

Responses

Status: 204 HTTP Status Code: `204` Inbox email notifictaion updated.

Status: 400 HTTP Status Code: `400` Bad Request Error Code: `3009` The voicemail email notification setting for inbox ''{inboxId}'' is locked and cannot be modified.

Status: 401 HTTP Status Code: `401` Unauthorized Error Code: `124` Invalid access token. Error Code: `124` Access token has expired. Error Code: `1002` The user associated with this access token was not found or is invalid.

Status: 403 HTTP Status Code: `403` Forbidden Error Code: `1021` User account is deactivated. Error Code: `1022` User does not have a Contact Center license. Error Code: `9001` The Contact Center user associated with this bearer token is missing privileges on their role required to operate this request.

Status: 404 HTTP Status Code: `404` Not Found Error Code: `3001` Inbox does not exist: {inboxId}. Error Code: `1001` User does not exist: {userId}.

Status: 429 HTTP Status Code: `429` Too Many Requests. For more information, see [rate limits](/docs/api/rate-limits/). Error Code: `4001` You have reached the maximum per-second rate limit for this API. Try again later.

Get an inbox email notification list

Method: GET
Path: /contact_center/inboxes/{inboxId}/email_notifications
Tags: Inboxes

Retrieve a list of inbox email notifications.

Scopes: contact_center_inbox:read:admin

Granular Scopes: contact_center:read:inbox:admin

Rate Limit Label: MEDIUM

Responses

Status: 200 HTTP Status Code: `200` \n \nInbox email notifictaion settings returned.

Content-Type: application/json

email_notifications

array — Information about the inbox email notification settings.

Items:
- display_name
  
  string — The user's display name.
- email_notification
  
  boolean — Enable email notification.
- user_email
  
  string, format: email — The user's email address.
- user_id
  
  string — The Meetings user identifier.
next_page_token

string — Use the next page token to paginate through large result sets. A next page token is returned whenever the set of available results exceeds the current page size. This token's expiration period is 15 minutes.
page_size

integer, default: 30 — The number of records returned in a single API call.
total_records

integer — The total number of all records available across pages.

Example:

{
  "next_page_token": "R4aF9Oj0fVM2hhezJTEmSKaBSkfesDwGy42",
  "page_size": 30,
  "total_records": 10,
  "email_notifications": [
    {
      "user_id": "IGTRVt3gQ2i-WjoUIjeZxw",
      "email_notification": true,
      "display_name": "Jane Doe",
      "user_email": "jchill@example.com"
    }
  ]
}

Status: 400 HTTP Status Code: `400` Bad Request Error Code: `3010` More than one matching inbox found.

Status: 401 HTTP Status Code: `401` Unauthorized Error Code: `124` Invalid access token. Error Code: `124` Access token has expired. Error Code: `1002` The user associated with this access token was not found or is invalid.

Status: 403 HTTP Status Code: `403` Forbidden Error Code: `1021` User account is deactivated. Error Code: `1022` User does not have a Contact Center license. Error Code: `9001` The Contact Center user associated with this bearer token is missing privileges on their role required to operate this request.

Status: 404 HTTP Status Code: `404` Not Found Error Code: `3001` Inbox does not exist: $inboxId.

Status: 429 HTTP Status Code: `429` Too Many Requests. For more information, see [rate limits](https://developers.zoom.us/docs/api/rate-limits/). Error Code: `4001` You have reached the maximum per-second rate limit for this API. Try again later.

List an inbox's messages

Method: GET
Path: /contact_center/inboxes/{inboxId}/messages
Tags: Inboxes

Return a list of all messages in an inbox.

Scopes: contact_center_inbox:read:admin

Granular Scopes: contact_center:read:inbox_messages:admin

Rate Limit Label: MEDIUM

Responses

Status: 200 HTTP Status Code: `200` Inbox messages returned.

Content-Type: application/json

messages

array — Information about the inbox message.

Items:
- consumer_display_name
  
  string — The consumer's name.
- consumer_id
  
  string — The consumer's ID.
- consumer_number
  
  string — The consumer's phone number.
- created_at
  
  string, format: date-time — The inbox message's creation time.
- download_url
  
  string — The URL to download the inbox message. For security purposes, you **must** provide an OAuth access token in the authorization header to download the inbox message file using this URL. Example: ```curl --request GET --url {download_url} --header 'authorization: Bearer {access_token}' --header 'content-type: application/json' ```
- engagement_id
  
  string — The engagement's ID.
- flow_id
  
  string — The flow's ID.
- flow_name
  
  string — The flow's name.
- inbox_id
  
  string — The inbox's unique ID.
- inbox_name
  
  string — The inbox's name.
- message_duration
  
  integer — The inbox message's duration in seconds.
- message_id
  
  string — The inbox message's ID.
- message_type
  
  string, possible values: "voicemail" — The inbox message's type.
- playback_url
  
  string — The URL to playback the inbox message. For security purposes, you **must** provide an OAuth access token in the authorization header to playback the inbox message file using this URL. Example: ```curl --request GET --url {playback_url} --header 'authorization: Bearer {access_token}' --header 'content-type: application/json' ```
- queue_id
  
  string — The queue ID of the inbox message routed by the queue.
- queue_name
  
  string — The queue name of the inbox message routed by the queue.
- status
  
  string, possible values: "normal", "deleted" — The inbox message soft delete flag.
- transcript_url
  
  string — The URL to download the inbox message transcript. For security purposes, you **must** provide an OAuth access token in the authorization header to download the recording transcript file using this URL. Example: ```curl --request GET --url {transcript_url} --header 'authorization: Bearer {access_token}' --header 'content-type: application/json' ```
next_page_token

string — Use the next page token to paginate through large result sets. A next page token returns when the set of available results exceeds the current page size. This token's expiration period is 15 minutes.
page_size

integer, default: 30 — The number of records returned in a single API call.
total_records

integer — The total number of all the records available across pages.

Example:

{
  "next_page_token": "R4aF9Oj0fVM2hhezJTEmSKaBSkfesDwGy42",
  "page_size": 30,
  "total_records": 1,
  "messages": [
    {
      "message_id": "4Q0ILNMfTA2nJolNxhg0Rw",
      "inbox_id": "W_VATTk_Q5aW6z5rZtBxAQ",
      "inbox_name": "example",
      "engagement_id": "xRk0eHNNTGygFDPrWqR9FA",
      "created_at": "2022-05-23T14:15:57Z",
      "flow_id": "1wGgU3HQR8u1wWjPFNXOyA",
      "flow_name": "inbox_message_flow",
      "queue_id": "ZWQ84A20CBBA11AFA5BC55079D5A12A28D7",
      "queue_name": "inbox_message_queue",
      "message_type": "voicemail",
      "download_url": "https://api.zoom.us/v2/contact_center/inbox/message/download/4Q0ILNMfTA2nJolNxhg0Rw?type=voicemail",
      "playback_url": "https://api.zoom.us/v2/contact_center/inbox/message/playback/4Q0ILNMfTA2nJolNxhg0Rw?type=voicemail",
      "transcript_url": "https://api.zoom.us/v2/contact_center/inbox/message/transcripts/download/4Q0ILNMfTA2nJolNxhg0Rw",
      "message_duration": 150,
      "consumer_number": "+12058945728",
      "consumer_id": "fsdfere78fserhgfyjb",
      "consumer_display_name": "Jill",
      "status": "normal"
    }
  ]
}

Status: 400 HTTP Status Code: `400` Bad Request Error Code: `3010` More than one matching inbox found.

Status: 404 HTTP Status Code: `404` Not Found Error Code: `3001` Inbox does not exist: $inboxId.

Status: 429 HTTP Status Code: `429` Too Many Requests. For more information, see [rate limits](/docs/api/rate-limits/).

Delete an inbox's messages

Method: DELETE
Path: /contact_center/inboxes/{inboxId}/messages
Tags: Inboxes

Delete messages in an inbox.

Scopes: contact_center_inbox:write:admin

Granular Scopes: contact_center:delete:inbox_messages:admin

Rate Limit Label: LIGHT

Responses

Status: 204 HTTP Status Code: `204` Inbox messages deleted.

Status: 400 HTTP Status Code: `400` Bad Request

Status: 404 HTTP Status Code: `404` Not Found Error Code: `3001` Inbox does not exist: $inboxId.

Status: 429 HTTP Status Code: `429` Too Many Requests. For more information, see [rate limits](https://developers.zoom.us/docs/api/rest/rate-limits/).

Delete an inbox message

Method: DELETE
Path: /contact_center/inboxes/{inboxId}/messages/{messageId}
Tags: Inboxes

Delete a single message in an inbox.

Scopes: contact_center_inbox:write:admin

Granular Scopes: contact_center:delete:inbox_message:admin

Rate Limit Label: LIGHT

Responses

Status: 204 HTTP Status Code: `204` Inbox message deleted.

Status: 400 HTTP Status Code: `400` Bad Request

Status: 404 HTTP Status Code: `404` Not Found Error Code: `3001` Inbox does not exist: $inboxId. Error Code: `3101` Inbox message does not exist: $messageId. Error Code: `3102` The inbox id that matches this message id is: $inboxId.

Status: 429 HTTP Status Code: `429` Too Many Requests. For more information, see [rate limits](https://developers.zoom.us/docs/api/rest/rate-limits/).

Get inbox access queues

Method: GET
Path: /contact_center/inboxes/{inboxId}/queues
Tags: Inboxes

Retrieve a list of queues that have access to an inbox.

Scopes: contact_center_queue:read:admin

Granular Scopes: contact_center:read:list_inbox_queues:admin

Rate Limit Label: MEDIUM

Responses

Status: 200 HTTP Status Code: `200` List of inbox queues returned.

Content-Type: application/json

next_page_token

string — Use the next page token to paginate through large result sets. A next page token returns whenever the set of available results exceeds the current page size. This token's expiration period is 15 minutes.
page_size

integer, default: 30 — The number of records returned within a single API call.
queues

array — Information about the task queues.

Items:
- agents_count
  
  integer — The number of assigned agents.
- cc_queue_id
  
  string — The Contact Center queue's ID.
- channel
  
  string, possible values: "voice", "video", "messaging", "email" — The Contact Center queue's channel.
- channel_types
  
  array — The task queue's channel types.
  
  Items:
  
  string, possible values: "voice", "chat", "sms", "video", "in_app_chat"
- queue_id
  
  string — The task queue's ID.
- queue_name
  
  string — The task queue's name.
- supervisors_count
  
  integer — The number of assigned supervisors.
total_records

integer — The total number of all the records available across pages.

Example:

{
  "next_page_token": "R4aF9Oj0fVM2hhezJTEmSKaBSkfesDwGy42",
  "page_size": 30,
  "total_records": 1,
  "queues": [
    {
      "cc_queue_id": "Ql3qxUWXSHes4PmcOmzyOg",
      "queue_name": "queue_661c6e4b-89fc-4b0d-9978-c7394725462",
      "agents_count": 1,
      "supervisors_count": 1,
      "channel": "voice"
    }
  ]
}

Status: 400 HTTP Status Code: `400` Bad Request Error Code: `3010` More than one matching inbox found.

Status: 401 HTTP Status Code: `401` Unauthorized Error Code: `124` Invalid access token. Error Code: `124` Access token has expired. Error Code: `1002` The user associated with this access token was not found or is invalid.

Status: 403 HTTP Status Code: `403` Forbidden Error Code: `1021` User account is deactivated. Error Code: `1022` User does not have a Contact Center license. Error Code: `9001` The Contact Center user associated with this bearer token is missing privileges on their role required to operate this request.

Status: 404 HTTP Status Code: `404` Not Found Error Code: `3001` Inbox does not exist: $inboxId.

Status: 429 HTTP Status Code: `429` Too Many Requests. For more information, see [rate limits](https://developers.zoom.us/docs/api/rate-limits/). Error Code: `4001` You have reached the maximum per-second rate limit for this API. Try again later.

Assign inbox access queues

Method: POST
Path: /contact_center/inboxes/{inboxId}/queues
Tags: Inboxes

Assign queues access to an inbox.

Scopes: contact_center_queue:write:admin

Granular Scopes: contact_center:write:inbox_queue:admin

Rate Limit Label: MEDIUM

Request Body

Content-Type: application/json

cc_queue_ids

array

Items:

string — The Contact Center queue's ID.
queue_ids

array

Items:

string — The queue's ID.

Example:

{
  "cc_queue_ids": [
    "zeYjXoDOS_eV1QmTpj63PQ"
  ]
}

Responses

Status: 200 HTTP Status Code: `200` List of queues has been updated.

Status: 400 HTTP Status Code: `400` Bad Request Error Code: `1202` "Queues do not exist: [$queue_id]." Error Code: `1203` Queue is already assigned to inbox: [$queue_id].

Status: 404 HTTP Status Code: `404` Not Found Error Code: `3001` Inbox does not exist: $inboxId.

Status: 429 HTTP Status Code: `429` Too Many Requests. For more information, see [rate limits](https://developers.zoom.us/docs/api/rest/rate-limits/).

Remove inbox access queues

Method: DELETE
Path: /contact_center/inboxes/{inboxId}/queues
Tags: Inboxes

Remove queues' access to an inbox.

Scopes: contact_center_queue:write:admin

Granular Scopes: contact_center:delete:inbox_queue:admin

Rate Limit Label: MEDIUM

Responses

Status: 200 HTTP Status Code: `200` Queues' access has been removed from the inbox.

Status: 400 HTTP Status Code: `400` Bad Request Error Code: `1202` "Queues do not exist: [$queue_id]." Error Code: `1204` Queue is not assigned to inbox: [$queue_id].

Status: 404 HTTP Status Code: `404` Not Found Error Code: `3001` Inbox does not exist: $inboxId.

Status: 429 HTTP Status Code: `429` Too Many Requests. For more information, see [rate limits](https://developers.zoom.us/docs/api/rest/rate-limits/).

List inbox users

Method: GET
Path: /contact_center/inboxes/{inboxId}/users
Tags: Inboxes

Retrieve a list of users assigned to an inbox.

Scopes: contact_center_user:read:admin

Granular Scopes: contact_center:read:inbox_user:admin

Rate Limit Label: MEDIUM

Responses

Status: 200 HTTP Status Code: `200` Returns a list of users assigned to the inbox.

Content-Type: application/json

next_page_token

string — Use the next page token to paginate through large result sets. A next page token is returned whenever the set of available results exceeds the current page size. This token's expiration period is 15 minutes.
page_size

integer, default: 30 — The number of records returned in a single API call.
total_records

integer — The total number of all records available across pages.
users

array — Information about the users.

Items:
- cc_user_id
  
  string — The Contact Center user identifier.
- display_name
  
  string — The user's display name.
- user_email
  
  string, format: email — The user's email address.
- user_id
  
  string — The Meetings user identifier.

Example:

{
  "next_page_token": "R4aF9Oj0fVM2hhezJTEmSKaBSkfesDwGy42",
  "page_size": 30,
  "total_records": 10,
  "users": [
    {
      "user_id": "IGTRVt3gQ2i-WjoUIjeZxw",
      "cc_user_id": "hKuMAiDdRlSwMkBxR5we7g",
      "display_name": "Jane Doe",
      "user_email": "jchill@example.com"
    }
  ]
}

Status: 400 HTTP Status Code: `400` Bad Request Error Code: `3010` More than one matching inbox found.

Status: 401 HTTP Status Code: `401` Unauthorized Error Code: `124` Invalid access token. Error Code: `124` Access token has expired. Error Code: `1002` The user associated with this access token was not found or is invalid.

Status: 403 HTTP Status Code: `403` Forbidden Error Code: `1021` User account is deactivated. Error Code: `1022` User does not have a Contact Center license. Error Code: `9001` The Contact Center user associated with this bearer token is missing privileges on their role required to operate this request.

Status: 404 HTTP Status Code: `404` Not Found Error Code: `3001` Inbox does not exist: $inboxId.

Status: 429 HTTP Status Code: `429` Too Many Requests. For more information, see [rate limits](/docs/api/rest/rate-limits/). Error Code: `4001` You have reached the maximum per-second rate limit for this API. Try again later.

Assign inbox access users

Method: POST
Path: /contact_center/inboxes/{inboxId}/users
Tags: Inboxes

Assign users to a Contact Center inbox. This operation is atomic - all specified users must be valid and not already assigned to the inbox, or the entire request fails. No partial assignments occur.

Scopes: contact_center_user:write:admin

Granular Scopes: contact_center:write:inbox_user:admin

Rate Limit Label: MEDIUM

Request Body

Content-Type: application/json

user_ids

array — The user identifiers. The values can be a mix of email addresses, Meetings user IDs, or Contact Center user IDs.

Items:

string

Example:

{
  "user_ids": [
    "ukAAkZKfROKMSw1bj_RDFQ"
  ]
}

Responses

Status: 204 HTTP Status Code: `204` Users successfully assigned to an inbox.

Status: 400 HTTP Status Code: `400` Bad Request Error Code: `1013` User is already assigned to inbox: [user_ids]. Error Code: `3010` More than one matching inbox found.

Status: 401 HTTP Status Code: `401` Unauthorized Error Code: `124` Invalid access token. Error Code: `124` Access token has expired. Error Code: `1002` The user associated with this access token was not found or is invalid.

Status: 403 HTTP Status Code: `403` Forbidden Error Code: `1021` User account is deactivated. Error Code: `1022` User does not have a Contact Center license. Error Code: `9001` The Contact Center user associated with this bearer token is missing privileges on their role required to operate this request.

Status: 404 HTTP Status Code: `404` Not Found Error Code: `3001` Inbox does not exist: {inboxId}. Error Code: `1012` Users do not exist: [user_ids].

Status: 429 HTTP Status Code: `429` Too Many Requests. For more information, see [rate limits](/docs/api/rest/rate-limits/). Error Code: `4001` You have reached the maximum per-second rate limit for this API. Try again later.

Unassign inbox access users

Method: DELETE
Path: /contact_center/inboxes/{inboxId}/users
Tags: Inboxes

Remove users' access to an inbox.

Scopes: contact_center_user:write:admin

Granular Scopes: contact_center:delete:inbox_user:admin

Rate Limit Label: MEDIUM

Responses

Status: 204 HTTP Status Code: `204` Users' access has been removed from the inbox.

Status: 400 HTTP Status Code: `400` Bad Request Error Code: `1012` Users do not exist: [$user_id]. Error Code: `1014` User is not assigned to inbox: [$user_id]. Error Code: `3010` More than one matching inbox found.

Status: 401 HTTP Status Code: `401` Unauthorized Error Code: `124` Invalid access token. Error Code: `124` Access token has expired. Error Code: `1002` The user associated with this access token was not found or is invalid.

Status: 403 HTTP Status Code: `403` Forbidden Error Code: `1021` User account is deactivated. Error Code: `1022` User does not have a Contact Center license. Error Code: `9001` The Contact Center user associated with this bearer token is missing privileges on their role required to operate this request.

Status: 404 HTTP Status Code: `404` Not Found Error Code: `3001` Inbox does not exist: $inboxId.

Status: 429 HTTP Status Code: `429` Too Many Requests. For more information, see [rate limits](/docs/api/rate-limits/). Error Code: `4001` You have reached the maximum per-second rate limit for this API. Try again later.

List email message history

Method: GET
Path: /contact_center/email/messages
Tags: Logs

Retrieve the list of messages exchanged during a specific email engagement.

Scopes: contact_center_messaging:read:admin

Granular Scopes: contact_center:read:engagement_log:admin

Rate Limit Label: MEDIUM

Responses

Status: 200 A list of messages belonging to the specified email engagement.

Content-Type: application/json

engagement_id

string — The email engagement's unique identifier.
has_more

boolean — Whether there are more records available beyond the current response.
messages

array — List of messages exchanged during the engagement.

Items:
- from_type (required)
  
  string, possible values: "agent", "customer", "supervisor" — The message sender's participant type.
- message_type (required)
  
  string, possible values: "general", "system" — The message type. `general` indicates a standard user message, while `system` indicates a message generated by the system, such as engagement events or status updates.
- sent_time (required)
  
  string, format: date-time — The timestamp when the email was sent, in ISO 8601 format (UTC), to the millisecond.
- text (required)
  
  string — The email's plain text portion.
- user_id (required)
  
  string — The agent's unique identifier.
- user_name (required)
  
  string — The agent's name.
- bcc
  
  array — The list of blind carbon copy (BCC) recipients for this email. These recipients cannot see each other's addresses.
  
  Items:
  - address
    
    string — The BCC recipient's email address.
  - name
    
    string — The BCC recipient's display name.
- cc
  
  array — The list of carbon copy (CC) recipients for this email. These recipients can see each other's addresses.
  
  Items:
  - address
    
    string — The CC recipient's email address.
  - name
    
    string — The CC recipient's display name.
- content
  
  string — The original full content of the email, including formatting or markup.
- content_mime_type
  
  string — The MIME type of the email content, indicating its format and character encoding.
- files
  
  array — The list of files attached to this email.
  
  Items:
  - download_url
    
    string — Attachment download link.
  - file_name
    
    string — The file's name, including its extension.
  - file_size
    
    integer, format: int64 — The file size, in bytes.
  - file_type
    
    string — The file's MIME type or format.
- from_address
  
  object — The sender's information.
  - address
    
    string — The sender's email address.
  - name
    
    string — The sender's display name.
- inline_files
  
  array — The list of inline files embedded within the email content, such as images or logos displayed directly in the message body.
  
  Items:
  - download_url
    
    string — Attachment download link
  - file_name
    
    string — The file's name, including its extension.
  - file_size
    
    integer, format: int64 — The file's size, in bytes.
  - file_type
    
    string — The file's MIME type or format.
- subject
  
  string — The email's subject.
- to
  
  array — The list of recipients for this email.
  
  Items:
  - address
    
    string — The recipient's email address.
  - name
    
    string — The recipient's display name.
next_page_token

string — Use the next page token to paginate through large result sets. A next page token is returned whenever the set of available results exceeds the current page size. This token's expiration period is 15 minutes.

Example:

{
  "engagement_id": "DmJzBVygRcaMuPqYar2lxU",
  "messages": [
    {
      "content": "<html><head>\r\n<meta http-equiv=\"Content-Type\" content=\"text/html; charset=utf-8\"></head><body><div dir=\"ltr\"><img src=\"cid:ii_me9niaqb0\" alt=\"image.png\" width=\"542\" height=\"224\"><br></div></body></html>",
      "text": "email text",
      "subject": "email subject",
      "sent_time": "2024-12-03T13:07:46.123Z",
      "from_type": "agent",
      "user_id": "JzBVygmRcaMzBVygr2lxU",
      "user_name": "Agent Alice",
      "from_address": {
        "name": "Jill",
        "address": "Jill63PQ@example.com"
      },
      "to": [
        {
          "name": "Jill",
          "address": "Jill63PQ@example.com"
        }
      ],
      "cc": [
        {
          "name": "Jill",
          "address": "Jill63PQ@example.com"
        }
      ],
      "bcc": [
        {
          "name": "Jill",
          "address": "Jill63PQ@example.com"
        }
      ],
      "content_mime_type": "text/plain; charset=UTF-8",
      "message_type": "system",
      "files": [
        {
          "file_type": "application/pdf",
          "file_name": "invoice_2025.pdf",
          "file_size": 1024,
          "download_url": "https://api.example.com/attachments/0AYFv9ePSsmPUSJYHorUWQ/download?type=email_attachment"
        }
      ],
      "inline_files": [
        {
          "file_type": "image/png",
          "file_name": "logo.png",
          "file_size": 2048,
          "download_url": "https://api.example.com/attachments/0AYFv9ePSsmPUSJYHorUWQ/download?type=email_attachment"
        }
      ]
    }
  ],
  "has_more": false,
  "next_page_token": "R4aF9Oj0fVM2hhezJTEmSKaBSkfesDwGy42"
}

Status: 400 HTTP Status Code: `400` Bad Request Error Code: `11004` Engagement not found.

Status: 401 HTTP Status Code: `401` Unauthorized

Status: 403 HTTP Status Code: `403` Forbidden

Status: 404 HTTP Status Code: `404` Not Found

Status: 429 HTTP Status Code: `429` Too Many Requests. For more information, see [rate limits](https://developers.zoom.us/docs/api/rate-limits/).

List message history

Method: GET
Path: /contact_center/messaging/messages
Tags: Logs

Retrieve the list of messages exchanged during a specific messaging engagement.

Scopes: contact_center_messaging:read:admin

Granular Scopes: contact_center:read:messaging:admin

Rate Limit Label: MEDIUM

Responses

Status: 200 A list of messages belonging to the specified engagement.

Content-Type: application/json

has_more (required)

boolean — Whether there are more records available beyond the current response.
messages

array — A list of messages exchanged during the engagement.

Items:
- message_id (required)
  
  string — The message's unique identifier.
- message_type (required)
  
  string, possible values: "general", "system" — The message type. `general` indicates a standard user message, while `system` indicates a message generated by the system, such as engagement events or status updates.
- sender_participant_id (required)
  
  string — The message sender's unique identifier, corresponding to the internally generated participant_id within the Contact Center.
- sender_participant_name (required)
  
  string — The sender's display name.
- sent_time (required)
  
  string, format: date-time — The timestamp when the message was sent, in ISO 8601 format (UTC), to the millisecond.
- content
  
  object — The message's content.
  - type (required)
    
    string, possible values: "text", "html", "markdown", "quickReplies", "card", "carousel", "form", "article", "video", "attachment", "multiAttachment", "error" — The message's content type.
  - value (required)
    
    string — The actual message content.
next_page_token

string — Use the next page token to paginate through large result sets. A next page token is returned whenever the set of available results exceeds the current page size. This token's expiration period is 15 minutes.

Example:

{
  "messages": [
    {
      "message_id": "lKK_xlqXQWex0mKUYyGHUw",
      "content": {
        "type": "text",
        "value": "Hi, I'm your virtual agent!"
      },
      "sent_time": "2024-12-03T13:07:46.123Z",
      "sender_participant_id": "wMLp6VvjTc6A1mkiwHt3dQ",
      "sender_participant_name": "Agent Alice",
      "message_type": "system"
    }
  ],
  "has_more": false,
  "next_page_token": "R4aF9Oj0fVM2hhezJTEmSKaBSkfesDwGy42"
}

Status: 400 HTTP Status Code: `400` Bad Request Error Code: `11006` The integration messaging channel feature is not enabled for this account.

Status: 401 HTTP Status Code: `401` Unauthorized

Status: 403 HTTP Status Code: `403` Forbidden Error Code: `9001` The Contact Center user associated with this bearer token is missing privileges on their role required to operate this request.

Status: 404 HTTP Status Code: `404` Not Found Error Code: `11004` Engagement not found.

Status: 429 HTTP Status Code: `429` Too Many Requests. For more information, see [rate limits](/docs/api/rate-limits/). Error Code: `4001` You have reached the maximum per-second rate limit for this API. Try again later.

List SMS logs

Method: GET
Path: /contact_center/sms
Tags: Logs

Returns a list of SMS engagement logs. Engagement data are available via API once they are completed.

Scopes: contact_center_sms:read:admin

Granular Scopes: contact_center:read:sms_log:admin

Rate Limit Label: HEAVY

Responses

Status: 200 HTTP Status Code: `200` Variables list returned

Content-Type: application/json

from

string, format: date-time — The start time and date in ISO 8601 format, either `yyyy-MM-dd'T'HH:mm:ss'Z'`, or `yyyy-MM-dd'T'HH:mm:ss'TZD'`. The defined date range should be a month, as the response only includes one month's worth of data. If no start date is specified, return data from the past 24 hours.
next_page_token

string — Use the next page token to paginate through large result sets. A next page token returns when the set of available results exceeds the current page size. This token's expiration period is 15 minutes.
page_size

integer, default: 10 — The number of records returned in a single API call.
sms

array — Information about the SMS.

Items:
- agents
  
  array — Information about the engagement's agents.
  
  Items:
  - display_name
    
    string — The agent's name.
  - user_id
    
    string — The agent's ID.
- consumer_display_name
  
  string — The consumer's name.
- consumer_number
  
  string — The consumer's phone number.
- contact_center_number
  
  string — The agent's number. An agent used a flow or queue number and did not really have its own number.
- country_name
  
  string — The country name.
- direction
  
  string, possible values: "inbound", "outbound" — The engagement's direction. `inbound` | `outbound`.
- end_time
  
  string, format: date-time — The date and time when the engagement ended in ISO 8601 format, either `yyyy-MM-dd'T'HH:mm:ss'Z'` or `yyyy-MM-dd'T'HH:mm:ss'TZD'`.
- engagement_id
  
  string — The engagement's ID
- queues
  
  array — Information about the engagement's queues.
  
  Items:
  - cc_queue_id
    
    string — The Contact Center queue's ID.
  - queue_id
    
    string — The queue's ID.
  - queue_name
    
    string — The queue's name.
- sms_types
  
  array — The SMS's type.
  
  Items:
  
  string, possible values: "sms", "mms"
- start_time
  
  string, format: date-time — The date and time when the engagement started in ISO 8601 format, either `yyyy-MM-dd'T'HH:mm:ss'Z'` or `yyyy-MM-dd'T'HH:mm:ss'TZD'`.
- total_received_files
  
  integer, format: int64 — The total number of received files.
- total_received_messages
  
  integer, format: int64 — The total number of received messages.
- total_sent_files
  
  integer, format: int64 — The total number of sent files.
- total_sent_messages
  
  integer, format: int64 — The total number of sent messages.
to

string, format: date-time — **Required** only when the `from` parameter is specified. The end time and date in ISO 8601 format, either `yyyy-MM-dd'T'HH:mm:ss'Z'` or `yyyy-MM-dd'T'HH:mm:ss'TZD'`, the same format as the `from` parameter.
total_records

integer — The total number of all the records available across pages.

Example:

{
  "next_page_token": "R4aF9Oj0fVM2hhezJTEmSKaBSkfesDwGy42",
  "page_size": 30,
  "total_records": 1,
  "from": "2023-01-01T08:00:00Z",
  "to": "2023-01-01T09:00:00Z",
  "sms": [
    {
      "direction": "inbound",
      "engagement_id": "3XilEfOvQEKRIWMWhX1jDg",
      "contact_center_number": "+18108001001",
      "start_time": "2023-01-01T08:00:00Z",
      "end_time": "2023-01-01T09:00:00Z",
      "consumer_number": "+12059300920",
      "consumer_display_name": "Tester",
      "queues": [
        {
          "cc_queue_id": "d95avl1eRJ-H162PZUJ-qg",
          "queue_name": "agentQueue"
        }
      ],
      "agents": [
        {
          "user_id": "ukAAkZKfROKMSw1bj_RDFQ",
          "display_name": "Jilly"
        }
      ],
      "country_name": "China",
      "sms_types": [
        "sms"
      ],
      "total_sent_messages": 0,
      "total_received_messages": 0,
      "total_sent_files": 0,
      "total_received_files": 0
    }
  ]
}

Status: 400 HTTP Status Code: `400` Bad Request

Status: 404 HTTP Status Code: `404` Not Found Error Code: `2901` Engagement does not exist: $engagementId. Error Code: `1001` User does not exist: $userId.

Status: 429 HTTP Status Code: `429` Too Many Requests. For more information, see [rate limits](/docs/api/rest/rate-limits/).

Send an SMS

Method: POST
Path: /contact_center/sms
Tags: SMS

Send an SMS message.

Scopes: contact_center_sms:write:admin

Granular Scopes: contact_center:write:sms:admin

Rate Limit Label: LIGHT

Request Body

Content-Type: application/json

body (required)

string — The content that needs to be sent as an SMS. Maximum length is 500 characters. Messages will be broken into smaller segments of 160 characters and concatenated at the time of delivery. Unicode characters and emojis are supported. You can send any text or URL. MMS is not supported. There is no support for handling inbound messages and delivery confirmations.
consumer_numbers (required)

array — The phone number of the person receiving the SMS. Consumer numbers should be in the E.164 format. Opt in - START - and opt out - STOP - keywords received from this number will be honored. This field may not be empty. Maximum length of the array is 20 items.

Items:

string — The consumer's e164 number.
contact_center_number (required)

string — This must be an SMS capable phone number allocated to Zoom Contact Center within the customer account. Enter the number in E.164 format. Get the number via Zoom PAYG Global Number SKU after meeting the in-country compliance requirements.

Example:

{
  "contact_center_number": "+12090000000",
  "consumer_numbers": [
    "+12090001111"
  ],
  "body": "hello contact sms"
}

Responses

Status: 201 Send SMS response.

Content-Type: application/json

Array of:

consumer_number (required)

string — The consumer's phone number, in e164 format.
contact_center_number (required)

string — E164 flow number.
success (required)

boolean — Indicates whether the SMS was sent successfully.
description

string, possible values: "Invalid consumer number. The format of the consumer number used is incorrect. E.164 format is required", "Zoom Contact Center numbers cannot be used as consumer numbers. Retry using a non Zoom Contact Center number", "The consumer number you have messaged has not opted in", "This consumer number has opted out of receiving SMS from this Zoom contact center number", "This consumer number is a part of the block list defined by your Zoom Contact Center account administrator and cannot be messaged", "International messaging is not supported on this account" — The error message returned when the SMS was not successfully sent.
message_id

string — The message ID. Indicates the action of sending a message from this `contact_center_number` to this consumer number.

Example:

[
  {
    "contact_center_number": "+12090000000",
    "consumer_number": "+12090001111",
    "message_id": "IQ-dhfaoufosadfb",
    "success": true,
    "description": "The consumer number you have messaged has not opted in"
  }
]

Status: 400 HTTP Status Code: `400` Bad Request Error Code: `1405` `contact_center_number` has not enabled SMS feature. Error Code: `1408` `consumer_number` cannot be more than 20 digits. Error Code: `1404` `contact_center_number` not found. Error Code: `1412` `body` can't be empty. Error Code: `1413` SMS `body` is too long.

Status: 429 HTTP Status Code: `429` Too Many Requests. For more information, see [rate limits](/docs/api/rate-limits/).

List voice call logs

Method: GET
Path: /contact_center/voice_calls
Tags: Logs

Return a list of voice call engagement logs. Engagement data is available via API once it is completed. Note These fields - agents.user_ip_address, agents.user_device_mac_address, agents.user_registered_sip_zone, agents.sip_zone_ip_address, sbcInfos.session_border_controller_name, sbcInfos.session_border_controller_ip_address, sbcInfos.consumer_zoom_trunk_name and sbcInfos.consumer_sbc_ip_address - are only available to accounts which have enabled an internal flag to return these additional fields. To enable the feature flag, contact Zoom Support.

Scopes: contact_center_voice_call:read:admin

Granular Scopes: contact_center:read:voice_call_log:admin

Rate Limit Label: HEAVY

Responses

Status: 200 HTTP Status Code: `200` Variables list returned.

Content-Type: application/json

from

string, format: date-time — The start time and date in ISO 8601 format, either `yyyy-MM-dd'T'HH:mm:ss'Z'` or `yyyy-MM-dd'T'HH:mm:ss'TZD'`. The defined date range should be a month, as the response only includes one month's worth of data. If no start date is specified, return data from the past 24 hours.
next_page_token

string — Use the next page token to paginate through large result sets. A next page token is returned whenever the set of available results exceeds the current page size. This token's expiration period is 15 minutes.
page_size

integer, default: 10 — The number of records returned within a single API call.
to

string, format: date-time — **Required** only when the `from` parameter is specified. The end time and date in ISO 8601 format, either `yyyy-MM-dd'T'HH:mm:ss'Z'` or `yyyy-MM-dd'T'HH:mm:ss'TZD'`, the same format as the `from` parameter.
total_records

integer — The total number of all the records available across pages.
voice_calls

array — Information about the voice call.

Items:
- agents
  
  array — Information about the engagement's agents.
  
  Items:
  - display_name
    
    string — The agent's name.
  - sip_zone_ip_address
    
    string, format: ipv4 — The SIP zome's IP address.
  - team_ids
    
    array — The agent's team IDs
    
    Items:
    
    string — agent team ID list
  - team_names
    
    array — The agent's team names.
    
    Items:
    
    string — agent team name list.
  - user_device_mac_address
    
    string — MAC address of the agent's device.
  - user_email
    
    string — The agent's email.
  - user_id
    
    string — The agent's ID.
  - user_ip_address
    
    string, format: ipv4 — IP address of the agent's device.
  - user_region
    
    string — The agent's region name
  - user_registered_sip_zone
    
    string — The SIP zone where the agent registered.
- call_legs
  
  array — The direction of the engagement call leg. `inbound` | `outbound`.
  
  Items:
  
  string, possible values: "inbound", "outbound"
- callee_number
  
  string — The callee's phone number.
- callee_number_type
  
  string, possible values: "toll_free_number", "virtual_service_number", "byoc_number" — The callee's number type.
- caller_id
  
  string — The caller's number.
- caller_number
  
  string — The caller's phone number.
- caller_number_type
  
  string, possible values: "toll_free_number", "virtual_service_number", "byoc_number" — The caller's number type.
- calling_party
  
  string, possible values: "consumer", "agent" — The calling's party.
- charge
  
  string — The bill's charge.
- charge_type
  
  string, possible values: "per_minute" — The charge type.
- consumer_display_name
  
  string — The consumer's name.
- consumer_number
  
  string — The consumer's phone number.
- country_name
  
  string — The country name.
- direction
  
  string, possible values: "inbound", "outbound" — The engagement's direction.
- distributions
  
  array — The engagement's distribution.
  
  Items:
  
  string, possible values: "acd", "non_acd"
- end_time
  
  string — The date and time when the engagement ended, in `yyyy-MM-dd'T'HH:mm:ss±HH:mm` format. The timezone offset is derived from the `from` input parameter if it includes a timezone offset (e.g., `-08:00`), otherwise it defaults to `+00:00` (UTC).
- engagement_id
  
  string — The engagement's ID
- flows
  
  array — Information about the engagement's flows.
  
  Items:
  - flow_id
    
    string — The flow's ID.
  - flow_name
    
    string — The flow's name.
- inbox
  
  boolean — Flag to determine whether a message is in the box.
- monitored
  
  boolean — Flag to determine whether to monitored.
- queues
  
  array — Information about the engagement's queues.
  
  Items:
  - cc_queue_id
    
    string — The Contact Center queue's ID.
  - queue_id
    
    string — The queue's ID.
  - queue_name
    
    string — The queue's name.
- rates
  
  array — The price for each sent message.
  
  Items:
  
  string
- recorded
  
  boolean — Flag to determine whether to recorded.
- result
  
  string, possible values: "completed", "short_abandoned", "long_abandoned", "hold_abandoned", "long_calls", "short_calls", "hang_up_calls", "overflowed_to_disconnect", "overflowed_to_inbox", "overflowed", "abandon_quit", "auto_closed", "contained", "missed", "declined", "callback_abandoned_by_consumer" — The engagement's results.
- session_border_controller_list
  
  array — Information about the session border controllers (SBCs) involved in the call.
  
  Items:
  - consumer_sbc_ip_address
    
    string — The customer's SBC IP address.
  - consumer_zoom_trunk_name
    
    string — The name of the trunk between the customer SBC and Zoom SBC.
  - session_border_controller_ip_address
    
    string — The SBC's IP address.
  - session_border_controller_name
    
    string — The session border controller's name.
- start_time
  
  string — The date and time when the engagement started in `yyyy-MM-dd'T'HH:mm:ss±HH:mm` format. The timezone offset matches the offset provided in the `from` input parameter, or defaults to UTC (+00:00) if no offset was provided.
- sub_types
  
  array — Specifies the detailed call leg type, such as a transfer or conference call.
  
  Items:
  
  string, possible values: "external_warm_conference_call", "external_direct_conference_call", "external_warm_transfer_call", "external_direct_transfer_call", "internal_warm_conference_call", "internal_direct_conference_call", "internal_warm_transfer_call", "internal_direct_transfer_call", "flow_initiated_outgoing_call"
- total_duration
  
  integer, format: int64 — The engagement's total duration, in seconds.
- types
  
  array — The call's type.
  
  Items:
  
  string, possible values: "external_call", "external_conference_call", "external_callback_call", "internal_call", "internal_conference_call", "internal_callback_call"
- voice_call_details
  
  array — All related call logs.
  
  Items:
  - agents
    
    array — Information about the engagement's agents.
    
    Items:
    - display_name
      
      string — The agent's name.
    - sip_zone_ip_address
      
      string, format: ipv4 — The SIP zone's IP address.
    - team_ids
      
      array — The agent's team IDs
      
      Items:
      
      string — Agent team ID list.
    - team_names
      
      array — The agent's team names.
      
      Items:
      
      string — Agent team name list.
    - user_device_mac_address
      
      string — The agent's device's MAC address.
    - user_email
      
      string — The agent's email.
    - user_id
      
      string — The agent's ID.
    - user_ip_address
      
      string, format: ipv4 — The agent's device's IP address.
    - user_region
      
      string — The agent's region name.
    - user_registered_sip_zone
      
      string — The SIP zone where the agent registered.
  - call_leg
    
    string, possible values: "inbound", "outbound" — The direction of the engagement call log.
  - callee_number
    
    string — The callee's phone number.
  - callee_number_type
    
    string, possible values: "toll_free_number", "virtual_service_number", "byoc_number" — The callee's number type.
  - caller_id
    
    string — The caller's number.
  - caller_number
    
    string — The caller's phone number.
  - caller_number_type
    
    string, possible values: "toll_free_number", "virtual_service_number", "byoc_number" — The caller's number type.
  - calling_party
    
    string, possible values: "consumer", "agent" — The calling's party.
  - charge
    
    string — The bill's charge.
  - charge_type
    
    string, possible values: "per_minute" — The charge type.
  - consumer_display_name
    
    string — The consumer's name.
  - consumer_number
    
    string — The consumer's phone number.
  - country_name
    
    string — The country name.
  - distribution
    
    string, possible values: "acd", "non_acd" — The call log's distribution.
  - end_time
    
    string — The date and time when the call ended, in ISO 8601 format, either `yyyy-MM-dd'T'HH:mm:ss'Z'` or `yyyy-MM-dd'T'HH:mm:ss'TZD'`.
  - engagement_id
    
    string — The engagement's ID.
  - flow
    
    object — Information about the flow.
    - flow_id
      
      string — The flow's ID.
    - flow_name
      
      string — The flow's name.
  - inbox
    
    boolean — Whether a message is in the box.
  - monitored
    
    boolean — Whether to monitor.
  - queue
    
    object — Information about the queue.
    - cc_queue_id
      
      string — The Contact Center queue's ID.
    - queue_name
      
      string — The queue's name.
  - rate
    
    string — The price for sent message.
  - recorded
    
    boolean — Whether to record.
  - result
    
    string, possible values: "completed", "short_abandoned", "long_abandoned", "hold_abandoned", "long_calls", "short_calls", "hang_up_calls", "overflowed_to_disconnect", "overflowed_to_inbox", "overflowed", "abandon_quit", "auto_closed", "contained", "missed", "declined", "callback_abandoned_by_consumer" — The engagement's results.
  - start_time
    
    string — The date and time when the call started, in ISO 8601 format, either `yyyy-MM-dd'T'HH:mm:ss'Z'` or `yyyy-MM-dd'T'HH:mm:ss'TZD'`.
  - total_duration
    
    integer, format: int64 — The call log's total duration, in seconds.
  - type
    
    string, possible values: "external_call", "external_conference_call", "external_callback_call", "internal_call", "internal_conference_call", "internal_callback_call" — The call's type.

Example:

{
  "next_page_token": "R4aF9Oj0fVM2hhezJTEmSKaBSkfesDwGy42",
  "page_size": 10,
  "total_records": 10,
  "from": "2023-01-01T08:00:00Z",
  "to": "2023-01-01T09:00:00Z",
  "voice_calls": [
    {
      "engagement_id": "3XilEfOvQEKRIWMWhX1jDg",
      "direction": "inbound",
      "call_legs": [
        "inbound"
      ],
      "distributions": [
        "acd"
      ],
      "types": [
        "external_call"
      ],
      "sub_types": [
        "external_direct_transfer_call"
      ],
      "caller_number": "+18108001001",
      "caller_number_type": "toll_free_number",
      "callee_number": "+12055437350",
      "callee_number_type": "toll_free_number",
      "start_time": "2023-01-01T00:00:00-08:00",
      "end_time": "2023-01-01T01:00:00-08:00",
      "total_duration": 10,
      "consumer_number": "+12059300920",
      "consumer_display_name": "Tester",
      "queues": [
        {
          "cc_queue_id": "d95avl1eRJ-H162PZUJ-qg",
          "queue_name": "agentQueue"
        }
      ],
      "agents": [
        {
          "user_id": "ukAAkZKfROKMSw1bj_RDFQ",
          "display_name": "Jilly",
          "user_email": "jakie@zoom.us",
          "user_ip_address": "38.145.73.4",
          "user_device_mac_address": "05:FA:15:25:EE:FF",
          "user_registered_sip_zone": "ams1sbc",
          "sip_zone_ip_address": "38.145.73.4",
          "user_region": "Main Region",
          "team_ids": [
            "[\"3XilEfOvQEKRIWMWhX1jDg\"]"
          ],
          "team_names": [
            "[\"My team\"]"
          ]
        }
      ],
      "flows": [
        {
          "flow_id": "zeYjXoDOS_eV1QmTpj63PQ",
          "flow_name": "Demo"
        }
      ],
      "country_name": "China",
      "recorded": false,
      "monitored": false,
      "inbox": false,
      "result": "completed",
      "caller_id": "+12058945728",
      "calling_party": "consumer",
      "charge": "$0.019",
      "rates": [
        "$0.019"
      ],
      "charge_type": "per_minute",
      "session_border_controller_list": [
        {
          "session_border_controller_name": "ams1sbc",
          "session_border_controller_ip_address": "38.145.73.20",
          "consumer_zoom_trunk_name": "C10010142296A06",
          "consumer_sbc_ip_address": "39.15.60.145"
        }
      ],
      "voice_call_details": [
        {
          "engagement_id": "3XilEfOvQEKRIWMWhX1jDg",
          "call_leg": "inbound",
          "distribution": "acd",
          "type": "external_call",
          "caller_number": "+18108001001",
          "caller_number_type": "toll_free_number",
          "callee_number": "+12055437350",
          "callee_number_type": "toll_free_number",
          "start_time": "2023-01-01T00:00:00-08:00",
          "end_time": "2023-01-01T01:00:00-08:00",
          "total_duration": 10,
          "consumer_number": "+12059300920",
          "consumer_display_name": "Tester",
          "queue": {
            "cc_queue_id": "d95avl1eRJ-H162PZUJ-qg",
            "queue_name": "agentQueue"
          },
          "agents": [
            {
              "user_id": "ukAAkZKfROKMSw1bj_RDFQ",
              "display_name": "Jilly",
              "user_email": "jakie@zoom.us",
              "user_ip_address": "38.145.73.4",
              "user_device_mac_address": "05:FA:15:25:EE:FF",
              "user_registered_sip_zone": "ams1sbc",
              "sip_zone_ip_address": "38.145.73.4",
              "user_region": "Main Region",
              "team_ids": [
                "3XilEfOvQEKRIWMWhX1jDg"
              ],
              "team_names": [
                "My team"
              ]
            }
          ],
          "flow": {
            "flow_id": "zeYjXoDOS_eV1QmTpj63PQ",
            "flow_name": "Demo"
          },
          "country_name": "China",
          "recorded": false,
          "monitored": false,
          "inbox": false,
          "result": "completed",
          "caller_id": "+12058945728",
          "calling_party": "consumer",
          "charge": "$0.019",
          "rate": "$0.019",
          "charge_type": "per_minute"
        }
      ]
    }
  ]
}

Status: 400 HTTP Status Code: `400` Bad Request Error Code: `300` The time and date must be in `yyyy-mm-dd`` or ISO 8601 format, either `yyyy-MM-dd'T'HH:mm:ss'Z'` or `yyyy-MM-dd'T'HH:mm:ss'TZD'`. Error Code: `300` The requested report exceeds the 1-month limit. Error Code: `300` Invalid field.

Status: 401 HTTP Status Code: `401` Unauthorized

Status: 403 HTTP Status Code: `403` Forbidden

Status: 404 HTTP Status Code: `404` Not Found Error Code: `1001` User does not exist: {userId}. Error Code: `1201` Queue does not exist: {queueId}.

Status: 429 HTTP Status Code: `429` Too Many Requests. For more information, see [rate limits](/docs/api/rate-limits/).

List work item message history

Method: GET
Path: /contact_center/work_item/messages
Tags: Logs

Retrieve the list of messages exchanged during a specific work item engagement.

Note This endpoint retrieves messages from work item sessions associated with the engagement.

Scopes: contact_center_messaging:read:admin

Granular Scopes: contact_center:read:engagement_log:admin

Rate Limit Label: MEDIUM

Responses

Status: 200 A list of messages belonging to the specified work item engagement.

Content-Type: application/json

has_more (required)

boolean — Whether there are more records available beyond the current response.
engagement_id

string — The work item engagement's unique identifier.
messages

array — List of messages exchanged during the work item engagement.

Items:
- message_id (required)
  
  string — The message's unique identifier.
- message_type (required)
  
  string, possible values: "general", "system" — The message type. * `general` - a standard user message * `system` - a message generated by the system, such as engagement events or status updates
- sender_participant_id (required)
  
  string — The message sender's unique identifier, corresponding to the internally generated `participant_id` within the Contact Center.
- sender_participant_name (required)
  
  string — The sender's display name.
- sent_time (required)
  
  string, format: date-time — The timestamp when the message was sent, in ISO 8601 format (UTC), to the millisecond.
- content
  
  object — **Deprecated**. Use `message_details`.
  - type (required)
    
    string, possible values: "text", "html", "action", "markdown", "quickReplies", "card", "carousel", "article", "image", "audio", "video", "link", "attachment" — **Deprecated**. Use `message_details.content_type`.
  - value (required)
    
    string — **Deprecated**. Use `message_details.content`.
- message_channel
  
  string, possible values: "email", "sms" — The message's channel, such as `email` or `sms`. This field is only set for flow send email or SMS messages. Otherwise it is empty.
- message_details
  
  object — Message payload details. For email, content is the original email body and text is the plain-text body. For other channels, content is the original message payload.
  - content
    
    string — The original message payload. For email, this is the full email body, typically HTML. For other channels, this is the original message content. The maximum content size is `400KB`, and UTF-8 encoded.
  - content_type
    
    string, possible values: "text", "html", "action", "markdown", "quickReplies", "card", "carousel", "article", "image", "audio", "video", "link", "attachment" — The type of `message_details.content`. For email, this is typically `html`, or `text` when there is no HTML body. For other channels, it indicates the original message payload type.
  - files
    
    array — The list of attachments. This field is truncated to a maximum of 20 items. Additional files will not be returned.
    
    Items:
    - download_url
      
      string — Attachment download link.
    - file_name
      
      string — The file's name, including its extension.
    - file_size
      
      integer, format: int64 — The file size, in bytes.
    - file_type
      
      string — The file's MIME type or format.
  - from_address
    
    object — Email-only. The email sender information.
    - address
      
      string — The email sender's email address.
    - name
      
      string — The email sender's display name.
  - inline_files
    
    array — Email-only. Inline files embedded in the email body, such as images or logos. This field is truncated to a maximum of 20 items. Additional inline files will not be returned.
    
    Items:
    - download_url
      
      string — Attachment download link
    - file_name
      
      string — The file's name, including its extension.
    - file_size
      
      integer, format: int64 — The file's size, in bytes.
    - file_type
      
      string — The file's MIME type or format.
  - subject
    
    string — Email-only. The subject of the email message.
  - text
    
    string — Email-only. The plain-text body extracted from the email content.
  - to_addresses
    
    array — Email-only. The list of email recipients. Maximum of 20 items will be returned. If there are more than 20 email addresses, only the first 20 will be included in the response.
    
    Items:
    - address
      
      string — The recipient's email address.
    - name
      
      string — The recipient's display name.
next_page_token

string — Use the next page token to paginate through large result sets. A next page token is returned whenever the set of available results exceeds the current page size. This token's expiration period is 15 minutes.

Example:

{
  "engagement_id": "DmJzBVygRcaMuPqYar2lxU",
  "messages": [
    {
      "message_id": "lKK_xlqXQWex0mKUYyGHUw",
      "message_details": {
        "content_type": "text",
        "content": "<html><head><meta charset=\"UTF-8\"></head><body><p>Refund request for order 774512.</p><p>Customer reports duplicate charge and asks for reversal.</p></body></html>",
        "text": "Refund request for order 774512. Customer reports duplicate charge and asks for reversal.",
        "subject": "Refund request for order",
        "from_address": {
          "name": "Jane Doe",
          "address": "jdoe@example.com"
        },
        "to_addresses": [
          {
            "name": "Jane Doe",
            "address": "jdoe@example.com"
          }
        ],
        "files": [
          {
            "file_type": "application/pdf",
            "file_name": "invoice_2025.pdf",
            "file_size": 1024,
            "download_url": "https://www.example.com/v2/contact_center/attachments/0AYFv9ePSsmPUSJYHorUWQ/download?type=email_attachment"
          }
        ],
        "inline_files": [
          {
            "file_type": "image/png",
            "file_name": "logo.png",
            "file_size": 2048,
            "download_url": "https://www.example.com/v2/contact_center/attachments/0AYFv9ePSsmPUSJYHorUWQ/download?type=email_attachment"
          }
        ]
      },
      "sent_time": "2025-12-03T13:07:46.123Z",
      "sender_participant_id": "wMLp6VvjTc6A1mkiwHt3dQ",
      "sender_participant_name": "Agent Alice",
      "message_type": "system",
      "message_channel": "email"
    }
  ],
  "has_more": false,
  "next_page_token": "R4aF9Oj0fVM2hhezJTEmSKaBSkfesDwGy42"
}

Status: 400 HTTP Status Code: `400` Bad Request Error Code: `300` Validation failed.

Status: 401 HTTP Status Code: `401` Unauthorized Error Code: `124` Invalid access token. Error Code: `124` Access token has expired. Error Code: `1002` The user associated with this access token was not found or is invalid.

Status: 403 HTTP Status Code: `403` Forbidden Error Code: `1021` User account is deactivated. Error Code: `1022` User does not have a Contact Center license. Error Code: `9001` The Contact Center user associated with this bearer token is missing privileges on their role required to operate this request.

Status: 404 HTTP Status Code: `404` Not Found Error Code: `11004` Engagement not found.

Status: 429 HTTP Status Code: `429` Too Many Requests. For more information, see [rate limits](https://developers.zoom.us/docs/api/rate-limits/). Error Code: `4001` You have reached the maximum per-second rate limit for this API. Try again later.

Send a message

Method: POST
Path: /contact_center/messages
Tags: Messaging

Send a message via the specified messaging channel.

Note A 200 OK response indicates that the request was successfully received and accepted by the API. It doesn't guarantee that the message has been sent or delivered.

Message delivery is processed asynchronously. To track the actual send and delivery status, use the contact_center.message_status webhook, which provides updates as the message progresses through the system.

Scopes: contact_center_messaging:write:admin

Granular Scopes: contact_center:write:messaging:admin

Rate Limit Label: LIGHT

Request Body

Content-Type: application/json

from (required)

string — The sender's identifier. Different channels use platform-specific formats. For number-based channels, like WhatsApp, the value must be in E.164 format. For the number-based SMS channel, we support either an E.164 formatted phone number or an alphanumeric ID.
to (required)

string — The recipient's identifier. Different channels use platform-specific formats. For number-based channels, like WhatsApp and SMS, the value must be in E.164 format.
create_engagement

boolean — Whether to create an engagement.
flow_id

string — The flow ID to trigger when the consumer replies. Only used if `create_engagement=true` and a new engagement is created.
sms_message

object — SMS-specific message content.
- type (required)
  
  string, possible values: "text" — The SMS message content type.
- value (required)
  
  string — The SMS message payload.
whatsapp_message

object — WhatsApp-specific message content, with type-specific structure.
- type (required)
  
  string, possible values: "whatsAppTemplate" — The message content type.
- value (required)
  
  string — The message payload.

Example:

{
  "from": "+12090000000",
  "to": "+12090001111",
  "whatsapp_message": {
    "type": "whatsAppTemplate",
    "value": "{\"name\":\"marketing_button\",\"language_code\":\"en\"}"
  },
  "sms_message": {
    "type": "text",
    "value": "Hello, this is a test SMS message."
  },
  "create_engagement": true,
  "flow_id": "zwKiV80hQ7CwRg9BEm0Bvw"
}

Responses

Status: 200 Message response sent.

Content-Type: application/json

from (required)

string — The sender's identifier. Different channels use platform-specific formats. For number-based channels, such as WhatsApp, the value must be in E.164 format.
message_id (required)

string — The unique identifier of the sent message, automatically generated by the Contact Center.
to (required)

string — The recipient's identifier. Different channels use platform-specific formats. For number-based channels, such as WhatsApp, the value must be in E.164 format.
engagement_id

string — The engagement's unique identifier, representing either a newly created engagement or an existing open engagement.
new_engagement

boolean — Returned when `create_engagement=true`. `true` indicates a new engagement was created, and `false` indicates an existing open engagement was reused.
opt_in_required

boolean — For SMS, `true` indicates the consumer has not opted in and an opt-in invitation was sent.

Example:

{
  "from": "+12090000000",
  "to": "+12090001111",
  "message_id": "f21b5055-5ec2-4e3f-8dde-916d4f76a2ee",
  "engagement_id": "u-ewaaDUS9qWlTNt8qhmmA",
  "new_engagement": true,
  "opt_in_required": true
}

Status: 400 HTTP Status Code: `400` Bad Request Error Code: `1019` feature OP flag is not enabled. Error Code: `1500` Input contains an invalid phone number. Please provide valid phone numbers in E.164 format.

Status: 401 HTTP Status Code: `401` Unauthorized Error Code: `124` Invalid access token. Error Code: `124` Access token has expired. Error Code: `1002` The user associated with this access token was not found or is invalid.

Status: 403 HTTP Status Code: `403` Forbidden Error Code: `1021` User account is deactivated. Error Code: `1022` User does not have a Contact Center license. Error Code: `9001` The Contact Center user associated with this bearer token is missing privileges on their role required to operate this request.

Status: 429 HTTP Status Code: `429` Too Many Requests. For more information, see [rate limits](https://developers.zoom.us/docs/api/rate-limits/). Error Code: `4001` You have reached the maximum per-second rate limit for this API. Try again later.

List notes

Method: GET
Path: /contact_center/engagements/notes
Tags: Notes

Return a list of notes.

Scopes: contact_center_note:read:admin

Granular Scopes: contact_center:read:list_notes:admin

Rate Limit Label: MEDIUM

Responses

Status: 200 HTTP Status Code: `200` Note list returned

Content-Type: application/json

next_page_token

string — Use the next page token to paginate through large result sets. A next page token returns when the set of available results exceeds the current page size. This token's expiration period is 15 minutes.
notes

array — Information about the notes.

Items:
- channel
  
  string, possible values: "voice", "sms", "chat", "video", "email" — The channel's type. * voice * sms * chat * video * email
- channel_source
  
  string — The channel source.
- channel_type
  
  string, possible values: "voice", "sms", "chat", "video" — The channel's type: * voice * sms * chat * video
- engagement_id
  
  string — The engagement event's unique ID.
- last_modified_time
  
  string, format: date-time — The note's last modification time.
- note
  
  string — The note's content.
- note_id
  
  string — The note's unique ID.
- user_id
  
  string — The ID of last user to modify the note.
page_size

integer, default: 30 — The number of records returned in a single API call.
total_records

integer — The total number of all the records available across pages.

Example:

{
  "next_page_token": "R4aF9Oj0fVM2hhezJTEmSKaBSkfesDwGy42",
  "page_size": 30,
  "total_records": 1,
  "notes": [
    {
      "note_id": "W_VATTk_Q5aW6z5rZtBxAQ",
      "engagement_id": "3XilEfOvQEKRIWMWhX1jDg",
      "channel": "email",
      "channel_source": "email_address",
      "note": "This is the content of the note.",
      "last_modified_time": "2022-05-23T14:15:57Z",
      "user_id": "IGTRVt3gQ2i-WjoUIjeZxw"
    }
  ]
}

Status: 400 HTTP Status Code: `400` Bad Request

Status: 429 HTTP Status Code: `429` Too Many Requests. For more information, see [rate limits](https://developers.zoom.us/docs/api/rest/rate-limits/).

List engagement notes

Method: GET
Path: /contact_center/engagements/{engagementId}/notes
Tags: Notes

Return a list of notes under an engagement.

Scopes: contact_center_note:read:admin

Granular Scopes: contact_center:read:list_notes:admin

Rate Limit Label: MEDIUM

Responses

Status: 200 HTTP Status Code: `200` Engagement note list returned

Content-Type: application/json

next_page_token

string — Use the next page token to paginate through large result sets. A next page token returns when the set of available results exceeds the current page size. This token's expiration period is 15 minutes.
notes

array — Information about the notes.

Items:
- channel
  
  string, possible values: "voice", "sms", "chat", "video", "email" — The channel's type. * voice * sms * chat * video* email
- channel_source
  
  string — The channel source.
- channel_type
  
  string, possible values: "voice", "sms", "chat", "video" — The channel's type. * voice * sms * chat * video
- engagement_id
  
  string — The engagement event's unique ID.
- last_modified_time
  
  string, format: date-time — The note's last modification time.
- note
  
  string — The note's content.
- note_id
  
  string — The note's unique ID.
- user_id
  
  string — The ID of last user to modify the note.
page_size

integer, default: 30 — The number of records returned in a single API call.
total_records

integer — The total number of all the records available across pages.

Example:

{
  "next_page_token": "R4aF9Oj0fVM2hhezJTEmSKaBSkfesDwGy42",
  "page_size": 30,
  "total_records": 1,
  "notes": [
    {
      "note_id": "W_VATTk_Q5aW6z5rZtBxAQ",
      "engagement_id": "3XilEfOvQEKRIWMWhX1jDg",
      "channel": "email",
      "channel_source": "email_address",
      "note": "This is the content of the note.",
      "last_modified_time": "2022-05-23T14:15:57Z",
      "user_id": "IGTRVt3gQ2i-WjoUIjeZxw"
    }
  ]
}

Status: 400 HTTP Status Code: `400` Bad Request

Status: 429 HTTP Status Code: `429` Too Many Requests. For more information, see [rate limits](https://developers.zoom.us/docs/api/rest/rate-limits/).

Get a note

Method: GET
Path: /contact_center/engagements/{engagementId}/notes/{noteId}
Tags: Notes

Retrieve a note.

Scopes: contact_center_note:read:admin

Granular Scopes: contact_center:read:note:admin

Rate Limit Label: LIGHT

Responses

Status: 200 HTTP Status Code: `200` Note returned

Content-Type: application/json

channel

string, possible values: "voice", "sms", "chat", "video", "email" — The channel's type. * voice * sms * chat * video * email
channel_source

string, possible values: "email_address" — channel source
channel_type

string, possible values: "voice", "sms", "chat", "video", "email" — The channel's type. * voice * sms * chat * video
engagement_id

string — The engagement event's unique ID.
last_modified_time

string, format: date-time — The note's last modification time.
note

string — The note's content.
note_id

string — The note's unique ID.
user_id

string — The ID of last user to modify the note.

Example:

{
  "note_id": "W_VATTk_Q5aW6z5rZtBxAQ",
  "engagement_id": "3XilEfOvQEKRIWMWhX1jDg",
  "channel": "email",
  "channel_source": "email_address",
  "note": "This is the content of the note.",
  "last_modified_time": "2022-05-23T14:15:57Z",
  "user_id": "IGTRVt3gQ2i-WjoUIjeZxw"
}

Status: 400 HTTP Status Code: `400` Bad Request Error Code: `2704` The engagementId that matches this noteId is: $engagementId

Status: 404 HTTP Status Code: `404` Not Found Error Code: `2701` Note does not exist: $noteId

Status: 429 HTTP Status Code: `429` Too Many Requests. For more information, see [rate limits](https://developers.zoom.us/docs/api/rest/rate-limits/).

Update a note

Method: PATCH
Path: /contact_center/engagements/{engagementId}/notes/{noteId}
Tags: Notes

Update a note.

Scopes: contact_center_note:write

Granular Scopes: contact_center:update:note

Rate Limit Label: LIGHT

Request Body

Content-Type: application/json

note

string — The note's content.

Example:

{
  "note": "This is the content of the note."
}

Responses

Status: 204 HTTP Status Code: `204` Note updated

Status: 400 HTTP Status Code: `400` Bad Request Error Code: `2702` Note can not be updated. You can only update the note that belongs to you. Error Code: `2704` The `engagementId` that matches this noteId is: $engagementId.

Status: 404 HTTP Status Code: `404` Not Found Error Code: `2701` Note does not exist: $noteId

Status: 429 HTTP Status Code: `429` Too Many Requests. For more information, see [rate limits](https://developers.zoom.us/docs/api/rest/rate-limits/).

List business hours

Method: GET
Path: /contact_center/business_hours
Tags: Operating Hours

Get a list of business hours. Admins can create business hours to select, such as the business hours "Default Hours".

Scopes: contact_center_operating_hours:read:admin,contact_center_queue:read:admin

Granular Scopes: contact_center:read:list_business_hours:admin

Rate Limit Label: MEDIUM

Responses

Status: 200 HTTP Status Code: `200` Business hours returned.

Content-Type: application/json

business_hours

array — Information about the business hours.

Items:
- account_default
  
  boolean — Default business hours for the newly created queue.
- business_hour_id
  
  string — The business hours' ID.
- business_hour_name
  
  string — The business hours' name.
- flows_count
  
  integer — The number of flows using the business hour.
- hours
  
  object — The business hours.
  - custom_hours
    
    array — The custom hours settings. It returns only for the `Custom hours` type.
    
    Items:
    - custom_hour_ranges
      
      array — The custom hours range. It returns only for the `Customized hours` type.
      
      Items:
      - end_time
        
        string — The custom hours end time, `HH:mm` and `24-hour clock` format.
      - start_time
        
        string — The custom hours start time, `HH:mm` and `24-hour clock` format.
    - custom_hour_type
      
      integer, possible values: 0, 1, 2 — The type of custom hours. * `0` — Disabled. * `1` — 24 hours. * `2` — Customized hours.
    - day_of_week
      
      integer, possible values: 1, 2, 3, 4, 5, 6, 7 — The day of the week. * `1` — Monday * `2` — Tuesday * `3` — Wednesday * `4` — Thursday * `5` — Friday * `6` — Saturday * `7` — Sunday
  - hour_type
    
    integer, possible values: 1, 2 — The type of business hours. * `1` — 24 hours, 7 days a week. * `2` — Custom hours.
- queues_count
  
  integer — The number of queues using the business hour.
- timezone
  
  string — The business hours' timezone ID.
next_page_token

string — Use the next page token to paginate through large result sets. A next page token is returned whenever the set of available results exceeds the current page size. This token's expiration period is 15 minutes.
page_size

integer, default: 30 — The number of records returned within a single API call.
total_records

integer — The total number of all the records available across pages.

Example:

{
  "next_page_token": "R4aF9Oj0fVM2hhezJTEmSKaBSkfesDwGy42",
  "page_size": 30,
  "total_records": 10,
  "business_hours": [
    {
      "business_hour_id": "66ZjSQ7YTOescnINN_4vog",
      "business_hour_name": "Default Business hours",
      "timezone": "America/New_York",
      "account_default": true,
      "queues_count": 1,
      "flows_count": 1,
      "hours": {
        "hour_type": 2,
        "custom_hours": [
          {
            "day_of_week": 1,
            "custom_hour_type": 2,
            "custom_hour_ranges": [
              {
                "start_time": "09:00",
                "end_time": "18:00"
              }
            ]
          }
        ]
      }
    }
  ]
}

Status: 400 HTTP Status Code: `400` Bad Request

Status: 429 HTTP Status Code: `429` Too Many Requests. For more information, see [rate limits](/docs/api/rest/rate-limits/).

Create business hours

Method: POST
Path: /contact_center/business_hours
Tags: Operating Hours

Create new business hours.

Scopes: contact_center_operating_hours:write:admin,contact_center_queue:write:admin

Granular Scopes: contact_center:write:business_hour:admin

Rate Limit Label: LIGHT

Request Body

Content-Type: application/json

account_default

boolean — Default business hours for the newly created queue.
business_hour_description

string — The business hours' description.
business_hour_name

string — The business hours' name.
hours

object
- custom_hours
  
  array — The custom hours' settings. Required only for the `Custom hours` type.
  
  Items:
  - custom_hour_ranges
    
    array — The custom hours' range. Required only for the `Customized hours` type.
    
    Items:
    - end_time
      
      string — The custom hours' end time, in `HH:mm` and `24-hour clock` format.
    - start_time
      
      string — The custom hours' start time, in `HH:mm` and `24-hour clock` format.
  - custom_hour_type
    
    integer, possible values: 1, 2 — The type of custom hours. * `1` — 24 hours. * `2` — Customized hours.
  - day_of_week
    
    integer, possible values: 1, 2, 3, 4, 5, 6, 7 — The day of the week. * `1` — Monday * `2` — Tuesday * `3` — Wednesday * `4` — Thursday * `5` — Friday * `6` — Saturday * `7` — Sunday
- hour_type
  
  integer, possible values: 1, 2 — The type of business hours. * `1` — 24 hours, 7 days a week. * `2` — Custom hours.
timezone

string — The business hours' timezone ID.

Example:

{
  "business_hour_name": "Default business hours",
  "business_hour_description": "This is a description.",
  "timezone": "America/New_York",
  "account_default": true,
  "hours": {
    "hour_type": 2,
    "custom_hours": [
      {
        "day_of_week": 1,
        "custom_hour_type": 2,
        "custom_hour_ranges": [
          {
            "start_time": "09:00",
            "end_time": "18:00"
          }
        ]
      }
    ]
  }
}

Responses

Status: 201 HTTP Status Code: `201` Business hours created.

Content-Type: application/json

account_default

boolean — Default business hours for the newly created queue.
business_hour_description

string — The business hours' description.
business_hour_id

string — The business hours' ID.
business_hour_name

string — The business hours' name.
hours

object
- custom_hours
  
  array — The custom hours' settings. Returned only for the `Custom hours` type.
  
  Items:
  - custom_hour_ranges
    
    array — The custom hours' range. Returned only for the `Customized hours` type.
    
    Items:
    - end_time
      
      string — The custom hours' end time, in `HH:mm` and `24-hour clock` format.
    - start_time
      
      string — The custom hours' start time, in `HH:mm` and `24-hour clock` format.
  - custom_hour_type
    
    integer, possible values: 0, 1, 2 — The type of custom hours. * `0` — Disabled. * `1` — 24 hours. * `2` — Customized hours.
  - day_of_week
    
    integer, possible values: 1, 2, 3, 4, 5, 6, 7 — The day of the week. * `1` — Monday * `2` — Tuesday * `3` — Wednesday * `4` — Thursday * `5` — Friday * `6` — Saturday * `7` — Sunday
- hour_type
  
  integer, possible values: 1, 2 — The type of business hours. * `1` — 24 hours, 7 days a week. * `2` — Custom hours.
timezone

string — The business hours' timezone ID.

Example:

{
  "business_hour_id": "66ZjSQ7YTOescnINN_4vog",
  "business_hour_name": "Default business hours",
  "business_hour_description": "This is a description.",
  "timezone": "America/New_York",
  "account_default": true,
  "hours": {
    "hour_type": 2,
    "custom_hours": [
      {
        "day_of_week": 1,
        "custom_hour_type": 2,
        "custom_hour_ranges": [
          {
            "start_time": "09:00",
            "end_time": "18:00"
          }
        ]
      }
    ]
  }
}

Status: 400 HTTP Status Code: `400` Bad Request Error Code: `3607` The `custom_hour_ranges` should not be empty when the `custom_hour_type` is `Customized hours`. Error Code: `3608` The `end_time` $endTime should not be earlier than the `start_time` $startTime. Error Code: `300` Validation failed. Error Code: `3604` The `custom_hours` should not be empty when the `hour_type` is `Custom hours`. Error Code: `3602` Timezone does not exist.

Status: 429 HTTP Status Code: `429` Too Many Requests. For more information, see [rate limits](/docs/api/rate-limits/).

Get business hours

Method: GET
Path: /contact_center/business_hours/{businessHourId}
Tags: Operating Hours

Get information about business hours.

Scopes: contact_center_operating_hours:read:admin,contact_center_queue:read:admin

Granular Scopes: contact_center:read:business_hour:admin

Rate Limit Label: LIGHT

Responses

Status: 200 HTTP Status Code: `200` Business hours returned.

Content-Type: application/json

account_default

boolean — Default business hours for the newly created queue.
business_hour_description

string — The business hours' description.
business_hour_id

string — The business hours' ID.
business_hour_name

string — The business hours' name.
hours

object
- custom_hours
  
  array — The custom hours settings. It returns only for the `Custom hours` type.
  
  Items:
  - custom_hour_ranges
    
    array — The custom hours range. It returns only for the `Customized hours` type.
    
    Items:
    - end_time
      
      string — The custom hours end time, in `HH:mm` and `24-hour clock` format.
    - start_time
      
      string — The custom hours start time, in `HH:mm` and `24-hour clock` format.
  - custom_hour_type
    
    integer, possible values: 0, 1, 2 — The type of custom hours. * `0` - Disabled. * `1` - 24 hours. * `2` - Customized hours.
  - day_of_week
    
    integer, possible values: 1, 2, 3, 4, 5, 6, 7 — The day of the week. * `1` - Monday * `2` - Tuesday * `3` - Wednesday * `4` - Thursday * `5` - Friday * `6` - Saturday * `7` - Sunday
- hour_type
  
  integer, possible values: 1, 2 — The type of business hours. * `1` - 24 hours, 7 days a week. * `2` - Custom hours.
timezone

string — The business hours' timezone ID.

Example:

{
  "business_hour_id": "66ZjSQ7YTOescnINN_4vog",
  "business_hour_name": "Default Business hours",
  "business_hour_description": "This is a description.",
  "timezone": "America/New_York",
  "account_default": true,
  "hours": {
    "hour_type": 2,
    "custom_hours": [
      {
        "day_of_week": 1,
        "custom_hour_type": 2,
        "custom_hour_ranges": [
          {
            "start_time": "09:00",
            "end_time": "18:00"
          }
        ]
      }
    ]
  }
}

Status: 400 HTTP Status Code: `400` Bad Request

Status: 401 HTTP Status Code: `401` Unauthorized

Status: 403 HTTP Status Code: `403` Forbidden

Status: 404 HTTP Status Code: `404` Not Found Error Code: `3601` Business hour does not exist: $businessHourId.

Status: 429 HTTP Status Code: `429` Too Many Requests. For more information, see [rate limits](/docs/api/rate-limits/).

Delete business hours

Method: DELETE
Path: /contact_center/business_hours/{businessHourId}
Tags: Operating Hours

Delete business hours.

Scopes: contact_center_operating_hours:write:admin

Granular Scopes: contact_center:delete:business_hour:admin

Rate Limit Label: LIGHT

Responses

Status: 204 HTTP Status Code: `204` Business hours deleted.

Status: 400 HTTP Status Code: `400` Bad Request Error Code: `3612` The business hours of account default cannot be deleted.

Status: 404 HTTP Status Code: `404` Not Found Error Code: `3601` Business hours do not exist: $businessHourId.

Status: 429 HTTP Status Code: `429` Too Many Requests. For more information, see [rate limits](/docs/api/rate-limits/).

Update business hours

Method: PATCH
Path: /contact_center/business_hours/{businessHourId}
Tags: Operating Hours

Update business hours.

Scopes: contact_center_operating_hours:write:admin

Granular Scopes: contact_center:update:business_hour:admin

Rate Limit Label: LIGHT

Request Body

Content-Type: application/json

account_default

boolean — Default business hours for the newly created queue. Only support `true` value.
business_hour_description

string — The business hours' description.
business_hour_name

string — The business hours' name.
hours

object — Hour items.
- custom_hours
  
  array — The custom hours' settings. Required only for the `custom` type.
  
  Items:
  - custom_hour_ranges
    
    array — The custom hours' range. Required only for the `specific_Time` type.
    
    Items:
    - end_time
      
      string — The custom hours' end time, in `HH:mm` and `24-hour clock` format.
    - start_time
      
      string — The custom hours' start time, in `HH:mm` and `24-hour clock` format.
  - custom_hour_type
    
    integer, possible values: 0, 1, 2 — The type of custom hours. * `0` — Disabled. * `1` — 24 hours. * `2` — Customized hours.
  - day_of_week
    
    integer, possible values: 1, 2, 3, 4, 5, 6, 7 — The day of the week. * `1` — Monday * `2` — Tuesday * `3` — Wednesday * `4` — Thursday * `5` — Friday * `6` — Saturday * `7` — Sunday
- hour_type
  
  integer, possible values: 1, 2 — The type of business hours. * `1` — 24 hours, 7 days a week. * `2` — Custom hours.
timezone

string — The business hours' timezone ID.

Example:

{
  "business_hour_name": "Default Business hours",
  "business_hour_description": "This is a description.",
  "timezone": "America/New_York",
  "account_default": true,
  "hours": {
    "hour_type": 2,
    "custom_hours": [
      {
        "day_of_week": 1,
        "custom_hour_type": 2,
        "custom_hour_ranges": [
          {
            "start_time": "09:00",
            "end_time": "18:00"
          }
        ]
      }
    ]
  }
}

Responses

Status: 204 HTTP Status Code: `204` Business hour updated.

Status: 400 HTTP Status Code: `400` Bad Request Error Code: `3602` Timezone does not exist. Error Code: `3611` Can't update default business hours to be non-default. Error Code: `3608` The `end_time` $endTime should not be earlier than the `start_time` $startTime. Error Code: `300` Validation Failed

Status: 404 HTTP Status Code: `404` Not Found Error Code: `3601` Business hour does not exist: $businessHourId.

Status: 429 HTTP Status Code: `429` Too Many Requests. For more information, see [rate limits](/docs/api/rate-limits/).

List the business hours' flows

Method: GET
Path: /contact_center/business_hours/{businessHourId}/flows
Tags: Operating Hours

Show a list of flows using business hours.

Scopes: contact_center_flow:read:admin

Granular Scopes: contact_center:read:business_hours_flow:admin

Rate Limit Label: LIGHT

Responses

Status: 200 HTTP Status Code: `200` Flows returned.

Content-Type: application/json

next_page_token (required)

string — Use the next page token to paginate through large result sets. A next page token is returned whenever the set of available results exceeds the current page size. This token's expiration period is 15 minutes.
page_size (required)

integer, default: 30 — The number of records returned within a single API call.
flows

array — Information about the flows.

Items:
- flow_id (required)
  
  string — The flow's ID.
- flow_name (required)
  
  string — The flow's name.
total_records

integer — The total number of all records available across pages.

Example:

{
  "next_page_token": "R4aF9Oj0fVM2hhezJTEmSKaBSkfesDwGy42",
  "page_size": 30,
  "total_records": 10,
  "flows": [
    {
      "flow_id": "psjHGHrHQbaX8Zk7ldc81Q",
      "flow_name": "Default Flow"
    }
  ]
}

Status: 400 HTTP Status Code: `400` Bad Request

Status: 401 HTTP Status Code: `401` Unauthorized

Status: 403 HTTP Status Code: `403` Forbidden

Status: 404 HTTP Status Code: `404` Not Found Error Code: `3601` Business hour does not exist: $businessHourId.

Status: 429 HTTP Status Code: `429` Too Many Requests. For more information, see [rate limits](/docs/api/rate-limits/).

List the business hours' queues

Method: GET
Path: /contact_center/business_hours/{businessHourId}/queues
Tags: Operating Hours

Show a list of queues using business hours.

Scopes: contact_center_queue:read:admin

Granular Scopes: contact_center:read:business_hours_queue:admin

Rate Limit Label: LIGHT

Responses

Status: 200 HTTP Status Code: `200` Queues returned.

Content-Type: application/json

next_page_token (required)

string — Use the next page token to paginate through large result sets. A next page token is returned whenever the set of available results exceeds the current page size. This token's expiration period is 15 minutes.
page_size (required)

integer, default: 30 — The number of records returned within a single API call.
queues

array — Information about the queues.

Items:
- cc_queue_id (required)
  
  string — The Contact Center queue's ID.
- queue_id (required)
  
  string — The task queue's ID.
- queue_name (required)
  
  string — The queue's name.
total_records

integer — The total number of all records available across pages.

Example:

{
  "next_page_token": "R4aF9Oj0fVM2hhezJTEmSKaBSkfesDwGy42",
  "page_size": 30,
  "total_records": 10,
  "queues": [
    {
      "cc_queue_id": "xqJE_cgERLyAJHYYL5LLeg",
      "queue_name": "VoiceQueue"
    }
  ]
}

Status: 400 HTTP Status Code: `400` Bad Request

Status: 401 HTTP Status Code: `401` Unauthorized

Status: 403 HTTP Status Code: `403` Forbidden

Status: 404 HTTP Status Code: `404` Not Found Error Code: `3601` Business hours do not exist: $businessHourId.

Status: 429 HTTP Status Code: `429` Too Many Requests. For more information, see [rate limits](/docs/api/rest/rate-limits/).

List closures

Method: GET
Path: /contact_center/closures
Tags: Operating Hours

Get a list of closures. Admins can create closures to select.

Scopes: contact_center_queue:read:admin,contact_center_operating_hours:read:admin

Granular Scopes: contact_center:read:list_closure_hours:admin

Rate Limit Label: MEDIUM

Responses

Status: 200 HTTP Status Code: `200` Closures returned.

Content-Type: application/json

next_page_token (required)

string — Use the next page token to paginate through large result sets. A next page token is returned whenever the set of available results exceeds the current page size. This token's expiration period is 15 minutes.
page_size (required)

integer, default: 30 — The number of records returned within a single API call.
closure_sets

array — Information about the closure.

Items:
- account_default (required)
  
  boolean — Default closure for the newly-created queue.
- closure_set_id (required)
  
  string — The closure set's ID.
- closure_set_name (required)
  
  string — The closure set's name.
- closures (required)
  
  array — The closure's details.
  
  Items:
  - closure_hour_type (required)
    
    integer, possible values: 1, 2 — The closure's time type. * `1` — All day. * `2` — Customized time.
  - closure_name (required)
    
    string — The closure item's name.
  - end_time (required)
    
    string — The closure's end time and date in ISO 8601 format: yyyy-MM-dd'T'HH:mm:ss'Z', or yyyy-MM-dd'T'HH:mm:ss'TZD'.
  - recurring_frequency (required)
    
    integer, possible values: 0, 1, 2, 3 — The frequency of a closure's recurrence. * `0` — Never. * `1` — Annually. * `2` — Monthly. * `3` — Weekly.
  - start_time (required)
    
    string — The closure's start time and date in ISO 8601 format: yyyy-MM-dd'T'HH:mm:ss'Z', or yyyy-MM-dd'T'HH:mm:ss'TZD'.
  - closure_id
    
    string — The closure item's ID.
  - recurring_days_of_week
    
    array — The week days of a recurrence. It returns only for the `Weekly/Customized`, the `Weekly/Specific`, the `Annually/Customized` and the `Monthly/Customized` recurrence time types. When the type is "`Weekly/Customized`", there may be multiple values. * `1` — Monday * `2` — Tuesday * `3` — Wednesday * `4` — Thursday * `5` — Friday * `6` — Saturday * `7` — Sunday
    
    Items:
    
    string
  - recurring_frequency_type
    
    integer, possible values: 1, 2 — The closure time's type of recurrence. This applies to `Annually`, `Monthly` and `Weekly` repeat frequency. It returns only for the not `Never` recurrence type. * `1` — Specific. * `2` — Customized.
  - recurring_month
    
    integer, possible values: 1, 2, 3, 4, 5, 6, 7, 8, 9, 10, 11, 12 — The recurrence month. It returns only for the `Annually` recurrence type. * `1` — January * `2` — February * `3` — March * `4` — April * `5` — May * `6` — June * `7` — July * `8` — August * `9` — September * `10` — October * `11` — November * `12` — December
  - recurring_week_interval
    
    integer — The number of weekly recurrences. It returns only for the `Customized` recurrence time types. When it is `Annually/Customized` or `Monthly/Customized` type, the minimum value is `1` and the maximum value is `5`. When it is `Weekly/Customized` type, the minimum value is `1` and the maximum value is `12`.
- flows_count (required)
  
  integer — The number of flows using the closure set.
- queues_count (required)
  
  integer — The number of queues using the closure set.
- timezone (required)
  
  string — The closure set's timezone ID.
total_records

integer — The total number of all the records available across pages.

Example:

{
  "next_page_token": "R4aF9Oj0fVM2hhezJTEmSKaBSkfesDwGy42",
  "page_size": 30,
  "total_records": 10,
  "closure_sets": [
    {
      "closure_set_id": "Ixo-Na0bRfCyQ4q2lAryDw",
      "closure_set_name": "Default Closure",
      "timezone": "America/New_York",
      "account_default": true,
      "queues_count": 1,
      "flows_count": 1,
      "closures": [
        {
          "closure_id": "ksbJvJ",
          "closure_name": "New Year",
          "closure_hour_type": 2,
          "start_time": "2023-01-01T00:00:00-04:00",
          "end_time": "2023-02-01T00:00:00-04:00",
          "recurring_frequency": 2,
          "recurring_frequency_type": 2,
          "recurring_month": 1,
          "recurring_week_interval": 1,
          "recurring_days_of_week": [
            "1"
          ]
        }
      ]
    }
  ]
}

Status: 400 HTTP Status Code: `400` Bad Request

Status: 429 HTTP Status Code: `429` Too Many Requests. For more information, see [rate limits](/docs/api/rest/rate-limits/).

Create a closure set

Method: POST
Path: /contact_center/closures
Tags: Operating Hours

Create a new closure set.

Scopes: contact_center_queue:write:admin,contact_center_operating_hours:write:admin

Granular Scopes: contact_center:write:closure_hour:admin

Rate Limit Label: LIGHT

Request Body

Content-Type: application/json

closure_set_name (required)

string — The closure set's name.
closures (required)

array — The closure's details.

Items:
- closure_hour_type (required)
  
  integer, possible values: 1, 2 — The closure's time type. * `1` — All day. * `2` — Customized time.
- closure_name (required)
  
  string — The closure item's name.
- end_time (required)
  
  string — The closure's end time and date in ISO 8601 format: yyyy-MM-dd'T'HH:mm:ss'Z', or yyyy-MM-dd'T'HH:mm:ss'TZD'.
- recurring_frequency (required)
  
  integer, possible values: 0, 1, 2, 3 — The frequency of a closure's recurrence. * `0` — Never. * `1` — Annually. * `2` — Monthly. * `3` — Weekly.
- start_time (required)
  
  string — The closure's start time and date in ISO 8601 format: yyyy-MM-dd'T'HH:mm:ss'Z', or yyyy-MM-dd'T'HH:mm:ss'TZD'.
- recurring_days_of_week
  
  array — The week days of a recurrence. Required only for the `Weekly/Customized`, `Weekly/Specific`, `Annually/Customized`, and `Monthly/Customized` recurrence time types. When the type is "`Weekly/Customized`", there may be multiple values. * `1` — Monday * `2` — Tuesday * `3` — Wednesday * `4` — Thursday * `5` — Friday * `6` — Saturday * `7` — Sunday
  
  Items:
  
  string
- recurring_frequency_type
  
  integer, possible values: 1, 2 — The closure time's type of recurrence. Applies to `Annually`, `Monthly`, and `Weekly` repeat frequency. Returns only for the not `Never` recurrence type. * `1` — Specific. * `2` — Customized.
- recurring_month
  
  integer, possible values: 1, 2, 3, 4, 5, 6, 7, 8, 9, 10, 11, 12 — The recurrence month. Required only for the `Annually` recurrence type. * `1` — January * `2` — February * `3` — March * `4` — April * `5` — May * `6` — June * `7` — July * `8` — August * `9` — September * `10` — October * `11` — November * `12` — December
- recurring_week_interval
  
  integer — The number of weekly recurrences. Required only for the `Customized` recurrence time types. When the type is `Annually/Customized` or `Monthly/Customized`, the minimum value is `1` and the maximum value is `5`. When the type is `Weekly/Customized`, the minimum value is `1` and the maximum value is `12`.
timezone (required)

string — The closure set's timezone ID.
account_default

boolean — Default closure for the newly created queue.
closure_set_description

string — The closure set's description.

Example:

{
  "closure_set_name": "Default closure",
  "closure_set_description": "This is a description.",
  "timezone": "America/New_York",
  "account_default": true,
  "closures": [
    {
      "closure_name": "New Year",
      "closure_hour_type": 2,
      "start_time": "2023-01-01T00:00:00-04:00",
      "end_time": "2023-02-01T00:00:00-04:00",
      "recurring_frequency": 2,
      "recurring_frequency_type": 2,
      "recurring_month": 1,
      "recurring_week_interval": 1,
      "recurring_days_of_week": [
        "1"
      ]
    }
  ]
}

Responses

Status: 201 HTTP Status Code: `201` Closure set created.

Content-Type: application/json

account_default (required)

boolean — Default closure for the newly created queue.
closure_set_description (required)

string — The closure set's description.
closure_set_id (required)

string — The closure set's ID.
closure_set_name (required)

string — The closure set's name.
closures (required)

array — The closure details.

Items:
- closure_hour_type (required)
  
  integer, possible values: 1, 2 — The closure's time type. * `1` — All day. * `2` — Customized time.
- closure_name (required)
  
  string — The closure item's name.
- end_time (required)
  
  string — The closure's end time and date in ISO 8601 format: yyyy-MM-dd'T'HH:mm:ss'Z', or yyyy-MM-dd'T'HH:mm:ss'TZD'.
- recurring_frequency (required)
  
  integer, possible values: 0, 1, 2, 3 — The frequency of a closure's recurrence. * `0` — Never. * `1` — Annually. * `2` — Monthly. * `3` — Weekly.
- start_time (required)
  
  string — The closure's start time and date in ISO 8601 format: yyyy-MM-dd'T'HH:mm:ss'Z', or yyyy-MM-dd'T'HH:mm:ss'TZD'.
- closure_id
  
  string — The closure item's ID.
- recurring_days_of_week
  
  array — The week days of a recurrence. Returns only for the `Weekly/Customized`, the `Weekly/Specific`, the `Annually/Customized`, and the `Monthly/Customized` recurrence time types. When the type is "`Weekly/Customized`", there may be multiple values. * `1` — Monday * `2` — Tuesday * `3` — Wednesday * `4` — Thursday * `5` — Friday * `6` — Saturday * `7` — Sunday
  
  Items:
  
  string
- recurring_frequency_type
  
  integer, possible values: 1, 2 — The closure time's type of recurrence. Applies to `Annually`, `Monthly`, and `Weekly` repeat frequency. Returns only for the not `Never` recurrence type. * `1` — Specific. * `2` — Customized.
- recurring_month
  
  integer, possible values: 1, 2, 3, 4, 5, 6, 7, 8, 9, 10, 11, 12 — The recurrence month. Returns only for the `Annually` recurrence type. * `1` — January * `2` — February * `3` — March * `4` — April * `5` — May * `6` — June * `7` — July * `8` — August * `9` — September * `10` — October * `11` — November * `12` — December
- recurring_week_interval
  
  integer — The number of weekly recurrences. Returns only for the `Customized` recurrence time types. When the type is `Annually/Customized` or `Monthly/Customized`, the minimum value is `1` and the maximum value is `5`. When it is `Weekly/Customized`, the minimum value is `1` and the maximum value is `12`.
timezone (required)

string — The closure set's timezone ID.

Example:

{
  "closure_set_id": "Ixo-Na0bRfCyQ4q2lAryDw",
  "closure_set_name": "Default closure",
  "closure_set_description": "This is a description.",
  "timezone": "America/New_York",
  "account_default": true,
  "closures": [
    {
      "closure_id": "ksbJvJ",
      "closure_name": "New Year",
      "closure_hour_type": 2,
      "start_time": "2023-01-01T00:00:00-04:00",
      "end_time": "2023-02-01T00:00:00-04:00",
      "recurring_frequency": 2,
      "recurring_frequency_type": 2,
      "recurring_month": 1,
      "recurring_week_interval": 1,
      "recurring_days_of_week": [
        "1"
      ]
    }
  ]
}

Status: 400 HTTP Status Code: `400` Bad Request Error Code: `3602` Timezone does not exist. Error Code: `3702` The closure name has already been duplicated: $closure_name. Error Code: `3703` The end time should be greater than the start time. Error Code: `3704` The `recurring_frequency_type` should not be empty when the `recurring_frequency` is anything other than `Never`. Error Code: `3705` The `start_time` and `end_time` must be in the same year when the `recurring_frequency` is `Annually`. Error Code: `3706` The `start_time` and `end_time` must be in the same month when the `recurring_frequency` is `Monthly`. Error Code: `3707` The `start_time` and `end_time` must be in the same week when the `recurring_frequency` is `Weekly`. Error Code: `3708` The `recurring_week_interval` should not be empty when the `recurring_frequency_type` type is `Customized`. Error Code: `3709` The `recurring_days_of_week` should not be empty when the `recurring_frequency_type` type is `Customized`. Error Code: `3710` The `recurring_month` should not be empty when the type is `Annually/Customized`. Error Code: `3711` The `recurring_week_interval` should be between `1` and `5` when the `recurring_frequency` type is `Annually` or `Monthly`. Error Code: `3712` The `start_time` and `end_time` must match the `timezone`: $start_time/$end_time. Error Code: `3603` The name already exists. Error Code: `3714` The `recurring_days_of_week` should be between `1` and `7`. Error Code: `300` Validation failed.

Status: 429 HTTP Status Code: `429` Too Many Requests. For more information, see [rate limits](/docs/api/rate-limits/).

Get a closure set

Method: GET
Path: /contact_center/closures/{closureSetId}
Tags: Operating Hours

Get information about a closure set.

Scopes: contact_center_queue:read:admin,contact_center_operating_hours:read:admin

Granular Scopes: contact_center:read:closure_hour:admin

Rate Limit Label: LIGHT

Responses

Status: 200 HTTP Status Code: `200` Closure set returned.

Content-Type: application/json

account_default (required)

boolean — Default closure for the newly-created queue.
closure_set_description (required)

string — The closure set's description.
closure_set_id (required)

string — The closure set's ID.
closure_set_name (required)

string — The closure set's name.
closures (required)

array — The closure's details.

Items:
- closure_hour_type (required)
  
  integer, possible values: 1, 2 — The closure's time type. * `1` - All day. * `2` - Customized time.
- closure_name (required)
  
  string — The closure item's name.
- end_time (required)
  
  string — The closure's end time and date in ISO 8601 format: `yyyy-MM-dd'T'HH:mm:ss'Z'`, or `yyyy-MM-dd'T'HH:mm:ss'TZD'`.
- recurring_frequency (required)
  
  integer, possible values: 0, 1, 2, 3 — The frequency of a closure's recurrence. * `0` - Never. * `1` - Annually. * `2` - Monthly. * `3` - Weekly.
- start_time (required)
  
  string — The closure's start time and date in ISO 8601 format: `yyyy-MM-dd'T'HH:mm:ss'Z'`, or `yyyy-MM-dd'T'HH:mm:ss'TZD'`.
- closure_id
  
  string — The closure item's ID.
- recurring_days_of_week
  
  array — The recurrence's week days. It returns only for the `Weekly/Customized`, the `Weekly/Specific`, the `Annually/Customized`, and the `Monthly/Customized` recurrence time types. When the recurrence type is "`Weekly/Customized`", there may be multiple values. * `1` - Monday * `2` - Tuesday * `3` - Wednesday * `4` - Thursday * `5` - Friday * `6` - Saturday * `7` - Sunday
  
  Items:
  
  string
- recurring_frequency_type
  
  integer, possible values: 1, 2 — The closure time's recurrence type. This applies to `Annually`, `Monthly` and `Weekly` recurrence frequency. It returns for recurrence types that are not `Never`. * `1` - Specific. * `2` - Customized.
- recurring_month
  
  integer, possible values: 1, 2, 3, 4, 5, 6, 7, 8, 9, 10, 11, 12 — The recurrence month. It returns only for the `Annually` recurrence type. * `1` - January * `2` - February * `3` - March * `4` - April * `5` - May * `6` - June * `7` - July * `8` - August * `9` - September * `10` - October * `11` - November * `12` - December
- recurring_week_interval
  
  integer — The number of weekly recurrences. It returns only for the `Customized` recurrence time types. When the recurrence type is either `Annually/Customized` or `Monthly/Customized` type, the minimum value is `1` and the maximum value is `5`. When it is `Weekly/Customized` type, the minimum value is `1` and the maximum value is `12`.
timezone (required)

string — The closure set's timezone ID.

Example:

{
  "closure_set_id": "Ixo-Na0bRfCyQ4q2lAryDw",
  "closure_set_name": "Default closure",
  "closure_set_description": "This is a description.",
  "timezone": "America/New_York",
  "account_default": true,
  "closures": [
    {
      "closure_id": "ksbJvJ",
      "closure_name": "New Year",
      "closure_hour_type": 2,
      "start_time": "2023-01-01T00:00:00-04:00",
      "end_time": "2023-02-01T00:00:00-04:00",
      "recurring_frequency": 2,
      "recurring_frequency_type": 2,
      "recurring_month": 1,
      "recurring_week_interval": 1,
      "recurring_days_of_week": [
        "1"
      ]
    }
  ]
}

Status: 400 HTTP Status Code: `400` Bad Request

Status: 401 HTTP Status Code: `401` Unauthorized

Status: 403 HTTP Status Code: `403` Forbidden

Status: 404 HTTP Status Code: `404` Not Found Error Code: `3701` Closures set does not exist: $closureId.

Status: 429 HTTP Status Code: `429` Too Many Requests. For more information, see [rate limits](/docs/api/rate-limits/).

Delete a closure set

Method: DELETE
Path: /contact_center/closures/{closureSetId}
Tags: Operating Hours

Delete closure sets.

Scopes: contact_center_operating_hours:write:admin

Granular Scopes: contact_center:delete:closure_hour:admin

Rate Limit Label: LIGHT

Responses

Status: 204 HTTP Status Code: `204` Closure sets deleted.

Status: 400 HTTP Status Code: `400` Bad Request Error Code: `3713` The closures of account default cannot be deleted.

Status: 404 HTTP Status Code: `404` Not Found Error Code: `3701` Closure set does not exist: $closureSetId.

Status: 429 HTTP Status Code: `429` Too Many Requests. For more information, see [rate limits](https://developers.zoom.us/docs/api/rest/rate-limits/).

Update a closure set

Method: PATCH
Path: /contact_center/closures/{closureSetId}
Tags: Operating Hours

Update information about a closure set.

Scopes: contact_center_operating_hours:write:admin

Granular Scopes: contact_center:update:closure_hour:admin

Rate Limit Label: LIGHT

Request Body

Content-Type: application/json

closure_set_name (required)

string — The closure set's name.
closures (required)

array — The closure set's details.

Items:
- closure_hour_type
  
  integer, possible values: 1, 2 — The closure's time type. * `1` — All day. * `2` — Customized time.
- closure_id
  
  string — The closure item's ID.
- closure_name
  
  string — The closure item's name.
- end_time
  
  string, format: datetime — The closure's end time and date in ISO 8601 format: yyyy-MM-dd'T'HH:mm:ss'Z', or yyyy-MM-dd'T'HH:mm:ss'TZD'.
- recurring_days_of_week
  
  array — The recurrence's week days. Required only for the `Weekly/Customized`, the `Weekly/Specific`, the `Annually/Customized`, and the `Monthly/Customized` recurrence time types. When the type is "`Weekly/Customized`", there may be multiple values. * `1` — Monday * `2` — Tuesday * `3` — Wednesday * `4` — Thursday * `5` — Friday * `6` — Saturday * `7` — Sunday
  
  Items:
  
  string
- recurring_frequency
  
  integer, possible values: 0, 1, 2, 3 — The frequency of a closure's recurrence. * `0` — Never. * `1` — Annually. * `2` — Monthly. * `3` — Weekly.
- recurring_frequency_type
  
  integer, possible values: 1, 2 — The closure time's type of recurrence. Applies to `Annually`, `Monthly`, and `Weekly` repeat frequency. Returns only for the not `Never` recurrence type. * `1` — Specific. * `2` — Customized.
- recurring_month
  
  integer, possible values: 1, 2, 3, 4, 5, 6, 7, 8, 9, 10, 11, 12 — The recurrence month. Required only for the `Annually` recurrence type. * `1` — January * `2` — February * `3` — March * `4` — April * `5` — May * `6` — June * `7` — July * `8` — August * `9` — September * `10` — October * `11` — November * `12` — December
- recurring_week_interval
  
  integer — The number of weekly recurrences. Required only for the `Customized` recurrence time types. When the type is `Annually/Customized` or `Monthly/Customized`, the minimum value is `1` and the maximum value is `5`. When the type is `Weekly/Customized`, the minimum value is `1` and the maximum value is `12`.
- start_time
  
  string — The closure's start time and date in ISO 8601 format: yyyy-MM-dd'T'HH:mm:ss'Z', or yyyy-MM-dd'T'HH:mm:ss'TZD'.
- to_delete
  
  boolean — Whether to delete this closure item.
timezone (required)

string — The closure set's timezone ID.
account_default

boolean — Default closure for the newly-created queue.
closure_set_description

string — The closure set's description.

Example:

{
  "closure_set_name": "Default closure",
  "closure_set_description": "This is a description.",
  "timezone": "America/New_York",
  "account_default": true,
  "closures": [
    {
      "closure_id": "ksbJvJ",
      "closure_name": "New Year",
      "closure_hour_type": 2,
      "start_time": "2023-01-01T00:00:00-04:00",
      "end_time": "2023-02-01T00:00:00-04:00",
      "recurring_frequency": 2,
      "recurring_frequency_type": 2,
      "recurring_month": 1,
      "recurring_week_interval": 1,
      "recurring_days_of_week": [
        "1"
      ],
      "to_delete": false
    }
  ]
}

Responses

Status: 204 HTTP Status Code: `204` Closure set updated.

Status: 400 HTTP Status Code: `400` Bad Request Error Code: `3602` Timezone does not exist. Error Code: `3702` The closure name has already been duplicated: $closure_name. Error Code: `3703` The end time should be greater than the start time. Error Code: `3704` The `recurring_frequency_type` should not be empty when the `recurring_frequency` is not `Never`. Error Code: `3705` The `start_time` and `end_time` must be in the same year when the `recurring_frequency` is `Annually`. Error Code: `3706` The `start_time` and `end_time` must be in the same month when the `recurring_frequency` is `Monthly`. Error Code: `3707` The "start_time" and "end_time" must be in the same week when the "recurring_frequency" is the "Weekly". Error Code: `3708` The `recurring_week_interval` should not be empty when the `recurring_frequency_type` type is `Customized`. Error Code: `3709` The `recurring_days_of_week` should not be empty when the `recurring_frequency_type` type is `Customized`. Error Code: `3710` The `recurring_month` should not be empty when the type is `Annually/Customized`. Error Code: `3711` The `recurring_week_interval` should between `1` and `5` when the `recurring_frequency` type is `Annually` or `Monthly`. Error Code: `3712` The `start_time` and `end_time` must match the `timezone`: $start_time/$end_time. Error Code: `3603` The name already exists. Error Code: `3901` The closure id has already been duplicated: $closure_id. Error Code: `3902` Closure does not exist: $closure_id. Error Code: `3903` The `hour_type` field cannot be empty when the `closure_id` field is empty. Error Code: `3904` The `closure_name` field cannot be empty when the `closure_id` field is empty. Error Code: `3905` The `start_time` field cannot be empty when the `closure_id` field is empty. Error Code: `3906` The `end_time` field cannot be empty when the `closure_id` field is empty. Error Code: `3907` The `recurring_frequency` field cannot be empty when the `closure_id` field is empty. Error Code: `3908` Every closure set has at least one closure item. Error Code: `300` Validation failed.

Status: 404 HTTP Status Code: `404` Not Found Error Code: `3701` Closure set does not exist: $closureSetId.

Status: 429 HTTP Status Code: `429` Too Many Requests. For more information, see [rate limits](/docs/api/rate-limits/).

List the closures' flows

Method: GET
Path: /contact_center/closures/{closureSetId}/flows
Tags: Operating Hours

Show a list of flows using closures.

Scopes: contact_center_flow:read:admin

Granular Scopes: contact_center:read:clousre_hour_flow:admin

Rate Limit Label: LIGHT

Responses

Status: 200 HTTP Status Code: `200` Flows returned.

Content-Type: application/json

next_page_token (required)

string — Use the next page token to paginate through large result sets. A next page token is returned whenever the set of available results exceeds the current page size. This token's expiration period is 15 minutes.
page_size (required)

integer, default: 30 — The number of records returned within a single API call.
flows

array — Information about the flows.

Items:
- flow_id (required)
  
  string — The flow's ID.
- flow_name (required)
  
  string — The flow's name.
total_records

integer — The total number of all records available across pages.

Example:

{
  "next_page_token": "R4aF9Oj0fVM2hhezJTEmSKaBSkfesDwGy42",
  "page_size": 30,
  "total_records": 10,
  "flows": [
    {
      "flow_id": "psjHGHrHQbaX8Zk7ldc81Q",
      "flow_name": "Default Flow"
    }
  ]
}

Status: 400 HTTP Status Code: `400` Bad Request

Status: 401 HTTP Status Code: `401` Unauthorized

Status: 403 HTTP Status Code: `403` Forbidden

Status: 404 HTTP Status Code: `404` Not Found Error Code: `3701` Closures set does not exist: $closureSetId.

Status: 429 HTTP Status Code: `429` Too Many Requests. For more information, see [rate limits](/docs/api/rate-limits/).

List the closures' queues

Method: GET
Path: /contact_center/closures/{closureSetId}/queues
Tags: Operating Hours

Show a list of queues using closures.

Scopes: contact_center_queue:read:admin

Granular Scopes: contact_center:read:closure_hour_queue:admin

Rate Limit Label: LIGHT

Responses

Status: 200 HTTP Status Code: `200` Queues returned.

Content-Type: application/json

next_page_token (required)

string — Use the next page token to paginate through large result sets. A next page token is returned whenever the set of available results exceeds the current page size. This token's expiration period is 15 minutes.
page_size (required)

integer, default: 30 — The number of records returned within a single API call.
queues

array — Information about the queues.

Items:
- cc_queue_id (required)
  
  string — The Contact Center queue's ID.
- queue_id (required)
  
  string — The task queue's ID.
- queue_name (required)
  
  string — The queue's name.
total_records

integer — The total number of all records available across pages.

Example:

{
  "next_page_token": "R4aF9Oj0fVM2hhezJTEmSKaBSkfesDwGy42",
  "page_size": 30,
  "total_records": 10,
  "queues": [
    {
      "cc_queue_id": "xqJE_cgERLyAJHYYL5LLeg",
      "queue_name": "VoiceQueue"
    }
  ]
}

Status: 400 HTTP Status Code: `400` Bad Request

Status: 401 HTTP Status Code: `401` Unauthorized

Status: 403 HTTP Status Code: `403` Forbidden

Status: 404 HTTP Status Code: `404` Not Found Error Code: `3701` Closures set does not exist: $closureSetId.

Status: 429 HTTP Status Code: `429` Too Many Requests. For more information, see [rate limits](/docs/api/rate-limits/).

List queue templates

Method: GET
Path: /contact_center/queue_templates
Tags: Queues

Retrieve a list of queue templates.

Scopes: contact_center_queue:read:admin

Granular Scopes: contact_center:read:queue:admin

Rate Limit Label: MEDIUM

Responses

Status: 200 Queue templates by page.

Content-Type: application/json

next_page_token

string — Use the next page token to paginate through large result sets. A next page token returns whenever the set of available results exceeds the current page size. This token's expiration period is 15 minutes.
page_size

number — The number of records returned within a single API call.
queue_templates

array — Information about the queue templates.

Items:
- channel (required)
  
  string, possible values: "voice", "messaging", "email", "video", "work_item" — Template channel.
- last_modified_time (required)
  
  string — The date and time when the asset was last modified.
- modified_by (required)
  
  string — The ID of user who last modified the asset.
- template_description (required)
  
  string — Template description.
- template_id (required)
  
  string — Template ID.
- template_name (required)
  
  string — Template name.
- template_need_attention (required)
  
  boolean — Whether the template needs attention or not.
- template_status (required)
  
  string, possible values: "active", "inactive" — Template status.
- template_type (required)
  
  string, possible values: "add", "update" — Template type.
total_records

number — The total number of all the records available across pages.

Example:

{
  "next_page_token": "3Y42JUhtdR7yav3CwXpQxzCA8b8LjPGySQ2",
  "page_size": 5,
  "total_records": 5,
  "queue_templates": [
    {
      "template_id": "cIInrJZUQWy12qoLPASXLw",
      "template_name": "voice add template 9",
      "template_description": "test voice add template 9",
      "channel": "voice",
      "template_type": "add",
      "template_status": "active",
      "template_need_attention": false,
      "modified_by": "CXF7npCJTQ2i3blpn9tSCw",
      "last_modified_time": "2025-05-14T23:30:38.000+00:00"
    }
  ]
}

Status: 400 HTTP Status Code: `400` Bad Request

Status: 429 HTTP Status Code: `429` Too Many Requests. For more information, see [rate limits](/docs/api/rate-limits/).

Create a queue template

Method: POST
Path: /contact_center/queue_templates
Tags: Queues

Create a Contact Center queue template.

Scopes: contact_center_queue:write:admin

Granular Scopes: contact_center:write:queue:admin

Rate Limit Label: LIGHT

Request Body

Content-Type: application/json

channel (required)

string, possible values: "voice", "video", "messaging", "email", "work_item" — The queue template's channel type.
queue_template_name (required)

string — The queue template's name.
queue_template_type (required)

string, possible values: "add", "update" — The queue template's type. Use `add` to create new queues, and use `update` to modify existing queues.
queue_template_description

string — The queue template's description.

Example:

{
  "queue_template_name": "Voice Queue Template",
  "queue_template_description": "Standard template for voice queues with default settings",
  "channel": "voice",
  "queue_template_type": "add"
}

Responses

Status: 201 Queue template created successfully.

Content-Type: application/json

channel (required)

string, possible values: "voice", "video", "messaging", "email", "work_item" — The queue template's channel type.
last_modified_time (required)

string — The date and time when the queue template was last modified, in ISO 8601 format.
modified_by (required)

string — The user ID of the user who last modified the queue template.
queue_template_id (required)

string — The queue template's unique identifier.
queue_template_name (required)

string — The queue template's name.
queue_template_status (required)

string, possible values: "active", "inactive" — The queue template's status. `active` templates can be used, `inactive` templates are disabled.
queue_template_type (required)

string, possible values: "add", "update" — The queue template's type. Use `add` to create new queues, and use `update` to modify existing queues.
queue_template_description

string — The queue template's description.
queue_template_need_attention

boolean — Whether the queue template requires attention due to configuration issues or missing dependencies.

Example:

{
  "queue_template_id": "cIInrJZUQWy12qoLPASXLw",
  "queue_template_name": "Voice Queue Template",
  "queue_template_description": "Standard template for voice queues with default settings",
  "channel": "voice",
  "queue_template_type": "add",
  "queue_template_status": "active",
  "queue_template_need_attention": false,
  "modified_by": "zIInwJQUCUy12qoLPASXJi",
  "last_modified_time": "2025-12-03T08:43:10.000+00:00"
}

Status: 400 HTTP Status Code: `400` Bad Request Error Code: `1214` Queue template is not enabled: {accountId}. Error Code: `1205` Queue channel type is invalid: {channel}. Error Code: `1240` Queue template type is invalid: {templateType}. Valid values: add, update. Error Code: `1242` Queue template name already exists: {templateName}. Error Code: `1243` Queue template limit exceeded. Maximum number of templates allowed has been reached.

Status: 401 HTTP Status Code: `401` Unauthorized Error Code: `1002` The user associated with this access token was not found or is invalid.

Status: 403 HTTP Status Code: `403` Forbidden Error Code: `9001` The Contact Center user associated with this bearer token is missing privileges on their role required to operate this request.

Status: 429 HTTP Status Code: `429` Too Many Requests. For more information, see [rate limits](https://developers.zoom.us/docs/api/rate-limits/). Error Code: `4001` You have reached the maximum per-second rate limit for this API. Try again later.

Batch delete queue templates

Method: DELETE
Path: /contact_center/queue_templates
Tags: Queues

Delete multiple Contact Center queue templates.

Scopes: contact_center_queue:write:admin

Granular Scopes: contact_center:delete:queue:admin

Rate Limit Label: MEDIUM

Request Body

Content-Type: application/json

queue_template_ids (required)

array — A list of queue template IDs to delete.

Items:

string

Example:

{
  "queue_template_ids": [
    "UdfmrJHUQWy12qoLPASXAa",
    "cIInrJZUQWy12qoLPASXLw"
  ]
}

Responses

Status: 204 Queue templates deleted successfully.

Status: 400 HTTP Status Code: `400` Bad Request Error Code: `1214` Queue template is not enabled: {accountId}.

Status: 401 HTTP Status Code: `401` Unauthorized Error Code: `1002` The user associated with this access token was not found or is invalid. Error Code: `124` Invalid access token. Error Code: `124` Access token has expired.

Status: 403 HTTP Status Code: `403` Forbidden Error Code: `9001` The Contact Center user associated with this bearer token is missing privileges on their role required to operate this request. Error Code: `1021` User account is deactivated. Error Code: `1022` User does not have a Contact Center license.

Status: 404 HTTP Status Code: `404` Not Found Error Code: `1213` Queue template does not exist: {queueTemplateId}.

Status: 429 HTTP Status Code: `429` Too Many Requests. For more information, see [rate limits](https://developers.zoom.us/docs/api/rate-limits/). Error Code: `4001` You have reached the maximum per-second rate limit for this API. Try again later.

Get a queue template

Method: GET
Path: /contact_center/queue_templates/{queueTemplateId}
Tags: Queues

Retrieve a Contact Center queue template.

Scopes: contact_center_queue:read:admin

Granular Scopes: contact_center:read:queue:admin

Rate Limit Label: LIGHT

Responses

Status: 200 Queue template retrieved successfully.

Content-Type: application/json

channel (required)

string, possible values: "voice", "video", "messaging", "email", "work_item" — The queue template's channel type.
last_modified_time (required)

string — The date and time when the queue template was last modified, in ISO 8601 format.
modified_by (required)

string — The user ID of the user who last modified the queue template.
queue_template_id (required)

string — The queue template's unique identifier.
queue_template_name (required)

string — The queue template's name.
queue_template_status (required)

string, possible values: "active", "inactive" — The queue template's status. `active` templates can be used, `inactive` templates are disabled.
queue_template_type (required)

string, possible values: "add", "update" — The queue template's type. Use `add` to create new queues, and use `update` to modify existing queues.
queue_template_description

string — The queue template's description.
queue_template_need_attention

boolean — Whether the queue template requires attention due to configuration issues or missing dependencies.

Example:

{
  "queue_template_id": "cIInrJZUQWy12qoLPASXLw",
  "queue_template_name": "Voice Queue Template",
  "queue_template_description": "Standard template for voice queues with default settings",
  "channel": "voice",
  "queue_template_type": "add",
  "queue_template_status": "active",
  "queue_template_need_attention": false,
  "modified_by": "zIInwJQUCUy12qoLPASXJi",
  "last_modified_time": "2025-12-03T08:43:10.000+00:00"
}

Status: 400 HTTP Status Code: `400` Bad Request Error Code: `1214` Queue template is not enabled: {accountId}. Error Code: `1245` More than one matching queue template found.

Status: 401 HTTP Status Code: `401` Unauthorized Error Code: `1002` The user associated with this access token was not found or is invalid.

Status: 403 HTTP Status Code: `403` Forbidden Error Code: `9001` The Contact Center user associated with this bearer token is missing privileges on their role required to operate this request.

Status: 404 HTTP Status Code: `404` Not Found Error Code: `1213` Queue template does not exist: {queueTemplateId}.

Status: 429 HTTP Status Code: `429` Too Many Requests. For more information, see [rate limits](https://developers.zoom.us/docs/api/rate-limits/). Error Code: `4001` You have reached the maximum per-second rate limit for this API. Try again later.

Delete a queue template

Method: DELETE
Path: /contact_center/queue_templates/{queueTemplateId}
Tags: Queues

Delete a Contact Center queue template.

Scopes: contact_center_queue:write:admin

Granular Scopes: contact_center:delete:queue:admin

Rate Limit Label: LIGHT

Responses

Status: 204 Queue template deleted successfully.

Status: 400 HTTP Status Code: `400` Bad Request Error Code: `1214` Queue template is not enabled: {accountId}. Error Code: `1245` More than one matching queue template found.

Status: 401 HTTP Status Code: `401` Unauthorized Error Code: `1002` The user associated with this access token was not found or is invalid.

Status: 403 HTTP Status Code: `403` Forbidden Error Code: `9001` The Contact Center user associated with this bearer token is missing privileges on their role required to operate this request.

Status: 404 HTTP Status Code: `404` Not Found Error Code: `1213` Queue template does not exist: {queueTemplateId}.

Status: 429 HTTP Status Code: `429` Too Many Requests. For more information, see [rate limits](https://developers.zoom.us/docs/api/rate-limits/). Error Code: `4001` You have reached the maximum per-second rate limit for this API. Try again later.

Update a queue template

Method: PATCH
Path: /contact_center/queue_templates/{queueTemplateId}
Tags: Queues

Update a Contact Center queue template.

Scopes: contact_center_queue:write:admin

Granular Scopes: contact_center:update:queue:admin

Rate Limit Label: LIGHT

Request Body

Content-Type: application/json

queue_template_description

string — The queue template's description.
queue_template_name

string — The queue template's name.
queue_template_status

string, possible values: "active", "inactive" — The queue template's status. `active` templates can be used, `inactive` templates are disabled.

Example:

{
  "queue_template_name": "Voice Queue Template",
  "queue_template_description": "Standard template for voice queues with default settings",
  "queue_template_status": "active"
}

Responses

Status: 204 Queue template updated successfully.

Status: 400 HTTP Status Code: `400` Bad Request Error Code: `1214` Queue template is not enabled: {accountId}. Error Code: `1241` Queue template status is invalid: {status}. Valid values: active, inactive. Error Code: `1242` Queue template name already exists: {templateName}. Error Code: `1245` More than one matching queue template found.

Status: 401 HTTP Status Code: `401` Unauthorized Error Code: `1002` The user associated with this access token was not found or is invalid.

Status: 403 HTTP Status Code: `403` Forbidden Error Code: `9001` The Contact Center user associated with this bearer token is missing privileges on their role required to operate this request.

Status: 404 HTTP Status Code: `404` Not Found Error Code: `1213` Queue template does not exist: {queueTemplateId}.

Status: 429 HTTP Status Code: `429` Too Many Requests. For more information, see [rate limits](https://developers.zoom.us/docs/api/rate-limits/). Error Code: `4001` You have reached the maximum per-second rate limit for this API. Try again later.

List queues

Method: GET
Path: /contact_center/queues
Tags: Queues

Get information about all available queues.

Scopes: contact_center_queue:read:admin

Granular Scopes: contact_center:read:list_queues:admin

Rate Limit Label: MEDIUM

Responses

Status: 200 HTTP Status Code: `200` Queues list returned.

Content-Type: application/json

next_page_token

string — Use the next page token to paginate through large result sets. A next page token returns whenever the set of available results exceeds the current page size. This token's expiration period is 15 minutes.
page_size

integer, default: 30 — The number of records returned within a single API call.
queues

array — Information about the task queues.

Items:
- agents_count
  
  integer — The number of assigned agents.
- cc_queue_id
  
  string — The Contact Center queue's ID.
- channel
  
  string, possible values: "voice", "video", "messaging", "email" — The Contact Center queue's channel.
- channel_types
  
  array — The task queue's channel types.
  
  Items:
  
  string, possible values: "voice", "chat", "sms", "video", "in_app_chat", "messaging"
- last_modified_time
  
  string, format: date-time — The date and time when the asset was last modified.
- modified_by
  
  string — The ID of user who last modified the asset.
- queue_id
  
  string — The task queue's ID.
- queue_name
  
  string — The task queue's name.
- supervisors_count
  
  integer — The number of assigned supervisors.
total_records

integer — The total number of all the records available across pages.

Example:

{
  "next_page_token": "R4aF9Oj0fVM2hhezJTEmSKaBSkfesDwGy42",
  "page_size": 30,
  "total_records": 1,
  "queues": [
    {
      "cc_queue_id": "xqJE_cgERLyAJHYYL5LLeg",
      "queue_name": "queue_661c6e4b-89fc-4b0d-9978-c7394725462",
      "agents_count": 1,
      "supervisors_count": 1,
      "channel": "voice",
      "modified_by": "IGTRVt3gQ2i-WjoUIjeZxw",
      "last_modified_time": "2022-02-15T09:27:15Z"
    }
  ]
}

Status: 429 HTTP Status Code: `429` Too Many Requests. For more information, see [rate limits](https://developers.zoom.us/docs/api/rest/rate-limits/).

Create a queue

Method: POST
Path: /contact_center/queues
Tags: Queues

Create an agent queue to determine which agents calls are routed to. Queues also link to an existing routing profile to determine how calls are routed.

Scopes: contact_center_queue:write:admin

Granular Scopes: contact_center:write:queue:admin

Rate Limit Label: LIGHT

Request Body

Content-Type: application/json

channel

string, possible values: "voice", "video", "messaging", "email", "work_item" — The Contact Center queue's channel.
channel_types

array — The task queue's channel types.

Items:

string, possible values: "voice", "chat", "sms", "video", "in_app_chat", "messaging", "work_item"
queue_description

string — The task queue's description.
queue_name

string — The task queue's name.

Example:

{
  "queue_name": "queue_661c6e4b-89fc-4b0d-9978-c7394725462",
  "queue_description": "This is a task queue.",
  "channel": "voice"
}

Responses

Status: 201 HTTP Status Code: `201` Queue created.

Content-Type: application/json

cc_queue_id

string — The Contact Center queue's ID.
channel

string, possible values: "voice", "video", "messaging", "email", "work_item" — The Contact Center queue's channel.
channel_types

array — The task queue's channel types.

Items:

string, possible values: "voice", "chat", "sms", "video", "in_app_chat", "messaging", "work_item"
queue_description

string — The task queue's description.
queue_id

string — The task queue's ID.
queue_name

string — The task queue's name.

Example:

{
  "cc_queue_id": "zeYjXoDOS_eV1QmTpj63PQ",
  "queue_name": "queue_661c6e4b-89fc-4b0d-9978-c7394725462",
  "queue_description": "This is a task queue.",
  "channel": "voice"
}

Status: 400 HTTP Status Code: `400` Bad Request Error Code: `1205` Invalid channel type.

Status: 429 HTTP Status Code: `429` Too Many Requests. For more information, see [rate limits](https://developers.zoom.us/docs/api/rate-limits/).

Batch create queues with a template

Method: POST
Path: /contact_center/queues/batch
Tags: Queues

Create bulk of contact center queues with templateId.

Scopes: contact_center_queue:write:admin

Granular Scopes: contact_center:write:queue:admin

Rate Limit Label: MEDIUM

Request Body

Content-Type: application/json

queues

array — List of queues need to be created.

Items:
- queue_description (required)
  
  string — The queue description.
- queue_name (required)
  
  string — The queue name.
template_id

string — The template ID

Example:

{
  "template_id": "urxORBoRRDCtvCT7xE5K9g",
  "queues": [
    {
      "queue_name": "voice queue 600",
      "queue_description": "test voice queue 600"
    }
  ]
}

Responses

Status: 201 List of queues created.

Content-Type: application/json

Array of:

cc_queue_id (required)

string — The Contact Center queue's ID.
channel (required)

string — The Contact Center queue's channel.
queue_description (required)

string — The task queue's description.
queue_name (required)

string — The task queue's name.

Max items: 50

Example:

[
  {
    "cc_queue_id": "GaMccDOOTvqV_bfmWqRVxA",
    "queue_name": "voice queue 200",
    "queue_description": "test voice queue 200",
    "channel": "voice"
  }
]

Status: 400 HTTP Status Code: `400` Bad Request Error Code: `1213` Queue template does not exist: {templateId}.

Status: 429 HTTP Status Code: `429` Too Many Requests. For more information, see [rate limits](/docs/api/rate-limits/).

Batch delete queues

Method: DELETE
Path: /contact_center/queues/batch
Tags: Queues

Delete bulk of Contact Center queues.

Scopes: contact_center_queue:write:admin

Granular Scopes: contact_center:delete:queue:admin

Rate Limit Label: MEDIUM

Request Body

Content-Type: application/json

cc_queue_ids

array — IDs of the queues to be deleted.

Items:

string — ID of the queue to be deleted.

Example:

{
  "cc_queue_ids": [
    "0HlBusg3QpqHGlGnaHJgOw"
  ]
}

Responses

Status: 204 Queues deleted.

Status: 404 HTTP Status Code: `404` Not Found Error Code: `1201` Queue does not exist: {quueId}.

Get a queue

Method: GET
Path: /contact_center/queues/{queueId}
Tags: Queues

Get information about a queue.

Scopes: contact_center_queue:read:admin

Granular Scopes: contact_center:read:queue:admin

Rate Limit Label: LIGHT

Responses

Status: 200 HTTP Status Code: `200` Queue returned.

Content-Type: application/json

agent_routing_profile_id

string — The queue's agent routing profile ID.
agent_routing_profile_name

string — The queue's agent routing profile name.
auto_close_alert_message

string — An alert message to web-chat users before auto-closing.
auto_close_alert_message_enabled

boolean — Send an alert message before auto-closing web chats. Channel type - chat.
auto_close_alert_message_time

integer — How long, in minutes, before a warning is sent to the user.
auto_close_message

string — Auto-closed message to users for web chats.
auto_close_message_enabled

boolean — Send an auto-closed message for web chats. Channel type - chat.
auto_close_timeout

integer — How long, in minutes, before the chat is auto-closed.
caller_ids

array — The queue's caller ID list. Only for voice queues. When a voice queue is configured with caller ID(s), the list will populate with phone numbers.

Items:

string — Caller ID number, in E.164 format.
cc_queue_id

string — The Contact Center queue's ID.
channel

string, possible values: "voice", "video", "messaging", "email", "work_item" — The Contact Center queue's channel.
channel_types

array — The task queue's channel types.

Items:

string, possible values: "voice", "chat", "sms", "video", "in_app_chat", "messaging", "work_item"
connecting_media_filename

string — **Deprecated** See `queue_waiting_experience` object. File name of the media in use while consumers are being connected. Channel type: voice.
connecting_media_id

string — **Deprecated** See `queue_waiting_experience` object. Media ID to use while users are being connected. Channel type: voice.
consumer_routing_profile_id

string — The queue's consumer routing profile ID.
consumer_routing_profile_name

string — The queue's consumer routing profile name.
disposition_sets_count

integer — The number of disposition sets.
dispositions_count

integer — The number of dispositions.
distribution_duration_in_seconds

integer — The notify duration for each queue user, in seconds.
distribution_type

integer, possible values: 0, 1, 2, 3, 4, 5, 6, 7 — Distribute incoming engagements.
engagement_acceptance

object — Queue engagement acceptance configurations.
- acceptance_type
  
  string, possible values: "auto", "manual" — Methods to accept an engagement.
- agent_greeting_asset_id
  
  string — The agent greeting's audio asset ID.
- agent_whisper_announcement_asset_id
  
  string — The agent whisper announcement's audio asset ID.
- enable_agent_alert_tone
  
  boolean — Whether to enable playing an alert tone to the agent.
- enable_agent_greeting
  
  boolean — Whether to enable playing a default agent greeting.
- enable_agent_whisper_announcement
  
  boolean — Whether to enable playing an announcement to the agent.
- greeting_filename
  
  string — The agent greeting audio's file name.
- whisper_filename
  
  string — The agent whisper announcement audio's file name.
engagement_distribution

string, possible values: "longest_idle", "sequential", "rotating", "simultaneous", "most_available", "manual", "longest_ready", "longest_idle_for_this_queue" — Method of engagement distribution.
holding_media_filename

string — **Deprecated** See `queue_waiting_experience` object. File name of the media to use while users are on hold. Channel type: voice.
holding_media_id

string — **Deprecated** See `queue_waiting_experience` object. Media ID to use while users are on hold. Channel type: voice.
inbound_dispositions

object — Queue configured inbound dispositions and disposition sets.
- default_disposition_id
  
  string — Inbound default disposition ID.
- default_disposition_name
  
  string — Inbound default disposition name.
- disposition_sets
  
  array — Inbound bounded disposition sets.
  
  Items:
  - disposition_set_id
    
    string — The disposition set's ID.
  - disposition_set_name
    
    string — The disposition set's name.
- dispositions
  
  array — Inbound bounded dispositions.
  
  Items:
  - disposition_id
    
    string — The disposition's ID.
  - disposition_name
    
    string — The disposition's name.
- enable_disposition
  
  boolean — Enable inbound disposition.
- queue_disposition_type
  
  integer — Type of inbound disposition. 0 - Mandatory, 1 - Optional.
inbound_launch_url_info

object — Inbound launch URL configurations.
- config
  
  array — Configurations of launching URL and methods to launch.
  
  Items:
  - launch_trigger
    
    string, possible values: "ringing", "answered", "ended" — Methods to launch URL.
  - launch_url
    
    string — URL to be launched.
- enable_launch_url
  
  boolean — Whether to enable inbound launch URL section.
max_engagement_in_queue

integer — The task queue's maximum engagement in queue value.
max_wait_time

integer — The task queue's maximum wait time, in seconds.
message_accept

string, possible values: "manual", "auto" — Option to accept a message manually or automatically. Channel types - chat, SMS.
outbound_dispositions

object — Queue configured outbound dispositions and disposition sets.
- default_disposition_id
  
  string — Outbound default disposition ID.
- default_disposition_name
  
  string — Outbound default disposition name.
- disposition_sets
  
  array — Outbound bounded disposition sets.
  
  Items:
  - disposition_set_id
    
    string — The disposition set's ID.
  - disposition_set_name
    
    string — The disposition set's name.
- dispositions
  
  array — Outbound bounded dispositions.
  
  Items:
  - disposition_id
    
    string — The disposition's ID.
  - disposition_name
    
    string — The disposition's name.
- enable_disposition
  
  boolean — Whether to enable outbound disposition.
- queue_disposition_type
  
  integer — Type of outbound disposition. 0 - Mandatory, 1 - Optional.
outbound_launch_url_info

object — Outbound launch URL configurations.
- config
  
  array — Configurations of launching URL and methods to launch.
  
  Items:
  - launch_trigger
    
    string, possible values: "initiated", "connected", "ended" — Methods to launch URL.
  - url
    
    string — URL to be launched.
- enable_launch_url
  
  boolean — Whether to enable outbound launch URL section.
outbound_settings

object — Queue configurations for outbound calls.
- enable_outbound_calls
  
  boolean — Whether to enable outbound call.
- outbound_default_disposition_id
  
  string — Outbound default disposition ID.
- outbound_disposition_required
  
  boolean — Whether an outbound disposition is required.
- outbound_holding_media_id
  
  string — Outbound holding media asset ID.
- outbound_labels
  
  object — Set up the talking duration for brief outbound engagements, labeled in reports as **short calls**, which also sets the duration for long calls and hang-up calls. Short calls - Select minimum and maximum talking duration of short calls using the `outbound_call_duration_lower_threshold` and `outbound_call_duration_upper_threshold` values. Long calls - Over 2 minutes. Hang-up calls - Under 10 seconds.
  - outbound_call_duration_lower_threshold
    
    integer — Minimum talking duration for brief outbound engagements, in seconds.
  - outbound_call_duration_upper_threshold
    
    integer — Maximum talking duration for brief outbound engagements, inseconds.
- outbound_launch_url_info
  
  object
  - config
    
    array
    
    Items:
    - launch_trigger
      
      string, possible values: "initiated", "connected", "ended" — Methods to launch URL.
    - url
      
      string — URL to be launched.
  - enable_launch_url
    
    boolean — Whether to enable outbound launch URL section.
- outbound_notes_asset_id
  
  string — Outbound notes audio asset ID.
- outbound_transferring_media_id
  
  string — Outbound transferring media asset ID.
- outbound_wrap_up_after_transfer
  
  boolean — Whether to enable wrap up after outbound transfer.
- outbound_wrap_up_expiration
  
  boolean — Auto-close outbound engagements at the end of wrap-up duration.
- outbound_wrap_up_time
  
  integer — Outbound wrap up time, in seconds.
- queue_caller_ids
  
  array — The queue's outbound caller ID number list. A caller ID number is what your customers will see on their phone when agents and supervisors reach out to them. Assign numbers that users can update from the default caller ID when they call consumers. Only for voice queues. When a voice queue is configured with caller ID(s), the list will populate with phone numbers.
  
  Items:
  
  string — Caller ID number, in E.164 format.
overflow_to_cc_queue_id

string — The Contact Center queue ID to receive the overflow. Only one of these overflow fields can be updated each time, either `overflow_to_goodbye_message`, `overflow_to_cc_queue_id`, `overflow_to_flow_id`, or `overflow_to_inbox_id`. Updating an overflow field will clear out the other overflow fields.
overflow_to_flow_id

string — The flow ID to receive the overflow.
overflow_to_goodbye_message

boolean — Reply goodbye message, then disconnect.
overflow_to_goodbye_message_asset_id

string — Reply goodbye message. Use asset instead of system default audio.
overflow_to_inbox_id

string — The voicemail inbox ID to receive the overflow.
overflow_to_queue_id

string — The queue ID to receive the overflow.
overflow_type

integer, possible values: 0, 1, 2, 3 — Type of overflow. 0 - Reply goodbye message, then disconnect. 1 - Route to queue. 2 - Leave email. 3 - Route to flow.
queue_description

string — The task queue's description.
queue_id

string — The task queue's ID.
queue_name

string — The task queue's name.
queue_waiting_experience

object — Queue configured waiting experience.
- connecting_music_asset_id
  
  string — Connecting music audio ID.
- connecting_music_filename
  
  string — Connecting music audio file name.
- connecting_music_url
  
  string — Connecting music audio file URL.
- default_connecting_music_file_id
  
  string — Default connecting music file ID.
- default_connecting_music_name
  
  string — Default connecting music file name.
- default_connecting_music_url
  
  string — Default connecting music file URL.
- default_hold_music_file_id
  
  string — Default holding music file ID.
- default_hold_music_name
  
  string — Default holding music file name.
- default_hold_music_url
  
  string — Default holding music file URL.
- default_transfer_music_url
  
  string — Default transferring music file URL.
- holding_music_asset_id
  
  string — Holding music audio asset ID.
- holding_music_filename
  
  string — Holding music audio file name.
- holding_music_url
  
  string — Holding music audio file URL.
- transfer_music_asset_id
  
  string — Transferring music audio asset ID.
- transfer_music_filename
  
  string — Transferring music audio file name.
- transfer_music_url
  
  string — Transferring music audio file URL.
recording_storage_location

string, possible values: "us", "au", "br", "ca", "de", "jp", "sg" — Determine where to store the recording. - us - United States - au - Australia - br - Brazil - ca - Canada - de - Germany - jp - Japan - sg - Singapore Supported channel types - voice, video.
scheduled_callback_settings

object — Queue configurations for callback and greeting message.
- consumer_inquiry_option
  
  string — The unique keyword that consumers can choose to identify this queue.
- enable_scheduled_callback
  
  boolean — Whether to enable scheduled callback.
- greeting_message
  
  object — The greeting message.
  - custom_media_asset_id
    
    string — Audio asset ID for custom media.
  - language_code
    
    string — The default message's language.
  - message_text
    
    string — Greeting message free text.
  - voice_id
    
    string, possible values: "Danielle", "Gregory", "Ivy", "Joanna", "Joey", "Justin", "Kendra", "Kevin", "Kimberly", "Matthew", "Ruth", "Salli", "Stephen" — The TTS service's voice ID to generate audio for the greeting message.
service_level_exclude_abandoned_quit_engagements

boolean — Choose to include quit engagements in service level metrics. Channel types - chat, in_app_chat, sms
service_level_exclude_long_abandoned_calls

boolean — Choose to include long abandoned calls in service level metrics. Channel types - voice, video.
service_level_exclude_short_abandoned_calls

boolean — Choose to include short abandoned calls in service level metrics. Channel types - voice, video.
service_level_target_in_percentage

integer — The service-level target as the benchmark to refer to in reports.
service_level_threshold_in_seconds

integer — Agents' first message speed for all engagements.
short_abandon

object — Information about the task queue's [**Short Abandon**](https://support.zoom.us/hc/en-us/articles/4469989300493-Changing-queue-settings#:~:text=for%20this%20queue.-,Short%20Abandon,-(only%20available%20if) settings. This setting is only available if the queue's channel type is a Zoom Room, voice, or video.
- enable
  
  boolean — Whether the **Enable short abandon** setting is enabled.
- threshold
  
  integer — The task queue's short abandon threshold, in seconds.
teams

array — Teams assigned to the Contact Center queue.

Items:
- team_id
  
  string — The team's unique identifier.
- team_name
  
  string — The team's name.
transferring_media_filename

string — **Deprecated** See `queue_waiting_experience` object. File name of the media to use while users are being transferred. Channel type: voice.
transferring_media_id

string — **Deprecated** See `queue_waiting_experience` object. Media ID to use while users are being transferred. Channel type: voice.
waiting_room_id

string — ID of the waiting room for users. Channel type - video.
waiting_room_name

string — Name of the user's waiting room. Channel type - video.
wrap_up_after_transfer

boolean — Whether to enable wrap up transfer.
wrap_up_expiration

boolean — Auto-close engagements at the end of wrap-up duration. Channel type - voice, video.
wrap_up_time

integer — The task queue's wrap up time, in seconds.

Example:

{
  "cc_queue_id": "xqJE_cgERLyAJHYYL5LLeg",
  "queue_name": "queue_661c6e4b-89fc-4b0d-9978-c7394725462",
  "queue_description": "This is a task queue.",
  "dispositions_count": 1,
  "disposition_sets_count": 1,
  "channel": "voice",
  "max_wait_time": 50,
  "wrap_up_time": 50,
  "max_engagement_in_queue": 50,
  "short_abandon": {
    "enable": false,
    "threshold": 5
  },
  "distribution_type": 1,
  "distribution_duration_in_seconds": 30,
  "waiting_room_name": "User Waiting Room",
  "waiting_room_id": "vPtSZOzBSLWMiorssYWTZw",
  "message_accept": "manual",
  "wrap_up_expiration": true,
  "overflow_type": 0,
  "overflow_to_goodbye_message": true,
  "overflow_to_goodbye_message_asset_id": "9gp4iyqUR_qq8tYpWw1EKg",
  "overflow_to_cc_queue_id": "m8IhNvUyTUmx7Jm8h5ZvLQ",
  "overflow_to_flow_id": "psjHGHrHQbaX8Zk7ldc81Q",
  "overflow_to_inbox_id": "cMH8RJA0QsyJBCWIFbWfBQ",
  "auto_close_message_enabled": true,
  "auto_close_timeout": 10,
  "auto_close_alert_message_enabled": true,
  "auto_close_alert_message_time": 10,
  "recording_storage_location": "us",
  "service_level_threshold_in_seconds": 15,
  "service_level_exclude_short_abandoned_calls": true,
  "service_level_exclude_long_abandoned_calls": true,
  "service_level_exclude_abandoned_quit_engagements": true,
  "service_level_target_in_percentage": 80,
  "agent_routing_profile_id": "fgjdkhgfieryt7465435kjhdkhg",
  "agent_routing_profile_name": "My agent routing profile",
  "consumer_routing_profile_id": "fgjdkhgfieryt7465435kjhdkhg",
  "consumer_routing_profile_name": "My Consumer Routing Profile",
  "caller_ids": [
    "+14155552671"
  ],
  "teams": [
    {
      "team_id": "qeYjXoDO3_eV1QmTpj63Pz",
      "team_name": "Sales Team"
    }
  ],
  "engagement_acceptance": {
    "acceptance_type": "manual",
    "enable_agent_alert_tone": true,
    "enable_agent_whisper_announcement": false,
    "agent_whisper_announcement_asset_id": "9gp4iyqUR_qq8tYpWw1EKg",
    "enable_agent_greeting": false,
    "agent_greeting_asset_id": "9gp4iyqUR_qq8tYpWw1EKg",
    "greeting_filename": "greeting.mp3",
    "whisper_filename": "whisper.mp3"
  },
  "inbound_launch_url_info": {
    "config": [
      {
        "launch_trigger": "ringing",
        "launch_url": "https://www.example.com"
      }
    ],
    "enable_launch_url": true
  },
  "outbound_launch_url_info": {
    "config": [
      {
        "launch_trigger": "connected",
        "url": "https://www.example.com"
      }
    ],
    "enable_launch_url": true
  },
  "queue_waiting_experience": {
    "default_connecting_music_file_id": "feca393267648418947gswurw70b4e43",
    "default_connecting_music_name": "Hold the Phone_Mastered",
    "default_connecting_music_url": "https://device.s3.example.com/default_wait/Hold_the_Phone_Mastered.mp3",
    "connecting_music_asset_id": "dORBRSTxTN6B0vLJ37Kvnw",
    "connecting_music_filename": "Connecting Tone",
    "connecting_music_url": "https://example.com/connecting.mp3",
    "default_transfer_music_url": "https://example.com/gocci/ringtone_music.wav",
    "transfer_music_asset_id": "dORBRSTxTN6B0vLJ37Kvnw",
    "transfer_music_filename": "Transferring Tone",
    "transfer_music_url": "https://example.com/transferring.mp3",
    "default_hold_music_file_id": "feca3932676484heud123568970b4e42",
    "default_hold_music_name": "Calming Hold_Mastered",
    "default_hold_music_url": "https://example.com/default_wait/Calming_Hold_Mastered.mp3",
    "holding_music_asset_id": "dORBRSTxTN6B0vLJ37Kvnw",
    "holding_music_filename": "Holding Tone",
    "holding_music_url": "https://example.com/holding.mp3"
  },
  "inbound_dispositions": {
    "enable_disposition": true,
    "queue_disposition_type": 0,
    "dispositions": [
      {
        "disposition_id": "2UiwcOPiS8y1XiQMKYFRfw",
        "disposition_name": "test disposition 10"
      }
    ],
    "disposition_sets": [
      {
        "disposition_set_id": "Q5cXMppKQgm0W_bV72Wrgw",
        "disposition_set_name": "test disposition set 1"
      }
    ],
    "default_disposition_id": "2UiwcOPiS8y1XiQMKYFRfw",
    "default_disposition_name": "test disposition 10"
  },
  "outbound_dispositions": {
    "enable_disposition": true,
    "queue_disposition_type": 0,
    "dispositions": [
      {
        "disposition_id": "2UiwcOPiS8y1XiQMKYFRfw",
        "disposition_name": "test disposition 10"
      }
    ],
    "disposition_sets": [
      {
        "disposition_set_id": "Q5cXMppKQgm0W_bV72Wrgw",
        "disposition_set_name": "test disposition set 1"
      }
    ],
    "default_disposition_id": "2UiwcOPiS8y1XiQMKYFRfw",
    "default_disposition_name": "test disposition 10"
  },
  "wrap_up_after_transfer": false,
  "engagement_distribution": "simultaneous",
  "outbound_settings": {
    "enable_outbound_calls": true,
    "queue_caller_ids": [
      "+14155552671"
    ],
    "outbound_launch_url_info": {
      "enable_launch_url": true,
      "config": [
        {
          "launch_trigger": "connected",
          "url": "https://www.example.com"
        }
      ]
    },
    "outbound_labels": {
      "outbound_call_duration_lower_threshold": 19,
      "outbound_call_duration_upper_threshold": 300
    },
    "outbound_transferring_media_id": "transferringAudioMp3",
    "outbound_holding_media_id": "holdingAudioMp3",
    "outbound_notes_asset_id": "notesAsset123",
    "outbound_disposition_required": true,
    "outbound_default_disposition_id": "2UiwcOPiS8y1XiQMKYFRfw",
    "outbound_wrap_up_time": 60,
    "outbound_wrap_up_expiration": true,
    "outbound_wrap_up_after_transfer": false
  },
  "scheduled_callback_settings": {
    "enable_scheduled_callback": true,
    "consumer_inquiry_option": "hello 100",
    "greeting_message": {
      "custom_media_asset_id": "9gp4iyqUR_qq8tYpWw1EKg",
      "language_code": "English (US)",
      "voice_id": "Joanna",
      "message_text": "You will be connected to the next available agent in a short moment."
    }
  }
}

Status: 400 HTTP Status Code: `400` Bad Request Error Code: `1244` More than one matching queue found.

Status: 401 HTTP Status Code: `401` Unauthorized Error Code: `124` Invalid access token. Error Code: `124` Access token has expired. Error Code: `1002` The user associated with this access token was not found or is invalid.

Status: 403 HTTP Status Code: `403` Forbidden Error Code: `1021` User account is deactivated. Error Code: `1022` User does not have a Contact Center license. Error Code: `9001` The Contact Center user associated with this bearer token is missing privileges on their role required to operate this request.

Status: 404 HTTP Status Code: `404` Not Found Error Code: `1201` Queue does not exist: $queueId.

Status: 429 HTTP Status Code: `429` Too Many Requests. For more information, see [rate limits](/docs/api/rate-limits/). Error Code: `4001` You have reached the maximum per-second rate limit for this API. Try again later.

Delete a queue

Method: DELETE
Path: /contact_center/queues/{queueId}
Tags: Queues

Delete a specified queue.

Scopes: contact_center_queue:write:admin

Granular Scopes: contact_center:delete:queue:admin

Rate Limit Label: LIGHT

Responses

Status: 204 HTTP Status Code: `204` Queue deleted.

Status: 400 HTTP Status Code: `400` Bad Request Error Code: `1244` More than one matching queue found.

Status: 401 HTTP Status Code: `401` Unauthorized Error Code: `124` Invalid access token. Error Code: `124` Access token has expired. Error Code: `1002` The user associated with this access token was not found or is invalid.

Status: 403 HTTP Status Code: `403` Forbidden Error Code: `1021` User account is deactivated. Error Code: `1022` User does not have a Contact Center license. Error Code: `9001` The Contact Center user associated with this bearer token is missing privileges on their role required to operate this request.

Status: 404 HTTP Status Code: `404` Not Found Error Code: `1201` Queue does not exist: $queueId.

Status: 429 HTTP Status Code: `429` Too Many Requests. For more information, see [rate limits](/docs/api/rest/rate-limits/). Error Code: `4001` You have reached the maximum per-second rate limit for this API. Try again later.

Update a queue

Method: PATCH
Path: /contact_center/queues/{queueId}
Tags: Queues

Update a queue's settings.

Scopes: contact_center_queue:write:admin

Granular Scopes: contact_center:update:queue:admin

Rate Limit Label: LIGHT

Request Body

Content-Type: application/json

agent_routing_profile_id

string — The queue's agent routing profile ID. If this is empty, the agent routing profile will be removed.
agent_routing_settings

object — A routing profile to route the engagement to queue users, based on who has the corresponding skills.
- allow_agent_select_skill_for_transfer
  
  boolean — Agent routing to allow agent to specify skills during the transfer. This requires the routing profile enable 'Route engagement to last engaged agent first'.
- last_engaged_agent_data_from_queue_ids
  
  array — Last engaged agent data from the queue. Select queues that will be evaluated to determine the last engaged agent, based on maximum look-back period. Default to `All queues` if no select queue ID. To get the queue ID, use [**List Queues API**](/docs/api/contact-center/#tag/queues/get/contact_center/queues). **Channels** voice, video.
  
  Items:
  
  string — The queue ID.
- maximum_look_back_period
  
  integer — The timeframe for searching previous engagements with the consumer to determine the last agent, in minutes. **Channels** voice, video.
auto_close_alert_message

string — An alert message to web-chat users before auto-closing.
auto_close_alert_message_enabled

boolean — Send an alert message before auto-closing web chats. **Channels** messaging.
auto_close_alert_message_time

integer — How long, in minutes, before a warning is sent to the user. Must be less than or equal to `auto_close_timeout`.
auto_close_message

string — Auto-closed message to web-chat users.
auto_close_message_enabled

boolean — Send an auto-closed message for web chats. **Channels** messaging.
auto_close_timeout

integer — How long, in minutes, before the chat is auto-closed.
channel

string, possible values: "voice", "video", "messaging", "email", "work_item" — The Contact Center queue's channel.
channel_types

array — The task queue's channel types.

Items:

string, possible values: "voice", "chat", "sms", "video", "in_app_chat", "messaging", "work_item"
connecting_media_id

string, default: "Passing an empty string will set this option to the default media." — Media ID to use while users are being connected. **Channels** voice.
consumer_routing_profile_id

string — The queue's consumer routing profile ID.
default_disposition_id

string — When a queue disposition is required. Must assign a default disposition.
disposition_required

boolean — Whether a queue disposition is required. * `true` - mandatory * `false` - optional
distribution_duration_in_seconds

integer — The notify duration for each queue user, in seconds. The default on new queues is 30 seconds.
distribution_type

integer, possible values: 0, 1, 2, 3, 4, 5, 6, 7 — Distribute incoming engagements. **Allowed** * 0 - Longest Idle. This value is only supported if the channel types contain voice or video. * 1 - Sequential. This value is only supported if the channel types contain voice or video. * 2 - Rotating. This value is only supported if the channel types contain voice or video. * 3 - Simultaneous. This value is only supported if the channel types contain voice or video. * 4 - Most Available. This value is only supported if the channel is **messaging**. * 5 - Manual. This value is only supported if the channel types contain video. * 6 - Longest idle while ready. This value is only supported if the channel types contain voice or video. * 7 - Longest idle for this queue. This value is only supported if the channel types contain voice or video.
engagement_acceptance

object — Queue engagement acceptance configurations.
- acceptance_type
  
  string, possible values: "manual", "auto" — How to accept an engagement.
- agent_greeting_asset_id
  
  string — Play a greeting message chosen from the asset library. To find the asset ID, use the [**List Assets API**](/docs/api/contact-center/#tag/asset-library/get/contact_center/asset_library/assets). Required when 'enable_agent_greeting' is `true`.
- agent_whisper_announcement_asset_id
  
  string — Play a whisper announcement, chosen from the [**List Assets API**](/docs/api/contact-center/#tag/asset-library/get/contact_center/asset_library/assets), to the agent. Required when 'enable_agent_whisper_announcement' is `true`.
- enable_agent_alert_tone
  
  boolean — Whether to play an alert tone to the agent. Can only enable 'enable_agent_alert_tone' or 'enable_agent_whisper_announcement'. This setting is for engagement acceptance type set as `auto`.
- enable_agent_greeting
  
  boolean — Whether to enable playing a default agent greeting. This setting is for engagements whose acceptance type is set as `auto`.
- enable_agent_whisper_announcement
  
  boolean — Whether to play an announcement to the agent. Can only enable 'enable_agent_alert_tone' or 'enable_agent_whisper_announcement'. This setting is for engagement acceptance type set as `auto`.
holding_media_id

string, default: "Passing an empty string will set this option to the default media." — Media ID to use while users are on hold. **Channels** voice.
inbound_launch_url_info

object — Inbound launch URL configurations. The URL link launches for each engagement according to the selected trigger.
- config
  
  array — Configurations of launching URL and methods to launch.
  
  Items:
  - launch_trigger
    
    string, possible values: "ringing", "answered", "ended" — Methods to trigger the launch URL.
  - launch_url
    
    string — URL to be launched. Enter a URL beginning with `https://`.
- enable_launch_url
  
  boolean — Whether to enable inbound launch URL section.
max_engagement_in_queue

integer — The task queue's maximum engagement in queue.
max_wait_time

integer — The task queue's maximum wait time, in seconds.
message_accept

string, possible values: "manual", "auto" — Option to accept a message manually or automatically. **Channels** messaging.
notes_asset_id

string — Provide a template from the asset library for agents to follow when writing notes. To find the asset ID, use the [**List Assets API**](/docs/api/contact-center/#tag/asset-library/get/contact_center/asset_library/assets).
outbound_settings

object — Queue configurations for outbound settings.
- enable_outbound_calls
  
  boolean — Whether to enable outbound call.
- outbound_default_disposition_id
  
  string — When a queue disposition is required. Must assign a default disposition.
- outbound_disposition_required
  
  boolean — Whether a queue disposition is required. * `true` - mandatory * `false` - optional
- outbound_holding_media_id
  
  string, default: "Passing an empty string will set this option to the default media." — Media ID, chosen from the asset library, to use while users are on hold. To find the asset ID, use the [**List Assets API**](/docs/api/contact-center/#tag/asset-library/get/contact_center/asset_library/assets). **Channels:** voice
- outbound_labels
  
  object — The talking duration for brief outbound engagements, labeled in reports as short calls. This also sets the duration for long calls and hang-up calls.
  - outbound_call_duration_lower_threshold
    
    integer — Minimum talking duration for brief outbound engagements, in seconds.
  - outbound_call_duration_upper_threshold
    
    integer — Maximum talking duration for brief outbound engagements, in seconds.
- outbound_launch_url_info
  
  object — Outbound launch URL configurations.
  - config
    
    array — Configurations for launching a URL and methods to launch.
    
    Items:
    - launch_trigger
      
      string, possible values: "initiated", "connected", "ended" — Methods to launch a URL.
    - url
      
      string — URL to be launched. Enter a URL beginning with `https://`.
  - enable_launch_url
    
    boolean — Whether to enable the outbound launch URL section.
- outbound_notes_asset_id
  
  string — Provide a template, chosen from the asset library, for agents to follow when writing notes. To find the asset ID, use the [**List Assets API**](/docs/api/contact-center/#tag/asset-library/get/contact_center/asset_library/assets). **Channels:** voice, video, messaging
- outbound_transferring_media_id
  
  string, default: "Passing an empty string will set this option to the default media." — Media, chosen from the asset library, to use while users are being transferred. To find the asset ID, use the [**List Assets API**](/docs/api/contact-center/#tag/asset-library/get/contact_center/asset_library/assets). **Channels:** voice
- outbound_wrap_up_after_transfer
  
  boolean — Agents can wrap up when transferring internally or when a supervisor takes over from them. **Channels** voice, video.
- outbound_wrap_up_expiration
  
  boolean — Auto-close engagements at the end of wrap-up duration. **Channels** voice, video.
- outbound_wrap_up_time
  
  integer — The task queue's wrap up time, in seconds.
- queue_caller_ids
  
  array — What customers see on their phone when agents and supervisors reach out to them. Assign numbers that users can update from the default caller ID when they call consumers. Get a caller ID from [Get A Queue API](/docs/api/contact-center/#tag/queues/get/contact_center/queues/{queueId}).
  
  Items:
  
  string — What customers see on their phone when agents and supervisors reach out to them. Assign numbers that users can update from the default caller ID when they call consumers. Get a caller ID from [Get A Queue API](/docs/api/contact-center/#tag/queues/get/contact_center/queues/{queueId}).
overflow_to_cc_queue_id

string — The Contact Center queue ID to receive the overflow. Only one of these overflow fields can be updated each time, `overflow_to_goodbye_message`, `overflow_to_cc_queue_id`, `overflow_to_flow_id`, or `overflow_to_inbox_id`. Updating an overflow field will clear out the other overflow fields.
overflow_to_flow_id

string — The flow ID to receive the overflow. Get the flow ID from [**List Flows API**](/docs/api/contact-center/#tag/flows/get/contact_center/flows). Only one of these overflow fields can be updated each time, `overflow_to_goodbye_message`, `overflow_to_queue_id`, `overflow_to_flow_id`, or `overflow_to_inbox_id`. Updating an overflow field will clear out the other overflow fields.
overflow_to_goodbye_message

boolean — Reply goodbye message, then disconnect. Only one of these overflow fields can be updated each time, `overflow_to_goodbye_message`, `overflow_to_queue_id`, `overflow_to_flow_id`, or `overflow_to_inbox_id`. Updating an overflow field will clear out the other overflow fields.
overflow_to_goodbye_message_asset_id

string — Reply goodbye message choose from an asset. Asset ID refer to Asset Library OpenAPI. * [**Create Asset API**](/docs/api/contact-center/#tag/asset-library/post/contact_center/asset_library/assets) * [**List Assets API**](/docs/api/contact-center/#tag/asset-library/get/contact_center/asset_library/assets)
overflow_to_inbox_id

string — The voicemail inbox ID to receive the overflow. Get the inbox ID from [**List Inboxes API**](/docs/api/contact-center/#tag/inboxes/get/contact_center/inboxes). Only one of these overflow fields can be updated each time, `overflow_to_goodbye_message`, `overflow_to_queue_id`, `overflow_to_flow_id`, or `overflow_to_inbox_id`. Updating an overflow field will clear out the other overflow fields. **Channels:** voice
overflow_to_queue_id

string — The queue ID to receive the overflow. Only one of these overflow fields can be updated each time, `overflow_to_goodbye_message`, `overflow_to_queue_id`, `overflow_to_flow_id`, or `overflow_to_inbox_id`. Updating an overflow field will clear out the other overflow fields.
queue_description

string — The Contact Center queue description.
queue_name

string — The Contact Center queue name.
recording_storage_location

string, possible values: "us", "au", "br", "ca", "de", "jp", "sg" — Determine where to store the recording. - us - United States - au - Australia - br - Brazil - ca - Canada - de - Germany - jp - Japan - sg - Singapore **Channels** voice, video.
scheduled_callback_settings

object — Queue configurations for the scheduled callback.
- consumer_inquiry_option
  
  string — The unique keyword that consumers can choose to identify this queue. This keyword displays to consumers as an inquiry option when they schedule callbacks.
- enable_scheduled_callback
  
  boolean — Whether to enable scheduled callbacks. When 'enable_scheduled_callback' is `false`, the other settings under 'scheduled_callback_settings' will not take effect.
- greeting_message
  
  object — Message to play when consumers receive the callback. Choose customized media from `asset_library` and set 'custom_media_asset_id'. Alternately, set the 'message_text', 'language_code', and 'voice_id' together, then will play the message according to language and voice.
  - custom_media_asset_id
    
    string — The audio asset ID for a greeting message's custom media.
  - language_code
    
    string, possible values: "zh-CN", "zh-TW", "yue-CN", "cmn-CN", "da-DK", "nl-NL", "en-AU", "en-NZ", "en-GB", "en-US", "fr-CA", "fr-FR", "de-DE", "it-IT", "ja-JP", "ko-KR", "pl-PL", "pt-BR", "pt-PT", "ro-RO", "ru-RU", "es-ES", "es-MX", "es-US", "sv-SE", "tr-TR" — The default message's language (IETF language tag).
  - message_text
    
    string — Greeting message free text.
  - voice_id
    
    string, possible values: "Danielle", "Gregory", "Ivy", "Joanna", "Joey", "Justin", "Kendra", "Kevin", "Kimberly", "Matthew", "Ruth", "Salli", "Stephen" — The TTS service's voice ID to generate audio for the greeting message.
service_level_exclude_abandoned_quit_engagements

boolean — Whether to exclude quit engagements from service level metrics. **Channels** messaging.
service_level_exclude_long_abandoned_calls

boolean — Whether to exclude long abandoned calls from service level metrics. **Channels** voice, video.
service_level_exclude_overflow_engagements

boolean — Whether to exclude overflow engagements from service level metrics. **Channels** email.
service_level_exclude_short_abandoned_calls

boolean — Whether to exclude short abandoned calls from service level metrics. **Channels** voice, video.
service_level_target_in_percentage

integer — The service-level target as the benchmark to refer to in reports.
service_level_threshold_in_seconds

integer — First message speed by agents for all engagements.
short_abandon

object — Information about the task queue's [**Short Abandon**](https://support.zoom.us/hc/en-us/articles/4469989300493-Changing-queue-settings) settings. **Channels** voice, video.
- enable
  
  boolean — Whether to enable the **Short Abandon** setting.
- threshold
  
  integer — The task queue's **Short Abandon** threshold, in seconds.
transferring_media_id

string, default: "Passing an empty string will set this option to the default media." — Media ID to use while users are being transferred. **Channels** voice.
video_callback_settings

object — Video callback settings. **Channels** video.
- callback_cancel_email_body
  
  string — Email body for callback cancellation.
- callback_cancel_email_subject
  
  string — Email subject for callback cancellation.
- callback_cancel_sms_text
  
  string — SMS text for callback cancellation.
- callback_offer_time
  
  array — Specific days and times when callbacks can be offered. Required when `enable_callback_offter_time` is `true`.
  
  Items:
  - callback_offer_day
    
    string, possible values: "Mon", "Tue", "Wed", "Thu", "Fri", "Sat", "Sun" — Day of the week.
  - callback_offer_end_time
    
    string — End time in `HH:mm` format.
  - callback_offer_start_time
    
    string — Start time in `HH:mm` format.
- callback_return_day
  
  array — Specific days and times when consumers can return callbacks. Required when `enable_callback_return_time` is `true`.
  
  Items:
  - callback_return_day
    
    string, possible values: "Mon", "Tue", "Wed", "Thu", "Fri", "Sat", "Sun" — Day of the week.
  - callback_return_end_time
    
    string — End time in `HH:mm` format.
  - callback_return_start_time
    
    string — Start time in `HH:mm` format.
- callback_return_timezone_id
  
  string — Timezone ID for callback return times. Required when `enable_callback_return_time` is `true`.
- callback_timeout
  
  integer — Callback timeout, in minutes. Maximum is 14 days.
- callback_url_expiration
  
  integer — Callback URL expiration time, in minutes.
- enable_callback_cancel_message
  
  boolean — Whether to enable callback cancellation email messages.
- enable_callback_cancel_sms_message
  
  boolean — Whether to enable callback cancellation SMS messages.
- enable_callback_offer_time
  
  boolean — Whether to enable specific callback offer times. When `true`, `callback_offer_time` is required.
- enable_callback_offter_time
  
  boolean — **Deprecated.** Use `enable_callback_offer_time` instead. Whether to enable specific callback offer times. When `true`, `callback_offer_time` is required.
- enable_callback_return_time
  
  boolean — Whether to enable specific callback return times. When `true`, `callback_return_timezone_id` and `callback_return_day` are required.
- enable_mobile_notification
  
  boolean — Whether to enable mobile notifications for callbacks.
- enable_resend_callback_url
  
  boolean — Whether to enable resending the callback URL.
- enable_video_callback
  
  boolean — Whether to enable video callbacks.
- resend_callback_url_time
  
  string, possible values: "60", "90", "120" — **Deprecated** use `resend_callback_url_time_in_seconds` instead. Time interval for resending the callback URL, in seconds. If both this and the `resend_callback_url_time_in_seconds` field are submitted, then `resend_callback_url_time_in_seconds` field takes precedence.
- resend_callback_url_time_in_seconds
  
  integer, possible values: 60, 90, 120 — Time interval for resending the callback URL, in seconds. Valid values are 60, 90, or 120. If both this and the deprecated `resend_callback_url_time` field are submitted, then this field takes precedence.
- time_to_offer_callback
  
  integer — Time to offer callback to consumers, in minutes. Must be in 5-minute intervals.
waiting_room_id

string — The users' waiting room ID. **Channels** video.
wrap_up_after_transfer

boolean — Add wrap-up time after transferring an engagement.
wrap_up_expiration

boolean — Auto-close engagements at the end of wrap-up duration. **Channels** voice, video.
wrap_up_time

integer — The task queue's wrap up time, in seconds.

Example:

{
  "queue_name": "Voice - Customer Support",
  "queue_description": "Agents assigned to this queue handle Customer Support voice calls.",
  "max_wait_time": 50,
  "wrap_up_time": 50,
  "max_engagement_in_queue": 50,
  "short_abandon": {
    "enable": false,
    "threshold": 5
  },
  "channel": "voice",
  "distribution_type": 1,
  "distribution_duration_in_seconds": 30,
  "connecting_media_id": "connectingAudioMp3",
  "transferring_media_id": "transferringAudioMp3",
  "holding_media_id": "holdingAudioMp3",
  "waiting_room_id": "vPtSZOzBSLWMiorssYWTZw",
  "message_accept": "manual",
  "wrap_up_expiration": true,
  "wrap_up_after_transfer": true,
  "overflow_to_goodbye_message": true,
  "overflow_to_cc_queue_id": "m8IhNvUyTUmx7Jm8h5ZvLQ",
  "overflow_to_flow_id": "psjHGHrHQbaX8Zk7ldc81Q",
  "overflow_to_inbox_id": "cMH8RJA0QsyJBCWIFbWfBQ",
  "overflow_to_goodbye_message_asset_id": "dORBRSTxTN6B0vLJ37Kvnw",
  "auto_close_message": "This chat has been auto-closed due to inactivity.",
  "auto_close_message_enabled": true,
  "auto_close_timeout": 10,
  "auto_close_alert_message": "Chat will auto-close soon if you don't reply",
  "auto_close_alert_message_enabled": true,
  "auto_close_alert_message_time": 10,
  "recording_storage_location": "us",
  "service_level_threshold_in_seconds": 15,
  "service_level_exclude_short_abandoned_calls": true,
  "service_level_exclude_long_abandoned_calls": true,
  "service_level_exclude_abandoned_quit_engagements": true,
  "service_level_exclude_overflow_engagements": true,
  "service_level_target_in_percentage": 80,
  "agent_routing_profile_id": "fgjdkhgfieryt7465435kjhdkhg",
  "agent_routing_settings": {
    "allow_agent_select_skill_for_transfer": true,
    "maximum_look_back_period": 30,
    "last_engaged_agent_data_from_queue_ids": [
      "BxTw_zCQTVO_kGOJh6-vkg"
    ]
  },
  "consumer_routing_profile_id": "fgjdkhgfieryt7465435kjhdkhg",
  "engagement_acceptance": {
    "acceptance_type": "manual",
    "enable_agent_alert_tone": true,
    "enable_agent_whisper_announcement": true,
    "agent_whisper_announcement_asset_id": "dORBRSTxTN6B0vLJ37Kvnw",
    "enable_agent_greeting": true,
    "agent_greeting_asset_id": "dORBRSTxTN6B0vLJ37Kvnw"
  },
  "inbound_launch_url_info": {
    "config": [
      {
        "launch_trigger": "ringing",
        "launch_url": "https://www.example.com"
      }
    ],
    "enable_launch_url": true
  },
  "notes_asset_id": "dORBRSTxTN6B0vLJ37Kvnw",
  "disposition_required": true,
  "default_disposition_id": "dORBRSTxTN6B0vLJ37Kvnw",
  "outbound_settings": {
    "enable_outbound_calls": true,
    "queue_caller_ids": [
      "jJ2QCIFaS9eLqNi9vF3WPg"
    ],
    "outbound_launch_url_info": {
      "config": [
        {
          "launch_trigger": "connected",
          "url": "https://www.example.com"
        }
      ],
      "enable_launch_url": true
    },
    "outbound_labels": {
      "outbound_call_duration_lower_threshold": 3,
      "outbound_call_duration_upper_threshold": 19
    },
    "outbound_transferring_media_id": "transferringAudioMp3",
    "outbound_holding_media_id": "holdingAudioMp3",
    "outbound_notes_asset_id": "dORBRSTxTN6B0vLJ37Kvnw",
    "outbound_disposition_required": true,
    "outbound_default_disposition_id": "dORBRSTxTN6B0vLJ37Kvnw",
    "outbound_wrap_up_time": 50,
    "outbound_wrap_up_expiration": true,
    "outbound_wrap_up_after_transfer": true
  },
  "scheduled_callback_settings": {
    "enable_scheduled_callback": false,
    "consumer_inquiry_option": "Tech Support 1",
    "greeting_message": {
      "custom_media_asset_id": "9gp4iyqUR_qq8tYpWw1EKg",
      "language_code": "en-US",
      "voice_id": "Joanna",
      "message_text": "You will be connected to the next available agent in a short moment."
    }
  },
  "video_callback_settings": {
    "enable_video_callback": true,
    "time_to_offer_callback": 10,
    "callback_url_expiration": 3,
    "enable_resend_callback_url": true,
    "resend_callback_url_time_in_seconds": 60,
    "enable_mobile_notification": true,
    "callback_timeout": 1440,
    "enable_callback_cancel_message": true,
    "callback_cancel_email_subject": "Your callback has been cancelled",
    "callback_cancel_email_body": "We regret to inform you that your scheduled callback has been cancelled.",
    "enable_callback_cancel_sms_message": true,
    "callback_cancel_sms_text": "Your callback has been cancelled.",
    "enable_callback_offer_time": true,
    "callback_offer_time": [
      {
        "callback_offer_day": "Mon",
        "callback_offer_start_time": "09:00",
        "callback_offer_end_time": "17:00"
      }
    ],
    "enable_callback_return_time": true,
    "callback_return_timezone_id": "America/Los_Angeles",
    "callback_return_day": [
      {
        "callback_return_day": "Mon",
        "callback_return_start_time": "09:00",
        "callback_return_end_time": "17:00"
      }
    ]
  }
}

Responses

Status: 204 HTTP Status Code: `204` Queue updated.

Status: 400 HTTP Status Code: `400` Bad Request Error Code: `1205` Queue channel type is invalid: {value}. Error Code: `1206` `video_callback_settings` can only be configured for video queues. Error Code: `1220` Invalid engagement acceptance type. Error Code: `1221` Cannot enable both `agent_alert_tone` and `agent_whisper_announcement`. Error Code: `1222` `agent_whisper_announcement_asset_id` is required when `enable_agent_whisper_announcement` is true. Error Code: `1223` `agent_greeting_asset_id` is required when `enable_agent_greeting` is true. Error Code: `1225` Invalid launch URL trigger specified. Error Code: `1233` Launch URL must start with `https://`. Error Code: `1234` Launch URL config is required when launch URL is enabled. Error Code: `1235` `default_disposition_id` is required when `disposition_required` is true. Error Code: `1236` `outbound_default_disposition_id` is required when `outbound_disposition_required` is true. Error Code: `1240` Agent routing profile is required. Error Code: `1241` Last Called Agent must be enabled in the agent routing profile. Error Code: `1206` Auto-close warning time must be less than or equal to the auto-close time. Error Code: `1237` Outbound launch URL config is required when launch URL is enabled. Error Code: `1238` Invalid outbound launch URL trigger specified. Error Code: `1239` Outbound launch URL must start with `https://`. Error Code: `1250` time_to_offer_callback must be in 5-minute intervals (5, 10, 15, 20, 25, 30, 35, 40). Error Code: `1251` callback_offer_time is required when enable_callback_offer_time is true. Error Code: `1252` callback_return_timezone_id is required when enable_callback_return_time is true. Error Code: `1253` callback_return_day is required when enable_callback_return_time is true. Error Code: `1244` More than one matching queue found.

Status: 401 HTTP Status Code: `401` Unauthorized Error Code: `124` Invalid access token. Error Code: `124` Access token has expired. Error Code: `1002` The user associated with this access token was not found or is invalid.

Status: 403 HTTP Status Code: `403` Forbidden Error Code: `1021` User account is deactivated. Error Code: `1022` User does not have a Contact Center license. Error Code: `9001` The Contact Center user associated with this bearer token is missing privileges on their role required to operate this request.

Status: 404 HTTP Status Code: `404` Not Found Error Code: `1201` Queue does not exist: {queueId}. Error Code: `1210` Agent routing profile does not exist. Error Code: `1900` Consumer routing profile not found. Error Code: `2301` Asset not found. Error Code: `2401` Disposition not found: {dispositionId}. Error Code: `2405` Disposition is not assigned to queue.

Status: 429 HTTP Status Code: `429` Too Many Requests. For more information, see [rate limits](https://developers.zoom.us/docs/api/rate-limits/). Error Code: `4001` You have reached the maximum per-second rate limit for this API. Try again later.

List queue agents

Method: GET
Path: /contact_center/queues/{queueId}/agents
Tags: Queues

Retrieve the list of Contact Center users assigned to a queue, including their agent persona assignments for that queue.

Scopes: contact_center_queue:read:admin

Granular Scopes: contact_center:read:list_queue_agents:admin

Rate Limit Label: MEDIUM

Responses

Status: 200 HTTP Status Code: `200` Queue agents list returned.

Content-Type: application/json

agents

array — Information about the agents.

Items:
- cc_user_id
  
  string — The Contact Center user identifier.
- display_name
  
  string — The user's display name.
- opt_in_out_status
  
  integer, possible values: 0, 1, 2 — Opt out status. `0` - Opted in by agent himself or supervisor. `1` - Opted out by supervisor or admin. `2` - Opted out by agent himself.
- role_id
  
  string — The user's Contact Center role identifier.
- role_name
  
  string — The user's Contact Center role name.
- status_id
  
  string — The user's availability status ID.
- status_name
  
  string, possible values: "Offline", "Ready", "Not Ready", "Occupied" — The user's [availability status](https://support.zoom.us/hc/en-us/articles/4470584918541-Setting-availability-status). * Offline * Ready * Not Ready * Occupied * A custom user status, such as **Lunch**.
- teams
  
  array — The teams the user is assigned to.
  
  Items:
  - team_id
    
    string — The ID of the team.
  - team_name
    
    string — The display name of the team.
- user_access
  
  string, possible values: "active", "inactive" — The user's access status. * `active` - The user's role permissions allow them to access the Contact Center. * `inactive` - The user cannot access the Contact Center.
- user_email
  
  string, format: email — The user's email address.
- user_id
  
  string — The Meetings user identifier.
next_page_token

string — Use the next page token to paginate through large result sets. A next page token is returned whenever the set of available results exceeds the current page size. This token's expiration period is 15 minutes.
page_size

integer, default: 30 — The number of records returned within a single API call.
total_records

integer — The total number of all records available across pages.

Example:

{
  "next_page_token": "R4aF9Oj0fVM2hhezJTEmSKaBSkfesDwGy42",
  "page_size": 30,
  "total_records": 10,
  "agents": [
    {
      "user_id": "IGTRVt3gQ2i-WjoUIjeZxw",
      "cc_user_id": "hKuMAiDdRlSwMkBxR5we7g",
      "display_name": "Jane Doe",
      "user_email": "jchill@example.com",
      "role_id": "0TFVsJqNS82CwkQJLqj1zA",
      "role_name": "Admin",
      "status_id": "1",
      "status_name": "Offline",
      "user_access": "active",
      "opt_in_out_status": 0,
      "teams": [
        {
          "team_id": "qlU902FoTD-dFi9QnCdZhw",
          "team_name": "Support Team"
        }
      ]
    }
  ]
}

Status: 400 HTTP Status Code: `400` Bad Request Error Code: `1244` More than one matching queue found.

Status: 401 HTTP Status Code: `401` Unauthorized Error Code: `124` Invalid access token. Error Code: `124` Access token has expired. Error Code: `1002` The user associated with this access token was not found or is invalid.

Status: 403 HTTP Status Code: `403` Forbidden Error Code: `1021` User account is deactivated. Error Code: `1022` User does not have a Contact Center license. Error Code: `9001` The Contact Center user associated with this bearer token is missing privileges on their role required to operate this request.

Status: 404 HTTP Status Code: `404` Not Found Error Code: `1201` Queue does not exist: $queueId.

Status: 429 HTTP Status Code: `429` Too Many Requests. For more information, see [rate limits](https://developers.zoom.us/docs/api/rate-limits/). Error Code: `4001` You have reached the maximum per-second rate limit for this API. Try again later.

Assign queue agents

Method: POST
Path: /contact_center/queues/{queueId}/agents
Tags: Queues

Assign users to a Contact Center queue as agent persona.

The API response will contain only those users confirmed to have been assigned to the queue, and ignores any unrecognized user ID or users already assigned to the queue.

Scopes: contact_center_queue:write:admin

Granular Scopes: contact_center:write:queue_agent:admin

Rate Limit Label: MEDIUM

Request Body

Content-Type: application/json

user_ids

array — The user identifiers. The values can be a mix of email addresses, Meetings user IDs, or Contact Center user IDs.

Items:

string

Example:

{
  "user_ids": [
    "ukAAkZKfROKMSw1bj_RDFQ"
  ]
}

Responses

Status: 201 HTTP Status Code: `201` Successfully assigned queue agents. Can be empty.

Content-Type: application/json

agents

array — Information about the agents.

Items:
- cc_user_id
  
  string — The Contact Center user identifier.
- display_name
  
  string — The user's display name.
- opt_in_out_status
  
  integer, possible values: 0, 1, 2 — Opt out status. `0` - Opted in by agent himself or supervisor. `1` - Opted out by supervisor or admin. `2` - Opted out by agent himself.
- role_id
  
  string — The user's Contact Center role identifier.
- role_name
  
  string — The user's Contact Center role name.
- status_id
  
  string — The user's availability status ID.
- status_name
  
  string, possible values: "Offline", "Ready", "Not Ready", "Occupied" — The user's [availability status](https://support.zoom.us/hc/en-us/articles/4470584918541-Setting-availability-status). * Offline * Ready * Not Ready * Occupied * A custom user status, such as Lunch.
- user_access
  
  string, possible values: "active", "inactive" — The user's access status. * `active` - The user's role permissions allow them to access the Contact Center. * `inactive` - The user cannot access the Contact Center.
- user_email
  
  string, format: email — The user's email address.
- user_id
  
  string — The Meetings user identifier.

Example:

{
  "agents": [
    {
      "user_id": "IGTRVt3gQ2i-WjoUIjeZxw",
      "cc_user_id": "hKuMAiDdRlSwMkBxR5we7g",
      "display_name": "Jane Doe",
      "user_email": "jchill@example.com",
      "role_id": "0TFVsJqNS82CwkQJLqj1zA",
      "role_name": "Admin",
      "status_id": "1",
      "status_name": "Offline",
      "user_access": "active",
      "opt_in_out_status": 0
    }
  ]
}

Status: 400 HTTP Status Code: `400` Bad Request Error Code: `300` Invalid field.

Status: 401 HTTP Status Code: `401` Unauthorized Error Code: `124` Invalid access token. Error Code: `124` Access token has expired. Error Code: `1002` The user associated with this access token was not found or is invalid.

Status: 403 HTTP Status Code: `403` Forbidden Error Code: `1021` User account is deactivated. Error Code: `1022` User does not have a Contact Center license. Error Code: `9001` The Contact Center user associated with this bearer token is missing privileges on their role required to operate this request.

Status: 404 HTTP Status Code: `404` Not Found Error Code: `1201` Queue does not exist: {queueId}.

Status: 429 HTTP Status Code: `429` Too Many Requests. For more information, see [rate limits](/docs/api/rate-limits/). Error Code: `4001` You have reached the maximum per-second rate limit for this API. Try again later.

Unassign a queue agent

Method: DELETE
Path: /contact_center/queues/{queueId}/agents/{userId}
Tags: Queues

Remove an agent from a Contact Center queue. The specified user will be unassigned from the queue and will no longer receive engagements routed through it. The user must be currently assigned as an agent to the queue.

Scopes: contact_center_queue:write:admin

Granular Scopes: contact_center:delete:queue_agent:admin

Rate Limit Label: LIGHT

Responses

Status: 204 HTTP Status Code: `204` Queue agent removed.

Status: 400 HTTP Status Code: `400` Bad Request Error Code: `300` Validation failed.

Status: 401 HTTP Status Code: `401` Unauthorized Error Code: `124` Invalid access token. Error Code: `124` Access token has expired. Error Code: `1002` The user associated with this access token was not found or is invalid.

Status: 403 HTTP Status Code: `403` Forbidden Error Code: `1021` User account is deactivated. Error Code: `1022` User does not have a Contact Center license. Error Code: `9001` The Contact Center user associated with this bearer token is missing privileges on their role required to operate this request.

Status: 404 HTTP Status Code: `404` Not Found Error Code: `1201` Queue does not exist: {queueId}. Error Code: `1001` User does not exist: {userId}.

Status: 429 HTTP Status Code: `429` Too Many Requests. For more information, see [rate limits](/docs/api/rate-limits/). Error Code: `4001` You have reached the maximum per-second rate limit for this API. Try again later.

Update a queue agent's opt-in/opt-out status

Method: PATCH
Path: /contact_center/queues/{queueId}/agents/{userId}
Tags: Queues

Updates the opt-in or opt-out status of an agent assigned to a Contact Center queue. Use this endpoint to control whether an agent receives engagements from the specified queue. Opting an agent out temporarily removes them from the queue's routing pool without removing their queue assignment.

Scopes: contact_center_queue:write:admin

Granular Scopes: contact_center:update:queue_agent:admin

Rate Limit Label: LIGHT

Request Body

Content-Type: application/json

opt_in_out_status (required)

integer, format: int32, possible values: 0, 1, 2 — Opt in/out status. `0` - Opted in. The agent is opted in and available to receive engagements from this queue. `1` - Opted out by supervisor or admin. A supervisor or administrator has opted out this agent from receiving engagements from this queue. `2` - Opted out by agent. The agent has opted themselves out from receiving engagements from this queue.

Example:

{
  "opt_in_out_status": 0
}

Responses

Status: 204 HTTP Status Code: `204` Queue agent updated.

Status: 400 HTTP Status Code: `400` Bad Request Error Code: `1010` The agent must be in available state (Ready) to opt-in for the queue. Error Code: `1011` The agent is not allowed to opt in or out of their assigned queues. Error Code: `300` Invalid field.

Status: 401 HTTP Status Code: `401` Unauthorized Error Code: `124` Invalid access token. Error Code: `124` Access token has expired. Error Code: `1002` The user associated with this access token was not found or is invalid.

Status: 403 HTTP Status Code: `403` Forbidden Error Code: `1021` User account is deactivated. Error Code: `1022` User does not have a Contact Center license. Error Code: `9001` The Contact Center user associated with this bearer token is missing privileges on their role required to operate this request.

Status: 404 HTTP Status Code: `404` Not Found Error Code: `1001` User does not exist: {userId}. Error Code: `1201` Queue does not exist: {queueId}.

Status: 429 HTTP Status Code: `429` Too Many Requests. For more information, see [rate limits](/docs/api/rest/rate-limits/). Error Code: `4001` You have reached the maximum per-second rate limit for this API. Try again later.

List queue dispositions

Method: GET
Path: /contact_center/queues/{queueId}/dispositions
Tags: Queues

Return a list of queue's dispositions.

Scopes: contact_center_queue:read:admin

Granular Scopes: contact_center:read:list_dispositions:admin

Rate Limit Label: MEDIUM

Responses

Status: 200 HTTP Status Code: `200` Queue dispositions list returned.

Content-Type: application/json

dispositions

array — Information about the task queue's dispositions.

Items:
- assign_type
  
  string, possible values: "inbound", "outbound", default: "inbound" — The disposition's assignment type.
- cc_queue_id
  
  string — The Contact Center queue's ID.
- disposition_description
  
  string — Information about the disposition.
- disposition_id
  
  string — The disposition's ID.
- disposition_name
  
  string — The disposition's name.
- last_modified_time
  
  string, format: date-time — The date and time when this data was last modified.
- modified_by
  
  string — The ID of the user that last modified this data.
- queue_name
  
  string — The Contact Center queue's name.
- status
  
  string, possible values: "inactive", "active" — The disposition's status. * `inactive` — Deactivated. * `active` — Activated.
next_page_token

string — Use the next page token to paginate through large result sets. A next page token is returned whenever the set of available results exceeds the current page size. This token's expiration period is 15 minutes.
page_size

integer, default: 30 — The number of records returned within a single API call.
total_records

integer — The total number of all records available across pages.

Example:

{
  "next_page_token": "R4aF9Oj0fVM2hhezJTEmSKaBSkfesDwGy42",
  "page_size": 30,
  "total_records": 10,
  "dispositions": [
    {
      "disposition_id": "W_VATTk_Q5aW6z5rZtBxAQ",
      "disposition_name": "Inquiry",
      "disposition_description": "Inquiry dispositions.",
      "status": "inactive",
      "last_modified_time": "2022-02-15T09:27:15Z",
      "modified_by": "IGTRVt3gQ2i-WjoUIjeZxw",
      "queue_name": "default voice queue",
      "cc_queue_id": "11Fx7UtNQaaWBM9XBCFX2Q",
      "assign_type": "inbound"
    }
  ]
}

Status: 400 HTTP Status Code: `400` Bad Request Error Code: `1244` More than one matching queue found.

Status: 401 HTTP Status Code: `401` Unauthorized Error Code: `124` Invalid access token. Error Code: `124` Access token has expired. Error Code: `1002` The user associated with this access token was not found or is invalid.

Status: 403 HTTP Status Code: `403` Forbidden Error Code: `1021` User account is deactivated. Error Code: `1022` User does not have a Contact Center license. Error Code: `9001` The Contact Center user associated with this bearer token is missing privileges on their role required to operate this request.

Status: 404 HTTP Status Code: `404` Not Found Error Code: `1201` Queue does not exist: $queueId.

Status: 429 HTTP Status Code: `429` Too Many Requests. For more information, see [rate limits](/docs/api/rest/rate-limits/). Error Code: `4001` You have reached the maximum per-second rate limit for this API. Try again later.

Assign queue dispositions

Method: POST
Path: /contact_center/queues/{queueId}/dispositions
Tags: Queues

Add dispositions to a queue.

Scopes: contact_center_queue:write:admin

Granular Scopes: contact_center:write:queue disposition:admin

Rate Limit Label: MEDIUM

Request Body

Content-Type: application/json

assign_type

string, possible values: "inbound", "outbound", default: "inbound" — The assignment type. The default is `inbound`.
disposition_ids

array — The dispositions to assign to the queue. This request supports a maximum of 30 dispositions per call.

Items:

string

Example:

{
  "disposition_ids": [
    "sgdfghr_2454y5hdfgsfsgsdg"
  ],
  "assign_type": "inbound"
}

Responses

Status: 201 HTTP Status Code: `201` Queue dispositions assigned.

Content-Type: application/json

dispositions

array — Information about the dispositions

Items:
- assign_type
  
  string, possible values: "inbound", "outbound", default: "inbound" — The disposition's assignment type.
- cc_queue_id
  
  string — The Contact Center queue's ID.
- disposition_description
  
  string — Information about the disposition.
- disposition_id
  
  string — The disposition's ID.
- disposition_name
  
  string — The disposition's name.
- last_modified_time
  
  string, format: date-time — The date and time when this data was last modified.
- modified_by
  
  string — The ID of the user that last modified this data.
- queue_name
  
  string — The Contact Center queue's name.
- status
  
  string, possible values: "inactive", "active" — The disposition's status. * `inactive` — Deactivated. * `active` — Activated.

Example:

{
  "dispositions": [
    {
      "disposition_id": "W_VATTk_Q5aW6z5rZtBxAQ",
      "disposition_name": "Inquiry",
      "disposition_description": "Inquiry dispositions.",
      "status": "inactive",
      "last_modified_time": "2022-02-15T09:27:15Z",
      "modified_by": "IGTRVt3gQ2i-WjoUIjeZxw",
      "queue_name": "default voice queue",
      "cc_queue_id": "11Fx7UtNQaaWBM9XBCFX2Q",
      "assign_type": "inbound"
    }
  ]
}

Status: 400 HTTP Status Code: `400` Bad Request Error Code: `300` Validation failed. Error Code: `1244` More than one matching queue found.

Status: 401 HTTP Status Code: `401` Unauthorized Error Code: `124` Invalid access token. Error Code: `124` Access token has expired. Error Code: `1002` The user associated with this access token was not found or is invalid.

Status: 403 HTTP Status Code: `403` Forbidden Error Code: `1021` User account is deactivated. Error Code: `1022` User does not have a Contact Center license. Error Code: `9001` The Contact Center user associated with this bearer token is missing privileges on their role required to operate this request.

Status: 404 HTTP Status Code: `404` Not Found Error Code: `1201` Queue does not exist: $queueId.

Status: 429 HTTP Status Code: `429` Too Many Requests. For more information, see [rate limits](/docs/api/rest/rate-limits/). Error Code: `4001` You have reached the maximum per-second rate limit for this API. Try again later.

List queue disposition sets

Method: GET
Path: /contact_center/queues/{queueId}/dispositions/sets
Tags: Queues

Return a list of queue's disposition sets(https://support.zoom.us/hc/en-us/articles/4470153057549-Managing-dispositions).

Scopes: contact_center_queue:read:admin

Granular Scopes: contact_center:read:list_disposition_sets:admin

Rate Limit Label: MEDIUM

Responses

Status: 200 HTTP Status Code: `200` Queue disposition sets list returned.

Content-Type: application/json

disposition_sets

array — Information about the task queue's disposition sets.

Items:
- assign_type
  
  string, possible values: "inbound", "outbound", default: "inbound" — The disposition set's assignment type.
- cc_queue_id
  
  string — The Contact Center queue's ID.
- disposition_set_description
  
  string — The information about the disposition set.
- disposition_set_id
  
  string — The disposition set's ID.
- disposition_set_name
  
  string — The disposition set's name.
- last_modified_time
  
  string, format: date-time — The date and time when this data was last modified.
- modified_by
  
  string — The ID of the user that last modified this data.
- queue_name
  
  string — The Contact Center queue's name.
- status
  
  string, possible values: "inactive", "active" — The disposition set's status. * `inactive` — Deactivated. * `active` — Activated.
next_page_token

string — Use the next page token to paginate through large result sets. A next page token is returned whenever the set of available results exceeds the current page size. This token's expiration period is 15 minutes.
page_size

integer, default: 30 — The number of records returned within a single API call.
total_records

integer — The total number of all records available across pages.

Example:

{
  "next_page_token": "R4aF9Oj0fVM2hhezJTEmSKaBSkfesDwGy42",
  "page_size": 30,
  "total_records": 10,
  "disposition_sets": [
    {
      "disposition_set_id": "W_VATTk_Q5aW6z5rZtBxAQ",
      "disposition_set_name": "Inquiry",
      "disposition_set_description": "Inquiry dispositions.",
      "status": "inactive",
      "last_modified_time": "2022-02-15T09:27:15Z",
      "modified_by": "IGTRVt3gQ2i-WjoUIjeZxw",
      "queue_name": "default voice queue",
      "cc_queue_id": "11Fx7UtNQaaWBM9XBCFX2Q",
      "assign_type": "inbound"
    }
  ]
}

Status: 400 HTTP Status Code: `400` Bad Request Error Code: `1244` More than one matching queue found.

Status: 404 HTTP Status Code: `404` Not Found Error Code: `1201` Queue does not exist: $queueId.

Status: 429 HTTP Status Code: `429` Too Many Requests. For more information, see [rate limits](/docs/api/rest/rate-limits/).

Assign queue disposition sets

Method: POST
Path: /contact_center/queues/{queueId}/dispositions/sets
Tags: Queues

Add disposition sets to a queue.

Scopes: contact_center_queue:write:admin

Granular Scopes: contact_center:write:queue_disposition_set:admin

Rate Limit Label: MEDIUM

Request Body

Content-Type: application/json

assign_type

string, possible values: "inbound", "outbound", default: "inbound" — The assignment type. The default is `inbound`.
disposition_set_ids

array — The IDs of the disposition sets to assign to the queue. This request supports a maximum of 30 dispositions per call.

Items:

string

Example:

{
  "disposition_set_ids": [
    "sgdfghr_2454y5hdfgsfsgsdg"
  ],
  "assign_type": "inbound"
}

Responses

Status: 201 HTTP Status Code: `201` Queue disposition sets assigned.

Content-Type: application/json

disposition_sets

array — Information about the queue's disposition sets.

Items:
- assign_type
  
  string, possible values: "inbound", "outbound", default: "inbound" — The disposition set's assignment type.
- cc_queue_id
  
  string — The Contact Center queue's ID.
- disposition_set_description
  
  string — The information about the disposition set.
- disposition_set_id
  
  string — The disposition set's ID.
- disposition_set_name
  
  string — The disposition set's name.
- last_modified_time
  
  string, format: date-time — The date and time when this data was last modified.
- modified_by
  
  string — The ID of the user that last modified this data.
- queue_name
  
  string — The Contact Center queue's name.
- status
  
  string, possible values: "inactive", "active" — The disposition set's status. * `inactive` — Deactivated. * `active` — Activated.

Example:

{
  "disposition_sets": [
    {
      "disposition_set_id": "W_VATTk_Q5aW6z5rZtBxAQ",
      "disposition_set_name": "Inquiry",
      "disposition_set_description": "Inquiry dispositions.",
      "status": "inactive",
      "last_modified_time": "2022-02-15T09:27:15Z",
      "modified_by": "IGTRVt3gQ2i-WjoUIjeZxw",
      "queue_name": "default voice queue",
      "cc_queue_id": "11Fx7UtNQaaWBM9XBCFX2Q",
      "assign_type": "inbound"
    }
  ]
}

Status: 400 HTTP Status Code: `400` Bad Request

Status: 404 HTTP Status Code: `404` Not Found Error Code: `1201` Queue does not exist: $queueId.

Status: 429 HTTP Status Code: `429` Too Many Requests. For more information, see [rate limits](/docs/api/rest/rate-limits/).

Unassign a queue disposition set

Method: DELETE
Path: /contact_center/queues/{queueId}/dispositions/sets/{dispositionSetId}
Tags: Queues

Delete a disposition set from a queue.

Scopes: contact_center_queue:write:admin

Granular Scopes: contact_center:delete:queue_disposition_set:admin

Rate Limit Label: LIGHT

Responses

Status: 204 HTTP Status Code: `204` Queue disposition set deleted.

Status: 400 HTTP Status Code: `400` Bad Request

Status: 404 HTTP Status Code: `404` Not Found Error Code: `1201` Queue disposition set does not exist: $dispositionSetId.

Status: 429 HTTP Status Code: `429` Too Many Requests. For more information, see [rate limits](https://developers.zoom.us/docs/api/rest/rate-limits/).

Unassign a queue disposition

Method: DELETE
Path: /contact_center/queues/{queueId}/dispositions/{dispositionId}
Tags: Queues

Delete a disposition from a queue.

Scopes: contact_center_queue:write:admin

Granular Scopes: contact_center:delete:queue_disposition:admin

Rate Limit Label: LIGHT

Responses

Status: 204 HTTP Status Code: `204` Queue disposition deleted.

Status: 400 HTTP Status Code: `400` Bad Request Error Code: `1244` More than one matching queue found.

Status: 401 HTTP Status Code: `401` Unauthorized Error Code: `124` Invalid access token. Error Code: `124` Access token has expired. Error Code: `1002` The user associated with this access token was not found or is invalid.

Status: 403 HTTP Status Code: `403` Forbidden Error Code: `1021` User account is deactivated. Error Code: `1022` User does not have a Contact Center license. Error Code: `9001` The Contact Center user associated with this bearer token is missing privileges on their role required to operate this request.

Status: 404 HTTP Status Code: `404` Not Found Error Code: `1201` Queue disposition does not exist: $dispositionId.

Status: 429 HTTP Status Code: `429` Too Many Requests. For more information, see [rate limits](https://developers.zoom.us/docs/api/rest/rate-limits/). Error Code: `4001` You have reached the maximum per-second rate limit for this API. Try again later.

Get a queue's interrupt settings

Method: GET
Path: /contact_center/queues/{queueId}/interrupt
Tags: Queues

Retrieve the interrupt settings for a specific queue, including audio interrupts and notify interrupts. If set up, returns detailed information about custom audio configurations.

Scopes: contact_center_queue:read:admin

Granular Scopes: contact_center:read:queue:admin

Rate Limit Label: LIGHT

Responses

Status: 200 HTTP Status Code: `200` Queue interrupt settings retrieved successfully.

Content-Type: application/json

audio_interrupts

array — List of audio messages to play during queue wait time.

Items:
- audio_asset_id
  
  string — The ID of the audio asset to play.
- audio_filename
  
  string — The audio asset's filename.
- audio_url
  
  string — The URL to access the audio asset.
- disable_audio
  
  boolean — Whether this audio interrupt is disabled.
- is_loop
  
  boolean — Whether to loop this audio message.
- loop_interval
  
  integer | null — Interval in seconds between loops. Required when `is_loop` is `true`.
- play_after_seconds
  
  integer — Number of seconds to wait before playing this audio.
bucket_id

string | null — The waiting experience bucket's unique identifier. Only present when the request includes a `bucket_id` parameter.
notify_interrupts

object — Notify interrupt settings for estimated wait time and position in queue announcements.
- is_loop
  
  boolean — Whether to repeat the notification periodically.
- loop_interval
  
  integer | null — Interval in seconds between notification repetitions. Required when `is_loop` is `true`.
- notify_estimated_wait_time
  
  object — Estimated wait time notification settings. Announces the estimated wait time to the caller.
  - backup_custom_audio
    
    array — Custom audio to play when the system cannot calculate an estimated wait time. Always uses STANDARD mode.
    
    Items:
    - audio_asset_id
      
      string | null — The ID of the audio asset to play at this position. **Note** Provide either `audio_asset_id` or `audio_variable`, but not both.
    - audio_filename
      
      string | null — The audio asset's filename. This is a read-only field populated by the system.
    - audio_variable
      
      string | null, possible values: "customer_position", "wait_time" — A dynamic variable to announce at this position. - `customer_position` - Announces the caller's position in the queue. - `wait_time` - Announces the estimated wait time. **Note** Provide either `audio_asset_id` or `audio_variable`, but not both.
    - order
      
      integer — The playback order of this audio prompt in the sequence.
  - custom_audio
    
    array — The main custom audio prompts for wait time announcement. **STANDARD mode** Exactly 1 audio file. **ADVANCED mode** 1-7 audio segments.
    
    Items:
    - audio_asset_id
      
      string | null — The ID of the audio asset to play at this position. **Note** Provide either `audio_asset_id` or `audio_variable`, but not both.
    - audio_filename
      
      string | null — The filename of the audio asset. This is a read-only field populated by the system.
    - audio_variable
      
      string | null, possible values: "customer_position", "wait_time" — A dynamic variable to announce at this position. - `customer_position` - Announces the caller's position in the queue. - `wait_time` - Announces the estimated wait time. **Note** Provide either `audio_asset_id` or `audio_variable`, but not both.
    - order
      
      integer — The playback order of this audio prompt in the sequence.
  - custom_audio_type
    
    string, possible values: "standard", "advanced" — The type of custom audio configuration. - `standard` - Single pre-recorded audio file that includes the complete message. - `advanced` - Multiple audio segments combined with dynamic variables.
  - over_limit_custom_audio
    
    array — Custom audio to play when the estimated wait time exceeds the digit audio library limit. Always uses STANDARD mode.
    
    Items:
    - audio_asset_id
      
      string | null — The ID of the audio asset to play at this position. **Note** Provide either `audio_asset_id` or `audio_variable`, but not both.
    - audio_filename
      
      string | null — The audio asset's filename. This is a read-only field populated by the system.
    - audio_variable
      
      string | null, possible values: "customer_position", "wait_time" — A dynamic variable to announce at this position. - `customer_position` - Announces the caller's position in the queue. - `wait_time` - Announces the estimated wait time. **Note** Provide either `audio_asset_id` or `audio_variable`, but not both.
    - order
      
      integer — The playback order of this audio prompt in the sequence.
- notify_position_in_queue
  
  object — Position In Queue notification settings. Announces the caller's position in the queue.
  - custom_audio
    
    array — The main custom audio prompts for position announcement. **STANDARD mode** - Exactly 1 audio file. **ADVANCED mode** - 1-7 audio segments.
    
    Items:
    - audio_asset_id
      
      string | null — The ID of the audio asset to play at this position. **Note** Provide either `audio_asset_id` or `audio_variable`, but not both.
    - audio_filename
      
      string | null — The audio asset's filename. This is a read-only field populated by the system.
    - audio_variable
      
      string | null, possible values: "customer_position", "wait_time" — A dynamic variable to announce at this position. - `customer_position` - Announces the caller's position in the queue. - `wait_time` - Announces the estimated wait time. **Note** Provide either `audio_asset_id` or `audio_variable`, but not both.
    - order
      
      integer — The playback order of this audio prompt in the sequence.
  - custom_audio_type
    
    string, possible values: "standard", "advanced" — The type of custom audio configuration. - `standard` - Single pre-recorded audio file that includes the complete message. - `advanced` - Multiple audio segments combined with dynamic variables.
  - over_limit_custom_audio
    
    array — Custom audio to play when the caller's position exceeds the digit audio library limit. Always uses STANDARD mode.
    
    Items:
    - audio_asset_id
      
      string | null — The ID of the audio asset to play at this position. **Note** Provide either `audio_asset_id` or `audio_variable`, but not both.
    - audio_filename
      
      string | null — The audio asset's filename. This is a read-only field populated by the system.
    - audio_variable
      
      string | null, possible values: "customer_position", "wait_time" — A dynamic variable to announce at this position. - `customer_position` - Announces the caller's position in the queue. - `wait_time` - Announces the estimated wait time. **Note** Provide either `audio_asset_id` or `audio_variable`, but not both.
    - order
      
      integer — The playback order of this audio prompt in the sequence.
- play_after_seconds
  
  integer — Number of seconds to wait before playing the first notification.

Example:

{
  "bucket_id": "zeYjXoDOS_eV1QmTpj63PQ",
  "audio_interrupts": [
    {
      "audio_asset_id": "asset_001",
      "audio_filename": "welcome_message.mp3",
      "audio_url": "https://www.example.com/audio/asset_001.mp3",
      "play_after_seconds": 30,
      "is_loop": false,
      "loop_interval": 45,
      "disable_audio": false
    }
  ],
  "notify_interrupts": {
    "play_after_seconds": 15,
    "is_loop": true,
    "loop_interval": 30,
    "notify_position_in_queue": {
      "custom_audio_type": "advanced",
      "custom_audio": [
        {
          "order": 1,
          "audio_asset_id": "piq_intro_001",
          "audio_filename": "you_are_number.mp3",
          "audio_variable": "customer_position"
        }
      ],
      "over_limit_custom_audio": [
        {
          "order": 1,
          "audio_asset_id": "piq_intro_001",
          "audio_filename": "you_are_number.mp3",
          "audio_variable": "customer_position"
        }
      ]
    },
    "notify_estimated_wait_time": {
      "custom_audio_type": "advanced",
      "custom_audio": [
        {
          "order": 1,
          "audio_asset_id": "piq_intro_001",
          "audio_filename": "you_are_number.mp3",
          "audio_variable": "customer_position"
        }
      ],
      "over_limit_custom_audio": [
        {
          "order": 1,
          "audio_asset_id": "piq_intro_001",
          "audio_filename": "you_are_number.mp3",
          "audio_variable": "wait_time"
        }
      ],
      "backup_custom_audio": [
        {
          "order": 1,
          "audio_asset_id": "piq_intro_001",
          "audio_filename": "you_are_number.mp3",
          "audio_variable": "wait_time"
        }
      ]
    }
  }
}

Status: 400 HTTP Status Code: `400` Bad Request Error Code: `1205` Queue channel type is invalid. Only voice queues support interrupt settings. Error Code: `2313` Bucket option is not enabled for queue {queueId}. Enable bucket option before using bucket_id. Error Code: ``

Status: 401 HTTP Status Code: `401` Unauthorized Error Code: `124` Invalid access token. Error Code: `1002` The user associated with this access token was not found or is invalid. Error Code: `124` Access token has expired.

Status: 403 HTTP Status Code: `403` Forbidden HTTP Status Code: `403` Forbidden User does not have permission to read queue settings. Error Code: `1021` User account is deactivated. Error Code: `1022` User does not have a Contact Center license. Error Code: `9001` The Contact Center user associated with this bearer token is missing privileges on their role required to operate this request.

Status: 404 HTTP Status Code: `404` Not Found Error Code: `1201` Queue does not exist: {queueId}. Error Code: `2312` The `bucket_id` {bucketId} does not exist or does not belong to queue {queueId}.

Status: 429 HTTP Status Code: `429` Too Many Requests. For more information, see [rate limits]https://developers.zoom.us/docs/api/rate-limits/. Error Code: `4001` You have reached the maximum per-second rate limit for this API. Try again later.

Update a queue's interrupt settings

Method: PATCH
Path: /contact_center/queues/{queueId}/interrupt
Tags: Queues

Update the interrupt settings for a voice queue.

While consumers wait to connect, the queue can interrupt the hold media to announce estimated wait time, position in queue, audio messages, or menu options. Configure interrupts to occur within the max wait duration.

Scopes: contact_center_queue:write:admin

Granular Scopes: contact_center:update:queue:admin

Rate Limit Label: LIGHT

Request Body

Content-Type: application/json

audio_interrupts

array — A list of audio interrupts to play during consumer wait in the queue.

Items:
- audio_asset_id (required)
  
  string — ID of the audio asset choose to play as queue audio interrupt.
- is_loop (required)
  
  boolean — Whether the audio interrupt repeat to play.
- play_after_seconds (required)
  
  integer — The number of seconds to wait for the first time to play the audio interrupt.
- disable_audio
  
  boolean — Choose to disable this audio interrupt. When set to true, the audio interrupt will be disabled and filled with background music. Defaults to false (enabled) if not provided.
- loop_interval
  
  integer — How long to wait between repeats. `loop_interval` must be at least 1 second when `is_loop` is `true`. Maximum value has no hard limit, but not exceed queue's maximum waiting time. As a best practice, stay within 5-300 seconds.
notify_interrupts

object — Notify the consumer of their position and estimated wait time while waiting in the queue.
- is_loop (required)
  
  boolean — Whether the position and estimated wait time notifications repeat.
- play_after_seconds (required)
  
  integer — The number of seconds to wait before playing the first notification to notify consumer about their position and estimated waiting time in queue.
- loop_interval
  
  integer — How long to wait between repeats. `loop_interval` must be at least 1 second when `is_loop` is `true`. Maximum value has no hard limit, but not exceed queue's maximum waiting time. As a best practice, stay within 5-300 seconds.
- notify_estimated_wait_time
  
  object — Notify the consumer of their estimated wait time while waiting in the queue. The wait time is calculated by the routing engine based on current queue conditions, agent availability, and historical data.
  - backup_custom_audio (required)
    
    array — Fallback audio message to play when the system cannot calculate or provide estimated wait time. **Play times** EWT service is unavailable No active agents are available Insufficient historical data for calculation System errors occur Queue is newly created without historical data
    
    Items:
    - audio_asset_id (required)
      
      string — ID of the audio asset choose to play when system not able to provide an estimated wait time.
    - order (required)
      
      integer — The order to play the audio message when system not able to provide an estimated wait time.
  - custom_audio (required)
    
    array — Set the custom audio settings for notifying the consumer of their estimated wait time in the queue. Currently, 'standard' mode supports a single audio message file. Specify using 'audio_asset_id' only. The 'advanced' mode supports up to 7 pre-recorded audio message files. Combine per-recorded audio file 'audio_asset_id' and with dynamic variable 'audio_variable'. For each part, select 'audio_asset_id' or 'audio_variable'. **Advanced mode example** { "order": 1, "audio_asset_id": "asset_wait_time_prefix" }, { "order": 2, "audio_variable": "wait_time" }, { "order": 3, "audio_asset_id": "asset_wait_time_suffix" }
    
    Items:
    - order (required)
      
      integer — The playback sequence order for audio segments. Must be unique within the array.
    - audio_asset_id
      
      string — ID of the audio asset choose to play to notify the consumer of their estimated wait time in the queue.
    - audio_variable
      
      string, possible values: "wait_time", default: "wait_time" — Dynamic variable for advanced mode only. Use `wait_time` to announce the estimated wait time, in minutes. The time is calculated in real time. **Note** Provide either `audio_asset_id` or `audio_variable`, but not both.
  - custom_audio_type (required)
    
    string, possible values: "standard", "advanced", default: "standard" — Select custom audio type. -standard - Single pre-recorded audio file. The audio prompt must include all words and time values as part of the message. Variables cannot be used with this option. -advanced - Audio message split into multiple reusable parts, up to 7 segments. Combines pre-recorded audio files with dynamic variables. Requires digit audio library to be configured first.
  - over_limit_custom_audio (required)
    
    array — Audio message to play when the estimated wait time exceeds the digit audio library limit, typically 60+ minutes. This provides a fallback message for very long wait times where specific durations can't be announced accurately.
    
    Items:
    - audio_asset_id (required)
      
      string — ID of the audio asset choose to play when the estimated wait time exceeds the maximum limit.
    - order (required)
      
      integer — The order to play the audio message when over limit, estimated wait time is more than 60 minutes.
- notify_position_in_queue
  
  object — Notify the consumer of their position while waiting in queue.
  - custom_audio (required)
    
    array — Set the custom audio settings for notifying a user of their queue position. Currently, 'standard' mode supports a single audio message file. Specify using 'audio_asset_id' only. 'advanced' mode supports up to 7 pre-recorded audio message files. Combine per-recorded audio file 'audio_asset_id' and dynamic variable 'audio_variable'. For each part, use 'audio_asset_id' or 'audio_variable'. **Advanced mode example** { "order": 1, "audio_asset_id": "asset_position_in_queue_prefix" }, { "order": 2, "audio_variable": "customer_position" }, { "order": 3, "audio_asset_id": "asset_position_in_queue_suffix" }
    
    Items:
    - order (required)
      
      integer — The playback sequence order for audio segments. Must be unique within the array. **Example** { "order": 1, "audio_asset_id": "asset_position_in_queue_prefix" }, { "order": 2, "audio_variable": "customer_position" }, { "order": 3, "audio_asset_id": "asset_position_in_queue_suffix" }
    - audio_asset_id
      
      string — ID of the audio asset choose to play for notifying a user of their queue position. **Note** Provide either `audio_asset_id` or `audio_variable`, but not both.
    - audio_variable
      
      string, possible values: "customer_position", default: "customer_position" — Dynamic variable for advanced mode only. Use `customer_position` to announce the caller's current position in the queue. The position is calculated in real-time. **Note** Provide either `audio_asset_id` or `audio_variable`, but not both.
  - custom_audio_type (required)
    
    string, possible values: "standard", "advanced", default: "standard" — Select custom audio type. -'standard' - Choose an audio file. The audio prompt must include all words, numbers, and keypress digits as part of the message. Variables cannot be used with this option. -'advanced' - With this option, the audio message can be split into multiple reusable audio parts. Variables are needed. Set up the digits library before using numbers with this option.
  - over_limit_custom_audio (required)
    
    array — Audio message to play when the caller's position exceeds the digit audio library limit, typically 60. Provides a fallback message for very long queues where specific position numbers cannot be announced.
    
    Items:
    - audio_asset_id
      
      string — ID of the audio asset to play when the position exceeds the maximum limit.
    - order
      
      integer — The playback sequence order for over-limit audio segments

Example:

{
  "audio_interrupts": [
    {
      "audio_asset_id": "dORBRSTxTN6B0vLJ37Kvnw",
      "play_after_seconds": 5,
      "is_loop": false,
      "loop_interval": 1,
      "disable_audio": true
    }
  ],
  "notify_interrupts": {
    "play_after_seconds": 10,
    "is_loop": false,
    "loop_interval": 1,
    "notify_position_in_queue": {
      "custom_audio_type": "advanced",
      "custom_audio": [
        {
          "audio_asset_id": "dORBRSTxTN6B0vLJ37Kvnw",
          "audio_variable": "customer_position",
          "order": 1
        }
      ],
      "over_limit_custom_audio": [
        {
          "order": 1,
          "audio_asset_id": "dORBRSTxTN6B0vLJ37Kvnw"
        }
      ]
    },
    "notify_estimated_wait_time": {
      "custom_audio_type": "advanced",
      "custom_audio": [
        {
          "audio_asset_id": "dORBRSTxTN6B0vLJ37Kvnw",
          "audio_variable": "wait_time",
          "order": 1
        }
      ],
      "over_limit_custom_audio": [
        {
          "order": 1,
          "audio_asset_id": "dORBRSTxTN6B0vLJ37Kvnw"
        }
      ],
      "backup_custom_audio": [
        {
          "order": 1,
          "audio_asset_id": "dORBRSTxTN6B0vLJ37Kvnw"
        }
      ]
    }
  }
}

Responses

Status: 204 HTTP Status Code: `204` Queue interrupts updated.

Status: 400 HTTP Status Code: `400` Bad Request Error Code: `1205` Queue channel type is invalid. Error Code: `2304` Asset '{assetId}' is not valid for this operation. Audio asset is required. Error Code: `2311` `disable_audio` cannot be set via API for this audio interrupt when `is_enable_api_control` is not enabled. Error Code: `1254` Bucket ID is invalid.

Status: 401 HTTP Status Code: `401` Unauthorized Error Code: `124` Invalid access token. Error Code: `124` Access token has expired. Error Code: `1002` The user associated with this access token was not found or is invalid.

Status: 403 HTTP Status Code: `403` Forbidden Error Code: `1021` User account is deactivated. Error Code: `1022` User does not have a Contact Center license. Error Code: `9001` The Contact Center user associated with this bearer token is missing privileges on their role required to operate this request.

Status: 404 HTTP Status Code: `404` Not Found Error Code: `1201` Queue does not exist: {queueId}. Error Code: `2301` Asset does not exist: {assetId}.

Status: 429 HTTP Status Code: `429` Too Many Requests. For more information, see [rate limits](https://developers.zoom.us/docs/api/rate-limits/). Error Code: `4001` You have reached the maximum per-second rate limit for this API. Try again later.

Assign a queue menu based interrupt

Method: POST
Path: /contact_center/queues/{queueId}/interrupt_menu
Tags: Queues

Create a menu of options to offer to consumers during the queue waiting experience. Currently, the only support for queue channel type is voice.

Scopes: contact_center_queue:write:admin

Granular Scopes: contact_center:update:queue:admin

Rate Limit Label: LIGHT

Request Body

Content-Type: application/json

menu_language_code (required)

string, possible values: "zh-CN", "zh-TW", "yue-CN", "cmn-CN", "da-DK", "nl-NL", "en-AU", "en-NZ", "en-GB", "en-US", "fr-CA", "fr-FR", "de-DE", "it-IT", "ja-JP", "ko-KR", "pl-PL", "pt-BR", "pt-PT", "ro-RO", "ru-RU", "es-ES", "es-MX", "es-US", "sv-SE", "tr-TR" — The menu language and voice applied to default messages for menu and callback prompts.
menu_options (required)

array — A list of menu options for keypresses and detail menu action. Each keypress can only be related to one action.

Items:
- keypress (required)
  
  string, possible values: "1", "2", "3", "4", "5", "6", "7", "8", "9", "0", "*", "#" — The keypress provided in the menu.
- menu_action (required)
  
  string, possible values: "request_callback", "leave_voicemail", "route_flow", "repeat_menu" — The keypress action for selecting the menu.
- callback_settings
  
  object — Set call back settings for when the menu action is `request_callback`.
  - accept_callback_timeout
    
    integer — Time to accept callback menu, in seconds. Configured at 5 second intervals.
  - advanced_callback_confirmation
    
    object — when 'enable_advanced_callback_confirmation' set as `true`, required to set the advanced callback confirmation voice message recording under this section.
    - advanced_callback_confirm_message
      
      string, default: "Your callback request is confirmed. We will use the phone number {{phoneNumber}} to call you back when it's your turn in the queue. To leave a voice message, press {{keyPress}}. Or hang up to end the call." — Mesage to caller with callback request. Do no edit or remove symbols or text in `{{}}`
    - advanced_callback_confirm_message_with_extension
      
      string, default: "Your request for callback is confirmed. We'll call you back at your {{current phone number}} and extension {{extension number}} when it's your turn in the queue. To leave a voice message, press {{keyPress}}, or hang up to end the call." — Message to caller with callback request, with extension entered. Do not edit or remove symbols or text in `{{}}`.
    - callback_voice_message_display_time
      
      integer, default: 5 — Callback voice message is displayed to the agent for the set number of seconds before contacting the consumer. If the agent does not click **Confirm** to dial consumer after the timeout, the system will automatically dial the number.
    - callback_voice_message_time_limit
      
      integer, default: 1 — The voice message time limit, in minutes.
    - enable_voice_message_transcription
      
      boolean — Allow agent to access voice message transcriptions from the Zoom client
    - end_message
      
      string, default: "Good bye." — End call message to play.
    - greeting_message
      
      string, default: "Please record your voice message after the tone, press {{starKey}} to discard and end call, or press any digit key to save the recording." — Greeting voice message to play. Do no edit or remove symbols or text in `{{}}`,
    - keypress_listen_recording_message
      
      string, default: "Press {{keyPress}} to listen to the voice message." — Customize the message for listen to voice message. The keypress is predefined as `1`. Do not edit or remove symbols or text in `{{}}`.
    - keypress_re_recording_message
      
      string, default: "Press {{keyPress}} to re-record your voice message." — Customize the message for re-record the voice message. The keypress is predefined as `3`. Do not edit or remove symbols or text in `{{}}`.
    - keypress_save_recording_message
      
      string, default: "Press {{keyPress}} to save the voice message and end the call." — Customize the message for save the voice message. The keypress is predefined as `2`. Do not edit or remove symbols or text in `{{}}`.
    - keypress_voice_message
      
      string, possible values: "1", "2", "3", "4", "5", "6", "7", "8", "9", "0", "*", default: "1" — The keypress provided in the menu for the leave a voice message action.
    - save_recording_message
      
      string, default: "Message saved" — Customize the message to play for save recording message to play.
    - short_recording_message
      
      string, default: "Sorry, your recording is too short. Please try again." — Customize the message to play for voice for short recording.
  - callback_cancel_message
    
    string, default: "Your callback has been canceled due to high call volumes. Please try calling again." — Notification message about callback cancellation.
  - callback_cancel_message_custom_audio
    
    object — Play prerecorded audio message about callback cancellation. **Note** Provide either 'callback_cancel_message' or 'callback_cancel_message_custom_audio'.
    - custom_audio (required)
      
      array — Set the custom audio settings for the message will be played to the consumer before selecting a keypress. Currently, 'standard' mode supports a single audio message file. Specify using 'audio_asset_id' only. 'advanced' mode supports up to 7 pre-recorded audio message files. Combine per-recorded audio file 'audio_asset_id' and dynamic variable 'audio_variable', here the variable is for {{keypress}}. For each part, use 'audio_asset_id' or 'audio_variable'. **Advanced mode example** { "order": 1, "audio_asset_id": "asset_play_message_prefix" }, { "order": 2, "audio_variable": "keypress" }, { "order": 3, "audio_asset_id":"asset_play_message_suffix" }
      
      Items:
      - order (required)
        
        integer — The order to play audio.
      - audio_asset_id
        
        string — ID of the audio asset choose to play message to consumer **Note** Provide either `audio_asset_id` or `audio_variable`, but not both.
      - audio_variable
        
        string, possible values: "keypress", default: "keypress" — Dynamic variable for advanced mode only. Use `keypress` to announce the keypress for consumer to chooes. **Note** Provide either `audio_asset_id` or `audio_variable`, but not both.
    - custom_audio_type (required)
      
      string, possible values: "advanced", "standard", default: "standard" — Select custom audio type. -'standard' - Choose an audio file. The audio prompt must include all words, numbers, and keypress digits as part of the message. Variables cannot be used with this option. -'advanced' - With this option, the audio message can be split into multiple reusable audio parts. Variables are needed. Set up the digits library before using numbers with this option.
  - callback_confirm_keypress
    
    string, possible values: "#", "*" — Callers use this key to confirm in response to message for a request callback.
  - callback_confirm_message
    
    string, default: "Your request for callback is confirmed. We will use the phone number {{current phone number}} and extension {{extension number}} to call you back when it's your turn in the queue" — Message to the returning caller with callback set up. Do not edit or remove symbols and text in {{}}. {{keyPress}} plays the keypress configured in 'callback_confirm_keypress' to the consumer.
  - callback_confirm_message_custom_audio
    
    object — Play prerecorded audio message to the returning caller with callback set up. **Note** Provide either 'callback_confirm_message' or 'callback_confirm_message_custom_audio'.
    - custom_audio (required)
      
      array — Set the custom audio settings for the message will be played to the consumer before selecting a keypress. Currently, 'standard' mode supports a single audio message file. Specify using 'audio_asset_id' only. 'advanced' mode supports up to 7 pre-recorded audio message files. Combine per-recorded audio file 'audio_asset_id' and dynamic variable 'audio_variable', here the variable is for {{keypress}}. For each part, use 'audio_asset_id' or 'audio_variable'. **Advanced mode example** { "order": 1, "audio_asset_id": "asset_play_message_prefix" }, { "order": 2, "audio_variable": "keypress" }, { "order": 3, "audio_asset_id":"asset_play_message_suffix" }
      
      Items:
      - order (required)
        
        integer — The order to play audio.
      - audio_asset_id
        
        string — ID of the audio asset choose to play message to consumer **Note** Provide either `audio_asset_id` or `audio_variable`, but not both.
      - audio_variable
        
        string, possible values: "keypress", default: "keypress" — Dynamic variable for advanced mode only. Use `keypress` to announce the keypress for consumer to chooes. **Note** Provide either `audio_asset_id` or `audio_variable`, but not both.
    - custom_audio_type (required)
      
      string, possible values: "advanced", "standard", default: "standard" — Select custom audio type. -'standard' - Choose an audio file. The audio prompt must include all words, numbers, and keypress digits as part of the message. Variables cannot be used with this option. -'advanced' - With this option, the audio message can be split into multiple reusable audio parts. Variables are needed. Set up the digits library before using numbers with this option.
  - callback_confirm_messsage
    
    string, default: "Your request for callback is confirmed. We will use the phone number {{current phone number}} and extension {{extension number}} to call you back when it's your turn in the queue" — Deprecate. Message to the returning caller with callback set up. Do not edit or remove symbols and text in {{}}. {{keyPress}} plays the keypress configured in 'callback_confirm_keypress' to the consumer.
  - callback_number_type
    
    string, possible values: "flow_entry_id", "account_default_caller_id", "queue_default_caller_id" — Callback caller ID number type.
  - callback_offer_time
    
    array — Set the day when callbacks will be offered and returned to consumers. Required when `enable_callback_offer_time` is `true`.
    
    Items:
    - callback_offer_day
      
      string, possible values: "Mon", "Tue", "Wed", "Thu", "Fri", "Sat", "Sun" — Set the day when callbacks will be offered to consumers.
    - callback_offer_end_time
      
      string — End time on the day when callbacks will be offered to consumers, between `00:00` and `23:59`.
    - callback_offer_start_time
      
      string — Start time on the day when callbacks will be offered to consumers, between `00:00` and `23:59`.
  - callback_offer_timezone_id
    
    string — Set the [timezone](/docs/api/references/abbreviations/#timezones) when callbacks will be offered and returned to consumers. Required when `enable_callback_offer_time` is `true`.
  - callback_return_day
    
    array — The day when callbacks will be returned to consumers. Required when `enable_callback_return_time` is `true`.
    
    Items:
    - callback_return_day
      
      string, possible values: "Mon", "Tue", "Wed", "Thu", "Fri", "Sat", "Sun" — The day when callbacks will be returned to consumers.
    - callback_return_end_time
      
      string — Set the end time range when callbacks will be returned to consumers, between `00:00` to `23:59`.
    - callback_return_start_time
      
      string — Set the start time range when callbacks will be returned to consumers, between `00:00` to `23:59`.
  - callback_return_timezone_id
    
    string — Set the [timezone ID](/docs/api/references/abbreviations/#timezones) to limit the times when callbacks will be returned to consumers. Required when `enable_callback_return_time` is `true`.
  - callback_returning_message
    
    string, default: "Hello again. You have a callback set up. Press {{keyPress}} to cancel your callback and wait on the line, or hang up to keep your callback request and end this call." — Message to returning caller with callback setup. Do not edit or remove symbols and text in {{}}.The {{keyPress}} plays the keypress configured in 'callback_confirm_keypress' to the consumer.
  - callback_returning_message_custom_audio
    
    object — Play prerecorded audio message to returning caller with callback setup. **Note** Provide either 'callback_returning_message' or 'callback_returning_message_custom_audio'.
    - custom_audio (required)
      
      array — Set the custom audio settings for the message will be played to the consumer before selecting a keypress. Currently, 'standard' mode supports a single audio message file. Specify using 'audio_asset_id' only. 'advanced' mode supports up to 7 pre-recorded audio message files. Combine per-recorded audio file 'audio_asset_id' and dynamic variable 'audio_variable', here the variable is for {{keypress}}. For each part, use 'audio_asset_id' or 'audio_variable'. **Advanced mode example** { "order": 1, "audio_asset_id": "asset_play_message_prefix" }, { "order": 2, "audio_variable": "keypress" }, { "order": 3, "audio_asset_id":"asset_play_message_suffix" }
      
      Items:
      - order (required)
        
        integer — The order to play audio.
      - audio_asset_id
        
        string — ID of the audio asset choose to play message to consumer **Note** Provide either `audio_asset_id` or `audio_variable`, but not both.
      - audio_variable
        
        string, possible values: "keypress", default: "keypress" — Dynamic variable for advanced mode only. Use `keypress` to announce the keypress for consumer to chooes. **Note** Provide either `audio_asset_id` or `audio_variable`, but not both.
    - custom_audio_type (required)
      
      string, possible values: "advanced", "standard", default: "standard" — Select custom audio type. -'standard' - Choose an audio file. The audio prompt must include all words, numbers, and keypress digits as part of the message. Variables cannot be used with this option. -'advanced' - With this option, the audio message can be split into multiple reusable audio parts. Variables are needed. Set up the digits library before using numbers with this option.
  - callback_timeout
    
    integer — Set the limit for how long callbacks will remain as tasks in the queue, in seconds.
  - confirm_extension_number_message
    
    string, default: "You entered the extension {{extension number}}. If this is correct, press {{keyPress}} to confirm. Otherwise, enter your extension number and then press {{keyPress}}." — Message asking the caller to confirm the phone number extension. Do not edit or remove symbols and text in {{}}. The {{keyPress}} plays the keypress configured in 'callback_confirm_keypress' to the consumer.
  - confirm_extension_number_message_custom_audio
    
    object — Play prerecorded audio message asking the caller to confirm the phone number extension. **Note** Provide either 'confirm_extension_number_message' or 'confirm_extension_number_message_custom_audio'.
    - custom_audio (required)
      
      array — Set the custom audio settings for the message will be played to the consumer before selecting a keypress. Currently, 'standard' mode supports a single audio message file. Specify using 'audio_asset_id' only. 'advanced' mode supports up to 7 pre-recorded audio message files. Combine per-recorded audio file 'audio_asset_id' and dynamic variable 'audio_variable', here the variable is for {{keypress}}. For each part, use 'audio_asset_id' or 'audio_variable'. **Advanced mode example** { "order": 1, "audio_asset_id": "asset_play_message_prefix" }, { "order": 2, "audio_variable": "keypress" }, { "order": 3, "audio_asset_id":"asset_play_message_suffix" }
      
      Items:
      - order (required)
        
        integer — The order to play audio.
      - audio_asset_id
        
        string — ID of the audio asset choose to play message to consumer **Note** Provide either `audio_asset_id` or `audio_variable`, but not both.
      - audio_variable
        
        string, possible values: "keypress", default: "keypress" — Dynamic variable for advanced mode only. Use `keypress` to announce the keypress for consumer to chooes. **Note** Provide either `audio_asset_id` or `audio_variable`, but not both.
    - custom_audio_type (required)
      
      string, possible values: "advanced", "standard", default: "standard" — Select custom audio type. -'standard' - Choose an audio file. The audio prompt must include all words, numbers, and keypress digits as part of the message. Variables cannot be used with this option. -'advanced' - With this option, the audio message can be split into multiple reusable audio parts. Variables are needed. Set up the digits library before using numbers with this option.
  - enable_advanced_callback_confirmation
    
    boolean — Enable or disable advanced callback confirmation feature. The account needs to enable the feature OP flag.
  - enable_callback_cancel_message
    
    boolean — Send a message to consumers if callbacks are canceled.
  - enable_callback_offer_time
    
    boolean — Limit the times when callbacks will be offered to consumers.
  - enable_callback_return_time
    
    boolean — Limit the times when callbacks will be returned to consumers.
  - enable_offer_extension_number
    
    boolean — Lets callers to add an extension to their callback phone number so that callers who don't have a direct line can still be reached directly.
  - enable_offer_phone_number
    
    boolean — Allow callers to provide a different callback number.
  - offer_extension_number_message
    
    string, default: "We'll call you back using the phone number {{current phone number}}. If you want to add an extension, enter it now and then press {{keyPress}}. Otherwise, please stay on the line or press {{keyPress}} now." — Message asking the caller to give a phone number extension. Do not edit or remove symbols and text in {{}}. The {{keyPress}} plays the keypress configured in 'callback_confirm_keypress' to the consumer.
  - offer_extension_number_message_custom_audio
    
    object — Play prerecorded audio message asking the caller to give a phone number extension. **Note** Provide either 'offer_extension_number_message' or 'offer_extension_number_message_custom_audio'.
    - custom_audio (required)
      
      array — Set the custom audio settings for the message will be played to the consumer before selecting a keypress. Currently, 'standard' mode supports a single audio message file. Specify using 'audio_asset_id' only. 'advanced' mode supports up to 7 pre-recorded audio message files. Combine per-recorded audio file 'audio_asset_id' and dynamic variable 'audio_variable', here the variable is for {{keypress}}. For each part, use 'audio_asset_id' or 'audio_variable'. **Advanced mode example** { "order": 1, "audio_asset_id": "asset_play_message_prefix" }, { "order": 2, "audio_variable": "keypress" }, { "order": 3, "audio_asset_id":"asset_play_message_suffix" }
      
      Items:
      - order (required)
        
        integer — The order to play audio.
      - audio_asset_id
        
        string — ID of the audio asset choose to play message to consumer **Note** Provide either `audio_asset_id` or `audio_variable`, but not both.
      - audio_variable
        
        string, possible values: "keypress", default: "keypress" — Dynamic variable for advanced mode only. Use `keypress` to announce the keypress for consumer to chooes. **Note** Provide either `audio_asset_id` or `audio_variable`, but not both.
    - custom_audio_type (required)
      
      string, possible values: "advanced", "standard", default: "standard" — Select custom audio type. -'standard' - Choose an audio file. The audio prompt must include all words, numbers, and keypress digits as part of the message. Variables cannot be used with this option. -'advanced' - With this option, the audio message can be split into multiple reusable audio parts. Variables are needed. Set up the digits library before using numbers with this option.
  - offer_number_message
    
    string, default: "We'll call you back using the phone number {{current phone number}}. If you want to use a different number, enter it now and then press {{keyPress}}. Otherwise, please stay on the line or press {{keyPress}} now." — The message to play to consumer asking for a call back phone number. Do not edit or remove symbols and text in {{}}. {{keyPress}} plays the keypress configured in 'callback_confirm_keypress' to the consumer.
  - offer_number_message_custom_audio
    
    object — The prerecorded audio message to play to consumers asking for a call back phone number. **Note** Provide either 'offer_number_message' or 'offer_number_message_custom_audio'.
    - custom_audio (required)
      
      array — Set the custom audio settings for the message will be played to the consumer before selecting a keypress. Currently, 'standard' mode supports a single audio message file. Specify using 'audio_asset_id' only. 'advanced' mode supports up to 7 pre-recorded audio message files. Combine per-recorded audio file 'audio_asset_id' and dynamic variable 'audio_variable', here the variable is for {{keypress}}. For each part, use 'audio_asset_id' or 'audio_variable'. **Advanced mode example** { "order": 1, "audio_asset_id": "asset_play_message_prefix" }, { "order": 2, "audio_variable": "keypress" }, { "order": 3, "audio_asset_id":"asset_play_message_suffix" }
      
      Items:
      - order (required)
        
        integer — The order to play audio.
      - audio_asset_id
        
        string — ID of the audio asset choose to play message to consumer **Note** Provide either `audio_asset_id` or `audio_variable`, but not both.
      - audio_variable
        
        string, possible values: "keypress", default: "keypress" — Dynamic variable for advanced mode only. Use `keypress` to announce the keypress for consumer to chooes. **Note** Provide either `audio_asset_id` or `audio_variable`, but not both.
    - custom_audio_type (required)
      
      string, possible values: "advanced", "standard", default: "standard" — Select custom audio type. -'standard' - Choose an audio file. The audio prompt must include all words, numbers, and keypress digits as part of the message. Variables cannot be used with this option. -'advanced' - With this option, the audio message can be split into multiple reusable audio parts. Variables are needed. Set up the digits library before using numbers with this option.
  - outbound_dial_greeting_message
    
    string, default: "Thanks for waiting in the queue. You will be connected to the next available agent shortly." — greeting message to callers before they are connected to an agent.
  - outbound_dial_greeting_message_custom_audio
    
    object — Play prerecorded greeting message to callers before they are connected to an agent. **Note** Provider either 'outbound_dial_greeting_message' or 'outbound_dial_greeting_message_custom_audio'.
    - custom_audio (required)
      
      array — Set the custom audio settings for the message will be played to the consumer before selecting a keypress. Currently, 'standard' mode supports a single audio message file. Specify using 'audio_asset_id' only. 'advanced' mode supports up to 7 pre-recorded audio message files. Combine per-recorded audio file 'audio_asset_id' and dynamic variable 'audio_variable', here the variable is for {{keypress}}. For each part, use 'audio_asset_id' or 'audio_variable'. **Advanced mode example** { "order": 1, "audio_asset_id": "asset_play_message_prefix" }, { "order": 2, "audio_variable": "keypress" }, { "order": 3, "audio_asset_id":"asset_play_message_suffix" }
      
      Items:
      - order (required)
        
        integer — The order to play audio.
      - audio_asset_id
        
        string — ID of the audio asset choose to play message to consumer **Note** Provide either `audio_asset_id` or `audio_variable`, but not both.
      - audio_variable
        
        string, possible values: "keypress", default: "keypress" — Dynamic variable for advanced mode only. Use `keypress` to announce the keypress for consumer to chooes. **Note** Provide either `audio_asset_id` or `audio_variable`, but not both.
    - custom_audio_type (required)
      
      string, possible values: "advanced", "standard", default: "standard" — Select custom audio type. -'standard' - Choose an audio file. The audio prompt must include all words, numbers, and keypress digits as part of the message. Variables cannot be used with this option. -'advanced' - With this option, the audio message can be split into multiple reusable audio parts. Variables are needed. Set up the digits library before using numbers with this option.
  - outbound_dial_option
    
    string, possible values: "auto_greeting", "directly_connect" — Choose the outbound method for how callers are connected when they receive a callback.
- play_message
  
  string — The text message to play for the keypress.
- play_message_custom_audio
  
  object — The prerecorded audio message to play for the keypress. **Note** Provide either 'play_message' or 'play_message_custom_audio'.
  - custom_audio (required)
    
    array — Set the custom audio settings for the message will be played to the consumer before selecting a keypress. Currently, 'standard' mode supports a single audio message file. Specify using 'audio_asset_id' only. 'advanced' mode supports up to 7 pre-recorded audio message files. Combine per-recorded audio file 'audio_asset_id' and dynamic variable 'audio_variable', here the variable is for {{keypress}}. For each part, use 'audio_asset_id' or 'audio_variable'. **Advanced mode example** { "order": 1, "audio_asset_id": "asset_play_message_prefix" }, { "order": 2, "audio_variable": "keypress" }, { "order": 3, "audio_asset_id":"asset_play_message_suffix" }
    
    Items:
    - order (required)
      
      integer — The order to play audio.
    - audio_asset_id
      
      string — ID of the audio asset choose to play message to consumer **Note** Provide either `audio_asset_id` or `audio_variable`, but not both.
    - audio_variable
      
      string, possible values: "keypress", default: "keypress" — Dynamic variable for advanced mode only. Use `keypress` to announce the keypress for consumer to chooes. **Note** Provide either `audio_asset_id` or `audio_variable`, but not both.
  - custom_audio_type (required)
    
    string, possible values: "advanced", "standard", default: "standard" — Select custom audio type. -'standard' - Choose an audio file. The audio prompt must include all words, numbers, and keypress digits as part of the message. Variables cannot be used with this option. -'advanced' - With this option, the audio message can be split into multiple reusable audio parts. Variables are needed. Set up the digits library before using numbers with this option.
- route_to_flow_id
  
  string — Select a voice flow to route when the chosen menu action is `route_flow`. Get the voice flow's ID from the [**List flows API**](/docs/api/contact-center/#tag/flows/get/contact_center/flows).
- voice_mail_inbox_id
  
  string — Select a voice mail inbox when the chosen menu action is `leave_voicemail`. Get the voicemail inbox's ID from the [**List Inboxes API**](/docs/api/contact-center/#tag/inboxes/get/contact_center/inboxes).
play_interval (required)

integer — Time, in seconds, to offer menu sets when consumers will be offered the menu, as long as they're still waiting. When this time is less than their estimated wait time, they will be asked right away. Maximum time is less than the maximum wait duration.
voice_id (required)

string, possible values: "Danielle", "Gregory", "Ivy", "Joanna", "Joey", "Justin", "Kendra", "Kevin", "Kimberly", "Matthew", "Ruth", "Salli", "Stephen" — The voice used to play the menu prompts.
accept_timeout

integer — Time to accept menu, at 5 second intervals. `0` means accept menu at any time.
invalid_option_message_custom_audio

object — Play prerecorded audio message to consumer when they press a phone key for invalid menu option.
- custom_audio (required)
  
  array — Set the custom audio settings for the message will be played to the consumer before selecting a keypress. Currently, 'standard' mode supports a single audio message file. Specify using 'audio_asset_id' only. 'advanced' mode supports up to 7 pre-recorded audio message files. Combine per-recorded audio file 'audio_asset_id' and dynamic variable 'audio_variable', here the variable is for {{keypress}}. For each part, use 'audio_asset_id' or 'audio_variable'. **Advanced mode example** { "order": 1, "audio_asset_id": "asset_play_message_prefix" }, { "order": 2, "audio_variable": "keypress" }, { "order": 3, "audio_asset_id":"asset_play_message_suffix" }
  
  Items:
  - order (required)
    
    integer — The order to play audio.
  - audio_asset_id
    
    string — ID of the audio asset choose to play message to consumer **Note** Provide either `audio_asset_id` or `audio_variable`, but not both.
  - audio_variable
    
    string, possible values: "keypress", default: "keypress" — Dynamic variable for advanced mode only. Use `keypress` to announce the keypress for consumer to chooes. **Note** Provide either `audio_asset_id` or `audio_variable`, but not both.
- custom_audio_type (required)
  
  string, possible values: "advanced", "standard", default: "standard" — Select custom audio type. -'standard' - Choose an audio file. The audio prompt must include all words, numbers, and keypress digits as part of the message. Variables cannot be used with this option. -'advanced' - With this option, the audio message can be split into multiple reusable audio parts. Variables are needed. Set up the digits library before using numbers with this option.
loop_interval

integer — Loop play interval, in seconds. Required when `loop_play` is `true`.
loop_play

boolean — Enable loop play based on loop interval time.

Example:

{
  "menu_language_code": "en-US",
  "voice_id": "Joanna",
  "accept_timeout": 10,
  "play_interval": 60,
  "loop_play": false,
  "loop_interval": 120,
  "menu_options": [
    {
      "keypress": "1",
      "menu_action": "request_callback",
      "play_message": "If you would like to leave a voicemail, press {{keyPress}}.\nDo not edit or remove symbols and text in {{}}, this will play and tell consumer the keypress for the menu action.",
      "play_message_custom_audio": {
        "custom_audio_type": "standard",
        "custom_audio": [
          {
            "order": 1,
            "audio_asset_id": "-6y2_bOWTBixtxmNywboJg",
            "audio_variable": "keypress"
          }
        ]
      },
      "route_to_flow_id": "c0SjVYqFTzOKs7wgAXM5cQ",
      "voice_mail_inbox_id": "rdc5hgEDTKuEVI7nz0umDg",
      "callback_settings": {
        "callback_number_type": "queue_default_caller_id",
        "callback_confirm_keypress": "#",
        "accept_callback_timeout": 10,
        "enable_offer_phone_number": false,
        "offer_number_message": "We'll call you back using the phone number {{current phone number}}. If you want to use a different number, enter it now and then press {{keyPress}}. Otherwise, please stay on the line or press {{keyPress}} now.",
        "offer_number_message_custom_audio": {
          "custom_audio_type": "standard",
          "custom_audio": [
            {
              "order": 1,
              "audio_asset_id": "-6y2_bOWTBixtxmNywboJg",
              "audio_variable": "keypress"
            }
          ]
        },
        "callback_confirm_message": "Your request for callback is confirmed. We will use the phone number {{current phone number}} and extension {{extension number}} to call you back when it's your turn in the queue",
        "callback_confirm_message_custom_audio": {
          "custom_audio_type": "standard",
          "custom_audio": [
            {
              "order": 1,
              "audio_asset_id": "-6y2_bOWTBixtxmNywboJg",
              "audio_variable": "keypress"
            }
          ]
        },
        "enable_offer_extension_number": false,
        "offer_extension_number_message": "We'll call you back using the phone number {{current phone number}}. If you want to add an extension, enter it now and then press {{keyPress}}. Otherwise, please stay on the line or press {{keyPress}} now.",
        "offer_extension_number_message_custom_audio": {
          "custom_audio_type": "standard",
          "custom_audio": [
            {
              "order": 1,
              "audio_asset_id": "-6y2_bOWTBixtxmNywboJg",
              "audio_variable": "keypress"
            }
          ]
        },
        "confirm_extension_number_message": "You entered the extension {{extension number}}. If this is correct, press {{keyPress}} to confirm. Otherwise, enter your extension number and then press {{keyPress}}.",
        "confirm_extension_number_message_custom_audio": {
          "custom_audio_type": "standard",
          "custom_audio": [
            {
              "order": 1,
              "audio_asset_id": "-6y2_bOWTBixtxmNywboJg",
              "audio_variable": "keypress"
            }
          ]
        },
        "outbound_dial_option": "auto_greeting",
        "outbound_dial_greeting_message": "Thanks for waiting in the queue. You will be connected to the next available agent shortly.",
        "outbound_dial_greeting_message_custom_audio": {
          "custom_audio_type": "standard",
          "custom_audio": [
            {
              "order": 1,
              "audio_asset_id": "-6y2_bOWTBixtxmNywboJg",
              "audio_variable": "keypress"
            }
          ]
        },
        "callback_timeout": 10,
        "enable_callback_cancel_message": false,
        "callback_cancel_message": "Your callback has been canceled due to high call volumes. Please try calling again.",
        "callback_cancel_message_custom_audio": {
          "custom_audio_type": "standard",
          "custom_audio": [
            {
              "order": 1,
              "audio_asset_id": "-6y2_bOWTBixtxmNywboJg",
              "audio_variable": "keypress"
            }
          ]
        },
        "callback_returning_message": "Hello again. You have a callback set up. Press {{keyPress}} to cancel your callback and wait on the line, or hang up to keep your callback request and end this call.",
        "callback_returning_message_custom_audio": {
          "custom_audio_type": "standard",
          "custom_audio": [
            {
              "order": 1,
              "audio_asset_id": "-6y2_bOWTBixtxmNywboJg",
              "audio_variable": "keypress"
            }
          ]
        },
        "enable_callback_offer_time": false,
        "callback_offer_timezone_id": "America/Los_Angeles",
        "callback_offer_time": [
          {
            "callback_offer_day": "Mon",
            "callback_offer_start_time": "09:00",
            "callback_offer_end_time": "18:00"
          }
        ],
        "enable_callback_return_time": false,
        "callback_return_timezone_id": "America/Los_Angeles",
        "callback_return_day": [
          {
            "callback_return_day": "Mon",
            "callback_return_start_time": "09:00",
            "callback_return_end_time": "18:00"
          }
        ],
        "enable_advanced_callback_confirmation": false,
        "advanced_callback_confirmation": {
          "keypress_voice_message": "1",
          "advanced_callback_confirm_message": "Your callback request is confirmed. We will use the phone number {{phoneNumber}} to call you back when it's your turn in the queue. To leave a voice message, press {{keyPress}}. Or hang up to end the call.",
          "callback_voice_message_time_limit": 1,
          "enable_voice_message_transcription": false,
          "callback_voice_message_display_time": 5,
          "advanced_callback_confirm_message_with_extension": "Your request for callback is confirmed. We'll call you back at your {{current phone number}} and extension {{extension number}} when it's your turn in the queue. To leave a voice message, press {{keyPress}}, or hang up to end the call.",
          "greeting_message": "Please record your voice message after the tone, press {{starKey}} to discard and end call, or press any digit key to save the recording.",
          "end_message": "Good bye.",
          "save_recording_message": "Save recording message to play.",
          "short_recording_message": "Sorry, your recording is too short. Please try again.",
          "keypress_listen_recording_message": "Press {{keyPress}} to listen to the voice message.",
          "keypress_save_recording_message": "Press {{keyPress}} to save the voice message and end the call.",
          "keypress_re_recording_message": "Press {{keyPress}} to re-record your voice message."
        }
      }
    }
  ],
  "invalid_option_message_custom_audio": {
    "custom_audio_type": "standard",
    "custom_audio": [
      {
        "order": 1,
        "audio_asset_id": "-6y2_bOWTBixtxmNywboJg",
        "audio_variable": "keypress"
      }
    ]
  }
}

Responses

Status: 201 HTTP Status Code: `201` Queue menu based interrupt assigned.

Content-Type: application/json

accept_timeout

integer — Time to accept menu, in 5 second intervals. `0` means accept the menu at any time.
invalid_option_message_custom_audio

object — Play prerecorded audio message to consumer when they press a phone key for an invalid menu option.
- custom_audio
  
  array — Set the custom audio settings for the message will be played to the consumer before selecting a keypress. Currently, 'standard' mode supports a single audio message file. Specify using 'audio_asset_id' only. 'advanced' mode supports up to 7 pre-recorded audio message files. Combine per-recorded audio file 'audio_asset_id' and dynamic variable 'audio_variable', here the variable is for {{keypress}}. For each part, use 'audio_asset_id' or 'audio_variable'. **Advanced mode example** { "order": 1, "audio_asset_id": "asset_play_message_prefix" }, { "order": 2, "audio_variable": "keypress" }, { "order": 3, "audio_asset_id":"asset_play_message_suffix" }
  
  Items:
  - order (required)
    
    integer — The order to play audio.
  - audio_asset_id
    
    string — ID of the audio asset choose to play message to consumer **Note** Provide either `audio_asset_id` or `audio_variable`, but not both.
  - audio_variable
    
    string, possible values: "keypress", default: "keypress" — Dynamic variable for advanced mode only. Use `keypress` to announce the keypress for consumer to chooes. **Note** Provide either `audio_asset_id` or `audio_variable`, but not both.
- custom_audio_type
  
  string, possible values: "advanced", "standard", default: "standard" — Select custom audio type. -'standard' - Choose an audio file. The audio prompt must include all words, numbers, and keypress digits as part of the message. Variables cannot be used with this option. -'advanced' - With this option, the audio message can be split into multiple reusable audio parts. Variables are needed. Set up the digits library before using numbers with this option.
loop_interval

integer — Loop play interval, in seconds. Required when `loop_play` is `true`.
loop_play

boolean — Enable loop play based on loop interval time.
menu_language_code

string, possible values: "zh-CN", "zh-TW", "yue-CN", "cmn-CN", "da-DK", "nl-NL", "en-AU", "en-NZ", "en-GB", "en-US", "fr-CA", "fr-FR", "de-DE", "it-IT", "ja-JP", "ko-KR", "pl-PL", "pt-BR", "pt-PT", "ro-RO", "ru-RU", "es-ES", "es-MX", "es-US", "sv-SE", "tr-TR" — The menu language and voice for default messages for menu and callback prompts.
menu_options

array — A list of menu options for keypresses and detail menu action. Each keypress can only relate to one action.

Items:
- keypress (required)
  
  string, possible values: "1", "2", "3", "4", "5", "6", "7", "8", "9", "0", "*", "#" — The keypress provided in the menu.
- menu_action (required)
  
  string, possible values: "request_callback", "leave_voicemail", "route_flow", "repeat_menu" — The action for selecting the menu when pressing a key.
- callback_settings
  
  object — Set call back settings when menu action choose as `request_callback`.
  - accept_callback_timeout
    
    integer — Time to accept callback menu, in 5 second intervals.
  - callback_cancel_message
    
    string, default: "Your callback has been canceled due to high call volumes. Please try calling again." — Message sent to notify of callback cancellation.
  - callback_cancel_message_custom_audio
    
    object — Play prerecorded audio message about callback cancellation. **Note** Provide either 'callback_cancel_message' or 'callback_cancel_message_custom_audio'.
    - custom_audio
      
      array — Set the custom audio settings for the message will be played to the consumer before selecting a keypress. Currently, 'standard' mode supports a single audio message file. Specify using 'audio_asset_id' only. 'advanced' mode supports up to 7 pre-recorded audio message files. Combine per-recorded audio file 'audio_asset_id' and dynamic variable 'audio_variable', here the variable is for {{keypress}}. For each part, use 'audio_asset_id' or 'audio_variable'. **Advanced mode example** { "order": 1, "audio_asset_id": "asset_play_message_prefix" }, { "order": 2, "audio_variable": "keypress" }, { "order": 3, "audio_asset_id":"asset_play_message_suffix" }
      
      Items:
      - order (required)
        
        integer — The order to play audio.
      - audio_asset_id
        
        string — ID of the audio asset choose to play message to consumer **Note** Provide either `audio_asset_id` or `audio_variable`, but not both.
      - audio_variable
        
        string, possible values: "keypress", default: "keypress" — Dynamic variable for advanced mode only. Use `keypress` to announce the keypress for consumer to chooes. **Note** Provide either `audio_asset_id` or `audio_variable`, but not both.
    - custom_audio_type
      
      string, possible values: "advanced", "standard", default: "standard" — Select custom audio type. -'standard' - Choose an audio file. The audio prompt must include all words, numbers, and keypress digits as part of the message. Variables cannot be used with this option. -'advanced' - With this option, the audio message can be split into multiple reusable audio parts. Variables are needed. Set up the digits library before using numbers with this option.
  - callback_confirm_keypress
    
    string, possible values: "#", "*" — Callers use this key to confirm in response to message for a request callback.
  - callback_confirm_message
    
    string, default: "Your request for callback is confirmed. We will use the phone number {{current phone number}} and extension {{extension number}} to call you back when it's your turn in the queue" — Message to returning caller with callback set up. Do not edit or remove symbols and text in {{}}. The {{keyPress}} will play the keypress configured in 'callback_confirm_keypress' to the consumer.
  - callback_confirm_message_custom_audio
    
    object — Play prerecorded audio message to the returning caller with callback set up. **Note** Provide either 'callback_confirm_message' or 'callback_confirm_message_custom_audio'.
    - custom_audio
      
      array — Set the custom audio settings for the message will be played to the consumer before selecting a keypress. Currently, 'standard' mode supports a single audio message file. Specify using 'audio_asset_id' only. 'advanced' mode supports up to 7 pre-recorded audio message files. Combine per-recorded audio file 'audio_asset_id' and dynamic variable 'audio_variable', here the variable is for {{keypress}}. For each part, use 'audio_asset_id' or 'audio_variable'. **Advanced mode example** { "order": 1, "audio_asset_id": "asset_play_message_prefix" }, { "order": 2, "audio_variable": "keypress" }, { "order": 3, "audio_asset_id":"asset_play_message_suffix" }
      
      Items:
      - order (required)
        
        integer — The order to play audio.
      - audio_asset_id
        
        string — ID of the audio asset choose to play message to consumer **Note** Provide either `audio_asset_id` or `audio_variable`, but not both.
      - audio_variable
        
        string, possible values: "keypress", default: "keypress" — Dynamic variable for advanced mode only. Use `keypress` to announce the keypress for consumer to chooes. **Note** Provide either `audio_asset_id` or `audio_variable`, but not both.
    - custom_audio_type
      
      string, possible values: "advanced", "standard", default: "standard" — Select custom audio type. -'standard' - Choose an audio file. The audio prompt must include all words, numbers, and keypress digits as part of the message. Variables cannot be used with this option. -'advanced' - With this option, the audio message can be split into multiple reusable audio parts. Variables are needed. Set up the digits library before using numbers with this option.
  - callback_confirm_messsage
    
    string, default: "Your request for callback is confirmed. We will use the phone number {{current phone number}} and extension {{extension number}} to call you back when it's your turn in the queue" — Message to returning caller with callback set up. Do not edit or remove symbols and text in {{}}. The {{keyPress}} will play the keypress configured in 'callback_confirm_keypress' to the consumer.
  - callback_number_type
    
    string, possible values: "flow_entry_id", "account_default_caller_id", "queue_default_caller_id" — Callback caller ID number type.
  - callback_offer_time
    
    array — Set the day when callbacks will be offered and returned to consumers. Required when `enable_callback_offer_time` is `true`.
    
    Items:
    - callback_offer_day
      
      string, possible values: "Mon", "Tue", "Wed", "Thu", "Fri", "Sat", "Sun" — The day callbacks will be offered to consumers.
    - callback_offer_end_time
      
      string — End time on the day that callback offer to consumers, between `00:00` and `23:59`.
    - callback_offer_start_time
      
      string — Start time on the day that callbacks are offered to consumers, between `00:00` and `23:59`.
  - callback_offer_timezone_id
    
    string — Set the [timezone](/docs/api/references/abbreviations/#timezones) when callbacks will be offered and returned to consumers. Required when `enable_callback_offer_time` is `true`.
  - callback_return_day
    
    array — The day when callbacks will be returned to consumers. Required when `enable_callback_return_time` is `true`.
    
    Items:
    - callback_return_day
      
      string, possible values: "Mon", "Tue", "Wed", "Thu", "Fri", "Sat", "Sun" — The day when callbacks will be returned to consumers.
    - callback_return_end_time
      
      string — The time range's end time when callbacks will be returned to consumers, between `00:00` and `23:59`.
    - callback_return_start_time
      
      string — The time range's start time when callbacks will be returned to consumers, between `00:00` and `23:59`.
  - callback_return_timezone_id
    
    string — Set the [timezoneID](/docs/api/references/abbreviations/#timezones) to limit the times when callbacks will be returned to consumers. Required when `enable_callback_return_time` is `true`.
  - callback_returning_message
    
    string, default: "Hello again. You have a callback set up. Press {{keyPress}} to cancel your callback and wait on the line. Or you can hang up to keep your callback request and end this call." — Message with callback setup sent to returning callers. Do not edit or remove symbols and text in {{}}. The {{keyPress}} will play to consumer the keypress configured in 'callback_confirm_keypress'.
  - callback_returning_message_custom_audio
    
    object — Play prerecorded audio message to returning caller with callback setup. **Note** Provide either 'callback_returning_message' or 'callback_returning_message_custom_audio'.
    - custom_audio
      
      array — Set the custom audio settings for the message will be played to the consumer before selecting a keypress. Currently, 'standard' mode supports a single audio message file. Specify using 'audio_asset_id' only. 'advanced' mode supports up to 7 pre-recorded audio message files. Combine per-recorded audio file 'audio_asset_id' and dynamic variable 'audio_variable', here the variable is for {{keypress}}. For each part, use 'audio_asset_id' or 'audio_variable'. **Advanced mode example** { "order": 1, "audio_asset_id": "asset_play_message_prefix" }, { "order": 2, "audio_variable": "keypress" }, { "order": 3, "audio_asset_id":"asset_play_message_suffix" }
      
      Items:
      - order (required)
        
        integer — The order to play audio.
      - audio_asset_id
        
        string — ID of the audio asset choose to play message to consumer **Note** Provide either `audio_asset_id` or `audio_variable`, but not both.
      - audio_variable
        
        string, possible values: "keypress", default: "keypress" — Dynamic variable for advanced mode only. Use `keypress` to announce the keypress for consumer to chooes. **Note** Provide either `audio_asset_id` or `audio_variable`, but not both.
    - custom_audio_type
      
      string, possible values: "advanced", "standard", default: "standard" — Select custom audio type. -'standard' - Choose an audio file. The audio prompt must include all words, numbers, and keypress digits as part of the message. Variables cannot be used with this option. -'advanced' - With this option, the audio message can be split into multiple reusable audio parts. Variables are needed. Set up the digits library before using numbers with this option.
  - callback_timeout
    
    integer — How long callbacks will remain as tasks in the queue, in seconds
  - confirm_extension_number_message
    
    string, default: "You entered the extension {{extension number}}. If this is correct, press {{keyPress}} to confirm. Otherwise, enter your extension number and then press {{keyPress}}." — Message to ask the caller to confirm the phone number extension. Do not edit or remove symbols and text in {{}}. The {{keyPress}} will play the keypress configured in 'callback_confirm_keypress' to the consumer.
  - confirm_extension_number_message_custom_audio
    
    object — Play prerecorded audio message asking the caller to confirm the phone number extension. **Note** Provide either 'confirm_extension_number_message' or 'confirm_extension_number_message_custom_audio'.
    - custom_audio
      
      array — Set the custom audio settings for the message will be played to the consumer before selecting a keypress. Currently, 'standard' mode supports a single audio message file. Specify using 'audio_asset_id' only. 'advanced' mode supports up to 7 pre-recorded audio message files. Combine per-recorded audio file 'audio_asset_id' and dynamic variable 'audio_variable', here the variable is for {{keypress}}. For each part, use 'audio_asset_id' or 'audio_variable'. **Advanced mode example** { "order": 1, "audio_asset_id": "asset_play_message_prefix" }, { "order": 2, "audio_variable": "keypress" }, { "order": 3, "audio_asset_id":"asset_play_message_suffix" }
      
      Items:
      - order (required)
        
        integer — The order to play audio.
      - audio_asset_id
        
        string — ID of the audio asset choose to play message to consumer **Note** Provide either `audio_asset_id` or `audio_variable`, but not both.
      - audio_variable
        
        string, possible values: "keypress", default: "keypress" — Dynamic variable for advanced mode only. Use `keypress` to announce the keypress for consumer to chooes. **Note** Provide either `audio_asset_id` or `audio_variable`, but not both.
    - custom_audio_type
      
      string, possible values: "advanced", "standard", default: "standard" — Select custom audio type. -'standard' - Choose an audio file. The audio prompt must include all words, numbers, and keypress digits as part of the message. Variables cannot be used with this option. -'advanced' - With this option, the audio message can be split into multiple reusable audio parts. Variables are needed. Set up the digits library before using numbers with this option.
  - enable_callback_cancel_message
    
    boolean — The message sent to consumers if callbacks are canceled.
  - enable_callback_offer_time
    
    boolean — Limit the times when callbacks will be offered to consumers.
  - enable_callback_return_time
    
    boolean — Limit the times when callbacks will be returned to consumers.
  - enable_offer_extension_number
    
    boolean — Lets callers to add an extension to their callback phone number so that callers who don't have a direct line can still be reached directly.
  - enable_offer_phone_number
    
    boolean — Allow callers to provide a different callback number.
  - offer_extension_number_message
    
    string, default: "We'll call you back using the phone number {{current phone number}}. If you want to add an extension, enter it now and then press {{keyPress}}. Otherwise, please stay on the line or press {{keyPress}} now." — Message to ask the caller to offer a phone number extension. Do not edit or remove symbols and text in {{}}. The {{keyPress}} will play the keypress configured in 'callback_confirm_keypress' to the consumer.
  - offer_extension_number_message_custom_audio
    
    object — Play prerecorded message asking the caller to give a phone number extension. **Note** Provide either 'offer_extension_number_message' or 'offer_extension_number_message_custom_audio'.
    - custom_audio
      
      array — Set the custom audio settings for the message will be played to the consumer before selecting a keypress. Currently, 'standard' mode supports a single audio message file. Specify using 'audio_asset_id' only. 'advanced' mode supports up to 7 pre-recorded audio message files. Combine per-recorded audio file 'audio_asset_id' and dynamic variable 'audio_variable', here the variable is for {{keypress}}. For each part, use 'audio_asset_id' or 'audio_variable'. **Advanced mode example** { "order": 1, "audio_asset_id": "asset_play_message_prefix" }, { "order": 2, "audio_variable": "keypress" }, { "order": 3, "audio_asset_id":"asset_play_message_suffix" }
      
      Items:
      - order (required)
        
        integer — The order to play audio.
      - audio_asset_id
        
        string — ID of the audio asset choose to play message to consumer **Note** Provide either `audio_asset_id` or `audio_variable`, but not both.
      - audio_variable
        
        string, possible values: "keypress", default: "keypress" — Dynamic variable for advanced mode only. Use `keypress` to announce the keypress for consumer to chooes. **Note** Provide either `audio_asset_id` or `audio_variable`, but not both.
    - custom_audio_type
      
      string, possible values: "advanced", "standard", default: "standard" — Select custom audio type. -'standard' - Choose an audio file. The audio prompt must include all words, numbers, and keypress digits as part of the message. Variables cannot be used with this option. -'advanced' - With this option, the audio message can be split into multiple reusable audio parts. Variables are needed. Set up the digits library before using numbers with this option.
  - offer_number_message
    
    string, default: "We'll call you back using the phone number {{current phone number}}. If you want to use a different number, enter it now and then press {{keyPress}}. Otherwise, please stay on the line or press {{keyPress}} now." — The message to play to ask the consumer to offer a callback phone number. Do not edit or remove symbols and text in {{}}. The {{keyPress}} will play the keypress configured in 'callback_confirm_keypress' to the consumer.
  - offer_number_message_custom_audio
    
    object — Play prerecorded audio message to consumer asking for a call back phone number. **Note** Provide either 'offer_number_message' or 'offer_number_message_custom_audio'.
    - custom_audio
      
      array — Set the custom audio settings for the message will be played to the consumer before selecting a keypress. Currently, 'standard' mode supports a single audio message file. Specify using 'audio_asset_id' only. 'advanced' mode supports up to 7 pre-recorded audio message files. Combine per-recorded audio file 'audio_asset_id' and dynamic variable 'audio_variable', here the variable is for {{keypress}}. For each part, use 'audio_asset_id' or 'audio_variable'. **Advanced mode example** { "order": 1, "audio_asset_id": "asset_play_message_prefix" }, { "order": 2, "audio_variable": "keypress" }, { "order": 3, "audio_asset_id":"asset_play_message_suffix" }
      
      Items:
      - order (required)
        
        integer — The order to play audio.
      - audio_asset_id
        
        string — ID of the audio asset choose to play message to consumer **Note** Provide either `audio_asset_id` or `audio_variable`, but not both.
      - audio_variable
        
        string, possible values: "keypress", default: "keypress" — Dynamic variable for advanced mode only. Use `keypress` to announce the keypress for consumer to chooes. **Note** Provide either `audio_asset_id` or `audio_variable`, but not both.
    - custom_audio_type
      
      string, possible values: "advanced", "standard", default: "standard" — Select custom audio type. -'standard' - Choose an audio file. The audio prompt must include all words, numbers, and keypress digits as part of the message. Variables cannot be used with this option. -'advanced' - With this option, the audio message can be split into multiple reusable audio parts. Variables are needed. Set up the digits library before using numbers with this option.
  - outbound_dial_greeting_message
    
    string, default: "Thanks for waiting in the queue. You will be connected to the next available agent in a short moment" — Greeting message sent to callers before they are connected to agent.
  - outbound_dial_greeting_message_custom_audio
    
    object — Play prerecorded greeting message to callers before they are connected to an agent. **Note** Provider either 'outbound_dial_greeting_message' or 'outbound_dial_greeting_message_custom_audio'.
    - custom_audio
      
      array — Set the custom audio settings for the message will be played to the consumer before selecting a keypress. Currently, 'standard' mode supports a single audio message file. Specify using 'audio_asset_id' only. 'advanced' mode supports up to 7 pre-recorded audio message files. Combine per-recorded audio file 'audio_asset_id' and dynamic variable 'audio_variable', here the variable is for {{keypress}}. For each part, use 'audio_asset_id' or 'audio_variable'. **Advanced mode example** { "order": 1, "audio_asset_id": "asset_play_message_prefix" }, { "order": 2, "audio_variable": "keypress" }, { "order": 3, "audio_asset_id":"asset_play_message_suffix" }
      
      Items:
      - order (required)
        
        integer — The order to play audio.
      - audio_asset_id
        
        string — ID of the audio asset choose to play message to consumer **Note** Provide either `audio_asset_id` or `audio_variable`, but not both.
      - audio_variable
        
        string, possible values: "keypress", default: "keypress" — Dynamic variable for advanced mode only. Use `keypress` to announce the keypress for consumer to chooes. **Note** Provide either `audio_asset_id` or `audio_variable`, but not both.
    - custom_audio_type
      
      string, possible values: "advanced", "standard", default: "standard" — Select custom audio type. -'standard' - Choose an audio file. The audio prompt must include all words, numbers, and keypress digits as part of the message. Variables cannot be used with this option. -'advanced' - With this option, the audio message can be split into multiple reusable audio parts. Variables are needed. Set up the digits library before using numbers with this option.
  - outbound_dial_option
    
    string, possible values: "auto_greeting", "directly_connect" — Choose the outbound method for how callers are connected when they receive a callback.
- play_message
  
  string — The keypress text message. This tells the consumer the menu action's keypress. Do not edit or remove symbols and text in `{{}}`.
- play_message_custom_audio
  
  object — The prerecorded audio message to play for the keypress. **Note** Provide either 'play_message' or 'play_message_custom_audio'.
  - custom_audio
    
    array — Set the custom audio settings for the message will be played to the consumer before selecting a keypress. Currently, 'standard' mode supports a single audio message file. Specify using 'audio_asset_id' only. 'advanced' mode supports up to 7 pre-recorded audio message files. Combine per-recorded audio file 'audio_asset_id' and dynamic variable 'audio_variable', here the variable is for {{keypress}}. For each part, use 'audio_asset_id' or 'audio_variable'. **Advanced mode example** { "order": 1, "audio_asset_id": "asset_play_message_prefix" }, { "order": 2, "audio_variable": "keypress" }, { "order": 3, "audio_asset_id":"asset_play_message_suffix" }
    
    Items:
    - order (required)
      
      integer — The order to play audio.
    - audio_asset_id
      
      string — ID of the audio asset choose to play message to consumer **Note** Provide either `audio_asset_id` or `audio_variable`, but not both.
    - audio_variable
      
      string, possible values: "keypress", default: "keypress" — Dynamic variable for advanced mode only. Use `keypress` to announce the keypress for consumer to chooes. **Note** Provide either `audio_asset_id` or `audio_variable`, but not both.
  - custom_audio_type
    
    string, possible values: "advanced", "standard", default: "standard" — Select custom audio type. -'standard' - Choose an audio file. The audio prompt must include all words, numbers, and keypress digits as part of the message. Variables cannot be used with this option. -'advanced' - With this option, the audio message can be split into multiple reusable audio parts. Variables are needed. Set up the digits library before using numbers with this option.
- route_to_flow_id
  
  string — Select a voice flow to route when the chosen menu action is `route_flow`. Get the voice flow's ID from [**List flows API**](/docs/api/contact-center/#tag/flows/get/contact_center/flows).
- voice_mail_inbox_id
  
  string — Select a voice mail inbox when the chosen menu action is `leave_voicemail`. Get the voicemail inbox's ID from [**List Inboxes API**](/docs/api/contact-center/#tag/inboxes/get/contact_center/inboxes).
play_interval

integer — Time, in seconds, when consumers will be offered the menu, as long as they're still waiting. When this time is less than their estimated wait time, they will be offered the menu right away. Maximum time is less than the maximum wait duration.
queue_id

string — Contact Center queue identifier.
voice_id

string, possible values: "Danielle", "Gregory", "Ivy", "Joanna", "Joey", "Justin", "Kendra", "Kevin", "Kimberly", "Matthew", "Ruth", "Salli", "Stephen" — The voice used to play the menu prompts.

Example:

{
  "queue_id": "zeYjXoDOS_eV1QmTpj63PQ",
  "menu_language_code": "en-US",
  "voice_id": "Joanna",
  "accept_timeout": 10,
  "play_interval": 60,
  "loop_play": false,
  "loop_interval": 120,
  "menu_options": [
    {
      "keypress": "1",
      "menu_action": "request_callback",
      "play_message": "If you would like to leave a voicemail, press {{keyPress}}.Do not edit or remove symbols and text in {{}}, this will play and tell consumer the keypress for the menu action.",
      "play_message_custom_audio": {
        "custom_audio_type": "standard",
        "custom_audio": [
          {
            "order": 1,
            "audio_asset_id": "-6y2_bOWTBixtxmNywboJg",
            "audio_variable": "keypress"
          }
        ]
      },
      "route_to_flow_id": "c0SjVYqFTzOKs7wgAXM5cQ",
      "voice_mail_inbox_id": "rdc5hgEDTKuEVI7nz0umDg",
      "callback_settings": {
        "callback_number_type": "queue_default_caller_id",
        "callback_confirm_keypress": "#",
        "accept_callback_timeout": 10,
        "enable_offer_phone_number": false,
        "offer_number_message": "We'll call you back using the phone number {{current phone number}}. If you want to use a different number, enter it now and then press {{keyPress}}. Otherwise, please stay on the line or press {{keyPress}} now.",
        "offer_number_message_custom_audio": {
          "custom_audio_type": "standard",
          "custom_audio": [
            {
              "order": 1,
              "audio_asset_id": "-6y2_bOWTBixtxmNywboJg",
              "audio_variable": "keypress"
            }
          ]
        },
        "callback_confirm_message": "Your request for callback is confirmed. We will use the phone number {{current phone number}} and extension {{extension number}} to call you back when it's your turn in the queue",
        "callback_confirm_message_custom_audio": {
          "custom_audio_type": "standard",
          "custom_audio": [
            {
              "order": 1,
              "audio_asset_id": "-6y2_bOWTBixtxmNywboJg",
              "audio_variable": "keypress"
            }
          ]
        },
        "enable_offer_extension_number": false,
        "offer_extension_number_message": "We'll call you back using the phone number {{current phone number}}. If you want to add an extension, enter it now and then press {{keyPress}}. Otherwise, please stay on the line or press {{keyPress}} now.",
        "offer_extension_number_message_custom_audio": {
          "custom_audio_type": "standard",
          "custom_audio": [
            {
              "order": 1,
              "audio_asset_id": "-6y2_bOWTBixtxmNywboJg",
              "audio_variable": "keypress"
            }
          ]
        },
        "confirm_extension_number_message": "You entered the extension {{extension number}}. If this is correct, press {{keyPress}} to confirm. Otherwise, enter your extension number and then press {{keyPress}}.",
        "confirm_extension_number_message_custom_audio": {
          "custom_audio_type": "standard",
          "custom_audio": [
            {
              "order": 1,
              "audio_asset_id": "-6y2_bOWTBixtxmNywboJg",
              "audio_variable": "keypress"
            }
          ]
        },
        "outbound_dial_option": "auto_greeting",
        "outbound_dial_greeting_message": "Thanks for waiting in the queue. You will be connected to the next available agent in a short moment.",
        "outbound_dial_greeting_message_custom_audio": {
          "custom_audio_type": "standard",
          "custom_audio": [
            {
              "order": 1,
              "audio_asset_id": "-6y2_bOWTBixtxmNywboJg",
              "audio_variable": "keypress"
            }
          ]
        },
        "callback_timeout": 10,
        "enable_callback_cancel_message": false,
        "callback_cancel_message": "Your callback has been canceled due to high call volumes. Please try calling again.",
        "callback_cancel_message_custom_audio": {
          "custom_audio_type": "standard",
          "custom_audio": [
            {
              "order": 1,
              "audio_asset_id": "-6y2_bOWTBixtxmNywboJg",
              "audio_variable": "keypress"
            }
          ]
        },
        "callback_returning_message": "Hello again. You have a callback set up. Press {{keyPress}} to cancel your callback and wait on the line. Or you can hang up to keep your callback request and end this call.",
        "callback_returning_message_custom_audio": {
          "custom_audio_type": "standard",
          "custom_audio": [
            {
              "order": 1,
              "audio_asset_id": "-6y2_bOWTBixtxmNywboJg",
              "audio_variable": "keypress"
            }
          ]
        },
        "enable_callback_offer_time": false,
        "callback_offer_timezone_id": "America/Los_Angeles",
        "callback_offer_time": [
          {
            "callback_offer_day": "Mon",
            "callback_offer_start_time": "09:00",
            "callback_offer_end_time": "18:00"
          }
        ],
        "enable_callback_return_time": false,
        "callback_return_timezone_id": "America/Los_Angeles",
        "callback_return_day": [
          {
            "callback_return_day": "Mon",
            "callback_return_start_time": "09:00",
            "callback_return_end_time": "18:00"
          }
        ]
      }
    }
  ],
  "invalid_option_message_custom_audio": {
    "custom_audio_type": "standard",
    "custom_audio": [
      {
        "order": 1,
        "audio_asset_id": "-6y2_bOWTBixtxmNywboJg",
        "audio_variable": "keypress"
      }
    ]
  }
}

Status: 400 HTTP Status Code: `400` Bad Request Error Code: `1205` Queue channel type is invalid. Error Code: `1254` Bucket ID is invalid.

Status: 401 HTTP Status Code: `401` Unauthorized Error Code: `124` Invalid access token. Error Code: `124` Access token has expired. Error Code: `1002` The user associated with this access token was not found or is invalid.

Status: 403 HTTP Status Code: `403` Forbidden Error Code: `1021` User account is deactivated. Error Code: `1022` User does not have a Contact Center license. Error Code: `9001` The Contact Center user associated with this bearer token is missing privileges on their role required to operate this request.

Status: 404 HTTP Status Code: `404` Not Found Not found. Error Code: `1201` Queue does not exist: {queueId}. Error Code: `3001` Inbox does not exist: {voice_mail_inbox_id}. Error Code: `3201` Flow does not exist: {route_to_flow_id}.

Status: 429 HTTP Status Code: `429` Too Many Requests. For more information, see [rate limits](https://developers.zoom.us/docs/api/rate-limits/). Error Code: `4001` You have reached the maximum per-second rate limit for this API. Try again later.

Delete a queue's interrupt menu configuration

Method: DELETE
Path: /contact_center/queues/{queueId}/interrupt_menu
Tags: Queues

Deletes the interrupt menu configuration for a specific queue. This removes all menu-based interrupt settings including menu options, callback settings, voice prompts, and timing configurations.

This operation only works for voice queues. Other channel types will return an error.

Scopes: contact_center_queue:write:admin

Granular Scopes: contact_center:delete:queue:admin

Rate Limit Label: LIGHT

Responses

Status: 204 HTTP Status Code: `204` Interrupt menu deleted successfully. No content is returned.

Status: 400 HTTP Status Code: `400` Bad Request Error Code: `1205` Queue channel type is invalid. Error Code: `1254` Bucket ID is invalid.

Status: 401 HTTP Status Code: `401` Unauthorized Error Code: `124` Invalid access token. Error Code: `124` Access token has expired. Error Code: `1002` The user associated with this access token was not found or is invalid.

Status: 403 HTTP Status Code: `403` Forbidden Error Code: `1021` User account is deactivated. Error Code: `1022` User does not have a Contact Center license. Error Code: `9001` The Contact Center user associated with this bearer token is missing privileges on their role required to operate this request.

Status: 404 HTTP Status Code: `404` Not Found Error Code: `1201` Queue not found.

Status: 429 HTTP Status Code: `429` Too Many Requests. For more information, see [rate limits](https://developers.zoom.us/docs/api/rate-limits/). Error Code: `4001` You have reached the maximum per-second rate limit for this API. Try again later.

Get a queue's operating hours

Method: GET
Path: /contact_center/queues/{queueId}/operating_hours
Tags: Queues

Get information about a queue's operating hours.

Scopes: contact_center_queue:read:admin

Granular Scopes: contact_center:read:queue_operating_hours:admin

Rate Limit Label: LIGHT

Responses

Status: 200 HTTP Status Code: `200` Operating hours returned.

Content-Type: application/json

account_default_business_hour (required)

boolean — Whether the queue's business hour is the account default business hour.
business_hour_id (required)

string — The business hours' ID.
business_hour_name (required)

string — The business hours' name.
account_default_closure_set

boolean — Whether the queue's closure set is the account default.
closure_set_id

string — The closure's ID.
closure_set_name

string — The closure's name.
operating_hours_overflow_enabled

boolean — Specify consumer handling when the queue is unavailable.
overflow_to_default_goodbye_message

boolean — Reply system default goodbye message, then disconnect.
overflow_to_flow_id

string — The flow ID to receive the overflow.
overflow_to_flow_name

string — The name of flow to receive the overflow.
overflow_to_goodbye_message_asset_id

string — Reply goodbye message choose from an asset
overflow_to_goodbye_message_asset_name

string — Reply goodbye message choose from an asset name
overflow_to_inbox_id

string — The voicemail inbox ID to receive the overflow.
overflow_to_inbox_name

string — The name voicemail inbox to receive the overflow.
overflow_to_queue_id

string — The queue ID to receive the overflow.
overflow_to_queue_name

string — The name of queue to receive the overflow.

Example:

{
  "business_hour_id": "66ZjSQ7YTOescnINN_4vog",
  "business_hour_name": "Default Business hours",
  "closure_set_id": "Ixo-Na0bRfCyQ4q2lAryDw",
  "closure_set_name": "Default Closure",
  "account_default_business_hour": true,
  "account_default_closure_set": true,
  "operating_hours_overflow_enabled": true,
  "overflow_to_default_goodbye_message": true,
  "overflow_to_goodbye_message_asset_id": "dORBRSTxTN6B0vLJ37Kvnw",
  "overflow_to_goodbye_message_asset_name": "message",
  "overflow_to_queue_id": "m8IhNvUyTUmx7Jm8h5ZvLQ",
  "overflow_to_queue_name": "voice_queue1",
  "overflow_to_flow_id": "psjHGHrHQbaX8Zk7ldc81Q",
  "overflow_to_flow_name": "voice_flow",
  "overflow_to_inbox_id": "cMH8RJA0QsyJBCWIFbWfBQ",
  "overflow_to_inbox_name": "voice_mail_1"
}

Status: 404 HTTP Status Code: `404` Not Found Error Code: `1201` Queue does not exist: $queueId.

Status: 429 HTTP Status Code: `429` Too Many Requests. For more information, see [rate limits](https://developers.zoom.us/docs/api/rate-limits/).

Update a queue's operating hours

Method: PATCH
Path: /contact_center/queues/{queueId}/operating_hours
Tags: Queues

Update a queue's operating hours.

Scopes: contact_center_queue:write:admin

Granular Scopes: contact_center:patch:queue_operating_hours:admin

Rate Limit Label: LIGHT

Request Body

Content-Type: application/json

account_default_business_hour

boolean — Whether to use the account's default business hours. When the account's default business hours change, the business hours used by the queue also change.
account_default_closure_set

boolean — Whether to use the account's default closure set. When the account's default closure set changes, the closure set used by the queue also changes.
operating_hours_business_hour_id

string — The business hours' ID.
operating_hours_closure_set_id

string — The closure set's ID.
operating_hours_overflow_enabled

boolean — Specify consumer handling when the queue is unavailable.
overflow_to_default_goodbye_message

boolean — Reply goodbye message, then disconnect. Only one of these overflow fields can be updated each time - `overflow_to_default_goodbye_message`, `overflow_to_goodbye_message_asset_id`, `overflow_to_queue_id`, `overflow_to_flow_id`, or `overflow_to_inbox_id`. Updating an overflow field will clear out the other overflow fields.
overflow_to_flow_id

string — The flow ID to receive the overflow. Only one of these overflow fields can be updated each time - `overflow_to_default_goodbye_message`, `overflow_to_goodbye_message_asset_id`, `overflow_to_queue_id`, `overflow_to_flow_id`, or `overflow_to_inbox_id`. Updating an overflow field will clear out the other overflow fields.
overflow_to_goodbye_message_asset_id

string — Reply goodbye message choose from an asset.
overflow_to_inbox_id

string — The voicemail inbox ID to receive the overflow. Only one of these overflow fields can be updated each time - `overflow_to_default_goodbye_message`, `overflow_to_goodbye_message_asset_id`, `overflow_to_queue_id`, `overflow_to_flow_id`, or `overflow_to_inbox_id`. Updating an overflow field will clear out the other overflow fields.
overflow_to_queue_id

string — The queue ID to receive the overflow. Only one of these overflow fields can be updated each time - `overflow_to_default_goodbye_message`, `overflow_to_goodbye_message_asset_id`, `overflow_to_queue_id`, `overflow_to_flow_id`, or `overflow_to_inbox_id`. Updating an overflow field will clear out the other overflow fields.

Example:

{
  "account_default_business_hour": true,
  "operating_hours_business_hour_id": "66ZjSQ7YTOescnINN_4vog",
  "account_default_closure_set": true,
  "operating_hours_closure_set_id": "Ixo-Na0bRfCyQ4q2lAryDw",
  "operating_hours_overflow_enabled": true,
  "overflow_to_default_goodbye_message": true,
  "overflow_to_goodbye_message_asset_id": "dORBRSTxTN6B0vLJ37Kvnw",
  "overflow_to_queue_id": "m8IhNvUyTUmx7Jm8h5ZvLQ",
  "overflow_to_flow_id": "psjHGHrHQbaX8Zk7ldc81Q",
  "overflow_to_inbox_id": "cMH8RJA0QsyJBCWIFbWfBQ"
}

Responses

Status: 204 HTTP Status Code: `204` Operating hours updated.

Status: 400 HTTP Status Code: `400` Bad Request

Status: 404 HTTP Status Code: `404` Not Found Error Code: `1201` Queue does not exist: $queueId.

Status: 429 HTTP Status Code: `429` Too Many Requests. For more information, see [rate limits](https://developers.zoom.us/docs/api/rate-limits/).

List queue recordings

Method: GET
Path: /contact_center/queues/{queueId}/recordings
Tags: Queues

Return a list of all recordings in a queue.

Note Use recording-related APIs to manipulate data whose recording was created after July 18, 2022.

Scopes: contact_center_recording:read:admin,contact_center_recording:read

Granular Scopes: contact_center:read:list_recordings:admin,contact_center:read:list_recordings

Rate Limit Label: MEDIUM

Responses

Status: 200 HTTP Status Code: `200` Queue recordings returned.

Content-Type: application/json

from

string, format: string — The start time and date in ISO 8601 format, either `yyyy-MM-dd'T'HH:mm:ss'Z'` or `yyyy-MM-dd'T'HH:mm:ss'TZD'`. The defined date range should be a month, as the response only includes one month's worth of data. If unspecified, this parameter returns data from the past 30 days.
next_page_token

string — Use the next page token to paginate through large result sets. A next page token is returned whenever the set of available results exceeds the current page size. This token's expiration period is 15 minutes.
page_size

integer, default: 30 — The number of records returned in a single API call.
recordings

array — Information about the recordings.

Items:
- cc_queue_id
  
  string — The Contact Center queue's ID.
- channel
  
  string, possible values: "voice", "video" — The recording's channel type. * `voice` - Voice recording. * `video` - Video recording.
- channel_type
  
  string, possible values: "voice", "video" — The recording's channel type. * `voice` - Voice recording. * `video` - Video recording.
- conference_participant
  
  array — Information about the recording conference participants.
  
  Items:
  - contact_id
    
    string — The participant's contact ID.
  - contact_name
    
    string — The participant's contact name.
  - contact_number
    
    string — The participant's contact number.
  - participant_type
    
    string, possible values: "agent", "customer", "supervisor", "outbound" — The participant's type.
  - queue_id
    
    string — The participant's queue ID.
  - queue_name
    
    string — The participant's queue name.
  - team_id
    
    string — The participant's team ID.
  - team_name
    
    string — The participant's team name.
  - user_id
    
    string — The participant's user ID.
  - user_name
    
    string — The participant's username.
- consumer_name
  
  string — The customer's name. * **Note** This field will be abolished, and the `consumer_name` in `consumers` will be used uniformly.
- consumer_number
  
  string — The customer's phone number. * **Note** This field will be abolished, and the `consumer_number` in `consumers` will be used uniformly.
- consumers
  
  array — Information about the recording consumers.
  
  Items:
  - consumer_name
    
    string — The customer's name.
  - consumer_number
    
    string — The customer's phone number.
- direction
  
  string, possible values: "inbound", "outbound" — The recording's call direction. * `inbound` - Call in. * `outbound` - Call out.
- display_name
  
  string — The user's name.
- download_url
  
  string — The URL to download the recording. For security purposes, you **must** provide an OAuth access token in the Authorization header to download the recording file using this URL. Example: ```curl --request GET \ --url {download_url} \ --header 'authorization: Bearer {access_token} \ --header 'content-type: application/json' ```
- engagement_id
  
  string — The engagement event's unique ID.
- exemption
  
  boolean — Whether the recording is exempted from data retention.
- flow_id
  
  string — The recording's flow ID.
- flow_name
  
  string — The recording's flow name.
- owner_id
  
  string — The recording's owner ID, either the queue ID or user ID.
- owner_name
  
  string — The recording's owner name, either the queue name or user name.
- owner_type
  
  string, possible values: "user", "queue" — The recording's owner type. * `user` - This recording belongs to an user. * `queue` - This recording belongs to a queue.
- playback_url
  
  string — The URL to play the recording. For security purposes, you **must** provide an OAuth access token in the authorization header to play the recording file using this URL. Example: ```curl --request GET --url {playback_url} --header 'authorization: Bearer {access_token}' --header 'content-type: application/json' ```
- queue_id
  
  string — The queue's unique ID.
- queue_name
  
  string — The queue's name.
- reason_details
  
  string — The recording's data retention exemption reason details.
- recording_duration
  
  integer — The recording's duration, in seconds.
- recording_end_time
  
  string, format: date-time — The date and time when the recording's end time in ISO 8601 format, either yyyy-MM-dd'T'HH:mm:ss'Z' or yyyy-MM-dd'T'HH:mm:ss'TZD'.
- recording_id
  
  string — The recording's unique ID.
- recording_start_time
  
  string, format: date-time — The date and time when the recording's start time in ISO 8601 format, either yyyy-MM-dd'T'HH:mm:ss'Z' or yyyy-MM-dd'T'HH:mm:ss'TZD'.
- recording_type
  
  string, possible values: "on_demand", "automatic" — The recording's type. * `on_demand` - Manually trigger recording. * `automatic` - Automatically trigger recording.
- segment_type
  
  string, possible values: "inbound", "conference" — Whether the recording is an inbound recording or a conference recording.
- team_id
  
  string — The team's ID.
- team_name
  
  string — The team's name.
- transcript_url
  
  string — The URL to download the recording transcript. For security purposes, you **must** provide an OAuth access token in the authorization header to download the recording transcript file using this URL. Example: ```curl --request GET --url {transcript_url} --header 'authorization: Bearer {access_token}' --header 'content-type: application/json' ```
- user_email
  
  string — The user's email.
- user_id
  
  string — The user's ID.
to

string, format: string — **Required** only when the `from` parameter is specified. The end time and date in ISO 8601 format, either `yyyy-MM-dd'T'HH:mm:ss'Z'` or `yyyy-MM-dd'T'HH:mm:ss'TZD'`, the same format as the `from` parameter.

Example:

{
  "next_page_token": "R4aF9Oj0fVM2hhezJTEmSKaBSkfesDwGy42",
  "page_size": 30,
  "from": "2023-01-01T00:00:00-08:00",
  "to": "2023-01-01T01:00:00-08:00",
  "recordings": [
    {
      "recording_id": "ghyetrjj_sdfsdgfkdjfl111",
      "cc_queue_id": "smyko04pSCWt9zLI0nn3AQ",
      "queue_name": "voice",
      "recording_duration": 150,
      "download_url": "https://example.com/contact_center/recording/download/01bdb222-9984-4f41-8141-2f760cb398aa?type=voice",
      "transcript_url": "https://example.com/contact_center/recording/transcripts/download/4Q0ILNMfTA2nJolNxhg0Rw?type=voice",
      "playback_url": "https://example.com/contact_center/recording/playback/4Q0ILNMfTA2nJolNxhg0Rw?type=voice",
      "recording_start_time": "2023-01-01T08:00:00Z",
      "recording_end_time": "2023-01-01T09:00:00Z",
      "user_id": "IGTRVt3gQ2i-WjoUIjeZxw",
      "display_name": "Jill",
      "user_email": "jcill@example.com",
      "recording_type": "automatic",
      "channel": "voice",
      "direction": "outbound",
      "owner_id": "auiketrjj_2342353fsewkdjfl",
      "owner_name": "voice",
      "owner_type": "queue",
      "engagement_id": "3XilEfOvQEKRIWMWhX1jDg",
      "flow_name": "voice",
      "flow_id": "fsdfsd4oippe0ffewcbhjk",
      "consumers": [
        {
          "consumer_name": "Jill",
          "consumer_number": "+12058945728"
        }
      ],
      "exemption": true,
      "team_id": "edlbknHGRjq35Y5WYxb7_A",
      "conference_participant": [
        {
          "user_id": "HljBAYkdSzqk_eXkXyEV7g",
          "user_name": "Jill Doe",
          "queue_id": "y5yK894sT4ixNaO__FO_Jg",
          "queue_name": "Jill Doe's queue",
          "team_id": "edlbknHGRjq35Y5WYxb7_A",
          "team_name": "Jill Doe's team",
          "contact_id": "edlbknHGRjq35Y5WYxb7_A",
          "contact_name": "Jill Doe",
          "contact_number": "+12058945728",
          "participant_type": "agent"
        }
      ],
      "segment_type": "conference",
      "reason_details": "Compliance review.",
      "team_name": "Jill Doe's team"
    }
  ]
}

Status: 401 HTTP Status Code: `401` Unauthorized

Status: 403 HTTP Status Code: `403` Forbidden

Status: 404 HTTP Status Code: `404` Not Found Error Code: `1204` Queue does not exist: $queueId.

Status: 429 HTTP Status Code: `429` Too Many Requests. For more information, see [rate limits](/docs/api/rate-limits/).

Delete queue recordings

Method: DELETE
Path: /contact_center/queues/{queueId}/recordings
Tags: Queues

Delete all recordings in a queue.

Note Use recording-related APIs to manipulate data whose recording creation time is after 2022-07-18.

Scopes: contact_center_recording:write:admin

Granular Scopes: contact_center:delete:recording:admin

Rate Limit Label: LIGHT

Responses

Status: 204 HTTP Status Code: `204` Queue recordings deleted.

Status: 400 HTTP Status Code: `400` Bad Request

Status: 404 HTTP Status Code: `404` Not Found Error Code: `1201` Queue does not exist: $queueId Error Code: `2803` Queue recordings does not exist: $queueId.

Status: 409 HTTP Status Code: `409` Conflict Error Code: `2820` You cannot delete this recording because it is exempt from retention policy due to legal hold.

Status: 429 HTTP Status Code: `429` Too Many Requests. For more information, see [rate limits](https://developers.zoom.us/docs/api/rest/rate-limits/).

Delete an attendee from a scheduled callback event

Method: DELETE
Path: /contact_center/queues/{queueId}/scheduled_callbacks/attendees/{attendeeId}
Tags: Queues

Remove an attendee from an event slot on a scheduled callback. If the attendee is the last remaining participant in that event, the entire event is deleted.

Scopes: contact_center_queue:write:admin

Granular Scopes: contact_center:delete:queue:admin

Rate Limit Label: HEAVY

Request Body

Content-Type: application/json

cancelation_reason

string — Reason for cancelation.

Example:

{
  "cancelation_reason": "I'm feeling unwell and need to rest."
}

Responses

Status: 204 HTTP Status Code: `204` Scheduled callback for attendee canceled.

Status: 400 HTTP Status Code: `400` Bad Request Bad Request. Error Code: `1503` Scheduler is not set up.

Status: 401 HTTP Status Code: `401` Unauthorized Unauthorized.

Status: 403 HTTP Status Code: `403` Forbidden Forbidden.

Status: 404 HTTP Status Code: `404` Not Found Not found. Error Code: `1201` Queue does not exist: {queueId}. Error Code: `1504` Attendee not found.

Status: 429 HTTP Status Code: `429` Too Many Requests. For more information, see [rate limits](https://developers.zoom.us/docs/api/rate-limits/).

Schedule a callback on a queue

Method: POST
Path: /contact_center/queues/{queueId}/scheduled_callbacks/events
Tags: Queues

Schedule a callback on a queue.

Scopes: contact_center_queue:write:admin

Granular Scopes: contact_center:write:queue:admin

Rate Limit Label: HEAVY

Request Body

Content-Type: application/json

attendees (required)

array — An array of attendees.

Items:
- email (required)
  
  string, format: email — The attendee's email address.
- first_name (required)
  
  string — The attendee's first name.
- last_name (required)
  
  string — The attendee's last name.
- phone_number (required)
  
  string — The attendee's phone number, in E.164 format.
start_time (required)

string, format: date-time — The `start_time` of the slot selected. Should match the `start_time` of the selected slot returned by the [Available slots API](/docs/api/contact-center/#tag/queues/GET/contact_center/queues/{queueId}/scheduled_callbacks/supportive_slots).

Example:

{
  "start_time": "2025-06-18T15:00:00Z",
  "attendees": [
    {
      "first_name": "Jill",
      "last_name": "Chill",
      "email": "jchill@example.com",
      "phone_number": "+1 555-555-5555"
    }
  ]
}

Responses

Status: 201 HTTP Status Code: `201` Callback Scheduled

Content-Type: application/json

attendees

array — An array of attendees.

Items:
- attendee_id
  
  string — The attendee's ID.
- email
  
  string — The attendee's email address.
- first_name
  
  string — The attendee's first name.
- last_name
  
  string — The attendee's last name.
- phone_number
  
  string — The attendee's phone number, in E.164 format.

Example:

{
  "attendees": [
    {
      "first_name": "Jill",
      "last_name": "Chill",
      "email": "jchill@example.com",
      "phone_number": "+1 555-555-5555",
      "attendee_id": "zeYjXoDOS_eV1QmTpj63PQ"
    }
  ]
}

Status: 400 HTTP Status Code: `400` Bad Request Bad request. Error Code: `300` Invalid `dateTime` format. Error Code: `300` Must be a well-formed email address. Error Code: `620003` Invalid phone number. Error Code: `400` Requested slot in the past. Error Code: `400` Requested slot does not exist. Error Code: `400` Requested duration changed. Error Code: `55008` Duplicated booking request. Error Code: `1503` Scheduler is not set up.

Status: 401 HTTP Status Code: `401` Unauthorized Unauthorized.

Status: 403 HTTP Status Code: `403` Forbidden Forbidden.

Status: 404 HTTP Status Code: `404` Not Found Not found. Error Code: `1201` Queue does not exist: {queueId}.

Status: 429 HTTP Status Code: `429` Too Many Requests. For more information, see [rate limits](/docs/api/rate-limits/).

List a queue's scheduled callbacks availability

Method: GET
Path: /contact_center/queues/{queueId}/scheduled_callbacks/supportive_slots
Tags: Queues

List scheduled callbacks booking slots for a scheduler set up under a queue.

Scopes: contact_center_queue:read:admin

Granular Scopes: contact_center:read:queue:admin

Rate Limit Label: MEDIUM

Responses

Status: 200 Return a list of booking spots.

Content-Type: application/json

booking_days

array — List of days that contain booking spots.

Items:
- slot_date
  
  string, format: date — Date of the day.
- slots
  
  array — List of spots.
  
  Items:
  - availability_status
    
    string, possible values: "available", "unavailable" — Whether the time slot is available to book.
  - available_count
    
    integer — Number of booking spots available for the specific time slot.
  - start_time
    
    string, format: date-time — The booking slot's start time.
slot_duration

integer — Duration for every booking spot, in minutes.
timezone

string — Time zone used to allocate booking spots to days.

Example:

{
  "timezone": "America/Los_Angeles",
  "slot_duration": 15,
  "booking_days": [
    {
      "slot_date": "2025-06-19",
      "slots": [
        {
          "available_count": 2,
          "start_time": "2025-06-18T15:00:00Z",
          "availability_status": "available"
        }
      ]
    }
  ]
}

Status: 400 HTTP Status Code: `400` Bad Request Bad request. Error Code: `300` `min_time` must come before `max_time`. Error Code: `300` Time range cannot exceed 45 days. Error Code: `300 ` Invalid `dateTime` format. Error Code: `300` Invalid time zone format. Error Code: `124` Invalid access token. Error Code: `1503` Scheduler is not set up.

Status: 401 HTTP Status Code: `401` Unauthorized Unauthorized.

Status: 403 HTTP Status Code: `403` Forbidden Forbidden.

Status: 404 HTTP Status Code: `404` Not Found Not found Error Code: `1201` Queue does not exist: {queueId}.

Status: 429 HTTP Status Code: `429` Too Many Requests. For more information, see [rate limits](/docs/api/rate-limits/).

List queue supervisors

Method: GET
Path: /contact_center/queues/{queueId}/supervisors
Tags: Queues

Retrieve the list of a queue's assigned Contact Center users with supervisor persona assignment to the Contact Center queue.

Scopes: contact_center_queue:read:admin

Granular Scopes: contact_center:delete:queue_supervisor:admin

Rate Limit Label: MEDIUM

Responses

Status: 200 HTTP Status Code: `200` Queue supervisors list returned.

Content-Type: application/json

next_page_token

string — Use the next page token to paginate through large result sets. A next page token is returned whenever the set of available results exceeds the current page size. This token's expiration period is 15 minutes.
page_size

integer, default: 30 — The number of records returned within a single API call.
supervisors

array — Information about the supervisors.

Items:
- cc_user_id
  
  string — The Contact Center user identifier.
- display_name
  
  string — The user's display name.
- role_id
  
  string — The user's Contact Center role identifier.
- role_name
  
  string — The user's Contact Center role name.
- status_id
  
  string — The user's availability status ID.
- status_name
  
  string, possible values: "Offline", "Ready", "Not Ready", "Occupied" — The user's [availability status](https://support.zoom.us/hc/en-us/articles/4470584918541-Setting-availability-status). * Offline * Ready * Not Ready * Occupied * A custom user status, such as **Lunch**.
- teams
  
  array — The teams the user is assigned to.
  
  Items:
  - team_id
    
    string — The ID of the team.
  - team_name
    
    string — The display name of the team.
- user_access
  
  string, possible values: "active", "inactive" — The user's access status. * `active` - The user's role permissions allow them to access the Contact Center. * `inactive` - The user cannot access the Contact Center.
- user_email
  
  string, format: email — The user's email address.
- user_id
  
  string — The Meetings user identifier.
total_records

integer — The total number of all records available across pages.

Example:

{
  "next_page_token": "R4aF9Oj0fVM2hhezJTEmSKaBSkfesDwGy42",
  "page_size": 30,
  "total_records": 10,
  "supervisors": [
    {
      "user_id": "IGTRVt3gQ2i-WjoUIjeZxw",
      "display_name": "Jane Doe",
      "user_email": "jchill@example.com",
      "role_id": "0TFVsJqNS82CwkQJLqj1zA",
      "role_name": "Admin",
      "status_id": "1",
      "status_name": "Offline",
      "user_access": "active",
      "teams": [
        {
          "team_id": "qlU902FoTD-dFi9QnCdZhw",
          "team_name": "Support Team"
        }
      ],
      "cc_user_id": "hKuMAiDdRlSwMkBxR5we7g"
    }
  ]
}

Status: 400 HTTP Status Code: `400` Bad Request Error Code: `1244` More than one matching queue found.

Status: 401 HTTP Status Code: `401` Unauthorized

Status: 403 HTTP Status Code: `403` Forbidden

Status: 404 HTTP Status Code: `404` Not Found Error Code: `1201` Queue does not exist: $queueId.

Status: 429 HTTP Status Code: `429` Too Many Requests. For more information, see [rate limits](/docs/api/rest/rate-limits/).

Assign queue supervisors

Method: POST
Path: /contact_center/queues/{queueId}/supervisors
Tags: Queues

Assign users to a Contact Center queue as supervisor persona.

The API response will contain only those users confirmed to have been assigned to the queue, and ignores any unrecognized user ID and users already assigned to the queue.

Scopes: contact_center_queue:write:admin

Granular Scopes: contact_center:delete:queue_supervisor:admin

Rate Limit Label: MEDIUM

Request Body

Content-Type: application/json

user_ids

array — The user identifiers. The values can be a mix of email addresses, Meetings user IDs, or Contact Center user IDs.

Items:

string

Example:

{
  "user_ids": [
    "ukAAkZKfROKMSw1bj_RDFQ"
  ]
}

Responses

Status: 201 HTTP Status Code: `201` Queue supervisors assigned. Can be empty.

Content-Type: application/json

supervisors

array — Information about the supervisors.

Items:
- cc_user_id
  
  string — The Contact Center user identifier.
- display_name
  
  string — The user's display name.
- role_id
  
  string — The user's Contact Center role identifier.
- role_name
  
  string — The user's Contact Center role name.
- status_id
  
  string — The user's availability status ID.
- status_name
  
  string, possible values: "Offline", "Ready", "Not Ready", "Occupied" — The user's [availability status](https://support.zoom.us/hc/en-us/articles/4470584918541-Setting-availability-status). * Offline * Ready * Not Ready * Occupied * A custom user status, such as "Lunch".
- user_access
  
  string, possible values: "active", "inactive" — The user's access status. * `active` - The user's role permissions allow them to access the Contact Center. * `inactive` - The user cannot access the Contact Center.
- user_email
  
  string, format: email — The user's email address.
- user_id
  
  string — The Meetings user identifier.

Example:

{
  "supervisors": [
    {
      "user_id": "IGTRVt3gQ2i-WjoUIjeZxw",
      "cc_user_id": "hKuMAiDdRlSwMkBxR5we7g",
      "display_name": "Jane Doe",
      "user_email": "jchill@example.com",
      "role_id": "0TFVsJqNS82CwkQJLqj1zA",
      "role_name": "Admin",
      "status_id": "1",
      "status_name": "Offline",
      "user_access": "active"
    }
  ]
}

Status: 400 HTTP Status Code: `400` Bad Request Error Code: `300` Invalid field.

Status: 401 HTTP Status Code: `401` Unauthorized Error Code: `124` Invalid access token. Error Code: `124` Access token has expired. Error Code: `1002` The user associated with this access token was not found or is invalid.

Status: 403 HTTP Status Code: `403` Forbidden Error Code: `1021` User account is deactivated. Error Code: `1022` User does not have a Contact Center license. Error Code: `9001` The Contact Center user associated with this bearer token is missing privileges on their role required to operate this request.

Status: 404 HTTP Status Code: `404` Not Found Error Code: `1201` Queue does not exist: {queueId}.

Status: 429 HTTP Status Code: `429` Too Many Requests. For more information, see [rate limits](/docs/api/rate-limits/). Error Code: `4001` You have reached the maximum per-second rate limit for this API. Try again later.

Unassign a queue supervisor

Method: DELETE
Path: /contact_center/queues/{queueId}/supervisors/{userId}
Tags: Queues

Remove a supervisor from a Contact Center queue. The specified user will be unassigned from the queue and will no longer have supervisory access to engagements routed through it. The user must be currently assigned as a supervisor to the queue.

Scopes: contact_center_queue:write:admin

Granular Scopes: contact_center:delete:queue_supervisor:admin

Rate Limit Label: LIGHT

Responses

Status: 204 HTTP Status Code: `204` Queue supervisor removed.

Status: 400 HTTP Status Code: `400` Bad Request Error Code: `300` Validation failed.

Status: 401 HTTP Status Code: `401` Unauthorized Error Code: `124` Invalid access token. Error Code: `124` Access token has expired. Error Code: `1002` The user associated with this access token was not found or is invalid.

Status: 403 HTTP Status Code: `403` Forbidden Error Code: `1021` User account is deactivated. Error Code: `1022` User does not have a Contact Center license. Error Code: `9001` The Contact Center user associated with this bearer token is missing privileges on their role required to operate this request.

Status: 404 HTTP Status Code: `404` Not Found Error Code: `1201` Queue does not exist: {0}. Error Code: `1001` User does not exist: {0}.

Status: 429 HTTP Status Code: `429` Too Many Requests. For more information, see [rate limits](/docs/api/rate-limits/). Error Code: `4001` You have reached the maximum per-second rate limit for this API. Try again later.

Assign queue teams

Method: POST
Path: /contact_center/queues/{queueId}/teams
Tags: Queues

Add teams to a queue.

Scopes: contact_center_queue:write:admin

Granular Scopes: contact_center:write:queue_team:admin

Rate Limit Label: MEDIUM

Request Body

Content-Type: application/json

team_ids (required)

array — The team's ID to assign to the queue, up to a maximum of 10 teams per call.

Items:

string

Example:

{
  "team_ids": [
    "ukAAkZKfROKMSw1bj_RDFQ"
  ]
}

Responses

Status: 201 HTTP Status Code: `201` Queue teams assigned.

Content-Type: application/json

teams

array — Information about the successful assigned teams.

Items:
- team_id
  
  string — The team's ID.
- team_name
  
  string — The team's name.

Example:

{
  "teams": [
    {
      "team_id": "2mDPBg3vSYC_l6crQgeCkA",
      "team_name": "Example team"
    }
  ]
}

Status: 400 HTTP Status Code: `400` Bad Request Error Code: `1215` Teams feature is not enabled.

Status: 404 HTTP Status Code: `404` Not Found Error Code: `1201` Queue does not exist: $queueId. Error Code: `1216` Teams does not exist.

Status: 429 HTTP Status Code: `429` Too Many Requests. For more information, see [rate limits](https://developers.zoom.us/docs/api/rate-limits/).

Unassign queue teams

Method: DELETE
Path: /contact_center/queues/{queueId}/teams
Tags: Queues

Remove teams from a queue.

Scopes: contact_center_queue:write:admin

Granular Scopes: contact_center:delete:queue_team:admin

Rate Limit Label: MEDIUM

Request Body

Content-Type: application/json

team_ids (required)

array — The team's ID to unassign from the queue.

Items:

string — The team's ID.

Example:

{
  "team_ids": [
    "ukAAkZKfROKMSw1bj_RDFQ"
  ]
}

Responses

Status: 204 HTTP Status Code: `204` Queue teams removed.

Status: 400 HTTP Status Code: `400` Bad Request Error Code: `1215` Teams feature is not enabled.

Status: 401 HTTP Status Code: `401` Unauthorized Error Code: `124` Invalid access token. Error Code: `124` Access token has expired. Error Code: `1002` The user associated with this access token was not found or is invalid.

Status: 403 HTTP Status Code: `403` Forbidden Error Code: `1021` User account is deactivated. Error Code: `1022` User does not have a Contact Center license. Error Code: `9001` The Contact Center user associated with this bearer token is missing privileges on their role required to operate this request.

Status: 404 HTTP Status Code: `404` Not Found Error Code: `1201` Queue does not exist: $queueId.

Status: 429 HTTP Status Code: `429` Too Many Requests. For more information, see [rate limits](https://developers.zoom.us/docs/api/rate-limits/). Error Code: `4001` You have reached the maximum per-second rate limit for this API. Try again later.

Unassign a queue team

Method: DELETE
Path: /contact_center/queues/{queueId}/teams/{teamId}
Tags: Queues

Remove a team from a queue.

Scopes: contact_center_queue:write:admin

Granular Scopes: contact_center:delete:queue_team:admin

Rate Limit Label: MEDIUM

Responses

Status: 204 HTTP Status Code: `204` Queue team removed.

Status: 400 HTTP Status Code: `400` Bad Request Error Code: `1215` Teams feature is not enabled.

Status: 404 HTTP Status Code: `404` Not Found Error Code: `1201` Queue does not exist: $queueId. Error Code: `1216` Team does not exist: $teamId.

Status: 429 HTTP Status Code: `429` Too Many Requests. For more information, see [rate limits](https://developers.zoom.us/docs/api/rate-limits/).

Update engagement Real-Time Media Streams (RTMS) app status

Method: PUT
Path: /contact_center/{engagementId}/rtms_app/status
Tags: RTMS

Update the RTMS status for a specific engagement. Contact Center allows changing status [start, pause, resume, stop] for RTMS at the engagement level.

Prerequisites:

The app has a media scope assigned in the Zoom Marketplace.
The app has an OpenAPI scope assigned in the Zoom Marketplace.
The app has queues assigned in the Contact Center web portal.
The engagement must be in progress.

Scopes: contact_center_rtms:write:admin

Granular Scopes: contact_center:update:engagement_rtms_app_status,contact_center:update:engagement_rtms_app_status:admin

Rate Limit Label: LIGHT

Request Body

Content-Type: application/json

action

string, possible values: "start", "stop", "pause", "resume" — The engagement's RTMS app status. * `start` - Start an RTMS app. * `stop` - Stop an ongoing RTMS app. * `pause` - Pause an ongoing RTMS app. * `resume` - Resume a paused RTMS app.
settings

object — Engagement's RTMS app settings.
- client_id (required)
  
  string — The unique identifier of the authorized app configured in MP.

Example:

{
  "action": "start",
  "settings": {
    "client_id": "a_Zu0X_FVBUycmEi9ms5hg"
  }
}

Responses

Status: 204 HTTP Status Code: `204` Engagement's RTMS app status updated.

Status: 400 HTTP Status Code: `400` Bad Request Error Code: `4100` Engagement {engagementId} is not yet ready for streaming. Error Code: `4101` Action {action} not valid for {engagementId}. Streaming is already in the requested state. Error Code: `4102` Action {action} is invalid. Engagement is in {state}. Error Code: `4103` Invalid app {clientId} for engagement {engagementId}. Error Code: `4105` Invalid streaming command.

Status: 403 HTTP Status Code: `403` Forbidden Error Code: `4106` The current engagement does not support the RTMS app feature.

Status: 404 HTTP Status Code: `404` Not Found Error Code: `2901` Engagement does not exist: {engagementId}. Error Code: `20006` Account not found. Error Code: `4109` The system could not find the session for the engagement.

Status: 409 HTTP Status Code: `409` Conflict Error Code: `4111` There was a problem processing this request.

Status: 429 HTTP Status Code: `429` Too Many Requests. For more information, see [rate limits](https://developers.zoom.us/docs/api/rate-limits/).

Status: 500 HTTP Status Code: `500` Internal Server Error Error Code: `4107` There was a problem processing this request.

List engagement recordings

Method: GET
Path: /contact_center/engagements/{engagementId}/recordings
Tags: Recordings

Return a list of all of an engagement's recordings.

Note: Use recording-related APIs to manipulate data whose recording was created after July 18, 2022.

Scopes: contact_center_recording:read:admin

Granular Scopes: contact_center:read:list_recordings:admin

Rate Limit Label: MEDIUM

Responses

Status: 200 HTTP Status Code: `200` Engagement recordings returned.

Content-Type: application/json

from

string, format: string — The start time and date in ISO 8601 format, either `yyyy-MM-dd'T'HH:mm:ss'Z'` or `yyyy-MM-dd'T'HH:mm:ss'TZD'`. The defined date range should be a month, as the response only includes one month's worth of data. If unspecified, this parameter returns data from the past 30 days.
next_page_token

string — Use the next page token to paginate through large result sets. A next page token is returned whenever the set of available results exceeds the current page size. This token's expiration period is 15 minutes.
page_size

integer, default: 30 — The number of records returned within a single API call.
recordings

array — Information about the recordings.

Items:
- cc_queue_id
  
  string — The Contact Center queue's ID.
- channel
  
  string, possible values: "voice", "video" — The recording's channel type. * `voice` - Voice recording. * `video` - Video recording.
- channel_type
  
  string, possible values: "voice", "video" — The recording's channel type. * `voice` - Voice recording. * `video` - Video recording.
- conference_participant
  
  array — Information about the recording conference participants.
  
  Items:
  - contact_id
    
    string — The participant's contact ID.
  - contact_name
    
    string — The participant's contact name.
  - contact_number
    
    string — The participant's contact number.
  - participant_type
    
    string, possible values: "agent", "customer", "supervisor", "outbound" — The participant's type.
  - queue_id
    
    string — The participant's queue ID.
  - queue_name
    
    string — The participant's queue name.
  - team_id
    
    string — The participant's team ID.
  - team_name
    
    string — The participant's team name.
  - user_id
    
    string — The participant's user ID.
  - user_name
    
    string — The participant's username.
- consumer_name
  
  string — The customer's name. * **Note** This field will be deprecated, and the `consumer_name` in `consumers` will be used uniformly.
- consumer_number
  
  string — The customer's phone number. * **Note** This field will be deprecated, and the `consumer_number` in `consumers` will be used uniformly.
- consumers
  
  array — Information about the recording consumers.
  
  Items:
  - consumer_name
    
    string — The customer's name.
  - consumer_number
    
    string — The customer's phone number.
- direction
  
  string, possible values: "inbound", "outbound" — The recording's call direction. * `inbound` - Call in. * `outbound` - Call out.
- display_name
  
  string — The user's name.
- download_url
  
  string — The URL to download the recording. For security purposes, you **must** provide an OAuth access token in the Authorization header to download the recording file using this URL. Example: ``` curl --request GET \ --url {download_url} \ --header 'authorization: Bearer {access_token}' \ --header 'content-type: application/json' ``` Note: The URL may be a redirect. In that case, use `curl --location` to follow redirects or use another tool, like Postman.
- engagement_id
  
  string — The engagement event's unique ID.
- exemption
  
  boolean — To specify whether the recording is exempted from data retention.
- flow_id
  
  string — The recording's flow ID.
- flow_name
  
  string — The recording's flow name.
- owner_id
  
  string — The recording's owner ID, either the queue ID or user ID.
- owner_name
  
  string — The recording's owner name, either the queue name or user name.
- owner_type
  
  string, possible values: "user", "queue" — The recording's owner type. * `user` - This recording belongs to an userl * `queue` - This recording belongs to a queue.
- playback_url
  
  string — The URL to play the recording. For security purposes, you **must** provide an OAuth access token in the authorization header to play the recording file using this URL. Example: ``` curl --request GET \ --url {playback_url} \ --header 'authorization: Bearer {access_token}' \ --header 'content-type: application/json' ``` Note: The URL may be a redirect. In that case, use `curl --location` to follow redirects or use another tool, like Postman.
- queue_id
  
  string — The queue's unique ID.
- queue_name
  
  string — The queue's name.
- reason_details
  
  string — The recording's data retention exemption reason details.
- recording_duration
  
  integer — The recording's duration in seconds.
- recording_end_time
  
  string, format: date-time — The date and time when the recording's end time in ISO 8601 format, either `yyyy-MM-dd'T'HH:mm:ss'Z'` or `yyyy-MM-dd'T'HH:mm:ss'TZD'`.
- recording_id
  
  string — The recording's unique ID.
- recording_start_time
  
  string, format: date-time — The date and time when the recording's start time in ISO 8601 format, either `yyyy-MM-dd'T'HH:mm:ss'Z'` or `yyyy-MM-dd'T'HH:mm:ss'TZD'`.
- recording_type
  
  string, possible values: "on_demand", "automatic" — The recording's type. * `on_demand` - Manually trigger recording. * `automatic` - Automatically trigger recording.
- segment_type
  
  string, possible values: "inbound", "conference" — Whether the recording is an inbound recording or a conference recording.
- team_id
  
  string — The team's ID.
- team_name
  
  string — The team's name.
- transcript_url
  
  string — The URL to download the recording transcript. For security purposes, you **must** provide an OAuth access token in the authorization header to download the recording transcript file using this URL. Example: ``` curl --request GET \ --url {transcript_url} \ --header 'authorization: Bearer {access_token}' \ --header 'content-type: application/json' ``` Note: The URL may be a redirect. In that case, use `curl --location` to follow redirects or use another tool, like Postman.
- user_email
  
  string — The user's email.
- user_id
  
  string — The user's ID.
to

string, format: string — **Required** only when the `from` parameter is specified. The end time and date in ISO 8601 format, either `yyyy-MM-dd'T'HH:mm:ss'Z'` or `yyyy-MM-dd'T'HH:mm:ss'TZD'`, the same format as the `from` parameter.

Example:

{
  "next_page_token": "R4aF9Oj0fVM2hhezJTEmSKaBSkfesDwGy42",
  "page_size": 30,
  "from": "2023-01-01T00:00:00-08:00",
  "to": "2023-01-01T01:00:00-08:00",
  "recordings": [
    {
      "recording_id": "ghyetrjj_sdfsdgfkdjfl111",
      "cc_queue_id": "smyko04pSCWt9zLI0nn3AQ",
      "queue_name": "voice",
      "recording_duration": 150,
      "download_url": "https://example.com/contact_center/recording/download/01bdb222-9984-4f41-8141-2f760cb398aa?type=voice",
      "transcript_url": "https://example.com/contact_center/recording/transcripts/download/4Q0ILNMfTA2nJolNxhg0Rw?type=voice",
      "playback_url": "https://example.com/contact_center/recording/playback/4Q0ILNMfTA2nJolNxhg0Rw?type=voice",
      "recording_start_time": "2023-01-01T08:00:00Z",
      "recording_end_time": "2023-01-01T09:00:00Z",
      "user_id": "IGTRVt3gQ2i-WjoUIjeZxw",
      "display_name": "Jill",
      "user_email": "jchill@example.com",
      "recording_type": "automatic",
      "channel": "voice",
      "direction": "outbound",
      "owner_id": "auiketrjj_2342353fsewkdjfl",
      "owner_name": "voice",
      "owner_type": "queue",
      "engagement_id": "3XilEfOvQEKRIWMWhX1jDg",
      "flow_name": "voice",
      "flow_id": "fsdfsd4oippe0ffewcbhjk",
      "consumers": [
        {
          "consumer_name": "Jill",
          "consumer_number": "+12058945728"
        }
      ],
      "exemption": true,
      "team_id": "edlbknHGRjq35Y5WYxb7_A",
      "conference_participant": [
        {
          "user_id": "HljBAYkdSzqk_eXkXyEV7g",
          "user_name": "Jill Doe",
          "queue_id": "y5yK894sT4ixNaO__FO_Jg",
          "queue_name": "Jill Doe's queue",
          "team_id": "edlbknHGRjq35Y5WYxb7_A",
          "team_name": "Jill Doe's team",
          "contact_id": "edlbknHGRjq35Y5WYxb7_A",
          "contact_name": "Jill Doe",
          "contact_number": "+12058945728",
          "participant_type": "agent"
        }
      ],
      "segment_type": "conference",
      "reason_details": "Compliance review.",
      "team_name": "Jill Doe's team"
    }
  ]
}

Status: 404 HTTP Status Code: `404` Not Found Error Code: `2805` Engagement recordings does not exist or you do not have the corresponding operation authority: $engagementId.

Status: 429 HTTP Status Code: `429` Too Many Requests. For more information, see [rate limits](/docs/api/rate-limits/).

Delete engagement recordings

Method: DELETE
Path: /contact_center/engagements/{engagementId}/recordings
Tags: Recordings

Delete all recordings in a given engagement.

Note: Use recording-related APIs to manipulate data whose recording creation time is after 2022-07-18.

Scopes: contact_center_recording:write:admin

Granular Scopes: contact_center:delete:recording:admin

Rate Limit Label: LIGHT

Responses

Status: 204 HTTP Status Code: `204` Engagement recordings deleted.

Status: 400 HTTP Status Code: `400` Bad Request

Status: 404 HTTP Status Code: `404` Not Found Error Code: `2805` Engagement recordings does not exist: $engagementId.

Status: 409 HTTP Status Code: `409` Conflict Error Code: `2820` You cannot delete this recording because it is exempt from retention policy due to legal hold.

Status: 429 HTTP Status Code: `429` Too Many Requests. For more information, see [rate limits](https://developers.zoom.us/docs/api/rest/rate-limits/).

List recordings

Method: GET
Path: /contact_center/recordings
Tags: Recordings

Return a list of available recordings.

Note Use recording-related APIs to manipulate data whose recording was created after July 18, 2022.

Scopes: contact_center_recording:read:admin

Granular Scopes: contact_center:read:list_recordings:admin

Rate Limit Label: MEDIUM

Responses

Status: 200 HTTP Status Code: `200` Recordings returned

Content-Type: application/json

from

string, format: string — The start time and date in ISO 8601 format, either `yyyy-MM-dd'T'HH:mm:ss'Z'` or `yyyy-MM-dd'T'HH:mm:ss'TZD'`. The defined date range should be a month, as the response only includes one month's worth of data. If unspecified, this parameter returns data from the past 30 days.
next_page_token

string — Use the next page token to paginate through large result sets. A next page token is returned whenever the set of available results exceeds the current page size. This token's expiration period is 15 minutes.
page_size

integer, default: 30 — The number of records returned within a single API call.
recordings

array — Information about the recordings.

Items:
- cc_queue_id
  
  string — The Contact Center queue's ID.
- channel
  
  string, possible values: "voice", "video" — The recording's channel type. * `voice` - Voice recording. * `video` - Video recording.
- channel_type
  
  string, possible values: "voice", "video" — The recording's channel type. * `voice` - Voice recording. * `video` - Video recording.
- conference_participant
  
  array — Information about the recording conference participants.
  
  Items:
  - contact_id
    
    string — The participant's contact ID.
  - contact_name
    
    string — The participant's contact name.
  - contact_number
    
    string — The participant's contact number.
  - participant_type
    
    string, possible values: "agent", "customer", "supervisor", "outbound" — The participant's type.
  - queue_id
    
    string — The participant's queue ID.
  - queue_name
    
    string — The participant's queue name.
  - team_id
    
    string — The participant's team ID.
  - team_name
    
    string — The participant's team name.
  - user_id
    
    string — The participant's user ID.
  - user_name
    
    string — The participant's username.
- consumer_name
  
  string — The customer's name. * **Note** This field will be abolished, and the `consumer_name` in `consumers` will be used uniformly.
- consumer_number
  
  string — The customer's phone number. * **Note** This field will be abolished, and the `consumer_number` in `consumers` will be used uniformly.
- consumers
  
  array — Information about the recording consumers.
  
  Items:
  - consumer_name
    
    string — The customer's name.
  - consumer_number
    
    string — The customer's phone number.
- direction
  
  string, possible values: "inbound", "outbound" — The recording's call direction. * `inbound` - Call in. * `outbound` - Call out.
- display_name
  
  string — The user's name.
- download_url
  
  string — The URL to download the recording. For security purposes, you **must** provide an OAuth access token in the Authorization header to download the recording file using this URL. Example: ``` curl --request GET \ --url {download_url} \ --header 'authorization: Bearer {access_token}' \ --header 'content-type: application/json' ``` Note: The URL may be a redirect. In that case, use `curl --location` to follow redirects or use another tool, like Postman.
- engagement_id
  
  string — The engagement event's unique ID.
- exemption
  
  boolean — Whether the recording is exempted from data retention.
- flow_id
  
  string — The recording's flow ID.
- flow_name
  
  string — The recording's flow name.
- owner_id
  
  string — The recording's owner ID, either the queue ID or user ID.
- owner_name
  
  string — The recording's owner name, either thequeue name or user name.
- owner_type
  
  string, possible values: "user", "queue" — The recording's owner type. * `user` - This recording belongs to a user. * `queue` - This recording belongs to a queue.
- playback_url
  
  string — The URL to play the recording. For security purposes, you **must** provide an OAuth access token in the authorization header to play the recording file using this URL. Example: ``` curl --request GET \ --url {playback_url} \ --header 'authorization: Bearer {access_token}' \ --header 'content-type: application/json' ``` Note: The URL may be a redirect. In that case, use `curl --location` to follow redirects or use another tool, like Postman.
- queue_id
  
  string — The queue's unique ID.
- queue_name
  
  string — The queue's name.
- reason_details
  
  string — The recording's data retention exemption reason details.
- recording_duration
  
  integer — The recording's duration in seconds.
- recording_end_time
  
  string, format: date-time — The date and time when the recording's end time in ISO 8601 format, either `yyyy-MM-dd'T'HH:mm:ss'Z'` or `yyyy-MM-dd'T'HH:mm:ss'TZD'`.
- recording_id
  
  string — The recording's unique ID.
- recording_start_time
  
  string, format: date-time — The date and time when the recording's start time in ISO 8601 format, either `yyyy-MM-dd'T'HH:mm:ss'Z'` or `yyyy-MM-dd'T'HH:mm:ss'TZD'`.
- recording_type
  
  string, possible values: "on_demand", "automatic" — The recording's type. * `on_demand` - Manually trigger recording. * `automatic` - Automatically trigger recording.
- segment_type
  
  string, possible values: "inbound", "conference" — Whether the recording is an inbound recording or a conference recording.
- team_id
  
  string — The team's ID.
- team_name
  
  string — The team's name.
- transcript_url
  
  string — The URL to download the recording transcript. For security purposes, you **must** provide an OAuth access token in the authorization header to download the recording transcript file using this URL. Example: ``` curl --request GET \ --url {transcript_url} \ --header 'authorization: Bearer {access_token}' \ --header 'content-type: application/json' ``` Note: The URL may be a redirect. In that case, use `curl --location` to follow redirects or use another tool, like Postman.
- user_email
  
  string — The user's email.
- user_id
  
  string — The user's ID.
to

string, format: string — **Required** only when the `from` parameter is specified. The end time and date in ISO 8601 format, either `yyyy-MM-dd'T'HH:mm:ss'Z'` or `yyyy-MM-dd'T'HH:mm:ss'TZD'`, the same format as the `from` parameter.

Example:

{
  "next_page_token": "R4aF9Oj0fVM2hhezJTEmSKaBSkfesDwGy42",
  "page_size": 30,
  "from": "2023-01-01T00:00:00-08:00",
  "to": "2023-01-01T01:00:00-08:00",
  "recordings": [
    {
      "recording_id": "ghyetrjj_sdfsdgfkdjfl111",
      "cc_queue_id": "smyko04pSCWt9zLI0nn3AQ",
      "queue_name": "voice",
      "recording_duration": 150,
      "download_url": "https://example.com/contact_center/recording/download/01bdb222-9984-4f41-8141-2f760cb398aa?type=voice",
      "transcript_url": "https://example.com/contact_center/recording/transcripts/download/4Q0ILNMfTA2nJolNxhg0Rw?type=voice",
      "playback_url": "https://example.com/contact_center/recording/playback/4Q0ILNMfTA2nJolNxhg0Rw?type=voice",
      "recording_start_time": "2023-01-01T08:00:00Z",
      "recording_end_time": "2023-01-01T09:00:00Z",
      "user_id": "IGTRVt3gQ2i-WjoUIjeZxw",
      "display_name": "Tom",
      "user_email": "xxxx@example.com",
      "recording_type": "automatic",
      "channel": "voice",
      "direction": "outbound",
      "owner_id": "auiketrjj_2342353fsewkdjfl",
      "owner_name": "voice",
      "owner_type": "queue",
      "engagement_id": "3XilEfOvQEKRIWMWhX1jDg",
      "flow_name": "voice",
      "flow_id": "fsdfsd4oippe0ffewcbhjk",
      "consumers": [
        {
          "consumer_name": "Jill",
          "consumer_number": "+12058945728"
        }
      ],
      "exemption": true,
      "team_id": "edlbknHGRjq35Y5WYxb7_A",
      "conference_participant": [
        {
          "user_id": "HljBAYkdSzqk_eXkXyEV7g",
          "user_name": "Jill Doe",
          "queue_id": "y5yK894sT4ixNaO__FO_Jg",
          "queue_name": "Jill Doe's queue",
          "team_id": "edlbknHGRjq35Y5WYxb7_A",
          "team_name": "Jill Doe's team",
          "contact_id": "edlbknHGRjq35Y5WYxb7_A",
          "contact_name": "Jill Doe",
          "contact_number": "+12058945728",
          "participant_type": "agent"
        }
      ],
      "segment_type": "conference",
      "reason_details": "Compliance review.",
      "team_name": "Jill Doe's team"
    }
  ]
}

Status: 400 HTTP Status Code: `400` Bad Request Error Code: `300` Validation failed.

Status: 429 HTTP Status Code: `429` Too Many Requests. For more information, see [rate limits](/docs/api/rate-limits/).

Delete a recording

Method: DELETE
Path: /contact_center/recordings/{recordingId}
Tags: Recordings

Delete a selected recording.

Note: Use recording-related APIs to manipulate data whose recording creation time is after 2022-07-18.

Scopes: contact_center_recording:write:admin

Granular Scopes: contact_center:delete:recording:admin

Rate Limit Label: LIGHT

Responses

Status: 204 HTTP Status Code: `204` Recording deleted.

Status: 400 HTTP Status Code: `400` Bad Request

Status: 404 HTTP Status Code: `404` Not Found Error Code: `2801` Recording does not exist: $recordingId.

Status: 409 HTTP Status Code: `409` Conflict Error Code: `2820` You cannot delete this recording because it is exempt from retention policy due to legal hold.

Status: 429 HTTP Status Code: `429` Too Many Requests. For more information, see [rate limits](https://developers.zoom.us/docs/api/rest/rate-limits/).

List regions

Method: GET
Path: /contact_center/regions
Tags: Regions

Get information about all available regions.

Scopes: contact_center_region:read:admin

Granular Scopes: contact_center:read:list_regions:admin

Rate Limit Label: MEDIUM

Responses

Status: 200 HTTP Status Code: `200` Region list returned.

Content-Type: application/json

next_page_token

string — Use the next page token to paginate through large result sets. A next page token returns whenever the set of available results exceeds the current page size. This token's expiration period is 15 minutes.
page_size

integer, default: 30 — The number of records returned within a single API call.
regions

array — Information about the regions.

Items:
- is_main_region
  
  boolean — Whether this region is the main region.
- last_modified_time
  
  string, format: date-time — The date and time when the asset was last modified.
- region_id
  
  string — The region's ID.
- region_name
  
  string — The region's name.
- sip_zone_id
  
  string — The region SIP zone's ID.
- sip_zone_name
  
  string — The region SIP zone's name.
- users_count
  
  integer — The number of users assigned to region.
total_records

integer — The total number of all the records available across pages.

Example:

{
  "next_page_token": "R4aF9Oj0fVM2hhezJTEmSKaBSkfesDwGy42",
  "page_size": 30,
  "total_records": 1,
  "regions": [
    {
      "region_id": "36c8dc7c-695f-11ed-a081-0a514d46f86b",
      "region_name": "Main Region",
      "is_main_region": true,
      "sip_zone_id": "AfgzMEweSQ6tqzC8jhYJ2A",
      "sip_zone_name": "zccsipzone",
      "users_count": 20,
      "last_modified_time": "2022-02-15T09:27:15Z"
    }
  ]
}

Status: 400 HTTP Status Code: `400` Bad Request

Status: 429 HTTP Status Code: `429` Too Many Requests. For more information, see [rate limits](https://developers.zoom.us/docs/api/rest/rate-limits/).

Create a region

Method: POST
Path: /contact_center/regions
Tags: Regions

Create a new region.

Scopes: contact_center_region:write:admin

Granular Scopes: contact_center:write:region:admin

Rate Limit Label: LIGHT

Request Body

Content-Type: application/json

region_name

string — The region's name.
sip_zone_id

string — The region SIP zone's ID.

Example:

{
  "region_name": "Customer region",
  "sip_zone_id": "AfgzMEweSQ6tqzC8jhYJ2A"
}

Responses

Status: 200 HTTP Status Code: `201` Region created.

Content-Type: application/json

region_id

string — The region's ID.
region_name

string — The region's name.
sip_zone_id

string — The region SIP zone's ID.

Example:

{
  "region_name": "Customer region",
  "region_id": "6c8dc7c-695f-11ed-a081-0a514d46f86b",
  "sip_zone_id": "AfgzMEweSQ6tqzC8jhYJ2A"
}

Status: 400 HTTP Status Code: `400` Bad Request

Status: 429 HTTP Status Code: `429` Too Many Requests. For more information, see [rate limits](https://developers.zoom.us/docs/api/rest/rate-limits/).

Get a region

Method: GET
Path: /contact_center/regions/{regionId}
Tags: Regions

Get information about a region.

Scopes: contact_center_region:read:admin

Granular Scopes: contact_center:read:region:admin

Rate Limit Label: LIGHT

Responses

Status: 200 HTTP Status Code: `200` Region returned.

Content-Type: application/json

is_main_region

boolean — Whether this region is the main region.
region_id

string — The region's ID.
region_name

string — The region's name.
sip_zone_id

string — The region SIP zone's ID.
sip_zone_name

string — The region SIP zone's ID.

Example:

{
  "region_id": "36c8dc7c-695f-11ed-a081-0a514d46f86b",
  "region_name": "Main Region",
  "sip_zone_id": "AfgzMEweSQ6tqzC8jhYJ2A",
  "sip_zone_name": "zccsipzone",
  "is_main_region": true
}

Status: 400 HTTP Status Code: `400` Bad Request Error Code: `3807` More than one matching region found.

Status: 404 HTTP Status Code: `404` Not Found

Status: 429 HTTP Status Code: `429` Too Many Requests. For more information, see [rate limits](https://developers.zoom.us/docs/api/rate-limits/).

Delete a region

Method: DELETE
Path: /contact_center/regions/{regionId}
Tags: Regions

Delete a site and move its members to another region.

Scopes: contact_center_region:write:admin

Granular Scopes: contact_center:delete:region:admin

Rate Limit Label: LIGHT

Responses

Status: 204 HTTP Status Code: `204` Region deleted.

Status: 400 HTTP Status Code: `400` Bad Request Error Code: `3802` The main region cannot be deleted. Error Code: `3803` The `regionId` and `move_to_region_id` can't be the same. Error Code: `3806` The `move_to_region_id`'s region has a misconfigured SIP zone country. Error Code: `3807` More than one matching region found.

Status: 401 HTTP Status Code: `401` Unauthorized Error Code: `124` Invalid access token. Error Code: `124` Access token has expired. Error Code: `1002` The user associated with this access token was not found or is invalid.

Status: 403 HTTP Status Code: `403` Forbidden Error Code: `1021` User account is deactivated. Error Code: `1022` User does not have a Contact Center license. Error Code: `9001` The Contact Center user associated with this bearer token is missing privileges on their role required to operate this request.

Status: 404 HTTP Status Code: `404` Not Found Error Code: `3801` Region does not exist: {regionId}.

Status: 429 HTTP Status Code: `429` Too Many Requests. For more information, see [rate limits](https://developers.zoom.us/docs/api/rate-limits/). Error Code: `4001` You have reached the maximum per-second rate limit for this API. Try again later.

Update a region

Method: PATCH
Path: /contact_center/regions/{regionId}
Tags: Regions

Update information for a region.

Scopes: contact_center_region:write:admin

Granular Scopes: contact_center:udpate:region:admin

Rate Limit Label: LIGHT

Request Body

Content-Type: application/json

region_name

string — The region's name.
sip_zone_id

string — The region SIP zone's ID.

Example:

{
  "region_name": "Customer region",
  "sip_zone_id": "AfgzMEweSQ6tqzC8jhYJ2A"
}

Responses

Status: 204 HTTP Status Code: `204` Region updated.

Status: 400 HTTP Status Code: `400` Bad Request Error Code: `3807` More than one matching region found.

Status: 404 HTTP Status Code: `404` Not Found

Status: 429 HTTP Status Code: `429` Too Many Requests. For more information, see [rate limits](https://developers.zoom.us/docs/api/rate-limits/).

List a region's users

Method: GET
Path: /contact_center/regions/{regionId}/users
Tags: Regions

Retrieve the list of a region's assigned Contact Center users.

Scopes: contact_center_region:read:admin

Granular Scopes: contact_center:read:list_region_users:admin

Rate Limit Label: MEDIUM

Responses

Status: 200 HTTP Status Code: `200` The region's Contact Center users.

Content-Type: application/json

next_page_token

string — Use the next page token to paginate through large result sets. A next page token is returned whenever the set of available results exceeds the current page size. This token's expiration period is 15 minutes.
page_size

integer, default: 10 — The number of records returned within a single API call.
total_records

integer — The total number of all records available across pages.
users

array — Contact Center users assigned to the region.

Items:
- cc_user_id
  
  string — The Contact Center user identifier.
- display_name
  
  string — The user's display name.
- role_id
  
  string — The user's Contact Center role identifier.
- role_name
  
  string — The user's Contact Center role name.
- user_email
  
  string, format: email — The user's email address.
- user_id
  
  string — The Meetings user identifier.

Example:

{
  "next_page_token": "R4aF9Oj0fVM2hhezJTEmSKaBSkfesDwGy42",
  "page_size": 10,
  "total_records": 10,
  "users": [
    {
      "user_id": "IGTRVt3gQ2i-WjoUIjeZxw",
      "cc_user_id": "hKuMAiDdRlSwMkBxR5we7g",
      "display_name": "Jane Doe",
      "user_email": "jchill@example.com",
      "role_id": "0TFVsJqNS82CwkQJLqj1zA",
      "role_name": "Admin"
    }
  ]
}

Status: 400 HTTP Status Code: `400` Bad Request Error Code: `400` Region is not enabled for this account: $accountId. Error Code: `3807` More than one matching region found.

Status: 401 HTTP Status Code: `401` Unauthorized Error Code: `124` Invalid access token. Error Code: `124` Access token has expired. Error Code: `1002` The user associated with this access token was not found or is invalid.

Status: 403 HTTP Status Code: `403` Forbidden Error Code: `1021` User account is deactivated. Error Code: `1022` User does not have a Contact Center license. Error Code: `9001` The Contact Center user associated with this bearer token is missing privileges on their role required to operate this request.

Status: 404 HTTP Status Code: `404` Not Found Error Code: `1017` Region does not exist: $regionId.

Status: 429 HTTP Status Code: `429` Too Many Requests. For more information, see [rate limits](/docs/api/rest/rate-limits/). Error Code: `4001` You have reached the maximum per-second rate limit for this API. Try again later.

Assign users to a region

Method: POST
Path: /contact_center/regions/{regionId}/users
Tags: Regions

Assign users to a region.

Scopes: contact_center_region:write:admin

Granular Scopes: contact_center:write:region_user:admin

Rate Limit Label: LIGHT

Request Body

Content-Type: application/json

user_ids

array — The user identifiers. The values can be a mix of email addresses, Meetings user IDs, or Contact Center user IDs.

Items:

string

Example:

{
  "user_ids": [
    "IGTRVt3gQ2i-WjoUIjeZxw"
  ]
}

Responses

Status: 201 HTTP Status Code: `201` Users assigned.

Status: 400 HTTP Status Code: `400` Bad Request Error Code: `400` Region is not enabled for this account: $accountId. Error Code: `3807` More than one matching region found.

Status: 404 HTTP Status Code: `404` Not Found Error Code: `1017` Region does not exist: $regionId.

Status: 429 HTTP Status Code: `429` Too Many Requests. For more information, see [rate limits](https://developers.zoom.us/docs/api/rest/rate-limits/).

List agent leg reports

Method: GET
Path: /contact_center/analytics/agents/leg_metrics
Tags: Reports V1 (Legacy)

Generate a list of agent's leg reports.

Scopes: contact_center_report:read:admin

Granular Scopes: contact_center:read:agent_report:admin

Rate Limit Label: HEAVY

Responses

Status: 200 HTTP Status Code: `200` Agent's leg reports list returned.

Content-Type: application/json

from

string — The start time and date. Format is either `yyyy-MM-dd'T'HH:mm:ss'Z'` or `yyyy-MM-dd'T'HH:mm:ss±HH:mm`, matching the input format when a timezone offset was provided.
next_page_token

string — Use the next page token to paginate through large result sets. A next page token is returned whenever the set of available results exceeds the current page size. This token's expiration period is 15 minutes.
page_size

integer, default: 10 — The number of records returned within a single API call.
timezone

string — The call's [timezone ID](/docs/api/references/abbreviations/#timezones). The default is `UTC`.
to

string — The end time and date. Format is either `yyyy-MM-dd'T'HH:mm:ss'Z'` or `yyyy-MM-dd'T'HH:mm:ss±HH:mm`, matching the input format when a timezone offset was provided.
total_records

integer — The total number of all the records available across pages.
users

array — Information about the agent's leg reports.

Items:
- display_name
  
  string — The agent's name.
- leg_metrics
  
  array — Details about the leg reports of the current agent.
  
  Items:
  - agent_end_time
    
    string — The agent leg end time. Format is either `yyyy-MM-dd'T'HH:mm:ss'Z'` or `yyyy-MM-dd'T'HH:mm:ss±HH:mm`, matching the input format when a timezone offset was provided.
  - agent_first_response_duration
    
    number — The amount of time it takes for an agent working a messaging channel to send the first message to a customer, in seconds.
  - agent_offered
    
    integer — The number of calls are offered to current agent.
  - agent_start_time
    
    string — The agent leg start time. Format is either `yyyy-MM-dd'T'HH:mm:ss'Z'` or `yyyy-MM-dd'T'HH:mm:ss±HH:mm`, matching the input format when a timezone offset was provided.
  - cc_queue_id
    
    string — The Contact Center queue's ID.
  - channel
    
    string, possible values: "voice", "video", "messaging", "email" — The task's channel.
  - channel_source
    
    string, possible values: "in_app_chat", "web_chat", "sms", "facebook_messenger", "whatsapp", "instagram" — The channel's source.
  - conference_count
    
    integer — The number of conferences the agent entered.
  - conference_duration
    
    number — The amount of time spent on conferences, including multiple confernces, in seconds.
  - conversation_duration
    
    number — The amount of time an agent spent in active conversation with an engagement for any channel, in seconds.
  - direct_transfer
    
    boolean — The indicator to determine if an agent initiated a direct transfer.
  - disposition_id
    
    string — The disposition's ID.
  - disposition_name
    
    string — The disposition's name.
  - engagement_id
    
    string — The engagement's ID
  - handle_duration
    
    number — The amount of time an agent spent actively working an engagement, in seconds.
  - handled_engagement
    
    boolean — The indicator to determine if an agent handled an agent offer.
  - hold_count
    
    integer — The number of times that the agent places a consumer on hold.
  - hold_duration
    
    number — The total amount of time that the agent placed a consumer on hold, in seconds.
  - queue_name
    
    string — The queue's name.
  - refused_engagement
    
    boolean — The indicator to determine if an agent missed or declined an agent offer.
  - ring_duration
    
    number — The amount of time it takes for an agent to answer the engagement, in seconds.
  - transferred_completed
    
    integer — The number of transfers an agent completed, including warm and direct transfers for voice and video channels, and all transfers for messaging and email channels with no distinction between warm and direct transfers.
  - transferred_initiated
    
    integer — The number of transfers an agent initiated, including warm and direct transfers for voice and video channels, and all transfers for messaging and email channels with no distinction between warm and direct transfers.
  - warm_conference
    
    integer — The number of warm conferences triggered by the agent.
  - warm_conference_duration
    
    number — The amount of time an agent spent in conversation with another agent while the engagement was on hold, in seconds.
  - warm_transfer_completed
    
    integer — The number of engagements an agent answered and then warm transferred with another participant and then fully transferred the engagements.
  - warm_transfer_duration
    
    number — The amount of time spent on warm transfers, in seconds.
  - warm_transfer_initiated
    
    integer — The number of engagements an agent answered and then warm transferred with another participant with or without fully transferring the engagement.
  - wrap_up_duration
    
    number — The amount of time agents spent completing engagement wrap-up, in seconds.
- user_email
  
  string — The agent's email.
- user_id
  
  string — The agent's ID.

Example:

{
  "next_page_token": "R4aF9Oj0fVM2hhezJTEmSKaBSkfesDwGy42",
  "page_size": 10,
  "total_records": 10,
  "timezone": "America/Los_Angeles",
  "from": "2021-12-10T00:00:00Z",
  "to": "2021-12-10T00:15:00Z",
  "users": [
    {
      "user_id": "ukAAkZKfROKMSw1bj_RDFQ",
      "display_name": "joe.chill",
      "user_email": "joe.chill@example.com",
      "leg_metrics": [
        {
          "channel": "messaging",
          "channel_source": "in_app_chat",
          "engagement_id": "reRAiabVQSqpXxJVDbsy2Q",
          "cc_queue_id": "Ql3qxUWXSHes4PmcOmzyOg",
          "queue_name": "agentQueue",
          "agent_offered": 1,
          "refused_engagement": false,
          "handled_engagement": true,
          "handle_duration": 90,
          "agent_first_response_duration": 1,
          "ring_duration": 8,
          "conversation_duration": 80,
          "hold_count": 0,
          "hold_duration": 0,
          "warm_conference": 1,
          "warm_conference_duration": 10,
          "conference_count": 1,
          "conference_duration": 10,
          "warm_transfer_initiated": 1,
          "warm_transfer_completed": 1,
          "warm_transfer_duration": 30,
          "direct_transfer": false,
          "transferred_initiated": 1,
          "transferred_completed": 1,
          "wrap_up_duration": 10,
          "disposition_id": "TaAGy_e7QgyPPAyDwGkl3Q",
          "disposition_name": "disposition1",
          "agent_start_time": "2020-02-11T05:39:50Z",
          "agent_end_time": "2020-02-11T05:39:56Z"
        }
      ]
    }
  ]
}

Status: 400 HTTP Status Code: `400` Bad Request Error Code: `300` The time and date must be in `yyyy-mm-dd` format, or ISO 8601 format, either `yyyy-MM-dd'T'HH:mm:ss'Z'` or `yyyy-MM-dd'T'HH:mm:ss'TZD'`. Error Code: `300` The requested report exceeds the 1-month limit. Error Code: `300` Timezone does not exist: {timezone}. Error Code: `300` Only provide report in recent 6 months. Error Code: `300` Invalid field.

Status: 404 HTTP Status Code: `404` Not Found Error Code: `1001` User does not exist: {userId}.

Status: 429 HTTP Status Code: `429` Too Many Requests. For more information, see [rate limits](/docs/api/rate-limits/).

List agent's status history reports

Method: GET
Path: /contact_center/analytics/agents/status_history
Tags: Reports V1 (Legacy)

Generate a list of an agent's status history reports.

Scopes: contact_center_report:read:admin

Granular Scopes: contact_center:read:agent_status_report:admin

Rate Limit Label: HEAVY

Responses

Status: 200 HTTP Status Code: `200` Agent's status history reports list returned.

Content-Type: application/json

from

string, format: date-time — The start date and time of the returned data. Format is either `yyyy-MM-dd'T'HH:mm:ss'Z'` or `yyyy-MM-dd'T'HH:mm:ss±HH:mm`, matching the input format when timezone offset was provided.
next_page_token

string — Use the next page token to paginate through large result sets. A next page token is returned whenever the set of available results exceeds the current page size. This token's expiration period is 15 minutes.
page_size

integer, default: 10 — The number of records returned within a single API call.
statuses

array — Information about the agent's status history reports.

Items:
- display_name
  
  string — The agent's name.
- duration
  
  integer, format: int64 — The agent's status-changed duration, in seconds.
- end_time
  
  string — The date and time when the status ended. Format: `yyyy-MM-dd'T'HH:mm:ss'Z'` or `yyyy-MM-dd'T'HH:mm:ss±HH:mm` (matching the input format when timezone offset was provided).
- occupied_engagement_id
  
  string — The engagement's ID when the agent status is occupied.
- occupied_engagements
  
  array — The engagements that the agent has while in the occupied status
  
  Items:
  - cc_queue_id
    
    string — The queue's ID.
  - engagement_id
    
    string — The engagement's ID.
  - queue_name
    
    string — The queue's version.
- occupied_queue_id
  
  string — The queue's ID when the agent status is occupied.
- occupied_queue_name
  
  string — The queue's name when the agent status is occupied.
- start_time
  
  string — The date and time when the status started. Format: `yyyy-MM-dd'T'HH:mm:ss'Z'` or `yyyy-MM-dd'T'HH:mm:ss±HH:mm` (matching the input format when timezone offset was provided).
- status_id
  
  string — The status's ID.
- status_name
  
  string, possible values: "Offline", "Ready", "Not Ready", "Occupied", "string" — The status's name. * Offline * Ready * Not Ready * Occupied * A custom user status, such as "Lunch" or "Out on Monday".
- sub_status_id
  
  string — The sub status's ID.
- sub_status_name
  
  string, possible values: "Inbound", "Transferring in", "Wrapping up", "Holding", "Transferring out", "Taking Over", "Monitoring", "Barging", "Whispering", "Outbound", "string" — The sub status's name. * Inbound * Transferring in * Wrapping up * Holding * Transferring out * Taking over * Monitoring * Barging * Whispering * Outbound * A custom sub status, such as "Break" or "Out on Monday".
- user_id
  
  string — The agent's ID.
timezone

string — The timezone used for the query. When the request used `yyyy-MM-dd'T'HH:mm:ss±HH:mm` format, this reflects the offset from the input. Otherwise, it reflects the `timezone` parameter value or the default `UTC`.
to

string, format: date-time — The end date and time of the returned data. Format matches the `from` field.
total_records

integer — The total number of all the records available across pages.

Example:

{
  "next_page_token": "R4aF9Oj0fVM2hhezJTEmSKaBSkfesDwGy42",
  "page_size": 10,
  "total_records": 10,
  "timezone": "America/Los_Angeles",
  "from": "2021-12-10T00:00:00Z",
  "to": "2021-12-10T00:15:00Z",
  "statuses": [
    {
      "user_id": "ukAAkZKfROKMSw1bj_RDFQ",
      "display_name": "Jilly",
      "status_id": "1",
      "occupied_engagements": [
        {
          "engagement_id": "zeYjXoDOS_eV1QmTpj63PQ",
          "cc_queue_id": "beGjiO3_TK2rxi5fh2Zv7A",
          "queue_name": "Demo"
        }
      ],
      "status_name": "Not Ready",
      "sub_status_id": "101",
      "sub_status_name": "Inbound",
      "start_time": "2022-07-20T14:00:00-08:00",
      "end_time": "2022-07-20T14:15:00-08:00",
      "duration": 1
    }
  ]
}

Status: 400 HTTP Status Code: `400` Bad Request Error Code: `300` The time and date must be in yyyy-mm-dd or ISO 8601 format (yyyy-MM-dd'T'HH:mm:ss'Z' or yyyy-MM-dd'T'HH:mm:ss'TZD'). Error Code: `300` The requested report exceeds the 1-month limit. Error Code: `300` Timezone does not exist: {timezone}. Error Code: `300` Only provide report in recent 6 months.

Status: 404 HTTP Status Code: `404` Not Found Error Code: `1201` Queue does not exist: $queueId. Error Code: `1001` User does not exist: $userId. Error Code: `1101` Status does not exist: $statusId. Error Code: `1102` Sub status does not exist: $subStatusId.

Status: 429 HTTP Status Code: `429` Too Many Requests. For more information, see [rate limits](https://developers.zoom.us/docs/api/rest/rate-limits/).

List agent's time sheet reports

Method: GET
Path: /contact_center/analytics/agents/time_sheets
Tags: Reports V1 (Legacy)

Generate a list of an agent's time sheet reports.

Scopes: contact_center_report:read:admin

Granular Scopes: contact_center:read:agent_report:admin

Rate Limit Label: HEAVY

Responses

Status: 200 HTTP Status Code: `200` Agent's time sheet reports list returned.

Content-Type: application/json

agents

array — Information about the agent's time sheet reports.

Items:
- average_video_call_talking_duration
  
  integer, format: int64 — The average video call duration, in seconds.
- average_wrap_up_duration
  
  integer, format: int64 — The average wrap-up call duration, in seconds.
- display_name
  
  string — The agent's name.
- end_time_interval
  
  string — The current interval's end date and time in ISO 8601 format, either yyyy-MM-dd'T'HH:mm:ss'Z' or yyyy-MM-dd'T'HH:mm:ss`TZD`.
- inbound_average_voice_call_talking_duration
  
  integer, format: int64 — The average voice call duration, in seconds.
- not_ready_duration
  
  integer, format: int64 — The total not-ready status time, in seconds.
- not_ready_percentage
  
  integer, format: int32 — The percentage of not ready status.
- occupied_duration
  
  integer, format: int64 — The total occupied-status time, in seconds.
- occupied_percentage
  
  integer, format: int32 — The occupied-status percentage.
- offline_duration
  
  integer, format: int64 — The total offline-status time, in seconds.
- online_duration
  
  integer, format: int64 — The total online-status time, in seconds.
- ready_duration
  
  integer, format: int64 — The total ready status time, in seconds.
- ready_percentage
  
  integer, format: int32 — The percentage of ready status.
- start_time_interval
  
  string — The current interval's start date and time in ISO 8601 format, either yyyy-MM-dd'T'HH:mm:ss'Z' or yyyy-MM-dd'T'HH:mm:ss`TZD`.
- total_inbound_voice_call
  
  integer, format: int64 — The total number of inbound voice calls.
- total_inbound_voice_call_duration
  
  number, format: double — The total inbound voice calls duration, in seconds.
- total_outbound_voice_call
  
  integer, format: int64 — The total number of outbound voice calls.
- total_outbound_voice_call_duration
  
  number, format: double — The total outbound voice calls duration, in seconds.
- user_id
  
  string — The agent's ID.
from

string, format: date-time — The start time and date in **yyyy-MM-dd'T'HH:mm:ss'Z'** format. The defined date range should be a month, as the response only includes one month's worth of data. If no start date is specified, return data from the past 24 hours.
next_page_token

string — Use the next-page token to paginate through large result sets. A next-page token returns whenever the set of available results exceeds the current page size.
page_size

integer, default: 10 — The number of records returned within a single API call.
timezone

string — The call's [timezone ID](https://developers.zoom.us/docs/api/rest/other-references/abbreviation-lists/#timezones). The default is **UTC**.
to

string, format: date-time — **Required** only when the `from` parameter is specified. The end time and date in **yyyy-MM-dd'T'HH:mm:ss'Z'** format, the same format as the `from` parameter.
total_records

integer — The total number of all the records available across pages.

Example:

{
  "next_page_token": "jA5csQv1W1oXuYZLspNIZzMOXqTD9r9Rje2",
  "page_size": 1,
  "total_records": 1,
  "timezone": "America/Los_Angeles",
  "from": "2021-12-10T00:00:00Z",
  "to": "2021-12-10T00:15:00Z",
  "agents": [
    {
      "user_id": "ukAAkZKfROKMSw1bj_RDFQ",
      "display_name": "Jilly",
      "ready_duration": 3600,
      "ready_percentage": 85,
      "not_ready_duration": 3600,
      "not_ready_percentage": 85,
      "occupied_duration": 3600,
      "occupied_percentage": 85,
      "online_duration": 3600,
      "offline_duration": 3600,
      "inbound_average_voice_call_talking_duration": 3600,
      "average_video_call_talking_duration": 3600,
      "average_wrap_up_duration": 3600,
      "start_time_interval": "2022-07-20T14:00:00-08:00",
      "end_time_interval": "2022-07-20T14:15:00-08:00",
      "total_outbound_voice_call": 3,
      "total_outbound_voice_call_duration": 50,
      "total_inbound_voice_call": 3,
      "total_inbound_voice_call_duration": 78
    }
  ]
}

Status: 400 HTTP Status Code: `400` Bad Request

Status: 404 HTTP Status Code: `404` Not Found Error Code: `1201` Queue does not exist: $queueId. Error Code: `1001` User does not exist: $userId.

Status: 429 HTTP Status Code: `429` Too Many Requests. For more information, see [rate limits](https://developers.zoom.us/docs/api/rest/rate-limits/).

List historical detail reports

Method: GET
Path: /contact_center/analytics/historical/details/metrics
Tags: Reports V1 (Legacy)

Retrieve historical engagement details.

The maximum lookback time is 6 months.

Scopes: contact_center_report:read:admin

Granular Scopes: contact_center:read:engagement_report:admin

Rate Limit Label: HEAVY

Responses

Status: 200 HTTP Status Code: `200` Historical detail reports list returned.

Content-Type: application/json

details

array — The information about the historical detail reports.

Items:
- agent_first_message_speed
  
  integer, format: int64 — The engagement's initial response time, in seconds.
- agent_skills
  
  array — The agent skill names. Applicable to voice channels.
  
  Items:
  - proficiency_level
    
    integer — The skill category's proficiency level.
  - skill_id
    
    string — The skill's ID.
  - skill_name
    
    string — The skill's name.
- agents
  
  array — Information about the engagement's agents.
  
  Items:
  - display_name
    
    string — The agent's name.
  - user_id
    
    string — The agent's ID.
- callback_pending_duration
  
  integer, format: int64 — The callback pending duration, in seconds. Applicable to voice channels.
- callback_waiting_duration
  
  integer, format: int64 — The callback waiting duration, in seconds. Applicable to voice channels.
- channels
  
  array — The task's channels
  
  Items:
  - channel
    
    string, possible values: "voice", "video", "messaging", "email" — The task's channel.
  - channel_source
    
    string, possible values: "web_chat", "in_app_chat", "sms", "facebook_messenger", "whatsapp", "email_address" — The channel's source. * `in_app_chat` - Only applies to messaging channel. * `web_chat` - Only applies to messaging channel. * `sms` - Only applies to messaging channel. * `facebook_messenger` - Only applies to messaging channel. * `whatsapp` - Only applies to messaging channel. * `email_address` - Only applies to email channel.
- consumer_country_code
  
  string — The consumer's number [country name](/docs/api/references/abbreviations/#countries), for voice and SMS.
- consumer_country_name
  
  string — The consumer's number [country name](/docs/api/references/abbreviations/#countries), for voice and SMS.
- consumer_id
  
  string — The consumer's ID, for video and chat and email.
- consumer_name
  
  string — The consumer's name, for video and chat and email.
- consumer_number
  
  string — The consumer's phone number.
- dialed_numbers
  
  array — The dialed numbers. Applicable to voice, video, and SMS channels.
  
  Items:
  
  string
- direction
  
  string, possible values: "inbound", "outbound" — The engagement's direction.
- disposition_id
  
  string — The disposition's ID.
- disposition_name
  
  string — The disposition's name.
- engagement_id
  
  string — The engagement's ID
- flows
  
  array — Information about the engagement's flows.
  
  Items:
  - flow_id
    
    string — The flow's ID.
  - flow_name
    
    string — The flow's name.
  - flow_version
    
    string — The flow's version.
- handling_duration
  
  integer, format: int64 — The handling duration, in seconds. Applicable to voice channels.
- hold_duration
  
  integer, format: int64 — The engagement's hold duration, in seconds.
- ivr_duration
  
  integer, format: int64 — The engagement's IVR duration, in seconds.
- last_widget_name
  
  string — The last widget's name.
- optional_skills
  
  array — The optional skill names. Applicable to voice channels.
  
  Items:
  - matched
    
    boolean — Whether the skill is matched.
  - skill_id
    
    string — The skill's ID.
  - skill_name
    
    string — The skill's name.
- queue_wait_type
  
  string, possible values: "live_waiting", "callback" — The queue's wait type. Applicable to voice channels.
- queues
  
  array — Information about the engagement's queues.
  
  Items:
  - cc_queue_id
    
    string — The Contact Center queue's ID.
  - queue_id
    
    string — The queue's ID.
  - queue_name
    
    string — The queue's name.
- required_skills
  
  array — The required skill names. Applicable to voice channels.
  
  Items:
  - minimum_proficiency_level
    
    integer — The skill category's minimum proficiency level.
  - skill_id
    
    string — The skill's ID.
  - skill_name
    
    string — The skill's name.
- results
  
  string, possible values: "completed", "contained", "short_abandoned", "long_abandoned", "hold_abandoned", "overflowed", "overflowed_to_inbox", "overflowed_to_disconnect", "long_calls", "short_calls", "hang_up_calls", "auto_closed", "abandon_quit", "callback_abandoned_by_consumer" — The engagement's result.
- ring_duration
  
  integer, format: int64 — The ring duration, in seconds. Applicable to voice and video channels.
- start_time
  
  string, format: date-time — The engagement's starting date and time. Format is `yyyy-MM-dd'T'HH:mm:ss'Z'` or `yyyy-MM-dd'T'HH:mm:ss±HH:mm`, matching the input format when timezone offset was provided.
- talking_duration
  
  integer, format: int64 — The engagement's talking duration, in seconds.
- total_duration
  
  integer, format: int64 — The engagement's maximum agent duration, in seconds.
- total_flow_duration
  
  integer, format: int64 — The total time of engagement's flows, in seconds.
- waiting_duration
  
  integer, format: int64 — The engagement's waiting duration, in seconds.
- wrap_up_duration
  
  integer, format: int64 — The engagement's wrap-up duration, in seconds.
from

string, format: date-time — The returned data's start date and time. Format: `yyyy-MM-dd'T'HH:mm:ss'Z'` or `yyyy-MM-dd'T'HH:mm:ss±HH:mm`, matching the input format when timezone offset was provided.
next_page_token

string — Use the next page token to paginate through large result sets. A next page token is returned whenever the set of available results exceeds the current page size. This token's expiration period is 15 minutes.
page_size

integer, default: 10 — The number of records returned within a single API call.
timezone

string — The timezone used for the query. When the request used `yyyy-MM-dd'T'HH:mm:ss±HH:mm` format, this reflects the offset from the input. Otherwise, it reflects the `timezone` parameter value or the default `UTC`.
to

string, format: date-time — The returned data's end date and time. Format matches the `from` field.
total_records

integer — The total number of all the records available across pages.

Example:

{
  "next_page_token": "R4aF9Oj0fVM2hhezJTEmSKaBSkfesDwGy42",
  "page_size": 10,
  "total_records": 10,
  "timezone": "America/Los_Angeles",
  "from": "2021-12-10T00:00:00Z",
  "to": "2021-12-10T00:15:00Z",
  "details": [
    {
      "engagement_id": "3XilEfOvQEKRIWMWhX1jDg",
      "channels": [
        {
          "channel": "messaging",
          "channel_source": "in_app_chat"
        }
      ],
      "direction": "inbound",
      "consumer_number": "+12059300920",
      "consumer_id": "zeYjXoDOS_eV1QmTpj63PQ",
      "consumer_name": "Tester",
      "consumer_country_name": "United States of America",
      "consumer_country_code": "US",
      "start_time": "2020-02-11T05:39:50Z",
      "results": "completed",
      "total_duration": 10,
      "ivr_duration": 5,
      "waiting_duration": 10,
      "talking_duration": 20,
      "hold_duration": 20,
      "wrap_up_duration": 10,
      "disposition_id": "W_VATTk_Q5aW6z5rZtBxAQ",
      "disposition_name": "Inquiry",
      "flows": [
        {
          "flow_id": "zeYjXoDOS_eV1QmTpj63PQ",
          "flow_name": "Demo",
          "flow_version": "5"
        }
      ],
      "queues": [
        {
          "cc_queue_id": "d95avl1eRJ-H162PZUJ-qg",
          "queue_name": "agentQueue"
        }
      ],
      "agents": [
        {
          "user_id": "ukAAkZKfROKMSw1bj_RDFQ",
          "display_name": "Jilly"
        }
      ],
      "total_flow_duration": 10,
      "queue_wait_type": "live_waiting",
      "last_widget_name": "PhoneEnQueue RouteTo",
      "agent_first_message_speed": 0,
      "dialed_numbers": [
        "+12059300920"
      ],
      "callback_waiting_duration": 0,
      "callback_pending_duration": 0,
      "handling_duration": 0,
      "ring_duration": 0,
      "required_skills": [
        {
          "skill_id": "saaHWgVMGQU69soco456oNA",
          "skill_name": "French",
          "minimum_proficiency_level": 1
        }
      ],
      "optional_skills": [
        {
          "skill_id": "saaHWgVMGQU69soco456oNA",
          "skill_name": "French",
          "matched": false
        }
      ],
      "agent_skills": [
        {
          "skill_id": "saaHWgVMGQU69soco456oNA",
          "skill_name": "French",
          "proficiency_level": 1
        }
      ]
    }
  ]
}

Status: 400 HTTP Status Code: `400` Bad Request Error Code: `300` `yyyy-mm-dd` or ISO 8601 format, either `yyyy-MM-dd'T'HH:mm:ss'Z' or yyyy-MM-dd'T'HH:mm:ss'TZD'. Error Code: `300` The requested report exceeds the 1-month limit. Error Code: `300` Timezone does not exist: {timezone}. Error Code: `300` Only provide report in recent 6 months.

Status: 404 HTTP Status Code: `404` Not Found Error Code: `1201` Queue does not exist: $queueId. Error Code: `1001` User does not exist: $userId.

Status: 429 HTTP Status Code: `429` Too Many Requests. For more information, see [rate limits](https://developers.zoom.us/docs/api/rate-limits/).

List historical agent reports by queue

Method: GET
Path: /contact_center/analytics/historical/queues/agents/metrics
Tags: Reports V1 (Legacy)

Generate detailed historical reports of agents from a specific queue.

Scopes: contact_center_report:read:admin

Granular Scopes: contact_center:read:agent_report:admin

Rate Limit Label: HEAVY

Responses

Status: 200 HTTP Status Code: 200 Historical queue's agents report list returned.

Content-Type: application/json

agents

array — Information about the queue's agents.

Items:
- display_name
  
  string — The agent's name.
- user_id
  
  string — The agent's ID.
- voice
  
  object — Metrics for voice channel engagements. Includes offer counts, handling durations, ring durations, hold durations, wrap-up durations, and outbound call metrics.
  - average_inbound_answer_duration
    
    number — The average time that consumers spent talking to an agent. Talking duration includes talking time and hold duration.
  - average_inbound_handling_duration
    
    number — Average inbound handling duration. Handling duration = talking duration (hold duration included) + wrap-up Duration.
  - average_inbound_hold_duration
    
    number — The average amount of time that a consumer was placed on hold during the inbound engagement.
  - average_inbound_ring_duration
    
    number — The average amount of time it takes for an agent to answer the inbound engagement. It is from the system assigning the call to the agent and before the agent answers
  - average_inbound_wrap_up_duration
    
    number — The average amount of time that an agent spent in the wrap-up period.
  - average_outbound_answer_duration
    
    number — The average time that consumers spent talking to an agent. Talking duration includes talking time and hold duration.
  - average_outbound_handling_duration
    
    number — Average outbound handling duration. Handling duration = talking duration (hold duration included) + wrap-up Duration.
  - average_outbound_hold_duration
    
    number — The average amount of time that a consumer was placed on hold during the outbound engagement.
  - average_outbound_ring_duration
    
    number — The average amount of time that agents wait for their outbound engagement to be answered.
  - average_outbound_wrap_up_duration
    
    number — The average amount of time that an agent spent in the wrap-up period.
  - hangup_outbound
    
    integer — How many of the agent's outbound calls had a duration shorter than the hang-up threshold for the queue.
  - hold_hang_up
    
    integer — Hold Hang Up that are presented how many engagements were hanged up by the consumer while on hold with the agent.
  - long_outbound
    
    integer — How many of the agent's outbound calls had a duration longer than the long call threshold for the queue.
  - longest_inbound_answer_duration
    
    number — The maximum amount of time it takes for an agent to answer the inbound engagement. It is from the system assigning the call to the agent and before the agent answers.
  - longest_inbound_handling_duration
    
    number — Maximum inbound handling duration. Handling duration = talking duration (hold duration included) + wrap-up Duration.
  - longest_inbound_hold_duration
    
    number — The maximum amount of time that a consumer was placed on hold during the inbound engagement.
  - longest_inbound_ring_duration
    
    number — The maximum amount of time it takes for an agent to answer the inbound engagement. It is from the system assigning the call to the agent and before the agent answers.
  - longest_inbound_wrap_up_duration
    
    number — The maximum amount of time that an agent spent in the wrap-up period.
  - longest_outbound_answer_duration
    
    number — The maximum time that consumers spent talking to an agent. Talking duration includes talking time and hold duration.
  - longest_outbound_handling_duration
    
    number — The maximum outbound handling duration. Handling duration = talking duration (hold duration included) + wrap-up Duration.
  - longest_outbound_hold_duration
    
    number — The maximum amount of time that a consumer was placed on hold during the outbound engagement.
  - longest_outbound_ring_duration
    
    number — The maximum amount of time that agents wait for their outbound engagement to be answered.
  - longest_outbound_wrap_up_duration
    
    number — The maximum amount of time that an agent spent in the wrap-up period.
  - offers_acd
    
    integer — Offers ACD metric indicates presented to the agent via the queue distribution.
  - offers_answered
    
    integer — The number of engagements assigned to the agent that were answered.
  - offers_answered_acd_inbound
    
    integer — The number of inbound engagements assigned to the agent that were answered.
  - offers_declined
    
    integer — The number of inbound engagements declined by the associated member. In other words, they clicked the option to decline the engagement in the inbound call notification.
  - offers_missed
    
    integer — The number of engagements assigned to the agent that went unanswered, including cases where the agent timed out or the customer abandoned.
  - offers_non_acd
    
    integer — Offers Non-ACD that are presented to the agent bypassing the queue, or manually assign the engagement to a queue agent.
  - offers_total
    
    integer — Offers happen every time an agent is presented with a call. An engagement can have multiple offers.
  - short_outbound
    
    integer — How many of the agent's outbound calls had a duration short than the long call threshold for the queue.
  - total_inbound_answer_duration
    
    number — The total time that consumers spent talking to an agent. Talking duration includes talking time and hold duration.
  - total_inbound_handling_duration
    
    number — Total inbound handling duration. Handling duration = talking duration (hold duration included) + wrap-up Duration
  - total_inbound_hold_duration
    
    number — The total amount of time that a consumer was placed on hold during the inbound engagement.
  - total_inbound_ring_duration
    
    number — The total amount of time it takes for an agent to answer the inbound engagement. It is from the system assigning the call to the agent and before the agent answers
  - total_inbound_wrap_up_duration
    
    number — The total amount of time that an agent spent in the wrap-up period.
  - total_outbound
    
    integer — How many outbound calls did the agent participate in (callbacks are not considered outbound calls).
  - total_outbound_answer_duration
    
    number — The total time that consumers spent talking to an agent. Talking duration includes talking time and hold duration.
  - total_outbound_handling_duration
    
    number — The total outbound handling duration. Handling duration = talking duration (hold duration included) + wrap-up Duration.
  - total_outbound_hold_duration
    
    number — The total amount of time that a consumer was placed on hold during the outbound engagement.
  - total_outbound_ring_duration
    
    number — The total amount of time that agents wait for their outbound engagement to be answered.
  - total_outbound_wrap_up_duration
    
    number — The total amount of time that an agent spent in the wrap-up period.
  - total_transferred_in
    
    integer — Transferred in metric indicates how many calls were routed to the queue because of the transfer. Transferred in = Transferred in to Queue + Transferred in to Agent.
  - total_transferred_out
    
    integer — How many of the calls answered by the agent were transferred out by the agent (instead of being completed by the agent or being abandoned while on hold).
  - upgraded_to_video_call
    
    integer — How many voice calls were upgraded to video by the agent.
from

string — The returned data's start date and time. Format is either `yyyy-MM-dd'T'HH:mm:ss'Z'` or `yyyy-MM-dd'T'HH:mm:ss±HH:mm`, matching the input format when timezone offset was provided.
next_page_token

string — Use the next page token to paginate through large result sets. A next page token is returned whenever the set of available results exceeds the current page size. This token's expiration period is 15 minutes.
page_size

integer, default: 10 — The number of records returned within a single API call.
timezone

string — The timezone used for the query. When the request used `yyyy-MM-dd'T'HH:mm:ss±HH:mm` format, this reflects the offset from the input. Otherwise, it reflects the `timezone` parameter value or the default `UTC`.
to

string — The returned data's end date and time. Format matches the `from` field.
total_records

integer — The total number of all the records available across pages.

Example:

{
  "next_page_token": "R4aF9Oj0fVM2hhezJTEmSKaBSkfesDwGy42",
  "page_size": 10,
  "total_records": 10,
  "timezone": "America/Los_Angeles",
  "from": "2021-12-10T00:00:00Z",
  "to": "2021-12-10T00:15:00Z",
  "agents": [
    {
      "user_id": "ukAAkZKfROKMSw1bj_RDFQ",
      "display_name": "Jilly",
      "voice": {
        "offers_total": 5,
        "offers_acd": 4,
        "offers_non_acd": 1,
        "offers_answered": 5,
        "offers_answered_acd_inbound": 2,
        "offers_missed": 0,
        "offers_declined": 4,
        "total_transferred_in": 1,
        "total_transferred_out": 1,
        "hold_hang_up": 1,
        "upgraded_to_video_call": 2,
        "total_inbound_handling_duration": 55,
        "average_inbound_handling_duration": 21,
        "longest_inbound_handling_duration": 25,
        "average_inbound_answer_duration": 25,
        "total_inbound_answer_duration": 45,
        "longest_inbound_answer_duration": 25,
        "total_inbound_ring_duration": 15,
        "average_inbound_ring_duration": 20,
        "longest_inbound_ring_duration": 35,
        "total_inbound_hold_duration": 10,
        "average_inbound_hold_duration": 11,
        "longest_inbound_hold_duration": 12,
        "total_inbound_wrap_up_duration": 16,
        "average_inbound_wrap_up_duration": 12,
        "longest_inbound_wrap_up_duration": 14,
        "total_outbound": 2,
        "short_outbound": 5,
        "long_outbound": 6,
        "hangup_outbound": 7,
        "total_outbound_ring_duration": 32,
        "average_outbound_ring_duration": 27,
        "longest_outbound_ring_duration": 15,
        "total_outbound_handling_duration": 23,
        "average_outbound_handling_duration": 24,
        "longest_outbound_handling_duration": 31,
        "total_outbound_answer_duration": 23,
        "average_outbound_answer_duration": 18,
        "longest_outbound_answer_duration": 19,
        "total_outbound_wrap_up_duration": 25,
        "average_outbound_wrap_up_duration": 21,
        "longest_outbound_wrap_up_duration": 34,
        "total_outbound_hold_duration": 23,
        "average_outbound_hold_duration": 27,
        "longest_outbound_hold_duration": 13
      }
    }
  ]
}

Status: 400 HTTP Status Code: `400` Bad Request Error Code: `300` The time and date must be in `yyyy-mm-dd` format, or ISO 8601 format, either `yyyy-MM-dd'T'HH:mm:ss'Z'` or `yyyy-MM-dd'T'HH:mm:ss'TZD'`. Error Code: `300` The requested report exceeds the 1-month limit. Error Code: `300` Timezone does not exist: {timezone}. Error Code: `300` Only provide report in recent 6 months.

Status: 404 HTTP Status Code: `404` Not Found Error Code: `1201` Queue does not exist: {queueId}.

Status: 429 HTTP Status Code: `429` Too Many Requests. For more information, see [rate limits](/docs/api/rest/rate-limits/).

List historical queue reports

Method: GET
Path: /contact_center/analytics/historical/queues/metrics
Tags: Reports V1 (Legacy)

Generate a list of historical queue reports.

Scopes: contact_center_report:read:admin

Granular Scopes: contact_center:read:queue_report:admin

Rate Limit Label: HEAVY

Responses

Status: 200 HTTP Status Code: `200` Historical queue reports list returned.

Content-Type: application/json

from

string, format: date-time — The returned data's start date and time. Format is either `yyyy-MM-dd'T'HH:mm:ss'Z'` or `yyyy-MM-dd'T'HH:mm:ss±HH:mm`, matching the input format when timezone offset was provided.
next_page_token

string — Use the next page token to paginate through large result sets. A next page token is returned whenever the set of available results exceeds the current page size. This token's expiration period is 15 minutes.
page_size

integer, default: 10 — The number of records returned within a single API call.
queues

array — Information about the queue reports.

Items:
- cc_queue_id
  
  string — The Contact Center queue's ID.
- chat
  
  object — Information about the chat metrics.
  - average_agent_first_message_speed
    
    number, format: double — The average agent first message speed, in seconds.
  - average_messaging_duration
    
    number, format: double — The average chat duration, in seconds.
  - average_sent
    
    number, format: double — The average sent chats.
  - average_waiting_duration
    
    number, format: double — The average waiting video call or chat duration, in seconds.
  - end_time_interval
    
    string — The current interval's end date and time in ISO 8601 format, either yyyy-MM-dd'T'HH:mm:ss'Z' or yyyy-MM-dd'T'HH:mm:ss`TZD`.
  - longest_agent_first_message_speed
    
    number, format: double — The longest agent first message speed, in seconds.
  - longest_messaging_duration
    
    number, format: double — The longest chat duration, in seconds.
  - longest_waiting_duration
    
    number, format: double — The longest waiting video call or chat duration, in seconds.
  - service_level
    
    number, format: double — The queue's service level.
  - shortest_agent_first_message_speed
    
    number, format: double — The shortest agent first message speed, in seconds.
  - shortest_messaging_duration
    
    number, format: double — The shortest chat duration, in seconds.
  - shortest_waiting_duration
    
    number, format: double — The shortest waiting video call or chat duration, in seconds.
  - start_time_interval
    
    string — The current interval's start date and time in ISO 8601 format, either yyyy-MM-dd'T'HH:mm:ss'Z' or yyyy-MM-dd'T'HH:mm:ss`TZD`.
  - total_abandoned
    
    integer, format: int64 — The total number of abandoned chats.
  - total_auto_closed
    
    integer, format: int64 — The total number of auto-closed chats.
  - total_released
    
    integer, format: int64 — The total number of released chats.
  - total_sent
    
    integer, format: int64 — The total number of sent chats.
  - upgraded_to_video_call
    
    integer, format: int64 — The total number of upgrade-to-video chats.
  - upgraded_to_voice_call
    
    integer, format: int64 — The total number of upgrade-to-voice chats.
- email
  
  object — The information about the email (`email_address`) metrics.
  - channel_sources
    
    array — The channel's source. * `email_address` - Only applies to email channel.
    
    Items:
    
    string, possible values: "email_address"
  - end_time_interval
    
    string — The current interval's end date and time in ISO 8601 format, either `yyyy-MM-dd'T'HH:mm:ss'Z'` or `yyyy-MM-dd'T'HH:mm:ss'TZD'`.
  - inbound_average_agent_first_reply_duration
    
    number, format: double — The average reply duration of the first agent in email (`email_address`) engagement, in seconds.
  - inbound_average_agent_reply_duration
    
    number, format: double — The average reply duration of email (`email_address`) engagement agents, excluding the response duration of the first agent, in seconds.
  - inbound_average_inactive_duration
    
    number, format: double — The average inactive duration in email (`email_address`) engagement, excluding the response duration of the first agent, in seconds.
  - inbound_average_messaging_duration
    
    number, format: double — The average email (`email_address`) engagement duration, in seconds.
  - inbound_average_waiting_duration
    
    number, format: double — The average waiting email (`email_address`) engagement, in seconds.
  - inbound_longest_agent_first_reply_duration
    
    number, format: double — The longest reply duration of the first agent in email (`email_address`) engagement, in seconds.
  - inbound_longest_agent_reply_duration
    
    number, format: double — The longest reply duration of email (`email_address`) engagement agents, excluding the response duration of the first agent, in seconds.
  - inbound_longest_inactive_duration
    
    number, format: double — The longest inactive duration in email (`email_address`) engagement, excluding the response duration of the first agent, in seconds.
  - inbound_longest_messaging_duration
    
    number, format: double — The longest email (`email_address`) engagement duration, in seconds.
  - inbound_longest_waiting_duration
    
    number, format: double — The longest waiting email (`email_address`) engagement, in seconds.
  - inbound_shortest_agent_first_reply_duration
    
    number, format: double — The shortest reply duration of the first agent in email (`email_address`) engagement, in seconds.
  - inbound_shortest_agent_reply_duration
    
    number, format: double — The shortest reply duration of email (`email_address`) engagement agents, excluding the response duration of the first agent, in seconds.
  - inbound_shortest_inactive_duration
    
    number, format: double — The shortest inactive duration in email (`email_address`) engagement, excluding the response duration of the first agent, in seconds.
  - inbound_shortest_messaging_duration
    
    number, format: double — The shortest email (`email_address`) engagement duration, in seconds.
  - inbound_shortest_waiting_duration
    
    number, format: double — The shortest waiting email (`email_address`) engagement, in seconds.
  - inbound_total_inactive_duration
    
    number, format: double — The total inactive duration in email (`email_address`) engagement, excluding the response duration of the first agent, in seconds.
  - inbound_total_messaging_duration
    
    number, format: double — The total email (`email_address`) engagement duration, in seconds.
  - outbound_average_active_duration
    
    number, format: double — The average active duration in outbound email (`email_address`) engagement, in seconds.
  - outbound_average_inactive_duration
    
    number, format: double — The average inactive duration in outbound email (`email_address`) engagement, in seconds.
  - outbound_longest_active_duration
    
    number, format: double — The longest active duration in outbound email (`email_address`) engagement, in seconds.
  - outbound_longest_inactive_duration
    
    number, format: double — The longest inactive duration in outbound email (`email_address`) engagement, in seconds.
  - outbound_messages_sent
    
    integer, format: int64 — The total number of outbound emails sent by the agent during outbound email engagements.
  - outbound_total_active_duration
    
    number, format: double — The total active duration in outbound email (`email_address`) engagement, in seconds.
  - outbound_total_inactive_duration
    
    number, format: double — The total inactive duration in outbound email (`email_address`) engagement, in seconds.
  - service_level
    
    number, format: double — The queue's service level.
  - start_time_interval
    
    string — The current interval's start date and time in ISO 8601 format, either `yyyy-MM-dd'T'HH:mm:ss'Z'` or `yyyy-MM-dd'T'HH:mm:ss'TZD'`.
  - total_auto_closed
    
    integer, format: int64 — The total number of auto-closed email (`email_address`) engagements.
  - total_handled
    
    integer, format: int64 — The total number of handled email (`email_address`) engagements.
  - total_offered
    
    integer, format: int64 — The total number of offered email (`email_address`) engagements.
  - total_offers
    
    integer, format: int64 — The total number of offers email (`email_address`) engagements.
  - total_offers_acd
    
    integer, format: int64 — The total number of offers ACD email (`email_address`) engagements.
  - total_offers_answered
    
    integer, format: int64 — The total number of offers answered email (`email_address`) engagements.
  - total_offers_declined
    
    integer, format: int64 — The total number of offers declined email (`email_address`) engagements.
  - total_offers_missed
    
    integer, format: int64 — The total number of offers missed email (`email_address`) engagements.
  - total_offers_non_acd
    
    integer, format: int64 — The total number of offers non-ACD email (`email_address`) engagements.
  - total_outbound
    
    integer, format: int64 — The total number of outbound email engagements.
  - total_overflowed
    
    integer, format: int64 — The total number of overflowed email (`email_address`) engagements.
  - total_released
    
    integer, format: int64 — The total number of released email (`email_address`) engagements.
  - total_transferred_in_to_agent
    
    integer, format: int64 — The total number of transferred-in to agent email (`email_address`) engagements.
  - total_transferred_in_to_queue
    
    integer, format: int64 — The total number of transferred-in to queue email (`email_address`) engagements.
  - total_transferred_out_of_queue
    
    integer, format: int64 — The total number of transferred-out of queue email (`email_address`) engagements.
  - total_transferred_out_within_queue
    
    integer, format: int64 — The total number of transferred-out within queue email (`email_address`) engagements.
- messaging
  
  object — The information about the messaging(web_chat/in_app_chat/sms) metrics.
  - average_agent_first_message_speed
    
    number, format: double — The average agent first message speed, in seconds.
  - average_outbound_answer_duration
    
    number, format: double — The average messaging(sms) outbound duration, in seconds.
  - average_outbound_wrap_up_duration
    
    number, format: double — The average messaging(sms) outbound wrap-up duration, in seconds.
  - average_sent
    
    number, format: double — The average sent messaging(web_chat/in_app_chat/sms) messages.
  - channel_sources
    
    array — The channel's source. * `in_app_chat` - Only applies to messaging channel. * `web_chat` - Only applies to messaging channel. * `sms` - Only applies to messaging channel. * `facebook_messenger` - Only applies to messaging channel. * `whatsapp` - Only applies to messaging channel.
    
    Items:
    
    string, possible values: "web_chat", "in_app_chat", "sms", "facebook_messenger", "whatsapp"
  - end_time_interval
    
    string — The current interval's end date and time in ISO 8601 format, either yyyy-MM-dd'T'HH:mm:ss'Z' or yyyy-MM-dd'T'HH:mm:ss`TZD`.
  - inbound_average_messaging_duration
    
    number, format: double — The average messaging(web_chat/in_app_chat/sms) engagement duration, in seconds.
  - inbound_average_waiting_duration
    
    number, format: double — The average waiting voice call or messaging(web_chat/in_app_chat/sms) engagement, in seconds.
  - inbound_longest_messaging_duration
    
    number, format: double — The longest messaging(web_chat/in_app_chat/sms) engagement duration, in seconds.
  - inbound_longest_waiting_duration
    
    number, format: double — The longest waiting voice call or messaging(web_chat/in_app_chat/sms) engagement, in seconds.
  - inbound_shortest_messaging_duration
    
    number, format: double — The shortest messaging(web_chat/in_app_chat/sms) engagement duration, in seconds.
  - inbound_shortest_waiting_duration
    
    number, format: double — The shortest waiting voice call or messaging(web_chat/in_app_chat/sms) engagement, in seconds.
  - longest_agent_first_message_speed
    
    number, format: double — The longest agent first message speed, in seconds.
  - service_level
    
    number, format: double — The queue's service level.
  - shortest_agent_first_message_speed
    
    number, format: double — The shortest agent first message speed, in seconds.
  - start_time_interval
    
    string — The current interval's start date and time in ISO 8601 format, either yyyy-MM-dd'T'HH:mm:ss'Z' or yyyy-MM-dd'T'HH:mm:ss`TZD`.
  - total_abandoned
    
    integer, format: int64 — The total number of abandoned quit messaging(web_chat/in_app_chat/sms) engagements.
  - total_auto_closed
    
    integer, format: int64 — The total number of auto-closed messaging(web_chat/in_app_chat/sms) engagements.
  - total_outbound
    
    integer, format: int64 — The total number of outbound messaging(sms) engagements.
  - total_outbound_answer_duration
    
    number, format: double — The total messaging(sms) outbound duration, in seconds.
  - total_outbound_wrap_up_duration
    
    number, format: double — The total messaging(sms) outbound wrap-up duration, in seconds.
  - total_overflowed
    
    integer, format: int64 — The total number of overflowed messaging(web_chat/in_app_chat/sms) engagements.
  - total_released
    
    integer, format: int64 — The total number of released messaging(web_chat/in_app_chat/sms) engagements.
  - total_sent
    
    integer, format: int64 — The total number of sent messages.
  - upgraded_to_video_call
    
    integer, format: int64 — The total number of upgrade-to-video messaging(web_chat/in_app_chat/sms) engagements.
  - upgraded_to_voice_call
    
    integer, format: int64 — The total number of upgrade-to-voice messaging(web_chat/in_app_chat/sms) engagements.
- queue_id
  
  string — The queue's ID.
- queue_name
  
  string — The queue's name.
- sms
  
  object — Information about the SMS metrics.
  - average_agent_first_message_speed
    
    number, format: double — The average agent first message speed, in seconds.
  - average_outbound_answer_duration
    
    number, format: double — The average SMS outbound duration, in seconds.
  - average_outbound_wrap_up_duration
    
    number, format: double — The average SMS outbound wrap-up duration, in seconds.
  - average_sent
    
    number, format: double — The average sent SMS messages.
  - end_time_interval
    
    string — The current interval's end date and time in ISO 8601 format, either yyyy-MM-dd'T'HH:mm:ss'Z' or yyyy-MM-dd'T'HH:mm:ss`TZD`.
  - inbound_average_messaging_duration
    
    number, format: double — The average SMS engagement duration, in seconds.
  - inbound_average_waiting_duration
    
    number, format: double — The average waiting voice call or SMS engagement, in seconds.
  - inbound_longest_messaging_duration
    
    number, format: double — The longest SMS engagement duration, in seconds.
  - inbound_longest_waiting_duration
    
    number, format: double — The longest waiting voice call or SMS engagement, in seconds.
  - inbound_shortest_messaging_duration
    
    number, format: double — The shortest SMS engagement duration, in seconds.
  - inbound_shortest_waiting_duration
    
    number, format: double — The shortest waiting voice call or SMS engagement, in seconds.
  - longest_agent_first_message_speed
    
    number, format: double — The longest agent first message speed, in seconds.
  - shortest_agent_first_message_speed
    
    number, format: double — The shortest agent first message speed, in seconds.
  - start_time_interval
    
    string — The current interval's start date and time in ISO 8601 format, either yyyy-MM-dd'T'HH:mm:ss'Z' or yyyy-MM-dd'T'HH:mm:ss`TZD`.
  - total_abandoned
    
    integer, format: int64 — The total number of abandoned quit SMS engagements.
  - total_auto_closed
    
    integer, format: int64 — The total number of auto-closed SMS engagements.
  - total_outbound
    
    integer, format: int64 — The total number of outbound SMS engagements.
  - total_outbound_answer_duration
    
    number, format: double — The total SMS outbound duration, in seconds.
  - total_outbound_wrap_up_duration
    
    number, format: double — The total SMS outbound wrap-up duration, in seconds.
  - total_overflowed
    
    integer, format: int64 — The total number of overflowed SMS engagements.
  - total_released
    
    integer, format: int64 — The total number of released SMS engagements.
  - total_sent
    
    integer, format: int64 — The total number of sent messages.
  - upgraded_to_video_call
    
    integer, format: int64 — The total number of upgrade-to-video SMS engagements.
  - upgraded_to_voice_call
    
    integer, format: int64 — The total number of upgrade-to-voice SMS engagements.
- total_completed
  
  integer, format: int64 — The total number of completed voice or video calls, chats, or SMS engagements.
- total_inbound
  
  integer, format: int64 — The total number of incoming voice or video calls, chats, or SMS engagements.
- total_transferred_in
  
  integer, format: int64 — The total number of transferred-in calls.
- total_transferred_out
  
  integer, format: int64 — The total number of transferred-out calls.
- video
  
  object — Information about the video metrics.
  - average_talking_duration
    
    number, format: double — The average video call duration, in seconds.
  - average_waiting_duration
    
    number, format: double — The average waiting video call or chat duration, in seconds.
  - average_wrap_up_duration
    
    number, format: double — The longest wrap-up video call, in seconds.
  - end_time_interval
    
    string — The current interval's end date and time in ISO 8601 format, either yyyy-MM-dd'T'HH:mm:ss'Z' or yyyy-MM-dd'T'HH:mm:ss`TZD`.
  - hold_abandoned
    
    integer, format: int64 — The total number of on-hold abandoned video calls, where the agent placed the call on hold and then the customer abandoned the call.
  - long_abandoned
    
    integer, format: int64 — The total number of long-duration abandoned video calls, where the talking duration is greater than the user-specified threshold value.
  - longest_talking_duration
    
    number, format: double — The longest video call duration, in seconds.
  - longest_waiting_duration
    
    number, format: double — The longest waiting video call or chat duration, in seconds.
  - longest_wrap_up_duration
    
    number, format: double — The longest wrap-up video call, in seconds.
  - service_level
    
    number, format: double — The queue's service level.
  - short_abandoned
    
    integer, format: int64 — The total number of short-duration abandoned video calls, where the talking duration is less than the user-specified threshold value.
  - shortest_talking_duration
    
    number, format: double — The shortest video call duration, in seconds.
  - shortest_waiting_duration
    
    number, format: double — The shortest waiting video call or chat duration, in seconds.
  - shortest_wrap_up_duration
    
    number, format: double — The shortest wrap-up video call, in seconds.
  - start_time_interval
    
    string — The current interval's start date and time in ISO 8601 format, either yyyy-MM-dd'T'HH:mm:ss'Z' or yyyy-MM-dd'T'HH:mm:ss`TZD`.
  - total_missed
    
    integer, format: int64 — The total number of missed video calls.
  - total_overflowed
    
    integer, format: int64 — The total number of overflowed video calls.
- voice
  
  object — Information about the voice metrics.
  - average_outbound_answer_duration
    
    number, format: double — The average outbound voice call duration, in seconds. It returns for voice channels with a provided interval.
  - average_outbound_hold_duration
    
    number, format: double — The average outbound voice call hold duration, in seconds. It returns for voice channels with a provided interval.
  - average_outbound_wrap_up_duration
    
    number, format: double — The average outbound wrap-up voice call duration, in seconds. It returns for voice channels with a provided interval.
  - end_time_interval
    
    string — The current interval's end date and time in ISO 8601 format, either yyyy-MM-dd'T'HH:mm:ss'Z' or yyyy-MM-dd'T'HH:mm:ss`TZD`. Returned for voice channels with a provided interval.
  - hangup_outbound
    
    integer, format: int64 — The total number of hang-up outbound calls, where the talking duration is less than the threshold value specified for hang-up calls.
  - hold_abandoned
    
    integer, format: int64 — The total number of on-hold abandoned voice calls, where the agent placed the call on hold and then the customer abandoned the call.
  - inbound_average_talking_duration
    
    number, format: double — The average voice call duration, in seconds.
  - inbound_average_waiting_duration
    
    number, format: double — The average waiting voice call or SMS engagement, in seconds.
  - inbound_average_wrap_up_duration
    
    number, format: double — The average wrap-up voice call, in seconds.
  - inbound_longest_talking_duration
    
    number, format: double — The longest voice call duration, in seconds.
  - inbound_longest_waiting_duration
    
    number, format: double — The longest waiting voice call or SMS engagement, in seconds.
  - inbound_longest_wrap_up_duration
    
    number, format: double — The longest wrap-up voice call, in seconds.
  - inbound_shortest_talking_duration
    
    number, format: double — The shortest voice call duration, in seconds.
  - inbound_shortest_waiting_duration
    
    number, format: double — The shortest waiting voice call or SMS engagement, in seconds.
  - inbound_shortest_wrap_up_duration
    
    number, format: double — The shortest wrap-up voice call, in seconds.
  - long_abandoned
    
    integer, format: int64 — The total number of long-duration abandoned voice calls, where the talking duration is greater than the user-specified threshold value.
  - long_outbound
    
    integer, format: int64 — The total number of long outbound calls, where the talking duration is greater than the threshold value specified for long outbound calls.
  - service_level
    
    number, format: double — The queue's service level.
  - short_abandoned
    
    integer, format: int64 — The total number of short-duration abandoned voice calls, where the talking duration is less than the user-specified threshold value.
  - short_outbound
    
    integer, format: int64 — The total number of short outbound calls, where the talking duration is between the threshold values specified for hang-up calls and long outbound calls.
  - start_time_interval
    
    string — The current interval's start date and time in ISO 8601 format, either yyyy-MM-dd'T'HH:mm:ss'Z' or yyyy-MM-dd'T'HH:mm:ss`TZD`. Returned for voice channels with a provided interval.
  - total_abandoned_duration
    
    number, format: double — The total duration of abandoned voice calls, in seconds. Returned for voice channels with a provided interval.
  - total_answer_duration
    
    number, format: double — The total voice call duration, in seconds. Returned for voice channels with a provided interval.
  - total_answered_users
    
    integer, format: int64 — The total number of agent-answered voice calls. Returned for voice channels with a provided interval.
  - total_hold_duration
    
    number, format: double — The total voice call hold duration, in seconds. Returned for voice channels with a provided interval.
  - total_missed
    
    integer, format: int64 — The total number of missed voice calls.
  - total_outbound
    
    integer, format: int64 — The total number of outbound voice calls.
  - total_outbound_answer_duration
    
    number, format: double — The total outbound voice call duration, in seconds. It returns for voice channels with a provided interval.
  - total_outbound_hold_duration
    
    number, format: double — The total outbound voice call hold duration, in seconds. It returns for voice channels with a provided interval.
  - total_outbound_wrap_up_duration
    
    number, format: double — The total outbound wrap-up voice call duration, in seconds. It returns for voice channels with a provided interval.
  - total_overflowed
    
    integer, format: int64 — The total number of overflowed voice calls.
  - total_queue_wait_duration
    
    number, format: double — The total voice-call queue wait duration, in seconds. Returned for voice channels with a provided interval.
  - total_wrap_up_duration
    
    number, format: double — The total wrap-up voice call duration, in seconds. Returned for voice channels with a provided interval.
  - upgraded_to_video_call
    
    integer, format: int64 — The total number of upgrade-to-video voice calls.
timezone

string — The call's [timezone ID](/docs/api/references/abbreviations/#timezones). The default is **UTC**.
to

string, format: date-time — The returned data's end date and time. Format matches the `from` field.
total_records

integer — The total number of all the records available across pages.

Example:

{
  "next_page_token": "R4aF9Oj0fVM2hhezJTEmSKaBSkfesDwGy42",
  "page_size": 10,
  "total_records": 10,
  "timezone": "America/Los_Angeles",
  "from": "2021-12-10T00:00:00Z",
  "to": "2021-12-10T00:15:00Z",
  "queues": [
    {
      "cc_queue_id": "Ql3qxUWXSHes4PmcOmzyOg",
      "queue_name": "agentQueue",
      "total_inbound": 1,
      "total_completed": 1,
      "total_transferred_in": 1,
      "total_transferred_out": 1,
      "voice": {
        "service_level": 0.85,
        "short_abandoned": 1,
        "long_abandoned": 1,
        "hold_abandoned": 1,
        "total_missed": 1,
        "total_overflowed": 1,
        "upgraded_to_video_call": 1,
        "inbound_average_waiting_duration": 11.8,
        "inbound_shortest_waiting_duration": 11.8,
        "inbound_longest_waiting_duration": 11.8,
        "inbound_average_talking_duration": 11.8,
        "inbound_longest_talking_duration": 11.8,
        "inbound_shortest_talking_duration": 11.8,
        "inbound_average_wrap_up_duration": 11.8,
        "inbound_longest_wrap_up_duration": 11.8,
        "inbound_shortest_wrap_up_duration": 11.8,
        "total_outbound": 1,
        "hangup_outbound": 1,
        "short_outbound": 1,
        "long_outbound": 1,
        "start_time_interval": "2022-07-20T14:00:00-08:00",
        "end_time_interval": "2022-07-20T14:15:00-08:00",
        "total_answered_users": 3,
        "total_answer_duration": 50,
        "total_hold_duration": 3,
        "total_wrap_up_duration": 78,
        "total_queue_wait_duration": 56,
        "total_abandoned_duration": 8,
        "total_outbound_answer_duration": 8,
        "total_outbound_hold_duration": 8,
        "total_outbound_wrap_up_duration": 78,
        "average_outbound_answer_duration": 8,
        "average_outbound_hold_duration": 8,
        "average_outbound_wrap_up_duration": 78
      },
      "video": {
        "start_time_interval": "2022-07-20T14:00:00-08:00",
        "end_time_interval": "2022-07-20T14:15:00-08:00",
        "service_level": 0.85,
        "short_abandoned": 1,
        "long_abandoned": 1,
        "hold_abandoned": 1,
        "total_missed": 1,
        "total_overflowed": 1,
        "average_waiting_duration": 11.8,
        "shortest_waiting_duration": 11.8,
        "longest_waiting_duration": 11.8,
        "average_talking_duration": 11.8,
        "longest_talking_duration": 11.8,
        "shortest_talking_duration": 11.8,
        "average_wrap_up_duration": 11.8,
        "longest_wrap_up_duration": 11.8,
        "shortest_wrap_up_duration": 11.8
      },
      "messaging": {
        "channel_sources": [
          "web_chat,in_app_chat"
        ],
        "start_time_interval": "2022-07-20T14:00:00-08:00",
        "end_time_interval": "2022-07-20T14:15:00-08:00",
        "service_level": 0.85,
        "total_sent": 1,
        "average_sent": 0.85,
        "total_auto_closed": 1,
        "total_released": 1,
        "total_abandoned": 1,
        "total_overflowed": 1,
        "upgraded_to_voice_call": 1,
        "upgraded_to_video_call": 1,
        "inbound_average_waiting_duration": 11.8,
        "inbound_shortest_waiting_duration": 11.8,
        "inbound_longest_waiting_duration": 11.8,
        "inbound_average_messaging_duration": 11.8,
        "inbound_longest_messaging_duration": 11.8,
        "inbound_shortest_messaging_duration": 11.8,
        "average_agent_first_message_speed": 11.8,
        "shortest_agent_first_message_speed": 11.8,
        "longest_agent_first_message_speed": 11.8,
        "total_outbound": 1,
        "total_outbound_answer_duration": 8,
        "total_outbound_wrap_up_duration": 78,
        "average_outbound_answer_duration": 8,
        "average_outbound_wrap_up_duration": 78
      },
      "email": {
        "channel_sources": [
          "email_address"
        ],
        "start_time_interval": "2022-07-20T14:00:00-08:00",
        "end_time_interval": "2022-07-20T14:15:00-08:00",
        "service_level": 0.85,
        "total_overflowed": 1,
        "total_auto_closed": 1,
        "total_offered": 1,
        "total_released": 1,
        "total_offers": 1,
        "total_offers_acd": 1,
        "total_offers_non_acd": 1,
        "total_offers_answered": 1,
        "total_offers_missed": 1,
        "total_offers_declined": 1,
        "total_handled": 1,
        "total_transferred_out_within_queue": 1,
        "total_transferred_out_of_queue": 1,
        "total_transferred_in_to_agent": 1,
        "total_transferred_in_to_queue": 1,
        "inbound_average_waiting_duration": 11.8,
        "inbound_shortest_waiting_duration": 11.8,
        "inbound_longest_waiting_duration": 11.8,
        "inbound_average_messaging_duration": 11.8,
        "inbound_longest_messaging_duration": 11.8,
        "inbound_shortest_messaging_duration": 11.8,
        "inbound_total_messaging_duration": 11.8,
        "inbound_average_agent_first_reply_duration": 11.8,
        "inbound_longest_agent_first_reply_duration": 11.8,
        "inbound_shortest_agent_first_reply_duration": 11.8,
        "inbound_average_agent_reply_duration": 11.8,
        "inbound_longest_agent_reply_duration": 11.8,
        "inbound_shortest_agent_reply_duration": 11.8,
        "inbound_average_inactive_duration": 11.8,
        "inbound_longest_inactive_duration": 11.8,
        "inbound_shortest_inactive_duration": 11.8,
        "inbound_total_inactive_duration": 11.8,
        "total_outbound": 1,
        "outbound_messages_sent": 1,
        "outbound_average_active_duration": 11.8,
        "outbound_longest_active_duration": 11.8,
        "outbound_total_active_duration": 11.8,
        "outbound_average_inactive_duration": 11.8,
        "outbound_longest_inactive_duration": 11.8,
        "outbound_total_inactive_duration": 11.8
      }
    }
  ]
}

Status: 400 HTTP Status Code: `400` Bad Request Error Code: `300` The requested report exceeds the 1-month limit. Error Code: `300` Timezone does not exist: {timezone}. Error Code: `300` Only provide report in recent 6 months. Error Code: `300` The time and date must be in yyyy-mm-dd or ISO 8601 format (yyyy-MM-dd'T'HH:mm:ss'Z' or yyyy-MM-dd'T'HH:mm:ss'TZD').

Status: 404 HTTP Status Code: `404` Not Found Error Code: `1201` Queue does not exist: $queueId.

Status: 429 HTTP Status Code: `429` Too Many Requests. For more information, see [rate limits](https://developers.zoom.us/docs/api/rest/rate-limits/).

List historical queue's agents reports

Method: GET
Path: /contact_center/analytics/historical/queues/{queueId}/agents/metrics
Tags: Reports V1 (Legacy)

Generate a list of a historical queue's agent reports.

Scopes: contact_center_report:read:admin

Granular Scopes: contact_center:read:agent_report:admin

Rate Limit Label: HEAVY

Responses

Status: 200 HTTP Status Code: `200` Historical queue's agents report list returned.

Content-Type: application/json

agents

array — Information about the queue's agents.

Items:
- chat
  
  object — Metrics for chat channel engagements. Use the `messaging` channel with `channel_sources=web_chat,in_app_chat` instead.
  - average_agent_first_message_speed
    
    number, format: double — The shortest agent first chat message speed, in seconds.
  - average_messaging_duration
    
    number, format: double — The average chat duration, in seconds.
  - average_sent
    
    number, format: double — The average number of sent chat messages.
  - average_waiting_duration
    
    number, format: double — The average chat waiting duration, in seconds.
  - longest_agent_first_message_speed
    
    number, format: double — The longest agent first chat message speed, in seconds.
  - longest_messaging_duration
    
    number, format: double — The longest chat duration, in seconds.
  - longest_waiting_duration
    
    number, format: double — The longest chat waiting duration, in seconds.
  - shortest_agent_first_message_speed
    
    number, format: double — The shortest agent first chat message speed, in seconds.
  - shortest_messaging_duration
    
    number, format: double — The shortest chat duration, in seconds.
  - shortest_waiting_duration
    
    number, format: double — The shortest chat waiting duration, in seconds.
  - total_abandoned
    
    integer, format: int64 — The total number of abandoned chat messages.
  - total_auto_closed
    
    integer, format: int64 — The total number of auto-closed chat messages.
  - total_overflowed
    
    integer, format: int64 — The total number of overflowed chat messages.
  - total_released
    
    integer, format: int64 — The total number of released chat messages.
  - total_sent
    
    integer, format: int64 — The total number of sent chat messages.
  - upgraded_to_video_call
    
    integer, format: int64 — The total number of chats that are upgraded to video calls.
  - upgraded_to_voice_call
    
    integer, format: int64 — The total number of chats that are upgraded to voice calls.
- display_name
  
  string — The agent's name.
- email
  
  object — Metrics for email channel engagements. Includes offer counts, transfer counts, reply durations, inactive durations, and interval data when an interval parameter is provided.
  - channel_sources
    
    array — The channel's source. * `email_address` - Only applies to email channel.
    
    Items:
    
    string, possible values: "email_address"
  - inbound_average_agent_first_reply_duration
    
    number, format: double — The average reply duration of the first-agent-in email (`email_address`) engagement, in seconds.
  - inbound_average_agent_reply_duration
    
    number, format: double — The average reply duration of email (`email_address`) engagement agents, excluding the response duration of the first agent, in seconds.
  - inbound_average_inactive_duration
    
    number, format: double — The average inactive duration in email (`email_address`) engagement, excluding the response duration of the first agent, in seconds.
  - inbound_average_messaging_duration
    
    number, format: double — The average email (`email_address`) engagement duration, in seconds.
  - inbound_longest_agent_first_reply_duration
    
    number, format: double — The longest reply duration of the first agent in email (`email_address`) engagement, in seconds.
  - inbound_longest_agent_reply_duration
    
    number, format: double — The longest reply duration of email (`email_address`) engagement agents, excluding the response duration of the first agent, in seconds.
  - inbound_longest_inactive_duration
    
    number, format: double — The longest inactive duration in email (`email_address`) engagement, excluding the response duration of the first agent, in seconds.
  - inbound_longest_messaging_duration
    
    number, format: double — The longest email (`email_address`) engagement duration, in seconds.
  - inbound_shortest_agent_first_reply_duration
    
    number, format: double — The shortest reply duration of the first agent in email (`email_address`) engagement, in seconds.
  - inbound_shortest_agent_reply_duration
    
    number, format: double — The shortest reply duration of email (`email_address`) engagement agents, excluding the response duration of the first agent, in seconds.
  - inbound_shortest_inactive_duration
    
    number, format: double — The shortest inactive duration in email (`email_address`) engagement, excluding the response duration of the first agent, in seconds.
  - inbound_shortest_messaging_duration
    
    number, format: double — The shortest email (`email_address`) engagement duration, in seconds.
  - total_auto_closed
    
    integer, format: int64 — The total number of auto-closed email (`email_address`) engagements.
  - total_offers
    
    integer, format: int64 — The total number of offers' email (`email_address`) engagements.
  - total_offers_acd
    
    integer, format: int64 — The total number of offers ACD email (`email_address`) engagements.
  - total_offers_answered
    
    integer, format: int64 — The total number of offers-answered email (`email_address`) engagements.
  - total_offers_declined
    
    integer, format: int64 — The total number of offers-declined email (`email_address`) engagements.
  - total_offers_missed
    
    integer, format: int64 — The total number of offers-missed email (`email_address`) engagements.
  - total_offers_non_acd
    
    integer, format: int64 — The total number of offers non-ACD email (`email_address`) engagements.
  - total_transferred_in_outside_queue
    
    integer, format: int64 — The total number of transferred-in-out-of-queue email (`email_address`) engagements.
  - total_transferred_in_within_queue
    
    integer, format: int64 — The total number of transferred-in-within-queue email (`email_address`) engagements.
  - total_transferred_out_of_queue
    
    integer, format: int64 — The total number of transferred-out-of-queue email (`email_address`) engagements.
  - total_transferred_out_within_queue
    
    integer, format: int64 — The total number of transferred-out-within-queue email (`email_address`) engagements.
- messaging
  
  object — Metrics for messaging channel engagements, including web chat, in-app chat, SMS, Facebook Messenger, and WhatsApp. Includes message counts, durations, agent response times, and interval data when an interval parameter is provided.
  - average_agent_first_message_speed
    
    number, format: double — The shortest agent of the first messaging message's speed in seconds, including `web_chat`, `in_app_chat`, and `sms` .
  - average_outbound_answer_duration
    
    number, format: double — The average outbound SMS messaging duration, in seconds.
  - average_outbound_wrap_up_duration
    
    number, format: double — The average outbound SMS messaging wrap-up duration, in seconds.
  - average_sent
    
    number, format: double — The average number of sent messaging messages, including `web_chat`, `in_app_chat`, and `sms` .
  - channel_sources
    
    array — The channel's source. * `in_app_chat` - Only applies to messaging channel. * `web_chat` - Only applies to messaging channel. * `sms` - Only applies to messaging channel. * `facebook_messenger` - Only applies to messaging channel. * `whatsapp` - Only applies to messaging channel.
    
    Items:
    
    string, possible values: "web_chat", "in_app_chat", "sms", "facebook_messenger", "whatsapp"
  - inbound_average_messaging_duration
    
    number, format: double — The average messaging(web_chat/in_app_chat/sms) message duration, in seconds, including `web_chat`, `in_app_chat`, and `sms` .
  - inbound_average_waiting_duration
    
    number, format: double — The average messaging waiting duration in seconds, including `web_chat`, `in_app_chat`, and `sms` .
  - inbound_longest_messaging_duration
    
    number, format: double — The longest messaging(web_chat/in_app_chat/sms) message duration, in seconds, including `web_chat`, `in_app_chat`, and `sms` .
  - inbound_longest_waiting_duration
    
    number, format: double — The longest messaging waiting duration in seconds, including `web_chat`, `in_app_chat`, and `sms` .
  - inbound_shortest_messaging_duration
    
    number, format: double — The shortest messaging(web_chat/in_app_chat/sms) message duration, in seconds, including `web_chat`, `in_app_chat`, and `sms` .
  - inbound_shortest_waiting_duration
    
    number, format: double — The shortest messaging waiting duration in seconds, including `web_chat`, `in_app_chat`, and `sms` .
  - longest_agent_first_message_speed
    
    number, format: double — The longest agent of the first messaging message's speed, in seconds, including `web_chat`, `in_app_chat`, and `sms` .
  - shortest_agent_first_message_speed
    
    number, format: double — The shortest agent of the first messaging message's speed, in seconds, including `web_chat`, `in_app_chat`, and `sms` .
  - total_abandoned
    
    integer, format: int64 — The total number of abandoned messaging messages, including `web_chat`, `in_app_chat`, and `sms` .
  - total_auto_closed
    
    integer, format: int64 — The total number of auto-closed messaging messages, including `web_chat`, `in_app_chat`, and `sms` .
  - total_outbound
    
    integer, format: int64 — The total number of outbound SMS messaging engagements.
  - total_outbound_answer_duration
    
    number, format: double — The total outbound SMS messaging duration, in seconds.
  - total_outbound_wrap_up_duration
    
    number, format: double — The total outbound SMS messaging wrap-up duration, in seconds.
  - total_overflowed
    
    integer, format: int64 — The total number of overflowed messaging messages, including `web_chat`, `in_app_chat`, and `sms` .
  - total_released
    
    integer, format: int64 — The total number of released messaging messages, including `web_chat`, `in_app_chat`, and `sms` .
  - total_sent
    
    integer, format: int64 — The total number of sent messaging messages, including `web_chat`, `in_app_chat`, and `sms` .
  - upgraded_to_video_call
    
    integer, format: int64 — The total number of messaging engagements that are upgraded to video calls, including `web_chat`, `in_app_chat`, and `sms` .
  - upgraded_to_voice_call
    
    integer, format: int64 — The total number of messaging engagements that are upgraded to voice calls, including `web_chat`, `in_app_chat`, and `sms` .
- sms
  
  object — Metrics for SMS channel engagements. Use the `messaging` channel with `channel_sources=sms` instead.
  - average_agent_first_message_speed
    
    number, format: double — The shortest agent first sms message speed, in seconds.
  - average_outbound_answer_duration
    
    number, format: double — The average SMS outbound duration, in seconds.
  - average_outbound_wrap_up_duration
    
    number, format: double — The average SMS outbound wrap-up duration, in seconds.
  - average_sent
    
    number, format: double — The average number of sent SMS messages.
  - inbound_average_messaging_duration
    
    number, format: double — The average sms messaging duration, in seconds.
  - inbound_average_waiting_duration
    
    number, format: double — The average sms waiting duration, in seconds.
  - inbound_longest_messaging_duration
    
    number, format: double — The longest sms messaging duration, in seconds.
  - inbound_longest_waiting_duration
    
    number, format: double — The longest sms waiting duration, in seconds.
  - inbound_shortest_messaging_duration
    
    number, format: double — The shortest sms messaging duration, in seconds.
  - inbound_shortest_waiting_duration
    
    number, format: double — The shortest sms waiting duration, in seconds.
  - longest_agent_first_message_speed
    
    number, format: double — The longest agent first sms message speed, in seconds.
  - shortest_agent_first_message_speed
    
    number, format: double — The shortest agent first sms message speed, in seconds.
  - total_abandoned
    
    integer, format: int64 — The total number of abandoned SMS messages.
  - total_auto_closed
    
    integer, format: int64 — The total number of auto-closed SMS messages.
  - total_outbound
    
    integer, format: int64 — The total number of outbound sms engagements.
  - total_outbound_answer_duration
    
    number, format: double — The total SMS outbound duration, in seconds.
  - total_outbound_wrap_up_duration
    
    number, format: double — The total SMS outbound wrap-up duration, in seconds.
  - total_overflowed
    
    integer, format: int64 — The total number of overflowed SMS messages.
  - total_released
    
    integer, format: int64 — The total number of released SMS messages.
  - total_sent
    
    integer, format: int64 — The total number of sent SMS messages.
  - upgraded_to_video_call
    
    integer, format: int64 — The total number of SMS engagements that are upgraded to video calls.
  - upgraded_to_voice_call
    
    integer, format: int64 — The total number of SMS engagements that are upgraded to voice calls.
- total_completed
  
  integer, format: int64 — The total number of completed voice calls, video calls, chats, or SMS engagements.
- total_inbound
  
  integer, format: int64 — The total number of incoming voice calls, video calls, chats, or SMS engagements.
- total_transferred_in
  
  integer, format: int64 — The total number of transferred-in voice calls, video calls, chats, or SMS engagements.
- total_transferred_out
  
  integer, format: int64 — The total number of transferred-out voice calls, video calls, chats, or SMS engagements.
- user_id
  
  string — The agent's ID.
- video
  
  object — Metrics for video channel engagements. Includes call durations, abandoned calls, service level, and interval data when an interval parameter is provided.
  - average_talking_duration
    
    number, format: double — The average video call duration, in seconds.
  - average_wrap_up_duration
    
    number, format: double — The average wrap-up video call, in seconds.
  - longest_talking_duration
    
    number, format: double — The longest video call duration, in seconds.
  - longest_wrap_up_duration
    
    number, format: double — The longest wrap-up video call, in seconds.
  - shortest_talking_duration
    
    number, format: double — The shortest video call duration, in seconds.
  - shortest_wrap_up_duration
    
    number, format: double — The shortest wrap-up video call, in seconds.
  - total_declined
    
    integer, format: int64 — The total number of declined video calls.
  - total_missed
    
    integer, format: int64 — The total number of missed video calls.
- voice
  
  object — Metrics for voice channel engagements. Includes call durations, abandoned calls, outbound calls, and interval data when an interval parameter is provided.
  - average_outbound_answer_duration
    
    number, format: double — The average outbound voice call duration, in seconds. It returns for voice channels with a provided interval.
  - average_outbound_hold_duration
    
    number, format: double — The average outbound voice call hold duration, in seconds. It returns for voice channels with a provided interval.
  - average_outbound_wrap_up_duration
    
    number, format: double — The average outbound wrap-up voice call duration, in seconds. It returns for voice channels with a provided interval.
  - end_time_interval
    
    string — The current interval's end date and time. Format is either `yyyy-MM-dd'T'HH:mm:ss'Z'` or `yyyy-MM-dd'T'HH:mm:ss±HH:mm`, matching the input format when timezone offset was provided. Returned for voice channels with a provided interval.
  - hangup_outbound
    
    integer, format: int64 — The total number of hang-up outbound calls, where the talking duration is less than the threshold value specified for hang-up calls.
  - inbound_average_talking_duration
    
    number, format: double — The average voice call duration, in seconds.
  - inbound_average_wrap_up_duration
    
    number, format: double — The average wrap-up voice or video call, in seconds.
  - inbound_longest_talking_duration
    
    number, format: double — The longest voice call duration, in seconds.
  - inbound_longest_wrap_up_duration
    
    number, format: double — The longest wrap-up voice or video call, in seconds.
  - inbound_shortest_talking_duration
    
    number, format: double — The shortest voice call duration, in seconds.
  - inbound_shortest_wrap_up_duration
    
    number, format: double — The shortest wrap-up voice or video call, in seconds.
  - long_outbound
    
    integer, format: int64 — The total number of long outbound calls, where the talking duration is greater than the threshold value specified for long outbound calls.
  - short_outbound
    
    integer, format: int64 — The total number of short outbound calls, where the talking duration is between the threshold values specified for hang-up calls and long outbound calls.
  - start_time_interval
    
    string — The current interval's start date and time. Format is either `yyyy-MM-dd'T'HH:mm:ss'Z'` or `yyyy-MM-dd'T'HH:mm:ss±HH:mm`, matching the input format when timezone offset was provided. Returned for voice channels with a provided interval.
  - total_abandoned_duration
    
    number, format: double — The total duration of abandoned calls, in seconds. Returned for voice channels with a provided interval.
  - total_answer_duration
    
    number, format: double — The total call duration, in seconds. Returned for voice channels with a provided interval.
  - total_answered_users
    
    integer, format: int64 — The total number of agent-answered calls. Returned for voice channels with a provided interval.
  - total_declined
    
    integer, format: int64 — The total number of declined voice calls.
  - total_hold_duration
    
    number, format: double — The total call hold duration, in seconds. Returned for voice channels with a provided interval.
  - total_missed
    
    integer, format: int64 — The total number of missed voice calls.
  - total_outbound
    
    integer, format: int64 — The total number of outbound voice calls, video calls, chats, or SMS engagements.
  - total_outbound_answer_duration
    
    number, format: double — The total outbound voice call duration, in seconds. It returns for voice channels with a provided interval.
  - total_outbound_hold_duration
    
    number, format: double — The total outbound voice call hold duration, in seconds. It returns for voice channels with a provided interval.
  - total_outbound_wrap_up_duration
    
    number, format: double — The total outbound wrap-up voice call duration, in seconds. It returns for voice channels with a provided interval.
  - total_queue_wait_duration
    
    number, format: double — The total queue wait duration, in seconds. Returned for voice channels with a provided interval.
  - total_wrap_up_duration
    
    number, format: double — The total wrap-up call duration, in seconds. Returned for voice channels with a provided interval.
  - upgraded_to_video_call
    
    integer, format: int64 — The total number of voice calls, chats or SMS engagements that are upgraded to video calls.
from

string, format: date-time — The start date and time of the returned data. Format: `yyyy-MM-dd'T'HH:mm:ss'Z'` or `yyyy-MM-dd'T'HH:mm:ss±HH:mm`, matching the input format when the timezone offset was provided.
next_page_token

string — Use the next page token to paginate through large result sets. A next page token is returned whenever the set of available results exceeds the current page size. This token's expiration period is 15 minutes.
page_size

integer, default: 10 — The number of records returned within a single API call.
timezone

string — The timezone used for the query. When the request uses `yyyy-MM-dd'T'HH:mm:ss±HH:mm` format, this reflects the offset from the input. Otherwise, it reflects the `timezone` parameter value or the default `UTC`.
to

string, format: date-time — The end date and time of the returned data. Format matches the `from` field.
total_records

integer — The total number of all the records available across pages.

Example:

{
  "next_page_token": "R4aF9Oj0fVM2hhezJTEmSKaBSkfesDwGy42",
  "page_size": 10,
  "total_records": 10,
  "timezone": "America/Los_Angeles",
  "from": "2021-12-10T00:00:00Z",
  "to": "2021-12-10T00:15:00Z",
  "agents": [
    {
      "user_id": "ukAAkZKfROKMSw1bj_RDFQ",
      "display_name": "Jilly",
      "total_inbound": 1,
      "total_completed": 1,
      "total_transferred_in": 1,
      "total_transferred_out": 1,
      "video": {
        "total_declined": 1,
        "total_missed": 1,
        "average_talking_duration": 11.8,
        "longest_talking_duration": 11.8,
        "shortest_talking_duration": 11.8,
        "average_wrap_up_duration": 11.8,
        "longest_wrap_up_duration": 11.8,
        "shortest_wrap_up_duration": 11.8
      },
      "messaging": {
        "channel_sources": [
          "web_chat,in_app_chat"
        ],
        "total_sent": 1,
        "average_sent": 11.8,
        "total_abandoned": 1,
        "total_auto_closed": 1,
        "total_released": 1,
        "total_overflowed": 1,
        "upgraded_to_voice_call": 1,
        "upgraded_to_video_call": 1,
        "inbound_average_messaging_duration": 11.8,
        "inbound_longest_messaging_duration": 11.8,
        "inbound_shortest_messaging_duration": 11.8,
        "inbound_average_waiting_duration": 11.8,
        "inbound_shortest_waiting_duration": 11.8,
        "inbound_longest_waiting_duration": 11.8,
        "average_agent_first_message_speed": 11.8,
        "shortest_agent_first_message_speed": 11.8,
        "longest_agent_first_message_speed": 11.8,
        "total_outbound": 1,
        "total_outbound_answer_duration": 8,
        "total_outbound_wrap_up_duration": 78,
        "average_outbound_answer_duration": 8,
        "average_outbound_wrap_up_duration": 78
      },
      "email": {
        "channel_sources": [
          "email_address"
        ],
        "total_offers": 1,
        "total_offers_acd": 1,
        "total_offers_non_acd": 1,
        "total_offers_answered": 1,
        "total_offers_missed": 1,
        "total_offers_declined": 1,
        "total_auto_closed": 1,
        "total_transferred_out_within_queue": 1,
        "total_transferred_out_of_queue": 1,
        "total_transferred_in_within_queue": 1,
        "total_transferred_in_outside_queue": 1,
        "inbound_average_messaging_duration": 11.8,
        "inbound_longest_messaging_duration": 11.8,
        "inbound_shortest_messaging_duration": 11.8,
        "inbound_average_agent_first_reply_duration": 11.8,
        "inbound_longest_agent_first_reply_duration": 11.8,
        "inbound_shortest_agent_first_reply_duration": 11.8,
        "inbound_average_agent_reply_duration": 11.8,
        "inbound_longest_agent_reply_duration": 11.8,
        "inbound_shortest_agent_reply_duration": 11.8,
        "inbound_average_inactive_duration": 11.8,
        "inbound_longest_inactive_duration": 11.8,
        "inbound_shortest_inactive_duration": 11.8
      }
    }
  ]
}

Status: 400 HTTP Status Code: `400` Bad Request Error Code: `300` The time and date must be in yyyy-mm-dd. or ISO 8601 format (yyyy-MM-dd'T'HH:mm:ss'Z' or yyyy-MM-dd'T'HH:mm:ss'TZD'). Error Code: `300` The requested report exceeds the 1-month limit. Error Code: `300` Timezone does not exist: {timezone}. Error Code: `300` Only provide report in recent 6 months.

Status: 404 HTTP Status Code: `404` Not Found Error Code: `1201` Queue does not exist: $queueId.

Status: 429 HTTP Status Code: `429` Too Many Requests. For more information, see [rate limits](https://developers.zoom.us/docs/api/rest/rate-limits/).

List historical agent performance dataset data

Method: GET
Path: /contact_center/analytics/dataset/historical/agent_performance
Tags: Reports V2 (CX Analytics)

Generate a list of agent performance dataset raw data.

Scopes: contact_center_report:read:admin

Granular Scopes: contact_center:read:dataset_agent_performance:admin

Rate Limit Label: HEAVY

Responses

Status: 200 Agent performance dataset raw data response.

Content-Type: application/json

end_time_from

string — The end time and date in `yyyy-MM-dd'T'HH:mm:ss'Z'` format to pull all agents that ended after this date and time. The response only includes one month's worth of data. If there is no specified end date, the API returns data from the past 24 hours.
end_time_to

string — Required only when specifying the `end_time_from` parameter. The end time and date in `yyyy-MM-dd'T'HH:mm:ss'Z'` format, same as the `end_time_from` parameter. Pulls all agents that ended in the given `end_time_from` and `end_time_to` time periods.
from

string — The start time and date in `yyyy-MM-dd'T'HH:mm:ss'Z'` format to pull all agents that started after this date and time. The response only includes one month's worth of data. If there is no specified start date, the API returns data from the past 24 hours.
next_page_token

string — Use the next page token to paginate through large result sets. A next page token is returned whenever the set of available results exceeds the current page size. This token's expiration period is 15 minutes.
page_size

integer, default: 30 — The number of records returned within a single API call.
start_time_from

string — The start time and date in `yyyy-MM-dd'T'HH:mm:ss'Z'` format to pull all agents that started after this date and time. The response only includes one month's worth of data. If there is no specified start date, the API returns data from the past 24 hours.
start_time_to

string — Required only when specifying the `start_time_from` parameter. The start time and date in `yyyy-MM-dd'T'HH:mm:ss'Z'` format, same as the `start_time_from` parameter. Pulls all agents that started in the given `start_time_from` and `start_time_to` time periods.
timezone

string — The [timezone ID](/docs/api/references/abbreviations/#timezones) to query the start time and end time in the query. . The default is `UTC`.
to

string — Required only when specifying the `from` parameter. The end time and date in `yyyy-MM-dd'T'HH:mm:ss'Z'` format, same as the `from` parameter. Pulls all agents that started in the given `from` and `to` time periods.
total_records

integer — The total number of all records available across pages.
users

array

Items:
- agent_declined_count
  
  integer — The total number of agent refused engagements that the agent declined.
- agent_first_response_duration
  
  number — The amount of time it takes for an agent working a messaging channel to send the first message to a customer, in milliseconds.
- agent_leg_id
  
  string — The unique identifier generated for each agent leg.
- agent_message_sent_count
  
  integer — A count of all messages sent by an agent for a unique engagement ID.
- agent_missed_count
  
  integer — The total number of agent refused engagements the agent missed.
- agent_offered_count
  
  integer — The total number of engagements offered to an agent.
- agent_refused_count
  
  integer — A number of times an agent missed or declined an engagement.
- ani_from
  
  string — The phone number that an engagement originated from.
- channel
  
  string, possible values: "voice", "video", "messaging", "email", "work_item" — The channel that the engagement contains.
- channel_source
  
  string, possible values: "voice", "in_app_video", "kiosk_video", "web_video", "in_app_chat", "in_video_chat", "web_chat", "sms", "facebook_messenger", "instagram", "team_chat", "whats_app", "email_domain", "api" — The source that the engagement contains. * `voice` - Only applies to voice channel. * `in_app_video` - Only applies to video channel. * `kiosk_video` - Only applies to video channel. * `web_video` - Only applies to video channel. * `in_app_chat` - Only applies to messaging channel. * `in_video_chat` - Only applies to messaging channel. * `web_chat` - Only applies to messaging channel. * `sms` - Only applies to messaging channel. * `facebook_messenger` - Only applies to messaging channel. * `instagram` - Only applies to messaging channel. * `team_chat` - Only applies to messaging channel. * `whats_app` - Only applies to messaging channel. * `email_domain` - Only applies to email channel. * `api` - Only applies to work_item channel.
- channel_switch_count
  
  number — The number of channel switches successfully completed by an agent.
- conference_count
  
  integer — The number of conferences that occured.
- conference_duration
  
  number — The amount of time an agent spent in conversation with an engagement and at least one additional agent, in milliseconds.
- conversation_duration
  
  number — The amount of time an agent spent in conversation with an engagement and at least one additional agent, in milliseconds.
- dial_duration
  
  number — The amount of time spent dialing the customer, in milliseconds.
- direct_transfer_count
  
  integer — The number of direct transfers initiated.
- direction
  
  string, possible values: "inbound", "outbound" — The engagement's direction.
- dnis_to
  
  string — The original number that was dialed for an engagement.
- end_time
  
  string — The agent date and time when the engagement ended, in ISO 8601 format, either `yyyy-MM-dd'T'HH:mm:ss'Z'` or `yyyy-MM-dd'T'HH:mm:ss'TZD'`. `start_time` will be the time according to the timezone indicated by the user. If no timezone is provided, `end_time` will be in UTC.
- engagement_id
  
  string — The engagement's ID.
- handle_duration
  
  number — The amount of time agents spent handling engagements, in milliseconds.
- handled_count
  
  integer — The number of inbound - including callback - and outbound engagements handled by the queue.
- hold_count
  
  integer — The number of times that a consumer was placed on hold.
- hold_duration
  
  number — The amount of time that a consumer was placed on hold, in milliseconds. NOTE: A call may have multiple hold times.
- inbound_conversation_duration
  
  number — The amount of time that an agent spent on an inbound engagement in communication with the consumer, in milliseconds.
- inbound_handle_duration
  
  number — The amount of time an agent spent handling an inbound engagement, in milliseconds.
- inbound_handled_count
  
  integer — The number of inbound engagements offered to and answered by an agent.
- origin_method
  
  string, possible values: "outbound", "callback", "scheduled_callback", "callback_retry", "conference", "transfer_to_agent", "transfer_to_queue", "warm_transfer_to_agent", "warm_transfer_to_queue", "direct_transfer_to_agent", "direct_transfer_to_queue", "route_to_queue", "route_to_agents", "switch_to_voice", "switch_to_video", "invite_agent", "takeover", "outbound_progressive_dial", "outbound_preview_dial", "outbound_third_party_dial" — How an engagement was assigned to the agent.
- outbound_conversation_duration
  
  number — The amount of time that an agent spent on an outbound engagement communicating with a consumer, in milliseconds.
- outbound_handle_duration
  
  number — The amount of time an agent spent handling an outbound engagement, in milliseconds.
- outbound_handled_count
  
  integer — The number of outbound engagements offered to and answered by an agent.
- parked_count
  
  integer — The number of times that an engagement was parked.
- perview_duration
  
  number — The amount of time an agent spent previewing an engagement, in milliseconds.
- queue_id
  
  string — The queue's specific ID.
- queue_name
  
  string — The queue's specific name.
- ring_disconnect_count
  
  integer — The count of all engagements that have been routed to a rung an agent, but the connection to this specific agent is not completed.
- ring_duration
  
  number — The amount of time between when an engagement is assigned to an agent and the agent answered, missed, or declined the engagement, in milliseconds.
- start_time
  
  string — The agent date and time when the engagement started, in ISO 8601 format, either `yyyy-MM-dd'T'HH:mm:ss'Z'` or `yyyy-MM-dd'T'HH:mm:ss'TZD'`. `start_time` will be the time according to the timezone indicated by the user. If no timezone is provided, `start_time` will be in UTC.
- switch_method
  
  string, possible values: "switch_messaging_to_voice", "switch_messaging_to_video", "switch_voice_to_video", "switch_work_item_to_voice", "switch_work_item_to_video" — What an agent uses to perform a channel switch, including the origin and destination channels.
- team_id
  
  string — The team's specific ID.
- team_name
  
  string — The team's specific name.
- third_party_dialer_wait_duration
  
  number — The amount of time an agent waited after being connected before the consumer joined the call. This metric only applies to third-party dialer scenarios.
- transfer_completed_count
  
  integer — The number of transfers an agent completed, including warm and direct transfers for voice and video channels, and all transfers for messaging and email channels with no distinction between warm and direct.
- transfer_initiated_count
  
  integer — The number of transfers an agent initiated, including warm and direct transfers for voice and video channels, and all transfers for messaging and email channels with no distinction between warm and direct.
- user_id
  
  string — The ID of the agent who is set up on the agent profile.
- user_name
  
  string — The name of the agent who is set up on the agent profile.
- warm_conference_count
  
  integer — The number of warm conferences initiated.
- warm_conference_duraton
  
  number — The amount of time spent on warm conferences, in milliseconds.
- warm_transfer_completed_count
  
  integer — The number of voice or video engagements an agent answered and then warm transferred with another participant and then fully transferred the engagements.
- warm_transfer_duration
  
  number — The amount of time spent on warm transfers, in milliseconds.
- warm_transfer_initiated_count
  
  integer — The number of voice or video engagements an agent answered and then warm transferred with another participant with or without fully transferring the engagement.
- wrap_up_duration
  
  number — The amount of time agents spent completing engagement wrap-up, in milliseconds.

Example:

{
  "next_page_token": "R4aF9Oj0fVM2hhezJTEmSKaBSkfesDwGy42",
  "page_size": 30,
  "total_records": 10,
  "timezone": "America/Los_Angeles",
  "from": "2021-12-10T00:00:00Z",
  "to": "2021-12-10T00:00:00Z",
  "users": [
    {
      "engagement_id": "reRAiabVQSqpXxJVDbsy2Q",
      "start_time": "2021-12-10T00:00:00Z",
      "end_time": "2021-12-10T00:00:00Z",
      "direction": "inbound",
      "user_id": "reRAiabVQSqpXxJVDbsy2Q",
      "user_name": "user_name_example",
      "channel": "voice",
      "channel_source": "voice",
      "queue_id": "FRDFsxkcQeCnhR5eMBdOHw",
      "queue_name": "jack_queue",
      "team_id": "FRDFsxkcQeCnhR5eMBdOHw",
      "team_name": "jack_team",
      "handled_count": 1,
      "handle_duration": 123,
      "direct_transfer_count": 1,
      "warm_transfer_initiated_count": 1,
      "warm_transfer_completed_count": 1,
      "transfer_initiated_count": 1,
      "transfer_completed_count": 1,
      "warm_conference_count": 1,
      "agent_offered_count": 1,
      "agent_refused_count": 2,
      "agent_missed_count": 3,
      "ring_disconnect_count": 1,
      "agent_declined_count": 1,
      "agent_message_sent_count": 1,
      "hold_count": 1,
      "conversation_duration": 123,
      "perview_duration": 123,
      "conference_duration": 123,
      "conference_count": 1,
      "hold_duration": 123,
      "wrap_up_duration": 123,
      "inbound_handled_count": 1,
      "outbound_handle_duration": 123,
      "warm_conference_duraton": 123,
      "warm_transfer_duration": 123,
      "ring_duration": 123,
      "agent_first_response_duration": 123,
      "dial_duration": 123,
      "inbound_conversation_duration": 123,
      "inbound_handle_duration": 123,
      "outbound_handled_count": 1,
      "outbound_conversation_duration": 123,
      "third_party_dialer_wait_duration": 123,
      "channel_switch_count": 1,
      "dnis_to": "+12095551212",
      "origin_method": "outbound",
      "agent_leg_id": "ZWR01A4AF5E1ED183F1BEE02C2F29EE723F",
      "parked_count": 1,
      "switch_method": "switch_voice_to_video",
      "ani_from": "+19135551212"
    }
  ],
  "start_time_from": "2021-12-10T00:00:00Z",
  "start_time_to": "2021-12-10T00:00:00Z",
  "end_time_to": "2021-12-10T00:00:00Z",
  "end_time_from": "2021-12-10T00:00:00Z"
}

Status: 400 HTTP Status Code: `400` Bad Request

Status: 401 HTTP Status Code: `401` Unauthorized Error Code: `124` Invalid access token. Error Code: `124` Access token has expired. Error Code: `1002` The user associated with this access token was not found or is invalid.

Status: 403 HTTP Status Code: `403` Forbidden Error Code: `1021` User account is deactivated. Error Code: `1022` User does not have a Contact Center license. Error Code: `9001` The Contact Center user associated with this bearer token is missing privileges on their role required to operate this request.

Status: 404 HTTP Status Code: `404` Not Found

Status: 429 HTTP Status Code: `429` Too Many Requests. For more information, see [rate limits](https://developers.zoom.us/docs/api/rate-limits/). Error Code: `4001` You have reached the maximum per-second rate limit for this API. Try again later.

List historical agent timecard dataset data

Method: GET
Path: /contact_center/analytics/dataset/historical/agent_timecard
Tags: Reports V2 (CX Analytics)

Generate a list of agent timecard dataset raw data.

Scopes: contact_center_report:read:admin

Granular Scopes: contact_center:read:dataset_agent_timecard:admin

Rate Limit Label: HEAVY

Responses

Status: 200 Agent timecard dataset raw data response.

Content-Type: application/json

end_time_from

string — The end time and date in `yyyy-MM-dd'T'HH:mm:ss'Z'` format to pull the agent status for all agents that ended after this date and time. The response only includes one month's worth of data. If there is no specified end date, the API returns data from the past 24 hours.
end_time_to

string — Required only when specifying the `end_time_from` parameter. The end time and date in `yyyy-MM-dd'T'HH:mm:ss'Z'` format, the same format as the `end_time_from` parameter. Pulls the agent status for all agents that ended in the given `end_time_from` and `end_time_to` time periods.
from

string — The start time and date in `yyyy-MM-dd'T'HH:mm:ss'Z'` format to pull the agent status for all agents that started after this date and time. The response only includes one month's worth of data. If there is no specified start date, the API returns data from the past 24 hours.
next_page_token

string — Use the next page token to paginate through large result sets. A next page token returns whenever the set of available results exceeds the current page size. This token's expiration period is 15 minutes.
page_size

integer, default: 30 — The number of records returned within a single API call.
start_time_from

string — The start time and date in `yyyy-MM-dd'T'HH:mm:ss'Z'` format to pull the agent status for all agents that started after this date and time. The response only includes one month's worth of data. If there is no specified start date, the API returns data from the past 24 hours.
start_time_to

string — Required only when specifying the `start_time_from` parameter. The start time and date in `yyyy-MM-dd'T'HH:mm:ss'Z'` format, same as the `start_time_from` parameter. Pulls the agent status for all agents that started in the given `start_time_from` and `start_time_to` time periods.
timezone

string — The [timezone ID](/docs/api/references/abbreviations/#timezones) to use for the start time and end time in the query. The default is `UTC`.
to

string — Required only when specifying the `from` parameter. The end time and date in `yyyy-MM-dd'T'HH:mm:ss'Z'` format, same as the `from` parameter. Pulls the agent status for all agents that started in the given `from` and `to` time periods.
total_records

integer — The total number of all the records available across pages.
users

array

Items:
- agent_country
  
  string — Two-letter country [ID](/docs/api/references/abbreviations/#countries).
- client_type
  
  string, possible values: "client", "pwa", "crm", "web", "mobile" — The type of client application.
- end_time
  
  string — The end timestamp of an agent's work session.
- ip_address
  
  string — The agent's IP address.
- not_ready_duration
  
  number — The time an agent spent in **Not Ready** status during an agent work session, in milliseconds.
- occupied_duration
  
  number — The time an agent spent in **Occupied** status during an agent work session, in milliseconds.
- ready_duration
  
  number — The time an agent spent in **Ready** status during an agent work session, in milliseconds.
- start_time
  
  string — The start timestamp of an agent's work session.
- team
  
  object — All teams related during the work session.
  - team_id
    
    string — The team's specific ID on the Zoom platform that allows for viewing reports as a group of agents.
  - team_name
    
    string — The specific name of a team on the Zoom platform that allows for viewing reports as a group of agents.
- user_id
  
  string — The ID of the agent set up on the agent profile.
- user_name
  
  string — The first and last name of the agent set up on the agent profile.
- user_status
  
  string — The status of an agent during a work session.
- user_sub_status
  
  string — The sub status of the agent who was in **Ready**, **Not Ready**, or **Occupied** status.
- work_session_duration
  
  number — The time between the start and end of an agents unique work session, in milliseconds.
- work_session_end_time
  
  string — The work session's end time.
- work_session_id
  
  string — The unique identifier of an agent's work session.
- work_session_start_time
  
  string — The work session's start time.

Example:

{
  "next_page_token": "R4aF9Oj0fVM2hhezJTEmSKaBSkfesDwGy42",
  "page_size": 30,
  "total_records": 10,
  "timezone": "America/Los_Angeles",
  "from": "2021-12-10T00:00:00Z",
  "to": "2021-12-10T00:00:00Z",
  "users": [
    {
      "work_session_id": "reRAiabVQSqpXxJVDbsy2Q",
      "start_time": "2021-12-10T00:00:00Z",
      "end_time": "2021-12-10T00:00:00Z",
      "user_id": "reRAiabVQSqpXxJVDbsy2Q",
      "user_name": "agent_name_example",
      "user_status": "not_ready",
      "user_sub_status": "launch time",
      "team": {
        "team_id": "team_id_example",
        "team_name": "team_name_example"
      },
      "ready_duration": 123,
      "occupied_duration": 234,
      "not_ready_duration": 123,
      "work_session_duration": 123,
      "work_session_start_time": "2025-12-10T00:00:00Z",
      "work_session_end_time": "2025-12-12T00:00:00Z",
      "client_type": "client",
      "agent_country": "US",
      "ip_address": "192.168.3.4"
    }
  ],
  "start_time_from": "2021-12-10T00:00:00Z",
  "start_time_to": "2021-12-10T00:00:00Z",
  "end_time_to": "2021-12-10T00:00:00Z",
  "end_time_from": "2021-12-10T00:00:00Z"
}

Status: 400 HTTP Status Code: `400` Bad Request

Status: 404 HTTP Status Code: `404` Not Found

Status: 429 HTTP Status Code: `429` Too Many Requests. For more information, see [rate limits](https://developers.zoom.us/docs/api/rate-limits/).

List historical custom report tabular data

Method: GET
Path: /contact_center/analytics/dataset/historical/custom_reports/{reportId}/widgets/{widgetId}
Tags: Reports V2 (CX Analytics)

Generate a list of tabular data based on the custom report after enabling the API in the CX Analytics.

Scopes: contact_center_report:read:admin

Granular Scopes: contact_center:read:custom_report:admin

Rate Limit Label: HEAVY

Responses

Status: 200 Historical custom report tabular data list returned.

Content-Type: application/json

data

array — The data in the tabular widget format configured on the CX Analytics historical report.

Items:
- field_name
  
  string — The field names are dynamic, and could be `user`, `queue`, `team`, or others, depending on the current historical report format. Enable the API access on the tabular widget. The field names are specified on the API response preview page.
from

string, format: date-time — The start time and date in `yyyy-MM-dd'T'HH:mm:ss'Z'` format. **Note** The overall time range needs to be less than 6 months.
page

integer — The page number.
page_size

integer, default: 30 — The number of records returned in a single API call.
report_id

string — The CX Analytics report ID.
timezone

string — The call's timezone.
to

string, format: date-time — The end time and date in `yyyy-MM-dd'T'HH:mm:ss'Z'` format. **Note** The overall time range needs to be less than 6 months.
total_records

integer — The total number of all records available across pages.
widget_id

string — The tabular widget ID of the CX Analytics report.

Example:

{
  "widget_id": "AtkB6sHxSjyslNMWL0-8IA",
  "report_id": "GcyNb1T9Tq6lyo4b-ebCNg",
  "timezone": "Asia/Shanghai",
  "from": "2025-12-10T00:00:00Z",
  "to": "2025-12-10T00:00:00Z",
  "page": 1,
  "page_size": 30,
  "total_records": 10,
  "data": [
    {
      "field_name": "dynamic value"
    }
  ]
}

Status: 400 HTTP Status Code: `400` Bad Request Input parameter format validation failed.

Status: 401 HTTP Status Code: `401` Unauthorized Error Code: `124` Invalid access token. Error Code: `124` Access token has expired. Error Code: `1002` The user associated with this access token was not found or is invalid.

Status: 403 HTTP Status Code: `403` Forbidden Error Code: `1021` User account is deactivated. Error Code: `1022` User does not have a Contact Center license. Error Code: `9001` The Contact Center user associated with this bearer token is missing privileges on their role required to operate this request.

Status: 404 HTTP Status Code: `404` Not Found The specified widget is not found.

Status: 429 HTTP Status Code: `429` Too Many Requests. For more information, see [rate limits](https://developers.zoom.us/docs/api/rate-limits/). Error Code: `4001` You have reached the maximum per-second rate limit for this API. Try again later.

Get historical custom report tabular schema

Method: GET
Path: /contact_center/analytics/dataset/historical/custom_reports/{reportId}/widgets/{widgetId}/schema
Tags: Reports V2 (CX Analytics)

Generate the schema information for a tabular based on the custom report after enabling API in the CX Analytics.

Scopes: contact_center_report:read:admin

Granular Scopes: contact_center:read:custom_report:admin

Rate Limit Label: LIGHT

Responses

Status: 200 Historical custom report tabular schema returned.

Content-Type: application/json

report_id (required)

string — The CX Analytics report ID.
schema (required)

array — The schema for the tabular widget format configured on the CX Analytics historical report.

Items:
- field_name (required)
  
  string — Field name generated by the platform based on report configuration.
- field_type (required)
  
  string, possible values: "string", "array", "object", "number", "integer", "id_name" — Field type. The 'id_name' is an object type, which contains two string fields `id` and `name`.
- description
  
  string — A brief description of the field.
widget_id (required)

string — The CX Analytics report's tabular widget ID.

Example:

{
  "widget_id": "AtkB6sHxSjyslNMWL0-8IA",
  "report_id": "GcyNb1T9Tq6lyo4b-ebCNg",
  "schema": [
    {
      "field_name": "queue",
      "field_type": "id_name",
      "description": "The specific name of a queue on the Zoom platform."
    }
  ]
}

Status: 400 HTTP Status Code: `400` Bad Request Input parameter format validation failed.

Status: 401 HTTP Status Code: `401` Unauthorized Error Code: `124` Invalid access token. Error Code: `124` Access token has expired. Error Code: `1002` The user associated with this access token was not found or is invalid.

Status: 403 HTTP Status Code: `403` Forbidden Error Code: `1021` User account is deactivated. Error Code: `1022` User does not have a Contact Center license. Error Code: `9001` The Contact Center user associated with this bearer token is missing privileges on their role required to operate this request.

Status: 404 HTTP Status Code: `404` Not Found The specified widget was not found.

Status: 429 HTTP Status Code: `429` Too Many Requests. For more information, see [rate limits](https://developers.zoom.us/docs/api/rate-limits/). Error Code: `4001` You have reached the maximum per-second rate limit for this API. Try again later.

List historical disposition dataset data

Method: GET
Path: /contact_center/analytics/dataset/historical/disposition
Tags: Reports V2 (CX Analytics)

View the historical disposition data for finished engagements in the Contact Center to conduct disposal data analysis, such as displaying the disposition data through dashboards or reports. Filter the results with the provided input parameters. The input filters are conjunctive.

Scopes: contact_center_report:read:admin

Granular Scopes: contact_center:read:dataset_disposition:admin

Rate Limit Label: HEAVY

Responses

Status: 200 View the historical disposition data that is finished engament in Contact Center response.

Content-Type: application/json

from

string, format: date-time — Filter results to dispositions that started after this date and time. The expected format is `yyyy-MM-dd'T'HH:mm:ss'Z'`.The response only includes one month's worth of data. If there is no specified start date, the API returns data from the past 24 hours.
historical_dispositions

array — dispositions

Items:
- account_id
  
  string — The account's ID.
- channel
  
  string, possible values: "voice", "video", "messaging", "email" — The names of the channels on the Contact Center. - `voice` - `video` - `messaging` - `email`
- channel_source
  
  string, possible values: "voice", "web_video", "in_app_video", "kiosk_video", "web_chat", "in_app_chat", "team_chat", "sms", "facebook_messenger", "instagram", "whatsapp", "email" — The channel's source. - `voice` - `web_video` - `in_app_video` - `kiosk_video` - `web_chat` - `in_app_chat` - `in_dideo_chat` - `sms` - `facebook_messenger` - `instagram` - `team_chat` - `whatsapp` - `email_address` - `email_web_form`
- direction
  
  string, possible values: "inbound", "outbound" — The engagement's direction. - `inbound` - `outbound`
- disposition_name
  
  string — The disposition's name.
- disposition_source
  
  string, possible values: "default", "agent" — The disposition's source. - `default` - `agent`
- disposition_type
  
  string, possible values: "single", "multi_level" — The disposition's type. - `single` - `multi-level`
- engagement_id
  
  string — The disposition's engagement ID.
- parent_account_id
  
  string — The parent account's ID.
- queue_id
  
  string — The queue's ID.
- queue_name
  
  string — The queue's name.
- team_id
  
  string — The team's ID.
- team_name
  
  string — The team's name.
- tier1_disposition_name
  
  string — The disposition's tier1 name.
- tier2_disposition_name
  
  string — The disposition's tier2 name.
- tier3_disposition_name
  
  string — The disposition's tier3 name.
- tier4_disposition_name
  
  string — The disposition's tier4 name.
- user_id
  
  string — The agent's ID.
- user_name
  
  string — The agent's name.
next_page_token

string — Use the next page token to paginate through large result sets. A next page token is returned whenever the set of available results exceeds the current page size. This token's expiration period is 15 minutes.
page_size

integer, default: 30 — The number of records returned within a single API call.
timezone

string — The [timezone ID](/docs/api/references/abbreviations/#timezones) to use for the start time and end time in the query. The default is `UTC`.
to

string, format: date-time — Required only when the `from` parameter is specified. Filter results to dispositions that started in the given `from` and `to` time periods. The expected format is `yyyy-MM-dd'T'HH:mm:ss'Z'`.
total_records

integer — The total number of all the records available across pages.

Example:

{
  "next_page_token": "R4aF9Oj0fVM2hhezJTEmSKaBSkfesDwGy42",
  "page_size": 30,
  "total_records": 10,
  "timezone": "UTC",
  "from": "2025-05-26T16:30:08Z",
  "to": "2025-07-26T16:30:08Z",
  "historical_dispositions": [
    {
      "disposition_name": "My Disposition",
      "tier1_disposition_name": "Disposition tier1 name",
      "tier2_disposition_name": "Disposition tier2 name",
      "tier3_disposition_name": "Disposition tier3 name",
      "tier4_disposition_name": "Disposition tier4 name",
      "account_id": "QxgttRd_QearwLDiZBcnAw",
      "parent_account_id": "0csc9RR7TR-k-bByzRGoyg",
      "user_id": "SVoAlV1URdOVhEZrodKHQw",
      "user_name": "Jane Smith",
      "disposition_type": "single",
      "disposition_source": "agent",
      "channel": "voice",
      "channel_source": "voice",
      "team_id": "MhHgsufKS5axWxVWHbghmQ",
      "team_name": "My Team",
      "queue_id": "3e8E2PnWTcC9FrKNaDuOeA",
      "queue_name": "My Queue",
      "engagement_id": "XYV29VsfROOGUS_BbSXFpQ",
      "direction": "inbound"
    }
  ]
}

Status: 400 HTTP Status Code: `400` Bad Request

Status: 401 HTTP Status Code: `401` Unauthorized

Status: 403 HTTP Status Code: `403` Forbidden

Status: 429 HTTP Status Code: `429` Too Many Requests. For more information, see [rate limits](https://developers.zoom.us/docs/api/rate-limits/).

List historical engagement dataset data

Method: GET
Path: /contact_center/analytics/dataset/historical/engagement
Tags: Reports V2 (CX Analytics)

Generate a list of engagement dataset raw data.

Scopes: contact_center_report:read:admin

Granular Scopes: contact_center:read:dataset_engagement:admin

Rate Limit Label: HEAVY

Responses

Status: 200 Engagement dataset raw data response.

Content-Type: application/json

end_time_from

string — The end time and date in `yyyy-MM-dd'T'HH:mm:ss'Z'` format to pull the engagements that ended after this date and time. The response only includes one month's worth of data. If there is no specified end date, the API returns data from the past 24 hours.
end_time_to

string — Required only when the `end_time_from` parameter. The end time and date in `yyyy-MM-dd'T'HH:mm:ss'Z'` format, same as the `end_time_from` parameter. Pulls the engagements that ended in the given `end_time_from` and `end_time_to` time periods.
engagements

array — Information about the engagement.

Items:
- abandoned_count
  
  integer — The number of times an end user abandoned an engagement before connecting with an agent.
- aiea_usage
  
  string, possible values: "used", "not_used" — Whether Agentic AI Expert Assist was involved in the engagement. This only applies to Agentic AI Expert Assist. **Note** Data is available only when the feature is enabled and properly licensed.
- ani
  
  string — The phone number that an engagement originated from.
- caller_id
  
  string — The caller's phone number.
- channels
  
  array — The all engagement related channel.
  
  Items:
  - channel
    
    string, possible values: "voice", "video", "messaging", "email", "work_item" — The channel that the engagement contains.
  - channel_source
    
    string, possible values: "voice", "in_app_video", "kiosk_video", "web_video", "in_app_chat", "in_video_chat", "web_chat", "sms", "facebook_messenger", "instagram", "team_chat", "whats_app", "email_domain", "api" — The source that the engagement contains. * `voice` - Only applies to voice channel. * `in_app_video` - Only applies to video channel. * `kiosk_video` - Only applies to video channel. * `web_video` - Only applies to video channel. * `in_app_chat` - Only applies to messaging channel. * `in_video_chat` - Only applies to messaging channel. * `web_chat` - Only applies to messaging channel. * `sms` - Only applies to messaging channel. * `facebook_messenger` - Only applies to messaging channel. * `instagram` - Only applies to messaging channel. * `team_chat` - Only applies to messaging channel. * `whats_app` - Only applies to messaging channel. * `email_domain` - Only applies to email channel. * `api` - Only applies to work_item channel.
- conference_count
  
  integer — The number of conferences that occurred.
- conference_duration
  
  number — The amount of time an agent spent in conversation with an engagement and at least one additional agent, in milliseconds.
- consumer
  
  object — The consumer information.
  - consumer_email
    
    string — The consumer's email address.
  - consumer_name
    
    string — The consumer's name.
- conversation_duration
  
  number — The amount of time that agents spent on engagements communicating with a consumer, in milliseconds.
- direct_transfer_count
  
  integer — The number of direct transfers initiated.
- direction
  
  string, possible values: "inbound", "outbound" — The engagement's direction.
- dnis
  
  string — The original number dialed for an engagement.
- duration
  
  number — The engagement's duration, in milliseconds.
- end_time
  
  string — The date and time when the engagement ended, in ISO 8601 format, either `yyyy-MM-dd'T'HH:mm:ss'Z'` or `yyyy-MM-dd'T'HH:mm:ss'TZD'`. `start_time` will be the time according to the timezone indicated by the user. If no timezone is provided, `start_time` will be in UTC.
- engagement_id
  
  string — The engagement's ID.
- enter_channel
  
  string, possible values: "voice", "video", "messaging", "email", "work_item" — The channel that the engagement was in when it entered the Zoom Contact Center.
- enter_channel_source
  
  string, possible values: "voice", "in_app_video", "kiosk_video", "web_video", "in_app_chat", "in_video_chat", "web_chat", "sms", "facebook_messenger", "instagram", "team_chat", "whats_app", "email_domain", "api" — The source that the engagement was in when it entered entered the Contact Center. * `voice` - Only applies to voice channel. * `in_app_video` - Only applies to video channel. * `kiosk_video` - Only applies to video channel. * `web_video` - Only applies to video channel. * `in_app_chat` - Only applies to messaging channel. * `in_video_chat` - Only applies to messaging channel. * `web_chat` - Only applies to messaging channel. * `sms` - Only applies to messaging channel. * `facebook_messenger` - Only applies to messaging channel. * `instagram` - Only applies to messaging channel. * `team_chat` - Only applies to messaging channel. * `whats_app` - Only applies to messaging channel. * `email_domain` - Only applies to email channel. * `api` - Only applies to work_item channel.
- handle_duration
  
  number — The amount of time agents spent handling engagements, in milliseconds.
- hold_count
  
  integer — The number of times that a consumer was placed on hold.
- hold_duration
  
  number — The amount of time that a consumer was placed on hold. **NOTE:** A call may have multiple hold times.
- queues
  
  array — All queues related to the engagement.
  
  Items:
  - queue_id
    
    string — A queue's specific ID.
  - queue_name
    
    string — A queue's specific name.
- start_time
  
  string — The date and time when the engagement started, in ISO 8601 format, either `yyyy-MM-dd'T'HH:mm:ss'Z'` or `yyyy-MM-dd'T'HH:mm:ss'TZD'`. `start_time` will be the time according to the timezone indicated by the user. If no timezone is provided, `start_time` will be in UTC.
- teams
  
  array — All teams related to the engagement.
  
  Items:
  - team_id
    
    string — A team's specific ID.
  - team_name
    
    string — A team's specific name.
- transfer_completed_count
  
  integer — The number of transfers an agent completed, including warm and direct transfers for voice and video channels, and all transfers for messaging and email channels, with no distinction between warm and direct.
- transfer_initiated_count
  
  integer — The number of transfers an agent initiated, including warm and direct transfers for voice and video channels, and all transfers for messaging and email channel, withno distinction between warm and direct.
- users
  
  array — All agents related to the engagement.
  
  Items:
  - user_id
    
    string — The ID of the agent who is set up on the agent profile.
  - user_name
    
    string — The first and last name of the agent who is set up on the agent profile.
- warm_conference_count
  
  integer — The number of warm conferences initiated.
- warm_conference_duration
  
  number — The amount of time an agent spent in conversation with another agent while the engagement was on hold, in milliseconds.
- warm_transfer_completed_count
  
  integer — The number of voice or video engagements an agent answered and then warm transferred with another participant and then fully transferred the engagements.
- warm_transfer_duration
  
  number — The amount of time an agent spent in conversation with another agent while the engagement was on hold, in milliseconds.
- warm_transfer_initiated_count
  
  integer — The number of voice or video engagements an agent answered and then warm transferred with another participant with or without fully transferring the engagement.
- wrap_up_duration
  
  number — The amount of time agents spent completing engagement wrap-up, in milliseconds.
from

string — The start time and date in `yyyy-MM-dd'T'HH:mm:ss'Z'` format to pull the engagements that started after this date and time. The response only includes one month's worth of data. If there is no specified start date, the API returns data from the past 24 hours.
next_page_token

string — Use the next page token to paginate through large result sets. A next page token is returned whenever the set of available results exceeds the current page size. This token's expiration period is 15 minutes.
page_size

integer, default: 30 — The number of records returned within a single API call.
start_time_from

string — The start time and date in `yyyy-MM-dd'T'HH:mm:ss'Z'` format to pull the engagements that started after this date and time. The response only includes one month's worth of data. If there is no specified start date, the API returns data from the past 24 hours.
start_time_to

string — Required only when the `start_time_from` parameter. The start time and date in `yyyy-MM-dd'T'HH:mm:ss'Z'` format, same as the `start_time_from` parameter. Pulls the engagements that started in the given `start_time_from` and `start_time_to` time periods.
timezone

string — The [timezone ID](/docs/api/references/abbreviations/#timezones) to use for the start time and end time in the query. . The default is `UTC`.
to

string — Required only when specifying the `from` parameter. The end time and date in `yyyy-MM-dd'T'HH:mm:ss'Z'` format, same as the `from` parameter. Pulls the engagements that started in the given `from` and `to` time periods.
total_records

integer — The total number of all records available across pages.

Example:

{
  "next_page_token": "R4aF9Oj0fVM2hhezJTEmSKaBSkfesDwGy42",
  "page_size": 30,
  "total_records": 10,
  "timezone": "America/Los_Angeles",
  "from": "2021-12-10T00:00:00Z",
  "to": "2021-12-10T00:00:00Z",
  "start_time_from": "2021-12-10T00:00:00Z",
  "start_time_to": "2021-12-10T00:00:00Z",
  "end_time_from": "2021-12-10T00:00:00Z",
  "end_time_to": "2021-12-10T00:00:00Z",
  "engagements": [
    {
      "engagement_id": "reRAiabVQSqpXxJVDbsy2Q",
      "direction": "inbound",
      "start_time": "2021-12-10T00:00:00Z",
      "end_time": "2021-12-10T00:00:00Z",
      "enter_channel": "messaging",
      "enter_channel_source": "in_app_chat",
      "channels": [
        {
          "channel": "voice",
          "channel_source": "voice"
        }
      ],
      "caller_id": "+12765551212",
      "dnis": "+12765551212",
      "ani": "+12055551212",
      "consumer": {
        "consumer_email": "jack@example.com",
        "consumer_name": "jack"
      },
      "queues": [
        {
          "queue_id": "FRDFsxkcQeCnhR5eMBdOHw",
          "queue_name": "jack_queue"
        }
      ],
      "users": [
        {
          "user_id": "FRDFsxkcQeCnhR5eMBdOHw",
          "user_name": "jack_agent"
        }
      ],
      "teams": [
        {
          "team_id": "FRDFsxkcQeCnhR5eMBdOHw",
          "team_name": "jack_team"
        }
      ],
      "duration": 35678,
      "handle_duration": 17922,
      "conversation_duration": 16901,
      "hold_count": 3,
      "hold_duration": 169,
      "warm_transfer_initiated_count": 1,
      "warm_transfer_completed_count": 1,
      "warm_transfer_duration": 1453,
      "direct_transfer_count": 2,
      "transfer_initiated_count": 1,
      "transfer_completed_count": 1,
      "warm_conference_count": 1,
      "warm_conference_duration": 283764,
      "conference_count": 1,
      "conference_duration": 283764,
      "wrap_up_duration": 143561,
      "abandoned_count": 0,
      "aiea_usage": "used"
    }
  ]
}

Status: 400 HTTP Status Code: `400` Bad Request

Status: 401 HTTP Status Code: `401` Unauthorized Error Code: `124` Invalid access token. Error Code: `124` Access token has expired. Error Code: `1002` The user associated with this access token was not found or is invalid.

Status: 403 HTTP Status Code: `403` Forbidden Error Code: `1021` User account is deactivated. Error Code: `1022` User does not have a Contact Center license. Error Code: `9001` The Contact Center user associated with this bearer token is missing privileges on their role required to operate this request.

Status: 404 HTTP Status Code: `404` Not Found

Status: 429 HTTP Status Code: `429` Too Many Requests. For more information, see [rate limits](https://developers.zoom.us/docs/api/rate-limits/). Error Code: `4001` You have reached the maximum per-second rate limit for this API. Try again later.

List historical engagement timelines

Method: GET
Path: /contact_center/analytics/dataset/historical/engagement_timelines
Tags: Reports V2 (CX Analytics)

Retrieve engagement timelines, including entities and segments, for engagements in a time range. Data is available after engagements have completed processing, not immediately after the engagements end. This API may return an empty or partial response while the data is persisting.

Retry this request for up to 1 minute to get timeline details, if querying shortly after an engagement_ended webhook event. Consider using a backoff between retries to avoid rate limiting.

Scopes: contact_center_report:read:admin

Granular Scopes: contact_center:read:engagement_timeline:admin

Rate Limit Label: HEAVY

Responses

Status: 200 HTTP Status Code: `200` Timeline information returned.

Content-Type: application/json

end_time_from

string — The end time and date in `yyyy-MM-dd'T'HH:mm:ss'Z'` format to pull all engagements that ended after this date and time.
end_time_to

string — Required only when specifying the `end_time_from` parameter. The end time and date in `yyyy-MM-dd'T'HH:mm:ss'Z'` format, same as the `end_time_from` parameter.
engagement_timelines

array — List of engagement timeline objects. One item per engagement. Each includes `engagement_id` and its entity timelines.

Items:
- engagement_id (required)
  
  string — The engagement's ID.
- channels
  
  array — The channels that the engagement contains. such as voice, video, digital, and messaging. Each item pairs one channel with its source.
  
  Items:
  - channel
    
    string, possible values: "voice", "video", "messaging", "email", "work_item" — The channels that the engagement contains.
  - channel_source
    
    string, possible values: "voice", "web_video", "in_app_video", "kiosk_video", "web_chat", "in_app_chat", "team_chat", "sms", "facebook_messenger", "instagram", "whatsapp", "email_address", "api" — The sources that the engagement contains. * `voice` - Only applies to voice channel. * `in_app_video` - Only applies to video channel. * `kiosk_video` - Only applies to video channel. * `web_video` - Only applies to video channel. * `in_app_chat` - Only applies to messaging channel. * `web_chat` - Only applies to messaging channel. * `team_chat` - Only applies to messaging channel. * `sms` - Only applies to messaging channel. * `facebook_messenger` - Only applies to messaging channel. * `instagram` - Only applies to messaging channel. * `whatsapp` - Only applies to messaging channel. * `email_address` - Only applies to email channel. * `api` - Only applies to work_item channel.
- disconnect_info
  
  string | null, possible values: "agent", "customer", "system" — The party that initiated the end of this engagement. Omitted when the disconnect party cannot be determined. * `agent` — The agent ended the engagement. * `customer` — The customer ended the engagement. * `system` — The system ended the engagement (for example, inactivity timeout, queue overflow, or SLA breach).
- entity_timelines
  
  array — One entry per entity, each containing the entity information and its ordered timeline segments. Empty when no data.
  
  Items:
  - entity
    
    object — Information about the entity.
    - channel
      
      string, possible values: "voice", "video", "messaging", "email", "work_item" — The channel that the task contains.
    - channel_source
      
      string, possible values: "voice", "web_video", "in_app_video", "kiosk_video", "web_chat", "in_app_chat", "team_chat", "sms", "facebook_messenger", "instagram", "whatsapp", "email_address", "api" — The source that the task contains. * `voice` - Only applies to voice channel. * `in_app_video` - Only applies to video channel. * `kiosk_video` - Only applies to video channel. * `web_video` - Only applies to video channel. * `in_app_chat` - Only applies to messaging channel. * `web_chat` - Only applies to messaging channel. * `team_chat` - Only applies to messaging channel. * `sms` - Only applies to messaging channel. * `facebook_messenger` - Only applies to messaging channel. * `instagram` - Only applies to messaging channel. * `whatsapp` - Only applies to messaging channel. * `email_address` - Only applies to email channel. * `api` - Only applies to work_item channel.
    - entity_descriptive_name
      
      string — The entity's human-readable name.
    - entity_id
      
      string — The entity's unique identifier.
    - entity_type
      
      string, possible values: "Queue", "Consumer", "Agent", "Supervisor", "Flow", "Campaign", "Virtual Agent" — The entity type.
    - matched_skills_and_intents
      
      array — Agent only. Skills and intents that led to matching this agent. Each item has type 'skill' or 'intent' with its category and name. Omitted or empty for non-agent entities.
      
      Items:
      - category (required)
        
        string — The category name (skill category when type is skill, intent category when type is intent).
      - name (required)
        
        string — The skill name or intent name.
      - type (required)
        
        string, possible values: "skill", "intent" — Whether this criterion is a skill or an intent.
      - min_proficiency
        
        integer | null — The minimum proficiency level required for the skill to match this agent. Only present when `type` is `skill`. A value between 1 and 10. Omitted when the routing record does not carry a proficiency threshold (for example, older engagements or intent-based routing).
  - segments
    
    array — This entity's ordered list of time segments.
    
    Items:
    - end_reason
      
      string — Event name that ended the segment.
    - end_time
      
      string — The date and time when the segment ended, in ISO 8601 format, either `yyyy-MM-dd'T'HH:mm:ss'Z'` or `yyyy-MM-dd'T'HH:mm:ss'TZD'`. The time is according to the timezone indicated by the request. If no timezone is provided, `end_time` will be in UTC.
    - segment_type
      
      string, possible values: "customer_interact_segment", "customer_ring_segment", "in_flow_segment", "queue_waiting_segment", "queue_park_segment", "queue_callback_waiting_segment", "agent_ring_segment", "dial_customer_segment", "agent_outbound_preview_dial_segment", "agent_hold_segment", "agent_conversation_segment", "agent_warm_transfer_segment", "agent_warm_conference_segment", "agent_conference_segment", "agent_wrap_up_segment", "supervisor_listen_segment", "supervisor_whisper_segment", "supervisor_view_segment", "supervisor_barge_segment", "supervisor_monitor_segment", "campaign_dial_segment", "zva_virtual_agent_conversation_segment", "zva_consumer_interact_segment" — Segment type code in `snake_case`.
    - start_time
      
      string — The date and time when the segment started, in ISO 8601 format, either `yyyy-MM-dd'T'HH:mm:ss'Z'` or `yyyy-MM-dd'T'HH:mm:ss'TZD'`. The time is according to the timezone indicated by the request. If no timezone is provided, `start_time` will be in UTC.
next_page_token

string — Use the next page token to paginate through large result sets. A next page token is returned whenever the set of available results exceeds the current page size. This token's expiration period is 15 minutes.
page_size

integer, default: 30 — The number of records returned within a single API call.
start_time_from

string — The start time and date in `yyyy-MM-dd'T'HH:mm:ss'Z'` format to pull all engagements that started after this date and time.
start_time_to

string — Required only when specifying the `start_time_from` parameter. The end time and date in `yyyy-MM-dd'T'HH:mm:ss'Z'` format, same as the `start_time_from` parameter.
timezone

string — The [timezone ID](/docs/api/references/abbreviations/#timezones) used for the request. The default is UTC.
total_records

integer — The total number of all records available across pages.

Example:

{
  "next_page_token": "R4aF9Oj0fVM2hhezJTEmSKaBSkfesDwGy42",
  "page_size": 30,
  "total_records": 10,
  "timezone": "America/Los_Angeles",
  "start_time_from": "2021-12-10T00:00:00Z",
  "start_time_to": "2021-12-10T00:15:00Z",
  "end_time_from": "2021-12-10T00:00:00Z",
  "end_time_to": "2021-12-10T00:15:00Z",
  "engagement_timelines": [
    {
      "engagement_id": "W_VATTk_Q5aW6z5rZtBxAQ",
      "channels": [
        {
          "channel": "video",
          "channel_source": "web_video"
        }
      ],
      "disconnect_info": "agent",
      "entity_timelines": [
        {
          "entity": {
            "entity_id": "agent-leg-abc123",
            "entity_type": "Agent",
            "entity_descriptive_name": "John Doe",
            "channel": "voice",
            "channel_source": "in_app_chat",
            "matched_skills_and_intents": [
              {
                "type": "skill",
                "category": "Language",
                "name": "Billing",
                "min_proficiency": 5
              }
            ]
          },
          "segments": [
            {
              "segment_type": "agent_conversation_segment",
              "start_time": "2021-12-10T00:00:00Z",
              "end_time": "2021-12-10T00:00:00Z",
              "end_reason": "agent.hangup"
            }
          ]
        }
      ]
    }
  ]
}

Status: 400 HTTP Status Code: `400` Bad Request

Status: 401 HTTP Status Code: `401` Unauthorized Error Code: `1002` The user associated with this access token was not found or is invalid. Error Code: `124` Invalid access token. Error Code: `124` Access token has expired.

Status: 403 HTTP Status Code: `403` Forbidden Error Code: `9001` The Contact Center user associated with this bearer token is missing privileges on their role required to operate this request. Error Code: `1021` User account is deactivated. Error Code: `1022` User does not have a Contact Center license.

Status: 429 HTTP Status Code: `429` Too Many Requests. For more information, see [rate limits](https://developers.zoom.us/docs/api/rate-limits/). Error Code: `4001` You have reached the maximum per-second rate limit for this API. Try again later.

List historical expert assist dataset data

Method: GET
Path: /contact_center/analytics/dataset/historical/expert_assist
Tags: Reports V2 (CX Analytics)

Display expert assist dataset key metrics on the adoption of AI expert assist and its impact on key engagement measures. This data is available only after an engagement has ended and includes only those engagements where AI expert assist data is present.

Scopes: contact_center_report:read:admin

Granular Scopes: contact_center:read:dataset_expert_assist:admin

Rate Limit Label: HEAVY

Responses

Status: 200 The expert assist dataset raw data response.

Content-Type: application/json

end_time_from

string — The end time and date in `yyyy-MM-dd'T'HH:mm:ss'Z'` format to pull the engagements that ended after this date and time. The response only includes one month's worth of data. If there is no specified end date, the API returns data from the past 24 hours.
end_time_to

string — Required only when specifying the `end_time_from` parameter. The end time and date in `yyyy-MM-dd'T'HH:mm:ss'Z'` format, same as the `end_time_from` parameter. Pulls the engagements that ended in the given `end_time_from` and `end_time_to` time periods.
engagements

array — The information about the engagement.

Items:
- channels
  
  array — The all engagement related channel.
  
  Items:
  - channel
    
    string, possible values: "voice", "video", "messaging", "email" — The channel contained in the engagement.
  - channel_source
    
    string, possible values: "voice", "in_app_video", "kiosk_video", "web_video", "in_app_chat", "in_video_chat", "web_chat", "sms", "facebook_messenger", "instagram", "team_chat", "whats_app", "email_domain" — The source contained in the engagement. * `voice` - Only applies to voice channel. * `in_app_video` - Only applies to video channel. * `kiosk_video` - Only applies to video channel. * `web_video` - Only applies to video channel. * `in_app_chat` - Only applies to messaging channel. * `in_video_chat` - Only applies to messaging channel. * `web_chat` - Only applies to messaging channel. * `sms` - Only applies to messaging channel. * `facebook_messenger` - Only applies to messaging channel. * `instagram` - Only applies to messaging channel. * `team_chat` - Only applies to messaging channel. * `whats_app` - Only applies to messaging channel. * `email_domain` - Only applies to email channel.
- direction
  
  string, possible values: "inbound", "outbound" — The engagement's direction.
- end_time
  
  string — The date and time when the engagement ended, in ISO 8601 format, either `yyyy-MM-dd'T'HH:mm:ss'Z'` or `yyyy-MM-dd'T'HH:mm:ss'TZD'`. `start_time` will be the time according to the timezone indicated by the user. If no timezone is provided, `start_time` will be in UTC.
- engagement_id
  
  string — The engagement's ID.
- expert_assist_feature
  
  array — The expert assist functions used by engagement.
  
  Items:
  
  string, possible values: "Unknown", "ea_info_retrieval", "ea_knowledge_base", "ea_next_best_action" — The expert assist function used by engagement.
- expert_assist_instance
  
  array — All expert assist instances related to the engagement.
  
  Items:
  - expert_assist_instance_id
    
    string — An expert assist instance's specific ID.
  - expert_assist_instance_name
    
    string — An expert assist instance's name.
- expert_assist_status
  
  string, possible values: "Unknown", "initiated", "available", "no_available" — The engagement status of using the expert assist function.
- handle_duration
  
  number — The amount of time agents spent handling engagements, in milliseconds.
- info_retrieval_group
  
  array — All expert assist information retrievals related to the engagement.
  
  Items:
  - info_retrieval_group_id
    
    string — An expert assist information retrieval's specific ID.
  - info_retrieval_group_name
    
    string — An expert assist information retrieval's name.
- knowledge_base
  
  array — All expert assist knowledge bases related to the engagement.
  
  Items:
  - knowledge_base_id
    
    string — An expert assist knowledge base's specific ID.
  - knowledge_base_name
    
    string — An expert assist knowledge base's name.
- next_best_action
  
  array — All expert assist next best actions related to the engagement.
  
  Items:
  - next_best_action_id
    
    string — An expert assist next best action's specific ID.
  - next_best_action_name
    
    string — An expert assist next best action's name.
- queues
  
  array — All queues related to the engagement.
  
  Items:
  - queue_id
    
    string — A queue's specific ID.
  - queue_name
    
    string — A queue's specific name.
- start_time
  
  string — The date and time when the engagement started, in ISO 8601 format, either `yyyy-MM-dd'T'HH:mm:ss'Z'` or `yyyy-MM-dd'T'HH:mm:ss'TZD'`. `start_time` will be the time according to the timezone indicated by the user. If no timezone is provided, `start_time` will be in UTC.
- teams
  
  array — All teams related to the engagement.
  
  Items:
  - team_id
    
    string — A team's specific ID.
  - team_name
    
    string — A team's specific name.
- users
  
  array — All agents related to the engagement.
  
  Items:
  - user_id
    
    string — The ID of the agent on the agent profile.
  - user_name
    
    string — The first and last name of the agent on the agent profile.
- wrap_up_duration
  
  number — The amount of time agents spent completing engagement wrap-up, in milliseconds.
from

string — The start time and date in `yyyy-MM-dd'T'HH:mm:ss'Z'` format to pull the engagements that started after this date and time. The response only includes one month's worth of data. If there is no specified start date, the API returns data from the past 24 hours.
next_page_token

string — Use the next page token to paginate through large result sets. A next page token is returned whenever the set of available results exceeds the current page size. This token's expiration period is 15 minutes.
page_size

integer, default: 30 — The number of records returned within a single API call.
start_time_from

string — The start time and date in `yyyy-MM-dd'T'HH:mm:ss'Z'` format to pull the engagements that started after this date and time. The response only includes one month's worth of data. If there is no specified start date, the API returns data from the past 24 hours.
start_time_to

string — Required only when specifying the `start_time_from` parameter. The start time and date in `yyyy-MM-dd'T'HH:mm:ss'Z'` format, same as the `start_time_from` parameter. Pulls the engagements that started in the given `start_time_from` and `start_time_to` time periods.
timezone

string — The [timezone ID](/docs/api/references/abbreviations/#timezones) to use for the start time and end time in the query. . The default is `UTC`.
to

string — Required only when specifying the `from` parameter. The end time and date in `yyyy-MM-dd'T'HH:mm:ss'Z'` format, same as the `from` parameter. Pulls the engagements that started in the given `from` and `to` time periods.
total_records

integer — The total number of all the records available across pages.

Example:

{
  "next_page_token": "R4aF9Oj0fVM2hhezJTEmSKaBSkfesDwGy42",
  "page_size": 30,
  "total_records": 10,
  "timezone": "America/Los_Angeles",
  "from": "2021-12-10T00:00:00Z",
  "to": "2021-12-10T00:00:00Z",
  "start_time_from": "2021-12-10T00:00:00Z",
  "start_time_to": "2021-12-10T00:00:00Z",
  "end_time_from": "2021-12-10T00:00:00Z",
  "end_time_to": "2021-12-10T00:00:00Z",
  "engagements": [
    {
      "engagement_id": "reRAiabVQSqpXxJVDbsy2Q",
      "direction": "inbound",
      "start_time": "2021-12-10T00:00:00Z",
      "end_time": "2021-12-10T00:00:00Z",
      "channels": [
        {
          "channel": "voice",
          "channel_source": "voice"
        }
      ],
      "queues": [
        {
          "queue_id": "FRDFsxkcQeCnhR5eMBdOHw",
          "queue_name": "jack_queue"
        }
      ],
      "users": [
        {
          "user_id": "FRDFsxkcQeCnhR5eMBdOHw",
          "user_name": "jack_agent"
        }
      ],
      "teams": [
        {
          "team_id": "FRDFsxkcQeCnhR5eMBdOHw",
          "team_name": "jack_team"
        }
      ],
      "handle_duration": 17922,
      "wrap_up_duration": 143561,
      "expert_assist_status": "initiated",
      "expert_assist_instance": [
        {
          "expert_assist_instance_id": "Y548oThR-GCyKeYeNg6TA\n",
          "expert_assist_instance_name": "order_list"
        }
      ],
      "info_retrieval_group": [
        {
          "info_retrieval_group_id": "Uu9pM0LRRl24RM3aNxDScA",
          "info_retrieval_group_name": "order_groups"
        }
      ],
      "knowledge_base": [
        {
          "knowledge_base_id": "1d4HuAFFSkGz7vmhU1wVGA",
          "knowledge_base_name": "know_base"
        }
      ],
      "next_best_action": [
        {
          "next_best_action_id": "04vm4K5zR_qnXeXhdvfcCA",
          "next_best_action_name": "recommend"
        }
      ],
      "expert_assist_feature": [
        "ea_info_retrieval"
      ]
    }
  ]
}

Status: 429 HTTP Status Code: `429` Too Many Requests. For more information, see [rate limits](https://developers.zoom.us/docs/api/rate-limits/).

List historical flow performance dataset data

Method: GET
Path: /contact_center/analytics/dataset/historical/flow_performance
Tags: Reports V2 (CX Analytics)

Generate a list of flow performance dataset raw data.

Scopes: contact_center_report:read:admin

Granular Scopes: contact_center:read:dataset_flow_performance:admin

Rate Limit Label: HEAVY

Responses

Status: 200 Flow performance dataset raw data response.

Content-Type: application/json

enter_time_from

string — The enter time and date in `yyyy-MM-dd'T'HH:mm:ss'Z'` format to pull the flows that entered after this date and time. The response only includes one month's worth of data. If there is no specified enter date, the API returns data from the past 24 hours.
enter_time_to

string — Required only when specifying the `enter_time_from` parameter. The enter time and date in `yyyy-MM-dd'T'HH:mm:ss'Z'` format, same as the `enter_time_from` parameter. Pulls the flows that entered in the given `enter_time_from` and `enter_time_to` time periods.
exit_time_from

string — The exit time and date in `yyyy-MM-dd'T'HH:mm:ss'Z'` format to pull the engagements that exited after this date and time. The response only includes one month's worth of data. If there is no specified exit date, the API returns data from the past 24 hours.
exit_time_to

string — The exit time and date in `yyyy-MM-dd'T'HH:mm:ss'Z'` format to pull the flows that exited after this date and time. The response only includes one month's worth of data. If there is no specified exit date, the API returns data from the past 24 hours.
flows

array

Items:
- ani_from
  
  string — The phone number that an engagement originated from.
- destination
  
  string — The name of the last widget the engagement reached before exiting the flow.
- dnis_to
  
  string — The original number that was dialed for an engagement.
- duration_to_first_handled_agent
  
  number — The amount of time from when engagements entered the flow until they were handled by the first assigned agent, in milliseconds.
- duration_to_first_handled_queue
  
  number — The amount of time from when engagements entered the flow until they were handled by the first assigned queue, in milliseconds.
- duration_to_first_offered_agent
  
  number — The amount of time from when engagements entered the flow until they were assigned with an agent, in milliseconds.
- engagement_id
  
  string — The engagement's unique identifier.
- enter_channel
  
  string, possible values: "voice", "video", "messaging", "email", "work_item" — The channel that an engagement was in when it entered the flow.
- enter_channel_source
  
  string, possible values: "voice", "in_app_video", "kiosk_video", "web_video", "in_app_chat", "in_video_chat", "web_chat", "sms", "facebook_messenger", "instagram", "team_chat", "whats_app", "email_domain", "api" — The source that an engagement was in when it entered the flow. * `voice` - Only applies to the voice channel. * `in_app_video` - Only applies to the video channel. * `kiosk_video` - Only applies to the video channel. * `web_video` - Only applies to the video channel. * `in_app_chat` - Only applies to the messaging channel. * `in_video_chat` - Only applies to the messaging channel. * `web_chat` - Only applies to the messaging channel. * `sms` - Only applies to the messaging channel. * `facebook_messenger` - Only applies to the messaging channel. * `instagram` - Only applies to the messaging channel. * `team_chat` - Only applies to the messaging channel. * `whats_app` - Only applies to the messaging channel. * `email_domain` - Only applies to the email channel. * `api` - Only applies to the work_item channel.
- entry_point
  
  string — The entry point where the engagement entered the flow.
- first_offered_queue_duration
  
  number — The amount of time an engagement took from entering the Contact Center until it was assigned to the first queue.
- first_widget_duration
  
  number — The amount of time an engagement took from entering the Contact Center until it reached the first widget in the flow, in milliseconds.
- flow_duration
  
  number — The amount of time an engagement took from entering the Contact Center until it reached the first widget in the flow, in milliseconds.
- flow_enter_time
  
  string — The timestamp when an engagement entered the flow.
- flow_exit_time
  
  string — The timestamp when an engagement exited the flow.
- flow_id
  
  string — The specific ID of a flow on the Zoom platform.
- flow_name
  
  string — The specific name of a flow on the Zoom platform.
- flow_offered_count
  
  integer — The total number of engagements that were offered to a flow.
- flow_upgraded_count
  
  integer — The number of times an engagement was upgraded within the flow, such as voice upgraded to video.
- flow_version
  
  string — The flow version that was used when an engagement entered it.
- handled_by_agent_count
  
  integer — Whether the engagement was handled by an agent within the flow.
- handled_by_first_offered_agent_count
  
  integer — The number of engagements that entered the flow and were handled by the first assigned agent.
- handled_by_first_offered_queue_count
  
  integer — The number of engagements that entered the flow and were handled by the first assigned queue.
- handled_by_queue_count
  
  integer — Whether the engagement was handled by a queue within the flow.
- offered_to_agent_count
  
  integer — Whether the engagement was assigned to an agent within the flow.
- offerred_to_queue_count
  
  integer — Whether the engagement was assigned to a queue within the flow.
from

string — The start time and date in `yyyy-MM-dd'T'HH:mm:ss'Z'` format to pull the flows that started after this date and time. The response only includes one month's worth of data. If there is no specified start date, the API returns data from the past 24 hours.
next_page_token

string — Use the next page token to paginate through large result sets. A next page token is returned whenever the set of available results exceeds the current page size. This token's expiration period is 15 minutes.
page_size

integer, default: 30 — The number of records returned within a single API call.
timezone

string — The [timezone ID](/docs/api/references/abbreviations/#timezones) to use for the start time and end time in the query. The default is `UTC`.
to

string — Required only when the `from` parameter is specified. The end time and date in `yyyy-MM-dd'T'HH:mm:ss'Z'` format, the same format as the `from` parameter. Pulls the flows that started in the given `from` and `to` time periods.
total_records

integer — The total number of all records available across pages.

Example:

{
  "next_page_token": "R4aF9Oj0fVM2hhezJTEmSKaBSkfesDwGy42",
  "page_size": 30,
  "total_records": 10,
  "from": "2021-12-10T00:00:00Z",
  "to": "2021-12-10T00:00:00Z",
  "enter_time_from": "2021-12-10T00:00:00Z",
  "enter_time_to": "2021-12-10T00:00:00Z",
  "exit_time_from": "2021-12-10T00:00:00Z",
  "exit_time_to": "2021-12-10T00:00:00Z",
  "timezone": "America/Los_Angeles",
  "flows": [
    {
      "flow_id": "reRAiabVQSqpXxJVDbsy2Q",
      "flow_name": "flow_example_name",
      "flow_version": "2",
      "flow_enter_time": "2021-12-10T00:15:00Z",
      "flow_exit_time": "2021-12-10T00:15:00Z",
      "enter_channel": "messaging",
      "enter_channel_source": "in_app_chat",
      "entry_point": "+12345678",
      "engagement_id": "reRAiabVQSqpXxJVDbsy2Q",
      "flow_offered_count": 1,
      "flow_upgraded_count": 1,
      "offerred_to_queue_count": 1,
      "handled_by_queue_count": 1,
      "handled_by_first_offered_queue_count": 1,
      "offered_to_agent_count": 2,
      "handled_by_agent_count": 1,
      "handled_by_first_offered_agent_count": 3,
      "flow_duration": 123,
      "first_widget_duration": 123,
      "first_offered_queue_duration": 123,
      "duration_to_first_handled_queue": 213,
      "duration_to_first_offered_agent": 123,
      "duration_to_first_handled_agent": 123,
      "destination": "Route to Sales Queue",
      "dnis_to": "+12095551212",
      "ani_from": "+19135551212"
    }
  ]
}

Status: 400 HTTP Status Code: `400` Bad Request

Status: 401 HTTP Status Code: `401` Unauthorized Error Code: `124` Invalid access token. Error Code: `124` Access token has expired. Error Code: `1002` The user associated with this access token was not found or is invalid.

Status: 403 HTTP Status Code: `403` Forbidden Error Code: `1021` User account is deactivated. Error Code: `1022` User does not have a Contact Center license. Error Code: `9001` The Contact Center user associated with this bearer token is missing privileges on their role required to operate this request.

Status: 404 HTTP Status Code: `404` Not Found

Status: 429 HTTP Status Code: `429` Too Many Requests. For more information, see [rate limits](https://developers.zoom.us/docs/api/rate-limits/). Error Code: `4001` You have reached the maximum per-second rate limit for this API. Try again later.

List historical outbound dialer performance dataset data

Method: GET
Path: /contact_center/analytics/dataset/historical/outbound_dialer_performance
Tags: Reports V2 (CX Analytics)

Generate a list of outbound dialer performance dataset raw data.

Scopes: contact_center_report:read:admin

Granular Scopes: contact_center:read:dataset_outbound_dialer_performance:admin

Rate Limit Label: HEAVY

Responses

Status: 200 The outbound dialer performance dataset raw data response.

Content-Type: application/json

end_time_from

string — The end time and date in `yyyy-MM-dd'T'HH:mm:ss'Z'` format to pull the outbound dialer engagements that ended after this date and time. The response only includes one month's worth of data. If there is no specified end date, the API returns data from the past 24 hours.
end_time_to

string — Required only when specifying the `end_time_from` parameter. The end time and date in `yyyy-MM-dd'T'HH:mm:ss'Z'` format, same as the `end_time_from` parameter. Pulls the outbound dialer engagements that ended in the given `end_time_from` and `end_time_to` time periods.
engagements

array — Information about the engagement.

Items:
- caller_id_number
  
  string — The caller ID number that is displayed when engagements are attempted from.
- calls_answered_count
  
  integer — The number of engagements answered.
- calls_blocked_count
  
  integer — The number of engagements blocked.
- calls_failed_count
  
  integer — The number of engagements failed.
- calls_skipped_count
  
  integer — The number of engagements skipped due to being outside callable hours.
- calls_with_amd_count
  
  integer — The number of engagements with AMD.
- campaign
  
  object — All campaignd created on the Zoom platform.
  - campaign_id
    
    string — The ID of a campaign created on the Zoom platform.
  - campaign_name
    
    string — The name of a campaign created on the Zoom platform.
- consumer_number
  
  string — The customer phone number that was attempted.
- contact
  
  object — All contact that the engagements are linked to.
  - contact_id
    
    string — The ID of the contact that the engagements are linked to.
  - contact_name
    
    string — The name of the contact that the engagements are linked to.
- contact_list
  
  object — All contact list that the engagements have been loaded into.
  - contact_list_id
    
    string — The ID of the contact list that the engagements have been loaded into.
  - contact_list_name
    
    string — The name of the contact list that the engagements have been loaded into.
- contacts_connected_count
  
  integer — The number of engagements connected to the consumer.
- dialer_method
  
  string, possible values: "progressive", "preview" — The method used, such as `preview` or `progressive`.
- dnc_count
  
  integer — The number of phone numbers that appear on the do not call list.
- dnc_flag
  
  boolean — Whether the prospective engagement has been flagged for a DNC list. This would be `true` or `false`.
- end_time
  
  string — The date and time when the engagement ended, in ISO 8601 format, either `yyyy-MM-dd'T'HH:mm:ss'Z'` or `yyyy-MM-dd'T'HH:mm:ss'TZD'`. `start_time` will be the time according to the timezone indicated by the user. If no timezone is provided, `start_time` will be in UTC.
- engagement_duration
  
  number — The total duration of the engagement. From when the engagement starts ringing until it is hung up, in milliseconds.
- engagement_id
  
  string — The engagement's ID.
- response_duration
  
  number — The amount of time the dialer takes to connect an agent to a live call after the customer answers the phone, in milliseconds.
- start_time
  
  string — The engagement date and time when the engagement started, in ISO 8601 format, either `yyyy-MM-dd'T'HH:mm:ss'Z'` or `yyyy-MM-dd'T'HH:mm:ss'TZD'`. `start_time` will be the time according to the timezone indicated by the user. If no timezone is provided, `start_time` will be in UTC.
from

string — The start time and date in `yyyy-MM-dd'T'HH:mm:ss'Z'` format to pull the outbound dialer engagements that started after this date and time. The response only includes one month's worth of data. If there is no specified start date, the API returns data from the past 24 hours.
next_page_token

string — Use the next page token to paginate through large result sets. A next page token is returned whenever the set of available results exceeds the current page size. This token's expiration period is 15 minutes.
page_size

integer, default: 30 — The number of records returned within a single API call.
start_time_from

string — The start time and date in `yyyy-MM-dd'T'HH:mm:ss'Z'` format to pull the outbound dialer engagements that started after this date and time. The response only includes one month's worth of data. If there is no specified start date, the API returns data from the past 24 hours.
start_time_to

string — Required only when specifying the `start_time_from` parameter. The start time and date in `yyyy-MM-dd'T'HH:mm:ss'Z'` format, same as the `start_time_from` parameter. Pulls the outbound dialer engagements that started in the given `start_time_from` and `start_time_to` time periods.
timezone

string — The [timezone ID](/docs/api/references/abbreviations/#timezones) to use for the start time and end time in the query. . The default is `UTC`.
to

string — Required only when specifying the `from` parameter. The end time and date in `yyyy-MM-dd'T'HH:mm:ss'Z'` format, the same format as the `from` parameter. Pulls the outbound dialer engagements that started in the given `from` and `to` time periods.
total_records

integer — The total number of all records available across pages.

Example:

{
  "next_page_token": "R4aF9Oj0fVM2hhezJTEmSKaBSkfesDwGy42",
  "page_size": 30,
  "total_records": 10,
  "timezone": "America/Los_Angeles",
  "from": "2021-12-10T00:00:00Z",
  "to": "2021-12-10T00:00:00Z",
  "engagements": [
    {
      "engagement_id": "reRAiabVQSqpXxJVDbsy2Q",
      "start_time": "2021-12-10T00:00:00Z",
      "end_time": "2021-12-10T00:00:00Z",
      "campaign": {
        "campaign_id": "reRAiabVQSqpXxJVDbsy2Q",
        "campaign_name": "campaign_example"
      },
      "contact_list": {
        "contact_list_id": "reRAiabVQSqpXxJVDbsy2Q",
        "contact_list_name": "John's Contacts"
      },
      "contact": {
        "contact_id": "reRAiabVQSqpXxJVDbsy2Q",
        "contact_name": "Jane Doe"
      },
      "dialer_method": "progressive",
      "dnc_flag": true,
      "caller_id_number": "+1234567890",
      "consumer_number": "+1234567890",
      "calls_answered_count": 1,
      "calls_failed_count": 0,
      "calls_with_amd_count": 0,
      "calls_blocked_count": 0,
      "contacts_connected_count": 1,
      "dnc_count": 0,
      "engagement_duration": 10000,
      "response_duration": 1000,
      "calls_skipped_count": 0
    }
  ],
  "start_time_from": "2021-12-10T00:00:00Z",
  "start_time_to": "2021-12-10T00:00:00Z",
  "end_time_to": "2021-12-10T00:00:00Z",
  "end_time_from": "2021-12-10T00:00:00Z"
}

Status: 400 HTTP Status Code: `400` Bad Request

Status: 404 HTTP Status Code: `404` Not Found

Status: 429 HTTP Status Code: `429` Too Many Requests. For more information, see [rate limits](https://developers.zoom.us/docs/api/rate-limits/).

List historical queue performance dataset data

Method: GET
Path: /contact_center/analytics/dataset/historical/queue_performance
Tags: Reports V2 (CX Analytics)

Generate a list of queue performance dataset raw data.

Scopes: contact_center_report:read:admin

Granular Scopes: contact_center:read:dataset_queue_performance:admin

Rate Limit Label: HEAVY

Responses

Status: 200 Queue performance dataset raw data response.

Content-Type: application/json

enter_time_from

string — The enter time and date in `yyyy-MM-dd'T'HH:mm:ss'Z'` format to pull the queues that entered after this date and time. The response only includes one month's worth of data. If there is no specified enter date, the API returns data from the past 24 hours.
enter_time_to

string — Required only when specifying the `enter_time_from` parameter. The enter time and date in `yyyy-MM-dd'T'HH:mm:ss'Z'` format, the same format as the `enter_time_from` parameter. Pulls the queues that entered in the given `enter_time_from` and `enter_time_to` time periods.
exit_time_from

string — The exit time and date in `yyyy-MM-dd'T'HH:mm:ss'Z'` format to pull the queues that exited after this date and time. The response only includes one month's worth of data. If there is no specified exit date, the API returns data from the past 24 hours.
exit_time_to

string — Required only when specifying the `exit_time_from` parameter. The exit time and date in `yyyy-MM-dd'T'HH:mm:ss'Z'` format, the same format as the `exit_time_from` parameter. Pulls the queues that exited in the given `exit_time_from` and `exit_time_to` time periods.
from

string — The start time and date in `yyyy-MM-dd'T'HH:mm:ss'Z'` format to pull the queues that started after this date and time. The response only includes one month's worth of data. If there is no specified start date, the API returns data from the past 24 hours.
next_page_token

string — Use the next page token to paginate through large result sets. A next page token is returned whenever the set of available results exceeds the current page size. This token's expiration period is 15 minutes.
page_size

integer, default: 30 — The number of records returned within a single API call.
queues

array

Items:
- abandon_duration
  
  number — The amount of time a customer waited in a specific queue before abandoning the engagement. Only applies to the queue where the abandonment actually occurred, in milliseconds.
- abandoned_count
  
  integer — The number of times an end user abandoned an engagement before connecting with an agent. Also the sum of Short Abandons and Long Abandons.
- ani_from
  
  string — The phone number that an engagement originated from.
- auto_close_disconnect_count
  
  integer — The count of messaging and email engagements that are auto closed by the system after not receiving a response from the consumer after a defined period of time.
- callback_abandoned_count
  
  integer — The number of callbacks where an agent was already connected, but not successfully connected to the consumer.
- callback_canceled_count
  
  integer — The number of callbacks which consumers choose to cancel and instead wait in the queue.
- callback_conversation_duration
  
  number — The amount of time that an agent spent on an engagement communicating with a consumer, in milliseconds.
- callback_handle_duration
  
  number — The amount of time agents spent handling callbacks, in milliseconds.
- callback_handled_count
  
  integer — The number of callbacks accepted by available agents.
- callback_pending_duration
  
  number — The amount of time from when the agent called back until the customer answered the call, customer did not answer or the agent hung up, in milliseconds.
- callback_registered_count
  
  integer — The number of engagements that entered the queue and requested a callback, or scheduled a callback via the dedicated web page.
- callback_timeout_count
  
  integer — The number of callbacks placed but did not speak to an agent before the callback expired.
- callback_wait_duration
  
  number — The amount of time from a callback being registered until either the agent calls back, the callback expires, or the callback is canceled, in milliseconds.
- callback_wrap_up_duration
  
  number — The amount of time agents spent completing after call work, in milliseconds.
- conference_count
  
  integer — The number of conferences that occurred.
- conference_duration
  
  number — The amount of time an agent spent in conversation with an engagement and at least one additional agent, in milliseconds.
- conversation_duration
  
  number — The amount of time that agents spent on engagements communicating with a consumer, in milliseconds.
- direct_transfer_count
  
  integer — The number of direct transfers initiated.
- direction
  
  string, possible values: "inbound", "outbound" — The queue task direction.
- dnis_to
  
  string — The original number that was dialed for an engagement.
- engagement_id
  
  string — The engagement's ID.
- enter_channel
  
  string, possible values: "voice", "video", "messaging", "email", "work_item" — The channel that the queue task enters.
- enter_channel_source
  
  string, possible values: "voice", "in_app_video", "kiosk_video", "web_video", "in_app_chat", "in_video_chat", "web_chat", "sms", "facebook_messenger", "instagram", "team_chat", "whats_app", "email_domain", "api" — The source that the queue task enters. * `voice` - Only applies to the voice channel. * `in_app_video` - Only applies to the video channel. * `kiosk_video` - Only applies to the video channel. * `web_video` - Only applies to the video channel. * `in_app_chat` - Only applies to the messaging channel. * `in_video_chat` - Only applies to the messaging channel. * `web_chat` - Only applies to the messaging channel. * `sms` - Only applies to the messaging channel. * `facebook_messenger` - Only applies to the messaging channel. * `instagram` - Only applies to the messaging channel. * `team_chat` - Only applies to the messaging channel. * `whats_app` - Only applies to the messaging channel. * `email_domain` - Only applies to the email channel. * `api` - Only applies to the work_item channel.
- enter_queue_id
  
  string — The unique identifier generated for each queue entry record of an engagement.
- enter_time
  
  string — The timestamp when an engagement entered the queue.
- exit_time
  
  string — The timestamp when an engagement exited the queue.
- handle_count
  
  integer — The number of inbound (including callback) and outbound engagements handled by the queue.
- handle_duration
  
  number — The amount of time agents spent handling engagements, in milliseconds.
- hold_count
  
  integer — The number of times that a consumer was placed on hold.
- hold_duration
  
  number — The amount of time that a consumer was placed on hold, in milliseconds. **NOTE** A call may have multiple hold times.
- in_queue_wait_duration
  
  number — The amount of time the consumer spent waiting live - not in callback - in the queue before the engagement was answered, overflowed, or abandoned, in milliseconds.
- inbound_conversation_duration
  
  number — The amount of time that an agent spent on an inbound engagement in communication with the consumer, in milliseconds.
- inbound_handle_duration
  
  number — The amount of time agents spent handling inbound engagements, in milliseconds.
- inbound_handled_count
  
  integer — The number of inbound engagements offered to and answered by an agent.
- inbound_wrap_up_duration
  
  number — The amount of time an agent spent completing inbound engagement wrap-up, in milliseconds.
- long_abandons_count
  
  integer — The number of engagements that were abandoned after the threshold defined for the queue.
- origin_method
  
  string, possible values: "take_over", "hand_over", "callback", "scheduled_callback", "callback_retry", "outbound", "conference", "release", "warm_transfer_to_agent", "warm_transfer_to_queue", "direct_transfer_to_agent", "direct_transfer_to_queue", "transfer_to_agent", "transfer_to_queue", "route_to_queue", "route_to_agent", "outbound_progressive_dial", "outbound_preview_dial", "outbound_third_party_dial", "park" — How the engagement was routed to the queue.
- outbound_connected_count
  
  integer — The number of outbound engagements that resulted in a successful connection between a customer and an agent.
- outbound_conversation_duration
  
  number — The amount of time that an agent spent on an outbound engagement communicating with a consumer, in milliseconds.
- outbound_count
  
  integer — The number of outbound engagements that entered a queue, regardless of a successful connection.
- outbound_dial_duration
  
  number — The amount of time spent dialing the customer, in milliseconds.
- outbound_handle_duration
  
  number — The amount of time agents spent handling outbound engagements. This also includes the time dialing a customer, in milliseconds.
- outbound_handled_count
  
  integer — The number of outbound engagements handled by agents, regardless of successful connection or not.
- outbound_wrap_up_duration
  
  number — The amount of time an agent spent completing outbound engagement wrap-up, in milliseconds.
- overflow_count
  
  integer — The number of engagements that entered and left a queue without being answered. This occurs because the capacity of available agent resources in queue was exceeded.
- parked_count
  
  integer — The number of times that an engagement was parked.
- parked_duration
  
  number — The amount of time that an engagement is in parked status, in milliseconds.
- queue_id
  
  string — A queue's specific ID.
- queue_name
  
  string — A queue's specific name.
- queue_offered_count
  
  integer — The number of engagements routed into the queue for agents to answer.
- short_abandons_count
  
  integer — The number of engagements that were abandoned before the threshold defined for the queue.
- speed_of_answer_duration
  
  number — The amount of time an engagement waited in the queue before an agent answered, in milliseconds. **NOTE** This metric does not include engagements that agents did not answer.
- transfer_completed_count
  
  integer — The number of transfers an agent completed, including warm and direct transfers for voice and video channels, and all transfers for messaging and email channels (no distinction between warm and direct).
- transfer_initiated_count
  
  integer — The number of transfers an agent initiated, including warm and direct transfers for voice and video channels, and all transfers for messaging and email channels (no distinction between warm and direct).
- warm_conference_count
  
  integer — The number of warm conferences initiated.
- warm_conference_duration
  
  number — The amount of time an agent spent in conversation with another agent while the engagement was on hold, in milliseconds.
- warm_transfer_completed_count
  
  integer — The number of voice or video engagements an agent answered and then warm transferred with another participant and then fully transferred the engagements.
- warm_transfer_duration
  
  number — The amount of time an agent spent in conversation with another agent while the engagement was on hold, in milliseconds.
- warm_transfer_initiated_count
  
  integer — The number of voice or video engagements an agent answered and then warm transferred with another participant with or without fully transferring the engagement.
- wrap_up_duration
  
  number — The amount of time agents spent completing engagement wrap-up, in milliseconds.
timezone

string — The [timezone ID](/docs/api/references/abbreviations/#timezones) to use for the start time and end time in the query. The default is `UTC`.
to

string — Required only when the `from` parameter is specified. The end time and date in `yyyy-MM-dd'T'HH:mm:ss'Z'` format, same as the `from` parameter. Pulls the queues that started in the given `from` and `to` time periods.
total_records

integer — The total number of all records available across pages.

Example:

{
  "next_page_token": "R4aF9Oj0fVM2hhezJTEmSKaBSkfesDwGy42",
  "page_size": 30,
  "total_records": 10,
  "timezone": "America/Los_Angeles",
  "from": "2021-12-10T00:00:00Z",
  "to": "2021-12-10T00:00:00Z",
  "enter_time_from": "2021-12-10T00:00:00Z",
  "enter_time_to": "2021-12-10T00:00:00Z",
  "exit_time_from": "2021-12-10T00:00:00Z",
  "exit_time_to": "2021-12-10T00:00:00Z",
  "queues": [
    {
      "engagement_id": "reRAiabVQSqpXxJVDbsy2Q",
      "enter_time": "2021-12-10T00:00:00Z",
      "exit_time": "2021-12-10T10:30:00Z",
      "queue_id": "reRAiabVQSqpXxJVDbsy2Q",
      "queue_name": "queue_example_name",
      "enter_channel": "messaging",
      "enter_channel_source": "in_app_chat",
      "origin_method": "take_over",
      "direction": "inbound",
      "queue_offered_count": 1,
      "abandoned_count": 1,
      "short_abandons_count": 0,
      "long_abandons_count": 1,
      "overflow_count": 1,
      "inbound_handled_count": 2,
      "in_queue_wait_duration": 123,
      "abandon_duration": 123,
      "speed_of_answer_duration": 123,
      "inbound_handle_duration": 123,
      "inbound_conversation_duration": 123,
      "inbound_wrap_up_duration": 123,
      "outbound_count": 1,
      "outbound_handled_count": 1,
      "outbound_connected_count": 1,
      "outbound_dial_duration": 123,
      "outbound_handle_duration": 123,
      "outbound_conversation_duration": 123,
      "outbound_wrap_up_duration": 123,
      "callback_registered_count": 1,
      "callback_abandoned_count": 1,
      "callback_canceled_count": 1,
      "callback_timeout_count": 1,
      "callback_handled_count": 1,
      "callback_wait_duration": 123,
      "callback_pending_duration": 123,
      "callback_handle_duration": 123,
      "callback_conversation_duration": 123,
      "callback_wrap_up_duration": 123,
      "handle_count": 1,
      "hold_count": 1,
      "warm_transfer_initiated_count": 1,
      "warm_transfer_completed_count": 1,
      "direct_transfer_count": 2,
      "transfer_initiated_count": 1,
      "transfer_completed_count": 1,
      "warm_conference_count": 1,
      "conference_count": 1,
      "auto_close_disconnect_count": 1,
      "handle_duration": 17922,
      "conversation_duration": 16901,
      "wrap_up_duration": 143561,
      "hold_duration": 169,
      "conference_duration": 283764,
      "warm_transfer_duration": 1453,
      "warm_conference_duration": 283764,
      "dnis_to": "+12095551212",
      "ani_from": "+19135551212",
      "parked_count": 1,
      "parked_duration": 123,
      "enter_queue_id": "ZWT70A1CE9D236F8E85DF9F80726A8DCEC5"
    }
  ]
}

Status: 400 HTTP Status Code: `400` Bad Request

Status: 401 HTTP Status Code: `401` Unauthorized Error Code: `124` Invalid access token. Error Code: `124` Access token has expired. Error Code: `1002` The user associated with this access token was not found or is invalid.

Status: 403 HTTP Status Code: `403` Forbidden Error Code: `1021` User account is deactivated. Error Code: `1022` User does not have a Contact Center license. Error Code: `9001` The Contact Center user associated with this bearer token is missing privileges on their role required to operate this request.

Status: 404 HTTP Status Code: `404` Not Found

Status: 429 HTTP Status Code: `429` Too Many Requests. For more information, see [rate limits](https://developers.zoom.us/docs/api/rate-limits/). Error Code: `4001` You have reached the maximum per-second rate limit for this API. Try again later.

List historical engagement log data

Method: GET
Path: /contact_center/analytics/log/historical/engagement
Tags: Reports V2 (CX Analytics)

Retrieve a list of all historical engagement log data. The log captures all details of closed engagements, including a timeline and key events, providing a clear record for tracking and analysis.

Scopes: contact_center_report:read:admin

Granular Scopes: contact_center:read:engagement_log:admin

Rate Limit Label: HEAVY

Responses

Status: 200 Generate a list of historical engagement logs data.

Content-Type: application/json

engagement_logs

array — The engagement log list.

Items:
- aiea_used
  
  string, possible values: "used", "not_used" — Whether Agentic AI Expert Assist was involved in the engagement. This only applies to Agentic AI Expert Assist. **NOTE** Data is available only when the feature is enabled and properly licensed.
- ani_from
  
  string — The phone number that an engagement originated from.
- blocked
  
  boolean — Is blocked.
- caller_id
  
  string — The caller's phone number.
- channels
  
  array — The channels on the Zoom platform such as voice, video, digital, and messaging.
  
  Items:
  - channel
    
    string, possible values: "voice", "video", "messaging", "email", "work_item" — The name of the channels on the Zoom platform.
  - channel_source
    
    string, possible values: "voice", "web_video", "in_app_video", "kiosk_video", "web_chat", "in_app_chat", "team_chat", "sms", "facebook_messenger", "instagram", "whatsapp", "email_address", "api" — The name of sources on the Zoom platform that specifically relate to a channel. * `voice` - Only applies to voice channel. * `in_app_video` - Only applies to video channel. * `kiosk_video` - Only applies to video channel. * `web_video` - Only applies to video channel. * `in_app_chat` - Only applies to messaging channel. * `in_video_chat` - Only applies to messaging channel. * `web_chat` - Only applies to messaging channel. * `sms` - Only applies to messaging channel. * `facebook_messenger` - Only applies to messaging channel. * `instagram` - Only applies to messaging channel. * `team_chat` - Only applies to messaging channel. * `whatsapp` - Only applies to messaging channel. * `email_address` - Only applies to email channel. * `api` - Only applies to work_item channel.
- conference_count
  
  integer — The number of conferences that occurred.
- conference_duration
  
  number — The amount of time an agent spent in conversation with an engagement and at least one additional agent, in milliseconds.
- consumer
  
  object — The consumer's information.
  - consumer_email
    
    string — The consumer email.
  - consumer_name
    
    string — The consumer name.
  - consumer_number
    
    string — The consumer number.
- direct_transfer_count
  
  integer — The number of direct transfers.
- direction
  
  string, possible values: "inbound", "outbound" — The engagement's direction. * inbound * outbound
- dispositions
  
  array — The dispositions.
  
  Items:
  - disposition_id
    
    string — A disposition's specific ID.
  - disposition_name
    
    string — A disposition's name.
- dnis_to
  
  string — The original number that was dialed for an engagement.
- duration
  
  number — The engagement's duration, in milliseconds.
- end_time
  
  string, format: date-time — The engagement end time.
- engagement_id
  
  string — The engagement's specific ID.
- enter_channel
  
  object — The channel that the engagement was in when it entered the Contact Center.
  - channel
    
    string, possible values: "voice", "video", "messaging", "email", "work_item" — The channel that the engagement was in when it entered the Zoom Contact Center.
  - channel_source
    
    string, possible values: "voice", "web_video", "in_app_video", "kiosk_video", "web_chat", "in_app_chat", "team_chat", "sms", "facebook_messenger", "instagram", "whatsapp", "email_address", "api" — The name of enter sources on the Zoom platform that specifically relate to a channel. * `voice` - voice * `web_video` - web video * `in_app_video` - in-app video * `kiosk_video` - kiosk video * `web_chat` - web chat * `in_app_chat` - in-app chat * `team_chat` - Zoom team chat * `sms` - SMS * `facebook_messenger` - Facebook messenger * `instagram` - Instagram * `whatsapp` - Whatsapp * `email_address` - email * `api` - Work Item API
- events
  
  array — All events related to the engagement
  
  Items:
  - event_id
    
    string — A event's specific ID.
  - event_name
    
    string — A event's name.
- flows
  
  array — All flows related to the engagement.
  
  Items:
  - flow_id
    
    string — A flow's specific ID.
  - flow_name
    
    string — A flow's name.
- hold_count
  
  integer — The number of times that a consumer was placed on hold.
- hold_duration
  
  number — The amount of time that a consumer was placed on hold, in milliseconds. **NOTE** A call may have multiple hold times.
- notes
  
  array — The notes.
  
  Items:
  - note_content
    
    string — This note's content.
  - note_id
    
    string — A note's specific ID.
  - user_id
    
    string — An agent's specific ID.
- queues
  
  array — All queues related to the engagement.
  
  Items:
  - queue_id
    
    string — A queue's specific ID.
  - queue_name
    
    string — A queue's specific name.
- start_time
  
  string, format: date-time — The engagement start time.
- survey_id
  
  string — The survey specfic ID.
- teams
  
  array — All teams related to the engagement.
  
  Items:
  - team_id
    
    string — A team's specific ID.
  - team_name
    
    string — A team's name.
- transcript_url
  
  string — The transcript URL, in `/v2/contact_center/engagements/transcripts/download/{engagementId}` format.
- transfer_completed_count
  
  integer — The number of direct transfers completed.
- transfer_initiated_count
  
  integer — The number of direct transfers initiated.
- users
  
  array — All agents related to the engagement.
  
  Items:
  - user_id
    
    string — The ID of the agent who is set up on the agent profile.
  - user_name
    
    string — The first and last name of the agent who is set up on the agent profile.
- voicemail_count
  
  integer — The number of voicemail.
- warm_conference_count
  
  integer — The number of warm conferences initiated.
- warm_conference_duration
  
  number — The amount of time an agent spent in conversation with an engagement and at least one additional agent, in **milliseconds**.
- warm_transfer_completed_count
  
  integer — The number of voice or video engagements an agent answered and then warm transferred with another participant and then fully transferred the engagements.
- warm_transfer_duration
  
  number — The amount of time an agent spent in conversation with another agent while the engagement was on hold, in **milliseconds**.
- warm_transfer_initiated_count
  
  integer — The number of voice or video engagements an agent answered and then warm transferred with another participant with or without fully transferring the engagement.
next_page_token

string — Use the next page token to paginate through large result sets. A next page token is returned whenever the set of available results exceeds the current page size. This token's expiration period is 15 minutes.
page_size

integer, default: 30 — The number of records returned within a single API call.
timezone

string — The [timezone ID](/docs/api/references/abbreviations/#timezones) to use for the start time and end time in the query. The default is **UTC**.
total_records

integer — The total number of all records available across pages.

Example:

{
  "timezone": "UTC",
  "engagement_logs": [
    {
      "engagement_id": "t0VAFD7FDkdfwHxlN40_w",
      "direction": "inbound",
      "channels": [
        {
          "channel": "video",
          "channel_source": "web_video"
        }
      ],
      "enter_channel": {
        "channel": "voice",
        "channel_source": "voice"
      },
      "start_time": "2025-05-26T16:30:08Z",
      "end_time": "2025-05-26T16:32:18Z",
      "consumer": {
        "consumer_name": "Jill Chill",
        "consumer_email": "jchill@example.com",
        "consumer_number": "+12095551212"
      },
      "queues": [
        {
          "queue_id": "_dkUfugn8eDFkRohArKqQ",
          "queue_name": "my_queue"
        }
      ],
      "users": [
        {
          "user_id": "i5iDfUroHKU&*FH",
          "user_name": "kevin_agent"
        }
      ],
      "teams": [
        {
          "team_id": "wdhgyuYD74wUF",
          "team_name": "agent team1"
        }
      ],
      "flows": [
        {
          "flow_id": "CBDH87436Hdjse",
          "flow_name": "flow1"
        }
      ],
      "events": [
        {
          "event_id": "rF61SnVrQjyLE2Je7a40uw",
          "event_name": "engagement.start"
        }
      ],
      "caller_id": "+19135551212",
      "ani_from": "+19135551212",
      "dnis_to": "+12095551212",
      "duration": 38000,
      "hold_count": 3,
      "hold_duration": 10000,
      "warm_transfer_initiated_count": 1,
      "warm_transfer_completed_count": 1,
      "warm_transfer_duration": 147000,
      "direct_transfer_count": 0,
      "transfer_initiated_count": 0,
      "transfer_completed_count": 0,
      "warm_conference_count": 0,
      "warm_conference_duration": 10000,
      "conference_count": 3,
      "blocked": false,
      "conference_duration": 54000,
      "voicemail_count": 3,
      "dispositions": [
        {
          "disposition_id": "sUEMfweg34GFE",
          "disposition_name": "kv"
        }
      ],
      "notes": [
        {
          "note_id": "sdfwe67gaDDG",
          "note_content": "content info",
          "user_id": "CBVD4fwdfw3DF"
        }
      ],
      "transcript_url": "/v2/contact_center/engagements/transcripts/download/t0VAFD7FDkdfwHxlN40_w",
      "survey_id": "sghewyDF73FDE",
      "aiea_used": "notUsed"
    }
  ],
  "page_size": 30,
  "total_records": 10,
  "next_page_token": "R4aF9Oj0fVM2hhezJTEmSKaBSkfesDwGy42"
}

Status: 400 HTTP Status Code: `400` Bad Request

Status: 401 HTTP Status Code: `401` Unauthorized Error Code: `124` Invalid access token. Error Code: `124` Access token has expired. Error Code: `1002` The user associated with this access token was not found or is invalid.

Status: 403 HTTP Status Code: `403` Forbidden Error Code: `1021` User account is deactivated. Error Code: `1022` User does not have a Contact Center license. Error Code: `9001` The Contact Center user associated with this bearer token is missing privileges on their role required to operate this request.

Status: 404 HTTP Status Code: `404` Not Found

Status: 429 HTTP Status Code: `429` Too Many Requests. For more information, see [rate limits](https://developers.zoom.us/docs/api/rate-limits/). Error Code: `4001` You have reached the maximum per-second rate limit for this API. Try again later.

List historical Zoom Phone to Contact Center call journey data

Method: GET
Path: /contact_center/analytics/log/historical/journey
Tags: Reports V2 (CX Analytics)

View the complete customer journey of a call across both Contact Center and Zoom Phone.

Scopes: contact_center_report:read:admin

Granular Scopes: contact_center:read:call_journey_log:admin

Rate Limit Label: HEAVY

Responses

Status: 200 Generate a list of historical Zoom Phone to Contact Center call journey data.

Content-Type: application/json

journeys

array — All Zoom Phone and Contact Center call journeys.

Items:
- ani_from
  
  string — The phone number that an engagement originated from.
- auto_receptionists
  
  array — A list of **Auto Receptionist** information. It answers incoming calls with a greeting or IVR menu and routes them to destinations such as phone users, call queues, common areas, voicemail, or an IVR system. With Contact Center integration, auto receptionists often serve as entry points into Contact Center voice flows, directing callers into Contact Center handling.
  
  Items:
  - extension_name
    
    string — The Zoom Phone auto receptionist.
  - extension_number
    
    string — The Zoom Phone extension number.
  - phone_number
    
    string — The Zoom Phone number.
- call_queues
  
  array — A list of **Call Queue** information. In Zoom Phone, this represents a group of phone users or common-area phones configured to handle incoming calls using defined distribution strategies such as simultaneous or round robin. When integrated with Contact Center, a call queue can be designated as a routing target for Contact Center voice flows, enabling Contact Center interactions to be processed through your Phone call queue infrastructure.
  
  Items:
  - extension_name
    
    string — The Zoom Phone call queue name.
  - extension_number
    
    string — The Zoom Phone extension number, such as 32784.
  - phone_number
    
    string — The Zoom Phone number.
- channels
  
  array — All channels on the Zoom platform such as voice, video, or digital.
  
  Items:
  - channel
    
    string, possible values: "voice", "video", "messaging", "email" — The name of the channels on the Zoom platform. * voice * video * messaging * email
  - channel_source
    
    string, possible values: "voice", "web_video", "in_app_video", "kiosk_video", "web_chat", "in_app_chat", "team_chat", "sms", "facebook_messenger", "instagram", "whatsapp", "email_address" — The name of sources on the Zoom platform that specifically relate to a channel. - `voice` - Only applies to voice channel. - `in_app_video` - Only applies to video channel. - `kiosk_video` - Only applies to video channel. - `web_video` - Only applies to video channel. - `in_app_chat` - Only applies to messaging channel. - `in_video_chat` - Only applies to messaging channel. - `web_chat` - Only applies to messaging channel. - `sms` - Only applies to messaging channel. - `facebook_messenger` - Only applies to messaging channel. - `instagram` - Only applies to messaging channel. - `team_chat` - Only applies to messaging channel. - `whatsapp` - Only applies to messaging channel. - `email_address` - Only applies to email channel.
- common_areas
  
  array — A list of **Common Areas** information, it typically deployed in shared office spaces like lobbies or conference rooms. These devices can be members of call queues, shared line groups, or receive calls via auto receptionist. In Zoom Contact Center enabled environments, common-area extensions may also serve as caller IDs or routing targets within Contact Center flows.
  
  Items:
  - extension_name
    
    string — The common area name.
  - extension_number
    
    string — The Zoom Phone extension number.
  - phone_number
    
    string — The Zoom Phone number.
- consumer
  
  object — The consumer's information.
  - consumer_number
    
    string — The consumer's number.
- direction
  
  string, possible values: "inbound", "outbound", "internal" — The engagement's direction. * `inbound` * `outbound` * `internal`
- dnis_to
  
  string — The original number that was dialed for an engagement.
- global_engagement_id
  
  string — The global engagement ID.
- inter_ops
  
  array — A list of **Interoperability Operation** information, representing standards-based SIP/H.323 room systems (e.g., Cisco Room, Polycom Room) integrated with Zoom through the Conference Room Connector. These devices are equipped with Zoom Phone calling capabilities, allowing them to make and receive phone calls. In Contact Center scenarios, interop rooms may serve as voice-flow targets or conferencing endpoints, enabling seamless integration of third-party hardware into Contact Center workflows.
  
  Items:
  - extension_name
    
    string — The Cisco/Polycom room name.
  - extension_number
    
    string — The Zoom Phone extension number.
  - phone_number
    
    string — The Zoom Phone number.
- queues
  
  array — All queues related to the engagement.
  
  Items:
  - queue_id
    
    string — A queue's specific ID.
  - queue_name
    
    string — A queue's specific name.
- shared_line_groups
  
  array — A list of **Shared Line Group** information. This allows multiple phone users or common-area phones to share a phone number and voicemail inbox. Zoom Phone admins can apply business hours and routing rules to these groups. When used with Zoom Contact Center, shared line groups can be selected as voice-flow targets—calls reaching the shared number are processed by any group member.
  
  Items:
  - extension_name
    
    string — The Zoom Phone share line group name.
  - extension_number
    
    string — The Zoom Phone extension number.
  - phone_number
    
    string — The Zoom Phone number.
- start_time
  
  string, format: date-time — The engagement's start time.
- teams
  
  array — All teams related to the engagement.
  
  Items:
  - team_id
    
    string — A team's specific ID.
  - team_name
    
    string — A team's name.
- users
  
  array — All agents related to the engagement.
  
  Items:
  - user_id
    
    string — The ID of the agent who is set up on the agent profile.
  - user_name
    
    string — The first and last name of the agent who is set up on the agent profile.
- zoom_phone_users
  
  array — A list of **Zoom Phone User** information, representing an individual extension-enabled user. In integrated Zoom Contact Center scenarios, phone users can act as contact-center agents or recipients—either receiving calls directly transferred from Zoom Contact Center or functioning as members of call queues or auto receptionist routes.
  
  Items:
  - extension_name
    
    string — The Zoom Phone user name.
  - extension_number
    
    string — The Zoom Phone short number.
  - phone_number
    
    string — The Zoom Phone number.
- zoom_rooms
  
  array — A list of **Zoom Room** information. Each represents a Zoom Room or standards-based SIP/H.323 room, like Cisco/Polycom, licensed for Zoom Phone. These rooms can make and receive phone calls using Zoom Phone services. When integrated with Contact Center, Zoom Rooms can be used as call destinations, entry points, or agent endpoints within Contact Center voice flows.
  
  Items:
  - extension_name
    
    string — The Zoom Room name.
  - extension_number
    
    string — The Zoom Phone extension number.
  - phone_number
    
    string — The Zoom Phone number.
next_page_token

string — Use the next page token to paginate through large result sets. A next page token is returned whenever the set of available results exceeds the current page size. This token's expiration period is 15 minutes.
page_size

integer, default: 30 — The number of records returned within a single API call.
timezone

string — The [timezone ID](/docs/api/references/abbreviations/#timezones) to use for the start time and end time in the query. The default is UTC.
total_records

integer — The total number of all records available across pages.

Example:

{
  "journeys": [
    {
      "global_engagement_id": "7512200802025393153",
      "direction": "inbound",
      "channels": [
        "voice"
      ],
      "ani_from": "+19135551212",
      "dnis_to": "+12095551212",
      "start_time": "2025-05-26T16:32:18Z",
      "consumer": {
        "consumer_number": "+19135551212"
      },
      "queues": [
        {
          "queue_id": "sfgwHE&gEFHE",
          "queue_name": "callen-voice-queue"
        }
      ],
      "users": [
        {
          "user_id": "sdFHEYF&G*E",
          "user_name": "callen huang-agent"
        }
      ],
      "teams": [
        {
          "team_id": "sdFHEYF&G*E",
          "team_name": "finlay-child"
        }
      ],
      "call_queues": [
        {
          "extension_name": "test call queue",
          "phone_number": "+12097481234",
          "extension_number": "7623"
        }
      ],
      "zoom_phone_users": [
        {
          "extension_name": "testSite",
          "phone_number": "+12095551212",
          "extension_number": "7623"
        }
      ],
      "shared_line_groups": [
        {
          "extension_name": "test slg",
          "phone_number": "+12095551212",
          "extension_number": "7623"
        }
      ],
      "auto_receptionists": [
        {
          "extension_name": "test-ar",
          "phone_number": "+12095551212",
          "extension_number": "7623"
        }
      ],
      "common_areas": [
        {
          "extension_name": "test common area",
          "phone_number": "+12095551212",
          "extension_number": "7623"
        }
      ],
      "zoom_rooms": [
        {
          "extension_name": "my room",
          "phone_number": "+12095551212",
          "extension_number": "7623"
        }
      ],
      "inter_ops": [
        {
          "extension_name": "Cisco room0101",
          "phone_number": "+12097481234",
          "extension_number": "26701"
        }
      ]
    }
  ],
  "timezone": "UTC",
  "page_size": 30,
  "total_records": 10,
  "next_page_token": "R4aF9Oj0fVM2hhezJTEmSKaBSkfesDwGy42"
}

Status: 400 HTTP Status Code: `400` Bad Request

Status: 401 HTTP Status Code: `401` Unauthorized

Status: 403 HTTP Status Code: `403` Forbidden

Status: 404 HTTP Status Code: `404` Not Found

Status: 429 HTTP Status Code: `429` Too Many Requests. For more information, see [rate limits](/docs/api/rate-limits/).

List operation logs

Method: GET
Path: /contact_center/reports/operation_logs
Tags: Reports V2 (CX Analytics)

Retrieve the Zoom Contact Center management system operation logs report.

The Zoom Contact Center management system operation logs report lets account owners and admins view monthly Zoom Contact Center related admin operation details.

Scopes: contact_center_operation_logs:read:admin

Granular Scopes: contact_center:read:operation_logs:admin

Rate Limit Label: HEAVY

Responses

Status: 200 HTTP Status Code: `200` Inbox messages returned.

Content-Type: application/json

highest_watermark

string, format: date-time — The latest time among the returned records within the query window.
next_page_token

string — Use the next page token to paginate through large result sets. A next page token is returned whenever the set of available results exceeds the current page size. This token's expiration period is 15 minutes.
operation_logs

array — The array of operation log objects.

Items:
- action
  
  string — The operation's action type.
- agent_region_id
  
  string — Region ID of the Agent.
- agent_region_name
  
  string — Region name of the Agent.
- category
  
  string — The operation's category type.
- object_id
  
  string — The operation's object ID.
- object_name
  
  string — The operation's object name.
- operation_detail
  
  string — The operation details.
- operation_log_id
  
  string — The operation's unique identifier.
- operator
  
  string — The user who performed the operation.
- team_id
  
  string — Unique identifier for the agent's team.
- team_name
  
  string — Name of the agent's team.
- time
  
  string, format: date-time — The time when the operation was performed.
page_size

integer, default: 30 — The number of records returned in a single API call.
total_records

integer — The total number of all records available across pages.

Example:

{
  "next_page_token": "R4aF9Oj0fVM2hhezJTEmSKaBSkfesDwGy42",
  "page_size": 30,
  "total_records": 10,
  "operation_logs": [
    {
      "time": "2024-04-25T07:51:30Z",
      "operator": "test@zoomtest.us",
      "category": "Account",
      "object_name": "test user",
      "operation_log_id": "VD8z8Q4UT4yGWhpiGdk5bw",
      "action": "Create",
      "operation_detail": "Add Flows: [inbox-voicemail]",
      "agent_region_id": "test_region_id",
      "agent_region_name": "test_region_name",
      "team_id": "test_team_id",
      "team_name": "test_team_name",
      "object_id": "rMTX7iq2RGy6ELcm91bcLA"
    }
  ],
  "highest_watermark": "2024-04-25T07:51:30Z"
}

Status: 400 HTTP Status Code: `400` Bad Request Error Code: `300` Invalid field. Error Code: `6002` The query time from cannot be greater than to. Error Code: `6003` The time range of the query from and to exceeds one month.

Status: 401 HTTP Status Code: `401` Unauthorized Error Code: `124` Invalid access token. Error Code: `124` Access token has expired. Error Code: `1002` The user associated with this access token was not found or is invalid.

Status: 403 HTTP Status Code: `403` Forbidden Error Code: `9001` The Contact Center user associated with this bearer token is missing privileges on their role required to operate this request. Error Code: `1021` User account is deactivated. Error Code: `1022` User does not have a Contact Center license.

Status: 429 HTTP Status Code: `429` Too Many Requests. For more information, see [rate limits](/docs/api/rest/rate-limits/). Error Code: `4001` You have reached the maximum per-second rate limit for this API. Try again later.

List roles

Method: GET
Path: /contact_center/roles
Tags: Roles

Use this API to return a list of roles.

Scopes: contact_center_role:read:admin

Granular Scopes: contact_center:read:list_roles:admin

Rate Limit Label: MEDIUM

Responses

Status: 200 HTTP Status Code: `200` Role list returned.

Content-Type: application/json

next_page_token

string — The next page token is used to paginate through large result sets. A next page token will be returned whenever the set of available results exceeds the current page size. The expiration period for this token is 15 minutes.
page_size

integer, default: 30 — The number of records returned within a single API call.
roles

array — Information about user roles.

Items:
- last_modified_time
  
  string, format: date-time — The date and time at which the role was last modified.
- modified_by
  
  string — The ID of the user who last modified the role.
- role_description
  
  string — The role's description.
- role_id
  
  string — The role's ID.
- role_name
  
  string — The role's name.
- total_users
  
  integer — Number of users with the role.
total_records

integer — The total number of all the records available across pages.

Example:

{
  "next_page_token": "R4aF9Oj0fVM2hhezJTEmSKaBSkfesDwGy42",
  "page_size": 30,
  "total_records": 1,
  "roles": [
    {
      "role_id": "-7uu_aUQRL-zXybozrSBWw",
      "role_name": "Agent",
      "role_description": "Agent role.",
      "total_users": 3,
      "modified_by": "IGTRVt3gQ2i-WjoUIjeZxw",
      "last_modified_time": "2022-03-03T05:07:46Z"
    }
  ]
}

Status: 400 HTTP Status Code: `400` Bad Request

Status: 429 HTTP Status Code: `429` Too Many Requests. For more information, see [rate limits](https://developers.zoom.us/docs/api/rest/rate-limits/).

Create a role

Method: POST
Path: /contact_center/roles
Tags: Roles

Create a new role. Admins can use the role management feature to control access to features and settings in the Zoom web portal.

Scopes: contact_center_role:write:admin

Granular Scopes: contact_center:write:role:admin

Rate Limit Label: LIGHT

Request Body

Content-Type: application/json

privileges

array — Any one or more of [these privileges](/docs/api/references/contact-center-privileges/) assigned to the role.

Items:

string
role_description

string — The role's description.
role_name

string — The user role's name.

Example:

{
  "role_name": "Agent",
  "role_description": "Agent role.",
  "privileges": [
    "UserManagement:Read"
  ]
}

Responses

Status: 201 HTTP Status Code: `201` Role created.

Content-Type: application/json

privileges

object — Any one or more of [these privileges](/docs/api/references/contact-center-privileges/) assigned to the role.
- administration_settings
  
  array
  
  Items:
  
  string
- analytics_settings
  
  array
  
  Items:
  
  string
- general_settings
  
  array
  
  Items:
  
  string
role_description

string — The role's description.
role_id

string — The role's ID.
role_name

string — The role's name.

Example:

{
  "role_id": "zeYjXoDOS_eV1QmTpj63PQ",
  "role_name": "Agent",
  "role_description": "Agent role.",
  "privileges": {
    "analytics_settings": [
      "RptWallboard:Read"
    ],
    "administration_settings": [
      "UserManagement:Read"
    ],
    "general_settings": [
      "OutboundVoiceCall"
    ]
  }
}

Status: 400 HTTP Status Code: `400` Bad Request Error Code: `2203` The role name already exists. Please change to a new one. Error Code: `300` Validation failed. Error Code: `2207` Invalid role privileges: $privileges.

Status: 429 HTTP Status Code: `429` Too Many Requests. For more information, see [rate limits](/docs/api/rate-limits/).

Duplicate a role

Method: POST
Path: /contact_center/roles/duplicate
Tags: Roles

Duplicate the role specified by the original role name and assign it a new name. All settings, permissions, and configurations of the original role will be copied to the new role.

Scopes: contact_center_role:write:admin

Granular Scopes: contact_center:write:role:admin

Rate Limit Label: LIGHT

Request Body

Content-Type: application/json

new_role_name

string — The new, duplicated role's name.
original_role_name

string — The name of the role to duplicate.

Example:

{
  "original_role_name": "Agent",
  "new_role_name": "Agent_Copy"
}

Responses

Status: 201 HTTP Status Code: `201` Role created.

Content-Type: application/json

role_description

string — The role's description.
role_id

string — The role's ID.
role_name

string — The role's name.

Example:

{
  "role_id": "zeYjXoDOS_eV1QmTpj63PQ",
  "role_name": "Agent_Copy",
  "role_description": "Agent role copy."
}

Status: 400 HTTP Status Code: `400` Bad Request Error Code: `2203` The role name already exists. Please change to a new one. Error Code: `300` Validation failed.

Status: 429 HTTP Status Code: `429` Too Many Requests. For more information, see [rate limits](/docs/api/rate-limits/).

Get a role

Method: GET
Path: /contact_center/roles/{roleId}
Tags: Roles

Get information about a role.

Scopes: contact_center_role:read:admin

Granular Scopes: contact_center:read:role:admin

Rate Limit Label: LIGHT

Responses

Status: 200 HTTP Status Code: `200` Role returned.

Content-Type: application/json

last_modified_time

string, format: date-time — The date and time when the role was last modified.
modified_by

string — The ID of the user who last modified the role.
privileges

object — Privileges assigned to the role. Can be one or more of [these permissions](/docs/api/references/contact-center-privileges/).
- administration_settings
  
  array
  
  Items:
  
  string — [These permissions](https://support.zoom.com/hc/en/article?id=zm_kb&sysparm_article=KB0061941#h_01GMEG7MDSBBXS4NSBME5617YX) control access to user and team management, as well as queue management, log management, etc. | Permission Name | Description | | --- | --- | | UserManagement:Read, UserManagement:Edit | Allow user to view and manage users. | | TeamManagement:Read, TeamManagement:Edit | Allow user to view and manage teams. | | RoleManagement:Read, RoleManagement:Edit | Allow user to view and manage roles. | | SkillManagement:Read, SkillManagement:Edit | Allow user to view and manage skills. | | InboxManagement:Read, InboxManagement:Edit | Allow user to view and manage inboxes. | | QueueManagement:Read, QueueManagement:Edit | Allow user to view and manage queues. | | NumberManagement:Read, NumberManagement:Edit | Allow user to view and manage numbers. | | RoutingProfileManagement:Read, RoutingProfileManagement:Edit | Allow user to view and manage routing profiles. | | DispositionManagement:Read, DispositionManagement:Edit | Allow user to view and manage dispositions. | | WaitingRoomManagement:Read, WaitingRoomManagement:Edit | Allow user to view and manage waiting rooms. | | FlowManagement:Read, FlowManagement:Edit | Allow user to view and manage flows in flow editor. | | PreferenceManagement:Read, PreferenceManagement:Edit | Allow user to view and manage account preferences. | | AddressBookManagement:Read, AddressBookManagement:Edit | Allow user to view and manage address books. | | AddressCustomFieldManagement:Read, AddressCustomFieldManagement:Edit | Allow user to view and manage address book custom fields. | | CampaignManagement:Read, CampaignManagement:Edit | Allow user to view and manage web campaigns. | | IntegrationManagement:Read, IntegrationManagement:Edit | Allow user to view and manage integrations. | | RoutingEngineManagement:Read, RoutingEngineManagement:Edit | Allow user to view Routing Engine console. | | LogManagement:Read | Allow user to view and manage logs. | | EngagementLogManagement:Read | Allow user to view the engagement log. | | EngagementLogExport:Edit | Allow user to export engagement log data. | | EngagementLogErasePII:Edit | Allow user to erase personal information in the engagement log. | | VoiceCallLogManagement:Read | Allow user to view the voice calls log. | | VoiceCallLogExport:Edit | Allow user to export voice calls log data. | | SMSLogManagement:Read | Allow user to view the SMS log. | | SMSLogExport:Edit | Allow user to export SMS log data. | | RecordingsLogManagement:Read | Allow user to view the recordings log. | | RecordingsLogExport:Edit | Allow user to export recordings log data. | | VariablesLogManagement:Read | Allow user to view the variables log. | | VariablesLogExport:Edit | Allow user to export variables log data. | | VariablesLogDelete:Edit | Allow user to permanently delete engagement variables. | | VoiceRecordingAccess:Read | Allow user to view list of Cobrowse recordings. | | RecordingPlay:Edit | Allow user to play voice, video and messaging Cobrowse recordings. | | VoiceRecordingDownload:Edit | Allow user to download voice, video and messaging Cobrowse recordings. | | VoiceRecordingDelete:Edit | Allow user to delete voice, video and messaging Cobrowse recordings. | | VoiceDataRetentionExemption:Edit | Allow user to manage data retention exemption for recordings. |
- analytics_settings
  
  array
  
  Items:
  
  string — [These permissions](https://support.zoom.com/hc/en/article?id=zm_kb&sysparm_article=KB0061941#h_01FWHA20K7CF310WJB29QXMNKC) control access to various analytics and reporting features, including real-time analytics, historical reports, and user activity tracking. | Privileges | Description | | :------ | :------ | | `RptMyAgents:Read` | Allow user to view the status of agents. | | `RptQueueAnalytics:Read` | Allow user to view real-time charts. | | `RptQueueAnalyticsOverview:Read` | Allow user to view overview data for all channels. | | `RptActiveChannelEngagements:Read` | Allow user to view active engagements for each channel. | | `RptWallboard:Read` | Allow user to view wallboards. | | `RptWallboard:Edit` | Allow user to add new wallboard views, duplicate existing ones and edit them. | | `RptWallboardShare:Edit` | Allow user to share the wallboard views they create. | | `RptAgentReport:Read` | Allow user to view agent’s timesheets. | | `RptAgentReportOverview:Read` | Allow user to view overview data for all channels. | | `RptAgentReportExport:Edit` | Allow user to export agent time sheet data. | | `RptQueueChartReport:Read` | Allow user to view historical queue charts. | | `RptQueueChartReportOverView:Read` | Allow user to view overview data for all channels. | | `RptQueueChartReportExport:Edit` | Allow user to export queue chart data. | | `RptQueueDetailReport:Read` | Allow user to view historical queue details. | | `RptQueueDetailReportExport:Edit` | Allow user to export queue detail data. | | `RptQueueIntervalReport:Read` | Allow user to view the interval report. | | `RptQueueIntervalReportExport:Edit` | Allow user to export interval report data | | `RptFlowChartReport:Read` | Allow user to view the flow chart report. | | `RptFlowChartReportExport:Edit` | Allow user to export flow chart data. | | `RptFlowDetailReport:Read` | Allow user to view the flow detail report. | | `RptFlowDetailReportExport:Edit` | Allow user to export flow detail data. | | `RptSurvey:Read` | Allow user to view the consumer engagement surveys report. | | `RptSurveyExport:Edit` | Allow user to export engagement survey results. | | `RptSubscriptions:Read` | Allow user to create or view subscriptions. | | `RptCustomReports:Read` | Allow user to view existing reports (including default reports). | | `RptCustomReports:Edit` | Allow user to create and duplicate reports. | | `RptCustomReportsShare:Edit` | Allow user to share default and custom reports with your organization. | | `RptCustomReportsExport:Edit` | Allow user to export default and custom reports. | | `RptCustomReportsSchedule:Edit` | Allow user to schedule default and custom reports. | | `RptLogs:Read` | Allow user to view the logs. | | `RptLogsExport:Edit` | Allow user to export logs. | | `RptLogsErasePII:Edit` | Allow user to erase personal information in the engagement log. | | `RptDashboards:Read` | Allow user to view existing dashboards (including default dashboards). | | `RptDashboards:Edit` | Allow user to create and duplicate dashboards. | | `RptDashboardsShare:Edit` | Allow user to share custom dashboards. | | `RptContactCenter:Read` | Allow user to view the contact center usage report. | | `RptContactCenterExport:Edit` | Allow user to export contact center usage report data. | | `RptContactCenterOperationLog:Read` | Allow user to view the contact center operation log. | | `RptContactCenterOperationLogExport:Edit` | Allow user to export operation log data. |
- general_settings
  
  array
  
  Items:
  
  string — [These permissions](https://support.zoom.com/hc/en/article?id=zm_kb&sysparm_article=KB0061941#h_01FWHA20K7CF310WJB29QXMNKC) control access to start various types of outbound engagements, engagement features, client customization features, etc. | Permission Name | Description | | --- | --- | | OutboundVoiceCall | Allow user to start a new outbound voice engagement to consumer(s). | | OutboundVideoCall | Allow user to start a new outbound video engagement to consumer(s). | | OutboundSMS | Allow user to start a new outbound messaging engagement to consumer(s). | | OutboundEmail | Allow user to start a new outbound email engagement to consumer(s). | | QueueOptInOut | Allow user to opt in or out of their assigned queues. | | OtherUserQueueOpt | Allow user to opt other users in or out of their assigned queues. | | ChangeUserStatus | Allow user to change the Ready/Not Ready status of other users. | | ContactManagement | Allow user to add or edit contacts information in the client. | | VoicemailManagement | Allow user to view and manage the voicemails. | | VoicemailPlay | Allow user to play voicemails. | | VoicemailDownload | Allow user to download voicemails. | | VoicemailAssign | Allow user to assign voicemail to others. | | VoicemailDelete | Allow user to delete voicemails. | | OwnCallRecordingView | Allow user to view and play their own voice, video and messaging Cobrowse recordings. | | MessagingTranscript | Allow user to access the list of messaging transcript. | | MessagingTranscriptDelete | Allow user to delete messaging transcript. | | MessagingTranscriptDownload | Allow user to download messaging transcript. | | EmailTranscript | Allow user to access the list of email transcript. | | EmailTranscriptDelete | Allow user to delete email transcript. | | EmailTranscriptDownload | Allow user to download email transcript. | | ConsumerHistory | Allow user to view consumer history under profile in the client. | | EngagementNote | Allow user to add or edit notes while in an engagement. | | FileShare | Allow user to send and receive files in messaging and email engagements. | | EngagementUpgrade | Allow user to upgrade engagements to voice or video calls. | | ChatToVoiceUpgrade | Allow user to upgrade engagements to voice from Chat(web). | | FacebookToVoiceUpgrade | Allow user to upgrade engagements to voice from Facebook Messenger. | | SMSToVoiceUpgrade | Allow user to upgrade engagements to voice from SMS. | | WhatsAppToVoiceUpgrade | Allow user to upgrade engagements to voice from WhatsApp. | | InstagramToVoiceUpgrade | Allow user to upgrade engagements to voice from Instagram. | | TeamChatToVoiceUpgrade | Allow user to upgrade engagements to voice from Zoom Team Chat. | | ChatToVideoUpgrade | Allow user to upgrade engagements to video from Chat(web). | | FacebookToVideoUpgrade | Allow user to upgrade engagements to video from Facebook Messenger. | | SMSToVideoUpgrade | Allow user to upgrade engagements to video from SMS. | | VoiceToVideoUpgrade | Allow user to upgrade engagements to video from Voice. | | WhatsAppToVideoUpgrade | Allow user to upgrade engagements to video from WhatsApp. | | InstagramToVideoUpgrade | Allow user to upgrade engagements to video from Instagram. | | TeamChatToVideoUpgrade | Allow user to upgrade engagements to video from Zoom Team Chat. | | VideoOnHold | Allow user to put video on hold. | | EngagementTransfer | Allow user to transfer engagements to queues, flows and/or agents. | | CobrowseSession | Allow user to start Cobrowse sessions during voice and web chat engagements. | | WaitingRoomVideoDropIn | Allow user to talk with consumers on video while they’re in the waiting room. | | WaitingRoomVideoChat | Allow user to chat with consumers on engagements while they wait. | | EngagementListen | Allow user to listen in on engagements assigned to other agents. | | EngagementWhisper | Allow user to whisper into engagements assigned to other agents. | | EngagementBarge | Allow user to barge in on engagements assigned to other agents. | | EngagementTakeover | Allow user to take over engagements assigned to other agents. | | ActiveEngagements | Allow user to view and use Open engagements in the client. | | ScheduledEngagements | Allow user to view and use Scheduled engagements in the client. | | CompletedEngagements | Allow user to view and use Closed engagements in the client. | | TeamTab | Allow user to view and use the Teams tab in the client. | | AddressBookTab | Allow user to view and use the Address book tab in the client. | | InboxTab | Allow user to view and use the Inbox tab in the client. | | AnalyticsTab | Allow user to view and use the Analytics tab in the client. |
role_description

string — The role's description.
role_id

string — The role's ID.
role_name

string — The role's name.
total_users

integer — The number of users with the role.

Example:

{
  "role_id": "zeYjXoDOS_eV1QmTpj63PQ",
  "role_name": "Agent",
  "role_description": "Agent role.",
  "total_users": 3,
  "modified_by": "IGTRVt3gQ2i-WjoUIjeZxw",
  "last_modified_time": "2022-03-03T05:07:46Z",
  "privileges": {
    "analytics_settings": [
      "RptWallboard:Read"
    ],
    "administration_settings": [
      "VecUser:Read"
    ],
    "general_settings": [
      "outbound-voice-call"
    ]
  }
}

Status: 400 HTTP Status Code: `400` Bad Request Error Code: `2210` More than one matching role found.

Status: 401 HTTP Status Code: `401` Unauthorized Error Code: `124` Invalid access token. Error Code: `124` Access token has expired. Error Code: `1002` The user associated with this access token was not found or is invalid.

Status: 403 HTTP Status Code: `403` Forbidden Error Code: `1021` User account is deactivated. Error Code: `1022` User does not have a Contact Center license. Error Code: `9001` The Contact Center user associated with this bearer token is missing privileges on their role required to operate this request.

Status: 404 HTTP Status Code: `404` Not Found Error Code: `2201` Role does not exist.

Status: 429 HTTP Status Code: `429` Too Many Requests. For more information, see [rate limits](/docs/api/rate-limits/). Error Code: `4001` You have reached the maximum per-second rate limit for this API. Try again later.

Delete a role

Method: DELETE
Path: /contact_center/roles/{roleId}
Tags: Roles

Delete a role.

Scopes: contact_center_role:write:admin

Granular Scopes: contact_center:delete:role:admin

Rate Limit Label: LIGHT

Responses

Status: 204 HTTP Status Code: `204` Role deleted.

Status: 400 HTTP Status Code: `400` Bad Request Error Code: `2102` Transfer role ID cannot be empty. Error Code: `2210` More than one matching role found.

Status: 404 HTTP Status Code: `404` Not Found Error Code: `2201` Role does not exist.

Status: 429 HTTP Status Code: `429` Too Many Requests. For more information, see [rate limits](/docs/api/rate-limits/).

Update a role

Method: PATCH
Path: /contact_center/roles/{roleId}
Tags: Roles

Update a role.

Scopes: contact_center_role:write:admin

Granular Scopes: contact_center:update:role:admin

Rate Limit Label: LIGHT

Request Body

Content-Type: application/json

privileges

array — One or more of [these privileges](/docs/api/references/contact-center-privileges/) assigned to the role.

Items:

string
role_description

string — The role's description. **Note:** The Admin, Agent, and Supervisor roles do not support modification.
role_name

string — The role's name.

Example:

{
  "role_name": "Agent",
  "role_description": "Agent role.",
  "privileges": [
    "UserManagement:Read"
  ]
}

Responses

Status: 204 HTTP Status Code: `204` Role updated.

Status: 400 HTTP Status Code: `400` Bad Request Error Code: `2203` The role name already exists. Please change to a new one. Error Code: `2204` Administrator|Supervisor|Agent role name cannot be updated. Error Code: `2207` Invalid role privileges: $privileges. Error Code: `2210` More than one matching role found.

Status: 401 HTTP Status Code: `401` Unauthorized Error Code: `124` Invalid access token. Error Code: `124` Access token has expired. Error Code: `1002` The user associated with this access token was not found or is invalid.

Status: 403 HTTP Status Code: `403` Forbidden Error Code: `1021` User account is deactivated. Error Code: `1022` User does not have a Contact Center license. Error Code: `9001` The Contact Center user associated with this bearer token is missing privileges on their role required to operate this request.

Status: 404 HTTP Status Code: `404` Not Found Error Code: `2201` Role does not exist.

Status: 429 HTTP Status Code: `429` Too Many Requests. For more information, see [rate limits](https://developers.zoom.us/docs/api/rate-limits/). Error Code: `4001` You have reached the maximum per-second rate limit for this API. Try again later.

Delete role privileges

Method: DELETE
Path: /contact_center/roles/{roleId}/privileges
Tags: Roles

Removes the specified privileges from a role when given a valid role ID and privilege list.

Scopes: contact_center_role:write:admin

Granular Scopes: contact_center:delete:role:admin

Rate Limit Label: LIGHT

Request Body

Content-Type: application/json

privileges

array — Privileges assigned to the role. Can be one or more of [these privileges](https://developers.zoom.us/docs/api/references/contact-center-privileges/).

Items:

string

Example:

{
  "privileges": [
    "UserManagement:Read"
  ]
}

Responses

Status: 204 HTTP Status Code: `204` Role privileges deleted.

Status: 400 HTTP Status Code: `400` Bad Request Error Code: `2207` Invalid role privileges: $privileges. Error Code: `300` Validation failed.

Status: 404 HTTP Status Code: `404` Not Found Error Code: `2201` Role does not exist.

Status: 429 HTTP Status Code: `429` Too Many Requests. For more information, see [rate limits](https://developers.zoom.us/docs/api/rate-limits/).

List users of a role

Method: GET
Path: /contact_center/roles/{roleId}/users
Tags: Roles

Retrieve a list of users assigned to a Contact Center role.

Scopes: contact_center_role:read:admin

Granular Scopes: contact_center:read:list_role_users:admin

Rate Limit Label: MEDIUM

Responses

Status: 200 HTTP Status Code: `200` Role users list returned.

Content-Type: application/json

next_page_token

string — Use the next page token to paginate through large result sets. A next page token is returned whenever the set of available results exceeds the current page size. This token's expiration period is 15 minutes.
page_size

integer, default: 30 — The number of records returned in a single API call.
total_records

integer — The total number of all records available across pages.
users

array — Information about the role's assigned users.

Items:
- cc_user_id
  
  string — The Contact Center user identifier.
- display_name
  
  string — The user's display name.
- user_email
  
  string, format: email — The user's email address.
- user_id
  
  string — The Meetings user identifier.

Example:

{
  "next_page_token": "R4aF9Oj0fVM2hhezJTEmSKaBSkfesDwGy42",
  "page_size": 30,
  "total_records": 10,
  "users": [
    {
      "user_id": "IGTRVt3gQ2i-WjoUIjeZxw",
      "cc_user_id": "hKuMAiDdRlSwMkBxR5we7g",
      "display_name": "Jane Doe",
      "user_email": "jchill@example.com"
    }
  ]
}

Status: 400 HTTP Status Code: `400` Bad Request Error Code: `2210` More than one matching role found.

Status: 401 HTTP Status Code: `401` Unauthorized Error Code: `124` Invalid access token. Error Code: `124` Access token has expired. Error Code: `1002` The user associated with this access token was not found or is invalid.

Status: 403 HTTP Status Code: `403` Forbidden Error Code: `1021` User account is deactivated. Error Code: `1022` User does not have a Contact Center license. Error Code: `9001` The Contact Center user associated with this bearer token is missing privileges on their role required to operate this request.

Status: 404 HTTP Status Code: `404` Not Found Error Code: `2201` Role does not exist: {roleId}.

Status: 429 HTTP Status Code: `429` Too Many Requests. For more information, see [rate limits](https://developers.zoom.us/docs/api/rate-limits/). Error Code: `4001` You have reached the maximum per-second rate limit for this API. Try again later.

Assign a role

Method: POST
Path: /contact_center/roles/{roleId}/users
Tags: Roles

Use this API to assign users to a role. Roles have unique privileges that assigned users have access to. For example, an Administrator or Agent role.

Scopes: contact_center_role:write:admin

Granular Scopes: contact_center:write:role_user:admin

Rate Limit Label: MEDIUM

Request Body

Content-Type: application/json

user_ids

array — The user identifiers. The values can be a mix of email addresses, Meetings user IDs, or Contact Center user IDs.

Items:

string

Example:

{
  "user_ids": [
    "ukAAkZKfROKMSw1bj_RDFQ"
  ]
}

Responses

Status: 201 HTTP Status Code: `201` Role assigned to user.

Content-Type: application/json

users

array — Information about the users.

Items:
- cc_user_id
  
  string — The Contact Center user identifier.
- display_name
  
  string — The user's display name.
- user_email
  
  string, format: email — The user's email address.
- user_id
  
  string — The Meetings user identifier.

Example:

{
  "users": [
    {
      "user_id": "IGTRVt3gQ2i-WjoUIjeZxw",
      "cc_user_id": "hKuMAiDdRlSwMkBxR5we7g",
      "display_name": "Jane Doe",
      "user_email": "jchill@example.com"
    }
  ]
}

Status: 400 HTTP Status Code: `400` Bad Request Error Code: `300` Validation failed.

Status: 401 HTTP Status Code: `401` Unauthorized Error Code: `124` Invalid access token. Error Code: `124` Access token has expired. Error Code: `1002` The user associated with this access token was not found or is invalid.

Status: 403 HTTP Status Code: `403` Forbidden Error Code: `1021` User account is deactivated. Error Code: `1022` User does not have a Contact Center license. Error Code: `9001` The Contact Center user associated with this bearer token is missing privileges on their role required to operate this request.

Status: 404 HTTP Status Code: `404` Not Found Error Code: `2201` Role does not exist: {roleId}.

Status: 429 HTTP Status Code: `429` Too Many Requests. For more information, see [rate limits](https://developers.zoom.us/docs/api/rate-limits/). Error Code: `4001` You have reached the maximum per-second rate limit for this API. Try again later.

Unassign a user from a role

Method: DELETE
Path: /contact_center/roles/{roleId}/users/{userId}
Tags: Roles

Remove a specific user from a Contact Center role. This operation removes the role-user assignment, meaning the user will no longer have the permissions and privileges associated with this role. The user must currently be assigned to the specified role. Both the role and user must exist in the account.

Scopes: contact_center_role:write:admin

Granular Scopes: contact_center:delete:role_user:admin

Rate Limit Label: LIGHT

Responses

Status: 204 HTTP Status Code: `204` The user was successfully removed from the role.

Status: 400 HTTP Status Code: `400` Bad Request Error Code: `300` The request is invalid or malformed.

Status: 401 HTTP Status Code: `401` Unauthorized Error Code: `124` Invalid access token. Error Code: `124` Access token has expired. Error Code: `1002` The user associated with this access token was not found or is invalid.

Status: 403 HTTP Status Code: `403` Forbidden Error Code: `1021` User account is deactivated. Error Code: `1022` User does not have a Contact Center license. Error Code: `9001` The Contact Center user associated with this bearer token is missing privileges on their role required to operate this request.

Status: 404 HTTP Status Code: `404` Not Found Error Code: `2201` Role does not exist: {roleId}. Error Code: `1001` User does not exist: {userId}.

Status: 429 HTTP Status Code: `429` Too Many Requests. For more information, see [rate limits](https://developers.zoom.us/docs/api/rate-limits/). Error Code: `4001` You have reached the maximum per-second rate limit for this API. Try again later.

List agent routing profiles

Method: GET
Path: /contact_center/agent_routing_profiles
Tags: Routing Profiles

Returns a list of agent routing profiles.

Scopes: contact_center_routing_profile:read:admin

Granular Scopes: contact_center:read:agent_routing_profile:admin

Rate Limit Label: MEDIUM

Responses

Status: 200 HTTP Status Code: `200` Agent routing profile list returned.

Content-Type: application/json

agent_routing_profiles

array — Information about the agent routing profiles.

Items:
- agent_routing_profile_description
  
  string — The agent routing profile's decription.
- agent_routing_profile_id
  
  string — The agent routing profile's ID.
- agent_routing_profile_name
  
  string — The agent routing profile's name.
- ignore_transferring_skills
  
  boolean, default: false — When transferred or in overflow, the routing system decides whether to ignore the skills in this routing profile.
- priorities
  
  array — The proficiency priority. The higher priority skill category - with proficiency based skills - takes precedence over those with lower priority. When comparing agents and all else is equal, the agents with the higher proficiency in the higher prioritized skill category should be considered for assignment.
  
  Items:
  - category_type (required)
    
    string, possible values: "skill", "intent" — The category's type. * `skill` - Skill category * `intent` - Intent group
  - backup_skills
    
    array — If customer's input skill or default skill doesn't match, agents with backup skills will be assigned to the engagement. It's only applied to accounts that have the **Agent Routing Profile Enhancement** feature enabled.
    
    Items:
    - backup_skill_id (required)
      
      string — The backup skill's ID
    - backup_skill_name
      
      string — The backup skill's name
    - minimum_proficiency_level
      
      integer — The skill's minimum proficiency level. **Note** Only applies to skill proficiency based skill categories. If minimum proficiency is set, agents must have a proficiency equal to or greater than the minimum proficiency value set. Only used when `category_type` is `skill`.
  - default_skill_id
    
    string — The default skill's ID. If customer doesn't input any skill, agents must have the default skill.
  - default_skill_name
    
    string — The default skill's name. If customer doesn't input any skill, agents must have the default skill.
  - intent_group_id
    
    string — The intent group's ID.
  - intent_group_name
    
    string — The intent group's name.
  - intent_group_required
    
    boolean — If an intent group is required, agents must have the corresponding intent or they will not be considered for assignment.
  - minimum_proficiency_level
    
    integer — The skill's minimum proficiency level. **Note** Only applies to skill proficiency based skill categories. If minimum proficiency is set, agents must have a proficiency equal to or greater than the minimum proficiency value set.
  - priority_id
    
    string — The priority's ID.
  - priority_order
    
    integer — **Note** This field's values are ordered and unique. This is the proficiency priority. The higher priority skill category - proficiency based skills - will take precedence over those with lower priority. When comparing agents and all else is equal, the agents with the higher proficiency in the higher prioritized skill category should be considered for assignment.
  - skill_category_id
    
    string — The skill category's ID.
  - skill_category_name
    
    string — The skill category's name.
  - skill_category_required
    
    boolean — If a skill category is required, agents must have the corresponding skill or they will not be considered for assignment.
  - skill_type
    
    string, possible values: "text", "proficiency" — The skill's type. Only applied when `category_type` is `skill`. * `text` - A text-based skill, such as a geographic location. Skills in this category do not have assigned skill levels. * `proficiency` - A proficiency-based skill, such as a second language. Skills in this category have assigned proficiency levels.
  - time_step
    
    integer — The time steps are using to divide queue wait time into intervals, in seconds. Each interval starts from the last time step to the current `time_step`. `-1` means the interval after the last time step. If there are two time steps, such as `10`, `-1`, it divides the queue wait time into two intervals: 0-10 seconds, and after 10 seconds. It's only applied to accounts that have the **Progressive Relaxation Routing Profile** feature enabled.
- time_steps
  
  array — Divide the queue wait time into intervals, in seconds. Each interval starst from last time step to current `time_step`. `-1` means the interval after the last time step. If the `time_step`s are [10, -1], it divides the queue wait time into two intervals: 0-10 seconds, after 10 seconds. It's only applied to accounts that have the **Progressive Relaxation Routing Profile** feature enabled.
  
  Items:
  
  integer — The time step, in seconds.
- wait_time_agent_in_seconds
  
  integer — Wait time for matched agent availability, in seconds. Set the minimum time before making an agent who matches the profile available for the queue.
next_page_token

string — Use the next page token to paginate through large result sets. A next page token is returned whenever the set of available results exceeds the current page size. This token's expiration period is 15 minutes.
page_size

integer, default: 30 — The number of records returned within a single API call.
total_records

integer — The total number of all the records available across pages.

Example:

{
  "next_page_token": "R4aF9Oj0fVM2hhezJTEmSKaBSkfesDwGy42",
  "page_size": 30,
  "total_records": 10,
  "agent_routing_profiles": [
    {
      "agent_routing_profile_id": "pkOWR9aiR1WLvyDJCBi06A",
      "agent_routing_profile_name": "My agent routing profile",
      "agent_routing_profile_description": "This is the agent routing profile's description.",
      "wait_time_agent_in_seconds": 10,
      "priorities": [
        {
          "priority_id": "jyuhjknkjgfkjhh9453fjdlg",
          "priority_order": 1,
          "category_type": "skill",
          "skill_category_id": "skill_category_id",
          "intent_group_id": "intent_group_id",
          "skill_category_name": "skill_category_name",
          "intent_group_name": "intent_group_name",
          "skill_type": "proficiency",
          "minimum_proficiency_level": 2,
          "skill_category_required": true,
          "intent_group_required": false,
          "default_skill_id": "sRrl8f3IKQp_LByU08Ibi6g",
          "default_skill_name": "default_skill__name",
          "time_step": 10,
          "backup_skills": [
            {
              "backup_skill_id": "sk_OpAInMSpGwbwzkbGz6sQ",
              "backup_skill_name": "backup_skill_name",
              "minimum_proficiency_level": 3
            }
          ]
        }
      ],
      "time_steps": [
        10
      ],
      "ignore_transferring_skills": false
    }
  ]
}

Status: 429 HTTP Status Code: `429` Too Many Requests. For more information, see [rate limits](/docs/api/rate-limits/).

Create an agent routing profile

Method: POST
Path: /contact_center/agent_routing_profiles
Tags: Routing Profiles

Create an agent routing profile.

Scopes: contact_center_routing_profile:write:admin

Granular Scopes: contact_center:write:agent_routing_profile:admin

Rate Limit Label: LIGHT

Request Body

Content-Type: application/json

agent_routing_profile_name (required)

string — The agent routing profile's name.
agent_routing_profile_description

string — The agent routing profile's description.
ignore_transferring_skills

boolean, default: false — When transferred or in overflow, the routing system decides whether to ignore the skills in this routing profile.
priorities

array — The proficiency priority. The higher priority skill category - with proficiency based skills - takes precedence over those with lower priority. When comparing agents and all else is equal, the agents with the higher proficiency in the higher prioritized skill category should be considered for assignment.

Items:
- category_type (required)
  
  string, possible values: "skill", "intent" — The category's type. * `skill` - Skill category * `intent` - Intent group
- backup_skills
  
  array — If customer's input skill or default skill doesn't match, agents with backup skills will be assigned to the engagement. Only applied to accounts that have the **Agent Routing Profile Enhancement** feature enabled.
  
  Items:
  - backup_skill_id (required)
    
    string — The backup skill's ID
  - minimum_proficiency_level
    
    integer — The skill's minimum proficiency level. **Note** Only applies to skill proficiency based skill categories. If minimum proficiency is set, agents must have a proficiency equal to or greater than the minimum proficiency value set. Only used when `category_type` is `skill`.
- default_skill_id
  
  string — If customer doesn't input any skill, agents must have the default skill.
- intent_group_id
  
  string — The intent group's ID. Required when `category_type` is `intent`.
- intent_group_required
  
  boolean — If an intent group is required, agents must have the corresponding intent or they will not be considered for assignment. Required when `category_type` is `intent`.
- minimum_proficiency_level
  
  integer, default: 0 — The skill's minimum proficiency level. **Note** Only applies to skill proficiency based skill categories. If minimum proficiency is set, agents must have a proficiency equal to or greater than the minimum proficiency value set. Only used when `category_type` is `skill`.
- skill_category_id
  
  string — The skill category's ID. Required when `category_type` is `skill`.
- skill_category_required
  
  boolean — If a category is required, agents must have the corresponding skill or they will not be considered for assignment. Required when `category_type` is `skill`.
- time_step
  
  integer — Divides the queue wait time into intervals, in seconds. Each interval starts from the last time step to the current `time_step`. `-1` means the interval after the last time step. If there are two time steps `10`, `-1`, it divides the queue wait time into two intervals: 0-10 seconds, and after 10 seconds. It's only applied to accounts that have the **Progressive Relaxation Routing Profile** feature enabled.
time_steps

array — The time steps are using to divide queue wait time into intervals, in seconds. Each interval will start from last time step to current `time_step`. `-1` means the interval after the last time step. If the `time_steps` are [10, -1], it will divide queue wait time into two intervals: 0-10 seconds, and after 10 seconds. It's only applied to account with the `Progressive Relaxation Routing Profile` feature enabled.

Items:

integer — The time step, in seconds.
wait_time_agent_in_seconds

integer, default: 3 — Wait time for matched agent availability, in seconds. Set the minimum time before making an agent who matches the profile available for the queue.

Example:

{
  "agent_routing_profile_name": "My agent routing profile",
  "agent_routing_profile_description": "This is the agent routing profile's description.",
  "wait_time_agent_in_seconds": 10,
  "priorities": [
    {
      "category_type": "skill",
      "skill_category_id": "skill_category_id",
      "intent_group_id": "intent_group_id",
      "minimum_proficiency_level": 2,
      "skill_category_required": true,
      "intent_group_required": false,
      "default_skill_id": "sRrl8f3IKQp_LByU08Ibi6g",
      "time_step": 10,
      "backup_skills": [
        {
          "backup_skill_id": "sk_OpAInMSpGwbwzkbGz6sQ",
          "minimum_proficiency_level": 3
        }
      ]
    }
  ],
  "time_steps": [
    10
  ],
  "ignore_transferring_skills": false
}

Responses

Status: 201 HTTP Status Code: `201` Agent routing profile created.

Content-Type: application/json

agent_routing_profile_description

string — The agent routing profile's decription.
agent_routing_profile_id

string — The agent routing profile's ID.
agent_routing_profile_name

string — The agent routing profile's name.
ignore_transferring_skills

boolean, default: false — When transferred or in overflow, the routing system decides whether to ignore the skills in this routing profile.
priorities

array — The proficiency priority. The higher priority skill category - with proficiency based skills - takes precedence over those with lower priority. When comparing agents and all else is equal, the agents with the higher proficiency in the higher prioritized skill category should be considered for assignment.

Items:
- category_type (required)
  
  string, possible values: "skill", "intent" — The category's type. * `skill` - Skill category * `intent` - Intent group
- backup_skills
  
  array — If customer's input skill or default skill doesn't match, agents with backup skills will be assigned to the engagement. It's only applied to accounts that have the **Agent Routing Profile Enhancement** feature enabled.
  
  Items:
  - backup_skill_id (required)
    
    string — The backup skill's ID
  - backup_skill_name
    
    string — The backup skill's name
  - minimum_proficiency_level
    
    integer — The skill's minimum proficiency level. **Note** Only applies to skill proficiency based skill categories. If minimum proficiency is set, agents must have a proficiency equal to or greater than the minimum proficiency value set. Only used when `category_type` is `skill`.
- default_skill_id
  
  string — The default skill's ID. If customer doesn't input any skill, agents must have the default skill.
- default_skill_name
  
  string — The default skill's name. If customer doesn't input any skill, agents must have the default skill.
- intent_group_id
  
  string — The intent group's ID.
- intent_group_name
  
  string — The intent group's name.
- intent_group_required
  
  boolean — If an intent group is required, agents must have the corresponding intent or they will not be considered for assignment.
- minimum_proficiency_level
  
  integer — The skill's minimum proficiency level. **Note** Only applies to skill proficiency based skill categories. If minimum proficiency is set, agents must have a proficiency equal to or greater than the minimum proficiency value set.
- priority_id
  
  string — The priority's ID.
- priority_order
  
  integer — **Note** This field's values are ordered and unique. This is the proficiency priority. The higher priority skill category - proficiency based skills - will take precedence over those with lower priority. When comparing agents and all else is equal, the agents with the higher proficiency in the higher prioritized skill category should be considered for assignment.
- skill_category_id
  
  string — The skill category's ID.
- skill_category_name
  
  string — The skill category's name.
- skill_category_required
  
  boolean — If a skill category is required, agents must have the corresponding skill or they will not be considered for assignment.
- skill_type
  
  string, possible values: "text", "proficiency" — The skill's type. Only applied when `category_type` is `skill`. * `text` - A text-based skill, such as a geographic location. Skills in this category do not have assigned skill levels. * `proficiency` - A proficiency-based skill, such as a second language. Skills in this category have assigned proficiency levels.
- time_step
  
  integer — The time steps are using to divide queue wait time into intervals, in seconds. Each interval starts from the last time step to the current `time_step`. `-1` means the interval after the last time step. If there are two time steps, such as `10`, `-1`, it divides the queue wait time into two intervals: 0-10 seconds, and after 10 seconds. It's only applied to accounts that have the **Progressive Relaxation Routing Profile** feature enabled.
time_steps

array — The time steps are using to divide queue wait time into intervals, in seconds. Each interval starts from the last time step to the current `time_step`. `-1` means the interval after the last time step. If the `time_steps` are [10, -1], it divides the queue wait time into two intervals: 0-10 seconds, after 10 seconds. It's only applied to account with the `Progressive Relaxation Routing Profile` feature enabled.

Items:

integer — The time step, time unit: seconds.
wait_time_agent_in_seconds

integer — Wait time for matched agent availability, in seconds. Set the minimum time before making an agent who matches the profile available for the queue.

Example:

{
  "agent_routing_profile_id": "pkOWR9aiR1WLvyDJCBi06A",
  "agent_routing_profile_name": "My agent routing profile",
  "agent_routing_profile_description": "This is the agent routing profile's description.",
  "wait_time_agent_in_seconds": 10,
  "priorities": [
    {
      "priority_id": "jyuhjknkjgfkjhh9453fjdlg",
      "priority_order": 1,
      "category_type": "skill",
      "skill_category_id": "skill_category_id",
      "intent_group_id": "intent_group_id",
      "skill_category_name": "skill_category_name",
      "intent_group_name": "intent_group_name",
      "skill_type": "proficiency",
      "minimum_proficiency_level": 2,
      "skill_category_required": true,
      "intent_group_required": false,
      "default_skill_id": "sRrl8f3IKQp_LByU08Ibi6g",
      "default_skill_name": "default_skill__name",
      "time_step": 10,
      "backup_skills": [
        {
          "backup_skill_id": "sk_OpAInMSpGwbwzkbGz6sQ",
          "backup_skill_name": "backup_skill_name",
          "minimum_proficiency_level": 3
        }
      ]
    }
  ],
  "time_steps": [
    10
  ],
  "ignore_transferring_skills": false
}

Status: 400 HTTP Status Code: `400` Bad Request Error Code: `4004` Category doesn't exist. Error Code: `4005` Number of priorities exceeds the maximum limit. Error Code: `4006` Category is duplicated in priorities. Error Code: `300` Missing required parameter.

Status: 409 HTTP Status Code: `409` Conflict Agent routing profile's name already exists.

Status: 429 HTTP Status Code: `429` Too Many Requests. For more information, see [rate limits](/docs/api/rate-limits/).

Get an agent routing profile

Method: GET
Path: /contact_center/agent_routing_profiles/{agentRoutingProfileId}
Tags: Routing Profiles

Retrieve the agent routing profile.

Scopes: contact_center_routing_profile:read:admin

Granular Scopes: contact_center:read:agent_routing_profile:admin

Rate Limit Label: LIGHT

Responses

Status: 200 HTTP Status Code: `200` Agent routing profile returned.

Content-Type: application/json

agent_routing_profile_description

string — The agent routing profile's description.
agent_routing_profile_id

string — The agent routing profile's ID.
agent_routing_profile_name

string — The agent routing profile's name.
ignore_transferring_skills

boolean, default: false — When transferred or in overflow, the routing system decides whether to ignore the skills in this routing profile.
priorities

array — The proficiency priority. The higher priority skill category - with proficiency based skills - takes precedence over those with lower priority. When comparing agents and all else is equal, the agents with the higher proficiency in the higher prioritized skill category should be considered for assignment.

Items:
- category_type (required)
  
  string, possible values: "skill", "intent" — The category's type. * `skill` - Skill category * `intent` - Intent group
- backup_skills
  
  array — If customer's input skill or default skill doesn't match, agents with backup skills will be assigned to the engagement. It's only applied to accounts that have the **Agent Routing Profile Enhancement** feature enabled.
  
  Items:
  - backup_skill_id (required)
    
    string — The backup skill's ID
  - backup_skill_name
    
    string — The backup skill's name
  - minimum_proficiency_level
    
    integer — The skill's minimum proficiency level. **Note** Only applies to skill proficiency based skill categories. If minimum proficiency is set, agents must have a proficiency equal to or greater than the minimum proficiency value set. Only used when `category_type` is `skill`.
- default_skill_id
  
  string — The default skill's ID. If customer doesn't input any skill, agents must have the default skill.
- default_skill_name
  
  string — The default skill's name. If customer doesn't input any skill, agents must have the default skill.
- intent_group_id
  
  string — The intent group's ID.
- intent_group_name
  
  string — The intent group's name.
- intent_group_required
  
  boolean — If an intent group is required, agents must have the corresponding intent or they will not be considered for assignment.
- minimum_proficiency_level
  
  integer — The skill's minimum proficiency level. **Note** Only applies to skill proficiency based skill categories. If minimum proficiency is set, agents must have a proficiency equal to or greater than the minimum proficiency value set.
- priority_id
  
  string — The priority's ID.
- priority_order
  
  integer — **Note** This field's values are ordered and unique. This is the proficiency priority. The higher priority skill category - proficiency based skills - will take precedence over those with lower priority. When comparing agents and all else is equal, the agents with the higher proficiency in the higher prioritized skill category should be considered for assignment.
- skill_category_id
  
  string — The skill category's ID.
- skill_category_name
  
  string — The skill category's name.
- skill_category_required
  
  boolean — If a skill category is required, agents must have the corresponding skill or they will not be considered for assignment.
- skill_type
  
  string, possible values: "text", "proficiency" — The skill's type. Only applied when `category_type` is `skill`. * `text` - A text-based skill, such as a geographic location. Skills in this category do not have assigned skill levels. * `proficiency` - A proficiency-based skill, such as a second language. Skills in this category have assigned proficiency levels.
- time_step
  
  integer — The time steps are using to divide queue wait time into intervals, in seconds. Each interval starts from the last time step to the current `time_step`. `-1` means the interval after the last time step. If there are two time steps, such as `10`, `-1`, it divides the queue wait time into two intervals: 0-10 seconds, and after 10 seconds. It's only applied to accounts that have the **Progressive Relaxation Routing Profile** feature enabled.
time_steps

array — The time steps used to divide queue wait time into intervals, in seconds. Each interval starts from the last time step to current `time_step`. `-1` means the interval after the last time step. If the `time_step`s are [10, -1], it divides the queue wait time into two intervals: 0-10 seconds, after 10 seconds. It's only applied to accounts that have the **Progressive Relaxation Routing Profile** feature enabled.

Items:

integer — The time step, in seconds.
wait_time_agent_in_seconds

integer — Wait time for matched agent availability, in seconds. Set the minimum time before making an agent who matches the profile available for the queue.

Example:

{
  "agent_routing_profile_id": "fgjdkhgfieryt7465435kjhdkhg",
  "agent_routing_profile_name": "My agent routing profile",
  "agent_routing_profile_description": "Example routing profile description.",
  "wait_time_agent_in_seconds": 10,
  "priorities": [
    {
      "priority_id": "jyuhjknkjgfkjhh9453fjdlg",
      "priority_order": 1,
      "category_type": "skill",
      "skill_category_id": "skill_category_id",
      "intent_group_id": "intent_group_id",
      "skill_category_name": "skill_category_name",
      "intent_group_name": "intent_group_name",
      "skill_type": "proficiency",
      "minimum_proficiency_level": 2,
      "skill_category_required": true,
      "intent_group_required": false,
      "default_skill_id": "sRrl8f3IKQp_LByU08Ibi6g",
      "default_skill_name": "default_skill__name",
      "time_step": 10,
      "backup_skills": [
        {
          "backup_skill_id": "sk_OpAInMSpGwbwzkbGz6sQ",
          "backup_skill_name": "backup_skill_name",
          "minimum_proficiency_level": 3
        }
      ]
    }
  ],
  "time_steps": [
    10
  ],
  "ignore_transferring_skills": false
}

Status: 400 HTTP Status Code: `400` Bad Request Error Code: `4007` More than one matching agent routing profile found.

Status: 401 HTTP Status Code: `401` Unauthorized Error Code: `124` Invalid access token. Error Code: `124` Access token has expired. Error Code: `1002` The user associated with this access token was not found or is invalid.

Status: 403 HTTP Status Code: `403` Forbidden Error Code: `1021` User account is deactivated. Error Code: `1022` User does not have a Contact Center license. Error Code: `9001` The Contact Center user associated with this bearer token is missing privileges on their role required to operate this request.

Status: 404 HTTP Status Code: `404` Not Found Agent routing profile does not exist.

Status: 429 HTTP Status Code: `429` Too Many Requests. For more information, see [rate limits](https://developers.zoom.us/docs/api/rate-limits/). Error Code: `4001` You have reached the maximum per-second rate limit for this API. Try again later.

Delete an agent routing profile

Method: DELETE
Path: /contact_center/agent_routing_profiles/{agentRoutingProfileId}
Tags: Routing Profiles

Delete an agent routing profile.

Scopes: contact_center_routing_profile:write:admin

Granular Scopes: contact_center:delete:agent_routing_profile:admin

Rate Limit Label: LIGHT

Responses

Status: 204 HTTP Status Code: `204` Agent routing profile deleted.

Status: 400 HTTP Status Code: `400` Bad Request Error Code: `4007` More than one matching agent routing profile found.

Status: 401 HTTP Status Code: `401` Unauthorized Error Code: `124` Invalid access token. Error Code: `124` Access token has expired. Error Code: `1002` The user associated with this access token was not found or is invalid.

Status: 403 HTTP Status Code: `403` Forbidden Error Code: `1021` User account is deactivated. Error Code: `1022` User does not have a Contact Center license. Error Code: `9001` The Contact Center user associated with this bearer token is missing privileges on their role required to operate this request.

Status: 404 HTTP Status Code: `404` Not Found Agent routing profileId doesn't exist.

Status: 429 HTTP Status Code: `429` Too Many Requests. For more information, see [rate limits](https://developers.zoom.us/docs/api/rate-limits/). Error Code: `4001` You have reached the maximum per-second rate limit for this API. Try again later.

Update an agent routing profile's details

Method: PATCH
Path: /contact_center/agent_routing_profiles/{agentRoutingProfileId}
Tags: Routing Profiles

Update an agent routing profile details.

Scopes: contact_center_routing_profile:write:admin

Granular Scopes: contact_center:update:agent_routing_profile:admin

Rate Limit Label: LIGHT

Request Body

Content-Type: application/json

agent_routing_profile_description

string — The agent routing profile's description.
agent_routing_profile_name

string — The agent routing profile's name.
ignore_transferring_skills

boolean, default: false — When transferred or in overflow, the routing system decides whether to ignore the skills in this routing profile.
priorities

array — The proficiency priority. The higher priority skill category - with proficiency based skills - takes precedence over those with lower priority. When comparing agents and all else is equal, the agents with the higher proficiency in the higher prioritized skill category should be considered for assignment.

Items:
- category_type (required)
  
  string, possible values: "skill", "intent" — The category's type. * `skill` - Skill category * `intent` - Intent group
- backup_skills
  
  array — If customer's input skill or default skill doesn't match, agents with backup skills will be assigned to the engagement. Only applied to accounts that have the **Agent Routing Profile Enhancement** feature enabled.
  
  Items:
  - backup_skill_id (required)
    
    string — The backup skill's ID
  - minimum_proficiency_level
    
    integer — The skill's minimum proficiency level. **Note** Only applies to skill proficiency based skill categories. If minimum proficiency is set, agents must have a proficiency equal to or greater than the minimum proficiency value set. Only used when `category_type` is `skill`.
- default_skill_id
  
  string — If customer doesn't input any skill, agents must have the default skill.
- intent_group_id
  
  string — The intent group's ID. Required when `category_type` is `intent`.
- intent_group_required
  
  boolean — If an intent group is required, agents must have the corresponding intent or they will not be considered for assignment. Required when `category_type` is `intent`.
- minimum_proficiency_level
  
  integer, default: 0 — The skill's minimum proficiency level. **Note** Only applies to skill proficiency based skill categories. If minimum proficiency is set, agents must have a proficiency equal to or greater than the minimum proficiency value set. Only used when `category_type` is `skill`.
- skill_category_id
  
  string — The skill category's ID. Required when `category_type` is `skill`.
- skill_category_required
  
  boolean — If a category is required, agents must have the corresponding skill or they will not be considered for assignment. Required when `category_type` is `skill`.
- time_step
  
  integer — Divides the queue wait time into intervals, in seconds. Each interval starts from the last time step to the current `time_step`. `-1` means the interval after the last time step. If there are two time steps `10`, `-1`, it divides the queue wait time into two intervals: 0-10 seconds, and after 10 seconds. It's only applied to accounts that have the **Progressive Relaxation Routing Profile** feature enabled.
time_steps

array — Divides the queue wait time into intervals, in seconds. Each interval starts from the last time step to the current `time_step`. `-1` means the interval after the last time step. If the `time_step`s are [10, -1], it divides the queue wait time into two intervals: 0-10 seconds, and after 10 seconds. It's only applied to accounts that have the **Progressive Relaxation Routing Profile** feature enabled.

Items:

integer — The time step, in seconds.
wait_time_agent_in_seconds

integer — Wait time for matched agent availability, in seconds. Set the minimum time before making an agent who matches the profile available for the queue.

Example:

{
  "agent_routing_profile_name": "My agent routing profile",
  "agent_routing_profile_description": "This is the agent routing profile's description.",
  "wait_time_agent_in_seconds": 10,
  "priorities": [
    {
      "category_type": "skill",
      "skill_category_id": "skill_category_id",
      "intent_group_id": "intent_group_id",
      "minimum_proficiency_level": 2,
      "skill_category_required": true,
      "intent_group_required": false,
      "default_skill_id": "sRrl8f3IKQp_LByU08Ibi6g",
      "time_step": 10,
      "backup_skills": [
        {
          "backup_skill_id": "sk_OpAInMSpGwbwzkbGz6sQ",
          "minimum_proficiency_level": 3
        }
      ]
    }
  ],
  "time_steps": [
    10
  ],
  "ignore_transferring_skills": false
}

Responses

Status: 204 HTTP Status Code: `204` Agent routing profile's details updated

Status: 400 HTTP Status Code: `400` Bad Request Error Code: `4004` Category doesn't exist. Error Code: `4005` Number of priorities exceeds maximum limit. Error Code: `4006` Category is duplicated in priorities. Error Code: `300` Missing required parameter. Error Code: `4007` More than one matching agent routing profile found.

Status: 401 HTTP Status Code: `401` Unauthorized Error Code: `124` Invalid access token. Error Code: `124` Access token has expired. Error Code: `1002` The user associated with this access token was not found or is invalid.

Status: 403 HTTP Status Code: `403` Forbidden Error Code: `1021` User account is deactivated. Error Code: `1022` User does not have a Contact Center license. Error Code: `9001` The Contact Center user associated with this bearer token is missing privileges on their role required to operate this request.

Status: 404 HTTP Status Code: `404` Not Found Agent routing profile doesn't exist.

Status: 409 HTTP Status Code: `409` Conflict Agent routing profile's name already exists.

Status: 429 HTTP Status Code: `429` Too Many Requests. For more information, see [rate limits](https://developers.zoom.us/docs/api/rate-limits/). Error Code: `4001` You have reached the maximum per-second rate limit for this API. Try again later.

List consumer routing profiles

Method: GET
Path: /contact_center/consumer_routing_profiles
Tags: Routing Profiles

Return a list of consumer routing profiles.

Scopes: contact_center_routing_profile:read:admin

Granular Scopes: contact_center:read:consumer_routing_profile:admin

Rate Limit Label: MEDIUM

Responses

Status: 200 HTTP Status Code: `200` Consumer routing profile list returned.

Content-Type: application/json

consumer_routing_profiles

array — Information about the consumer routing profiles.

Items:
- accumulated_priorities
  
  array — The consumers' accumulated priority. Use ratings to serve consumers from the highest to lowest value, from 100 to 1, based on a consumer attribute. Consumers accumulate priority while waiting in the queue, after top priority consumers.
  
  Items:
  - attribute_type (required)
    
    string, possible values: "address_book_contacts", "entrance_to_queue", "new_customer", "returning_customer", "release_to_queue", "skills", "address_book_variable", "global_variable" — The attribute's type. * `address_book_contacts` - Address book contacts * `entrance_to_queue` - Entrance to queue * `new_customer` - New customer * `returning_customer` - Returning customer * `release_to_queue` - Release to queue * `skills` - Skills * `address_book_variable` - Address book variable * `global_variable` - Global variable
  - incremental_rate (required)
    
    integer — The rate that consumers accumulate priority while waiting in line. For example, consumer A and consumer B have the same top priority. If consumer A.wait_time \* consumer A.`incremental_rate` > consumer B.wait_time \* consumer B.`incremental_rate`, consumer A will be first serviced.
  - parameter
    
    object — The parameter for priority's attribute. Parameter is different for each `attribute_type`: 1. `address_book_contacts` `parameter` = { `ids`: [`contanct1_id`, `contact2_id`] // address book contact ID list } 2. `entrance_to_queue` `parameter` = { `enter_queue_start_time`: `09:00 AM`, `enter_queue_end_time`: `11:00 PM`, `enter_queue_timezone`: `America/New_York` } 3. `new_customer` `parameter` = `null` 4. `returning_customer` `parameter` = { `max_returning_minutes`: `60` } 5. `release_to_queue` `parameter` = { `ids`: [`queue1_id`, `queue2_id`] // queue ID list } 6. `skills` `parameter` = { `ids`: [`skill1_id`, `skill2_id`] // skill ID list } 7. `address_book_variable` `parameter` = { `variable_id` = `address_book_variable_id`, `ids` = [`address_book_id1`, `address_book_id2`] // address book ID list `variable_values` = [`value1`, `value2`] } 8. `global_variable` `parameter` = { `variable_id` = `global_variable_id`, `operator` = `equal_to`, `compared_value` = `value` }
    - compared_value
      
      string — Compare the specified value to the variable's value. Only used when `attribute_type` is `global_variable`.
    - enter_queue_end_time
      
      string — The end time when the consumer enters the queue. Only used when `attribute_type` is `entrance_to_queue`.
    - enter_queue_start_time
      
      string — The start time when the consumer enters the queue. Only used when `attribute_type` is `entrance_to_queue`.
    - enter_queue_timezone
      
      string — The timezone when the consumer enters the queue.
    - ids
      
      array — The related entity ID list for priority's attribute. `address_book_contacts` IDs - Address book contact ID list `release_to_queue` IDs - Queue ID list `skills` IDs - Skill ID list. Should under the same skill category. `address_book_variable` IDs - Address book ID list
      
      Items:
      
      string
    - max_returning_minutes
      
      integer — Maximum number of minutes from last participation to now. Only used when `attribute_type` is `returning_customer`.
    - operator
      
      string, possible values: "equal_to", "greater_than", "less_than", "contains" — The operator between global variable and `compared_value`. Only used when `attribute_type` is `global_variable`.
    - variable_id
      
      string — The variable's ID. Only used when `attribute_type` is `global_variable` or `address_book_variable`.
    - variable_values
      
      array — The optional variable's values. If variable matches any of them, it will match the priority. Only used when `attribute_type` is `address_book_variable`.
      
      Items:
      
      string
- consumer_routing_profile_description
  
  string — The consumer routing profile's description.
- consumer_routing_profile_id
  
  string — The consumer routing profile's ID.
- consumer_routing_profile_name
  
  string — The consumer routing profile's name.
- top_priorities
  
  array — The consumers' top priority. Decide the consumer's position in the queue. The higher the consumer's priority, the earlier the consumer will be served.
  
  Items:
  - attribute_type (required)
    
    string, possible values: "address_book_contacts", "entrance_to_queue", "new_customer", "returning_customer", "release_to_queue", "skills", "address_book_variable", "global_variable" — The attribute's type. * `address_book_contacts` - Address book contacts * `entrance_to_queue` - Entrance to queue * `new_customer` - New customer * `returning_customer` - Returning customer * `release_to_queue` - Release to queue * `skills` - Skills * `address_book_variable` - Address book variable * `global_variable` - Global variable
  - parameter
    
    object — The parameter for priority's attribute. Parameter is different for each `attribute_type`: 1. `address_book_contacts` `parameter` = { `ids`: [`contanct1_id`, `contact2_id`] // address book contact ID list } 2. `entrance_to_queue` `parameter` = { `enter_queue_start_time`: `09:00 AM`, `enter_queue_end_time`: `11:00 PM`, `enter_queue_timezone`: `America/New_York` } 3. `new_customer` `parameter` = `null` 4. `returning_customer` `parameter` = { `max_returning_minutes`: `60` } 5. `release_to_queue` `parameter` = { `ids`: [`queue1_id`, `queue2_id`] // queue ID list } 6. `skills` `parameter` = { `ids`: [`skill1_id`, `skill2_id`] // skill ID list } 7. `address_book_variable` `parameter` = { `variable_id` = `address_book_variable_id`, `ids` = [`address_book_id1`, `address_book_id2`] // address book ID list `variable_values` = [`value1`, `value2`] } 8. `global_variable` `parameter` = { `variable_id` = `global_variable_id`, `operator` = `equal_to`, `compared_value` = `value` }
    - compared_value
      
      string — Compare the specified value to the variable's value. Only used when `attribute_type` is `global_variable`.
    - enter_queue_end_time
      
      string — The end time when the consumer enters the queue. Only used when `attribute_type` is `entrance_to_queue`.
    - enter_queue_start_time
      
      string — The start time when the consumer enters the queue. Only used when `attribute_type` is `entrance_to_queue`.
    - enter_queue_timezone
      
      string — The timezone when the consumer enters the queue. Only used when `attribute_type` is `entrance_to_queue`.
    - ids
      
      array — The related entity ID list for priority's attribute. `address_book_contacts` IDs - Address book contact ID list `release_to_queue` IDs - Queue ID list `skills` IDs - Skill ID list. Should under the same skill category. `address_book_variable` IDs - Address book ID list
      
      Items:
      
      string
    - max_returning_minutes
      
      integer — Maximum number of minutes from last participation to now. Only used when `attribute_type` is `returning_customer`.
    - operator
      
      string, possible values: "equal_to", "greater_than", "less_than", "contains" — The operator between global variable and `compared_value`. Only used when `attribute_type` is `global_variable`.
    - variable_id
      
      string — The variable's ID. Only used when `attribute_type` is `global_variable` or `address_book_variable`.
    - variable_values
      
      array — The optional variable's values. If variable matches any of them, it will match the priority. Only used when `attribute_type` is `address_book_variable`.
      
      Items:
      
      string
next_page_token

string — Use the next page token to paginate through large result sets. A next page token is returned whenever the set of available results exceeds the current page size. This token's expiration period is 15 minutes.
page_size

integer, default: 30 — The number of records returned within a single API call.
total_records

integer — The total number of all the records available across pages.

Example:

{
  "next_page_token": "R4aF9Oj0fVM2hhezJTEmSKaBSkfesDwGy42",
  "page_size": 30,
  "total_records": 10,
  "consumer_routing_profiles": [
    {
      "consumer_routing_profile_id": "-6JPFRKERXymVrf_h2EISQ",
      "consumer_routing_profile_name": "My consumer routing profile",
      "consumer_routing_profile_description": "This is the consumer routing profile's description.",
      "top_priorities": [
        {
          "attribute_type": "global_variable",
          "parameter": {
            "ids": [
              "mF8W-YRDRHCWyGMl4UNHWA"
            ],
            "enter_queue_start_time": "09:00 AM",
            "enter_queue_end_time": "11:00 PM",
            "enter_queue_timezone": "America/New_York",
            "max_returning_minutes": 60,
            "variable_id": "--FBpU8hSGqIPNUv4lXR4A",
            "variable_values": [
              "vip"
            ],
            "operator": "equal_to",
            "compared_value": "1"
          }
        }
      ],
      "accumulated_priorities": [
        {
          "attribute_type": "global_variable",
          "incremental_rate": 10,
          "parameter": {
            "ids": [
              "mF8W-YRDRHCWyGMl4UNHWA"
            ],
            "enter_queue_start_time": "09:00 AM",
            "enter_queue_end_time": "11:00 PM",
            "enter_queue_timezone": "America/New_York",
            "max_returning_minutes": 60,
            "variable_id": "--FBpU8hSGqIPNUv4lXR4A",
            "variable_values": [
              "vip"
            ],
            "operator": "equal_to",
            "compared_value": "1"
          }
        }
      ]
    }
  ]
}

Status: 429 HTTP Status Code: `429` Too Many Requests. For more information, see [rate limits](/docs/api/rate-limits/).

Create a consumer routing profile

Method: POST
Path: /contact_center/consumer_routing_profiles
Tags: Routing Profiles

Create a consumer routing profile.

Scopes: contact_center_routing_profile:write:admin

Granular Scopes: contact_center:write:consumer_routing_profile:admin

Rate Limit Label: LIGHT

Request Body

Content-Type: application/json

consumer_routing_profile_name (required)

string — The consumer routing profile's name.
accumulated_priorities

array — The consumers' accumulated priority. Use ratings to serve consumers from the highest to lowest value, from 100 to 1, based on a consumer attribute. Consumers accumulate priority while waiting in the queue, after top priority consumers.

Items:
- attribute_type (required)
  
  string, possible values: "address_book_contacts", "entrance_to_queue", "new_customer", "returning_customer", "release_to_queue", "skills", "address_book_variable", "global_variable" — The attribute's type. * `address_book_contacts` - Address book contacts * `entrance_to_queue` - Entrance to queue * `new_customer` - New customer * `returning_customer` - Returning customer * `release_to_queue` - Release to queue * `skills` - Skills * `address_book_variable` - Address book variable * `global_variable` - Global variable
- incremental_rate (required)
  
  integer — The rate that consumers accumulate priority while waiting in line. For example, consumer A and consumer B have the same top priority. If consumer A.wait_time \* consumer A.`incremental_rate` > consumer B.wait_time \* consumer B.`incremental_rate`, consumer A will be first serviced.
- parameter
  
  object — The parameter for priority's attribute. Parameter is different for each `attribute_type`: 1. `address_book_contacts` `parameter` = { `ids`: [`contanct1_id`, `contact2_id`] // address book contact ID list } 2. `entrance_to_queue` `parameter` = { `enter_queue_start_time`: `09:00 AM`, `enter_queue_end_time`: `11:00 PM`, `enter_queue_timezone`: `America/New_York` } 3. `new_customer` `parameter` = `null` 4. `returning_customer` `parameter` = { `max_returning_minutes`: `60` } 5. `release_to_queue` `parameter` = { `ids`: [`queue1_id`, `queue2_id`] // queue ID list } 6. `skills` `parameter` = { `ids`: [`skill1_id`, `skill2_id`] // skill ID list } 7. `address_book_variable` `parameter` = { `variable_id` = `address_book_variable_id`, `ids` = [`address_book_id1`, `address_book_id2`] // address book ID list `variable_values` = [`value1`, `value2`] } 8. `global_variable` `parameter` = { `variable_id` = `global_variable_id`, `operator` = `equal_to`, `compared_value` = `value` }
  - compared_value
    
    string — Compare the specified value to the variable's value. Only used when `attribute_type` is `global_variable`.
  - enter_queue_end_time
    
    string — The end time when the consumer enters the queue. Only used when `attribute_type` is `entrance_to_queue`.
  - enter_queue_start_time
    
    string — The start time when the consumer enters the queue. Only used when `attribute_type` is `entrance_to_queue`.
  - enter_queue_timezone
    
    string — The timezone when the consumer enters the queue.
  - ids
    
    array — The related entity ID list for priority's attribute. `address_book_contacts` IDs - Address book contact ID list `release_to_queue` IDs - Queue ID list `skills` IDs - Skill ID list. Should under the same skill category. `address_book_variable` IDs - Address book ID list
    
    Items:
    
    string
  - max_returning_minutes
    
    integer — Maximum number of minutes from last participation to now. Only used when `attribute_type` is `returning_customer`.
  - operator
    
    string, possible values: "equal_to", "greater_than", "less_than", "contains" — The operator between global variable and `compared_value`. Only used when `attribute_type` is `global_variable`.
  - variable_id
    
    string — The variable's ID. Only used when `attribute_type` is `global_variable` or `address_book_variable`.
  - variable_values
    
    array — The optional variable's values. If variable matches any of them, it will match the priority. Only used when `attribute_type` is `address_book_variable`.
    
    Items:
    
    string
consumer_routing_profile_description

string — The consumer routing profile's description.
top_priorities

array — The consumers' top priority. Decide the consumer's position in the queue. The higher the consumer's priority, the earlier the consumer will be served.

Items:
- attribute_type (required)
  
  string, possible values: "address_book_contacts", "entrance_to_queue", "new_customer", "returning_customer", "release_to_queue", "skills", "address_book_variable", "global_variable" — The attribute's type. * `address_book_contacts` - Address book contacts * `entrance_to_queue` - Entrance to queue * `new_customer` - New customer * `returning_customer` - Returning customer * `release_to_queue` - Release to queue * `skills` - Skills * `address_book_variable` - Address book variable * `global_variable` - Global variable
- parameter
  
  object — The parameter for priority's attribute. Parameter is different for each `attribute_type`: 1. `address_book_contacts` `parameter` = { `ids`: [`contanct1_id`, `contact2_id`] // address book contact ID list } 2. `entrance_to_queue` `parameter` = { `enter_queue_start_time`: `09:00 AM`, `enter_queue_end_time`: `11:00 PM`, `enter_queue_timezone`: `America/New_York` } 3. `new_customer` `parameter` = `null` 4. `returning_customer` `parameter` = { `max_returning_minutes`: `60` } 5. `release_to_queue` `parameter` = { `ids`: [`queue1_id`, `queue2_id`] // queue ID list } 6. `skills` `parameter` = { `ids`: [`skill1_id`, `skill2_id`] // skill ID list } 7. `address_book_variable` `parameter` = { `variable_id` = `address_book_variable_id`, `ids` = [`address_book_id1`, `address_book_id2`] // address book ID list `variable_values` = [`value1`, `value2`] } 8. `global_variable` `parameter` = { `variable_id` = `global_variable_id`, `operator` = `equal_to`, `compared_value` = `value` }
  - compared_value
    
    string — Compare the specified value to the variable's value. Only used when `attribute_type` is `global_variable`.
  - enter_queue_end_time
    
    string — The end time when the consumer enters the queue. Only used when `attribute_type` is `entrance_to_queue`.
  - enter_queue_start_time
    
    string — The start time when the consumer enters the queue. Only used when `attribute_type` is `entrance_to_queue`.
  - enter_queue_timezone
    
    string — The timezone when the consumer enters the queue. Only used when `attribute_type` is `entrance_to_queue`.
  - ids
    
    array — The related entity ID list for priority's attribute. `address_book_contacts` IDs - Address book contact ID list `release_to_queue` IDs - Queue ID list `skills` IDs - Skill ID list. Should under the same skill category. `address_book_variable` IDs - Address book ID list
    
    Items:
    
    string
  - max_returning_minutes
    
    integer — Maximum number of minutes from last participation to now. Only used when `attribute_type` is `returning_customer`.
  - operator
    
    string, possible values: "equal_to", "greater_than", "less_than", "contains" — The operator between global variable and `compared_value`. Only used when `attribute_type` is `global_variable`.
  - variable_id
    
    string — The variable's ID. Only used when `attribute_type` is `global_variable` or `address_book_variable`.
  - variable_values
    
    array — The optional variable's values. If variable matches any of them, it will match the priority. Only used when `attribute_type` is `address_book_variable`.
    
    Items:
    
    string

Example:

{
  "consumer_routing_profile_name": "My consumer routing profile",
  "consumer_routing_profile_description": "This is the consumer routing profile's description.",
  "top_priorities": [
    {
      "attribute_type": "global_variable",
      "parameter": {
        "ids": [
          "mF8W-YRDRHCWyGMl4UNHWA"
        ],
        "enter_queue_start_time": "09:00 AM",
        "enter_queue_end_time": "11:00 PM",
        "enter_queue_timezone": "America/New_York",
        "max_returning_minutes": 60,
        "variable_id": "--FBpU8hSGqIPNUv4lXR4A",
        "variable_values": [
          "vip"
        ],
        "operator": "equal_to",
        "compared_value": "1"
      }
    }
  ],
  "accumulated_priorities": [
    {
      "attribute_type": "global_variable",
      "incremental_rate": 10,
      "parameter": {
        "ids": [
          "mF8W-YRDRHCWyGMl4UNHWA"
        ],
        "enter_queue_start_time": "09:00 AM",
        "enter_queue_end_time": "11:00 PM",
        "enter_queue_timezone": "America/New_York",
        "max_returning_minutes": 60,
        "variable_id": "--FBpU8hSGqIPNUv4lXR4A",
        "variable_values": [
          "vip"
        ],
        "operator": "equal_to",
        "compared_value": "1"
      }
    }
  ]
}

Responses

Status: 201 HTTP Status Code: `201` Consumer routing profile created.

Content-Type: application/json

accumulated_priorities

array — The consumers' accumulated priority. Use ratings to serve consumers from the highest to lowest value, from 100 to 1, based on a consumer attribute. Consumers accumulate priority while waiting in the queue, after top priority consumers.

Items:
- attribute_type (required)
  
  string, possible values: "address_book_contacts", "entrance_to_queue", "new_customer", "returning_customer", "release_to_queue", "skills", "address_book_variable", "global_variable" — The attribute's type. * `address_book_contacts` - Address book contacts * `entrance_to_queue` - Entrance to queue * `new_customer` - New customer * `returning_customer` - Returning customer * `release_to_queue` - Release to queue * `skills` - Skills * `address_book_variable` - Address book variable * `global_variable` - Global variable
- incremental_rate (required)
  
  integer — The rate that consumers accumulate priority while waiting in line. For example, consumer A and consumer B have the same top priority. If consumer A.wait_time \* consumer A.`incremental_rate` > consumer B.wait_time \* consumer B.`incremental_rate`, consumer A will be first serviced.
- parameter
  
  object — The parameter for priority's attribute. Parameter is different for each `attribute_type`: 1. `address_book_contacts` `parameter` = { `ids`: [`contanct1_id`, `contact2_id`] // address book contact ID list } 2. `entrance_to_queue` `parameter` = { `enter_queue_start_time`: `09:00 AM`, `enter_queue_end_time`: `11:00 PM`, `enter_queue_timezone`: `America/New_York` } 3. `new_customer` `parameter` = `null` 4. `returning_customer` `parameter` = { `max_returning_minutes`: `60` } 5. `release_to_queue` `parameter` = { `ids`: [`queue1_id`, `queue2_id`] // queue ID list } 6. `skills` `parameter` = { `ids`: [`skill1_id`, `skill2_id`] // skill ID list } 7. `address_book_variable` `parameter` = { `variable_id` = `address_book_variable_id`, `ids` = [`address_book_id1`, `address_book_id2`] // address book ID list `variable_values` = [`value1`, `value2`] } 8. `global_variable` `parameter` = { `variable_id` = `global_variable_id`, `operator` = `equal_to`, `compared_value` = `value` }
  - compared_value
    
    string — Compare the specified value to the variable's value. Only used when `attribute_type` is `global_variable`.
  - enter_queue_end_time
    
    string — The end time when the consumer enters the queue. Only used when `attribute_type` is `entrance_to_queue`.
  - enter_queue_start_time
    
    string — The start time when the consumer enters the queue. Only used when `attribute_type` is `entrance_to_queue`.
  - enter_queue_timezone
    
    string — The timezone when the consumer enters the queue.
  - ids
    
    array — The related entity ID list for priority's attribute. `address_book_contacts` IDs - Address book contact ID list `release_to_queue` IDs - Queue ID list `skills` IDs - Skill ID list. Should under the same skill category. `address_book_variable` IDs - Address book ID list
    
    Items:
    
    string
  - max_returning_minutes
    
    integer — Maximum number of minutes from last participation to now. Only used when `attribute_type` is `returning_customer`.
  - operator
    
    string, possible values: "equal_to", "greater_than", "less_than", "contains" — The operator between global variable and `compared_value`. Only used when `attribute_type` is `global_variable`.
  - variable_id
    
    string — The variable's ID. Only used when `attribute_type` is `global_variable` or `address_book_variable`.
  - variable_values
    
    array — The optional variable's values. If variable matches any of them, it will match the priority. Only used when `attribute_type` is `address_book_variable`.
    
    Items:
    
    string
consumer_routing_profile_description

string — The consumer routing profile's description.
consumer_routing_profile_id

string — The consumer routing profile's ID.
consumer_routing_profile_name

string — The consumer routing profile's name.
top_priorities

array — The consumers' top priority. Decide the consumer's position in the queue. The higher the consumer's priority, the earlier the consumer will be served.

Items:
- attribute_type (required)
  
  string, possible values: "address_book_contacts", "entrance_to_queue", "new_customer", "returning_customer", "release_to_queue", "skills", "address_book_variable", "global_variable" — The attribute's type. * `address_book_contacts` - Address book contacts * `entrance_to_queue` - Entrance to queue * `new_customer` - New customer * `returning_customer` - Returning customer * `release_to_queue` - Release to queue * `skills` - Skills * `address_book_variable` - Address book variable * `global_variable` - Global variable
- parameter
  
  object — The parameter for priority's attribute. Parameter is different for each `attribute_type`: 1. `address_book_contacts` `parameter` = { `ids`: [`contanct1_id`, `contact2_id`] // address book contact ID list } 2. `entrance_to_queue` `parameter` = { `enter_queue_start_time`: `09:00 AM`, `enter_queue_end_time`: `11:00 PM`, `enter_queue_timezone`: `America/New_York` } 3. `new_customer` `parameter` = `null` 4. `returning_customer` `parameter` = { `max_returning_minutes`: `60` } 5. `release_to_queue` `parameter` = { `ids`: [`queue1_id`, `queue2_id`] // queue ID list } 6. `skills` `parameter` = { `ids`: [`skill1_id`, `skill2_id`] // skill ID list } 7. `address_book_variable` `parameter` = { `variable_id` = `address_book_variable_id`, `ids` = [`address_book_id1`, `address_book_id2`] // address book ID list `variable_values` = [`value1`, `value2`] } 8. `global_variable` `parameter` = { `variable_id` = `global_variable_id`, `operator` = `equal_to`, `compared_value` = `value` }
  - compared_value
    
    string — Compare the specified value to the variable's value. Only used when `attribute_type` is `global_variable`.
  - enter_queue_end_time
    
    string — The end time when the consumer enters the queue. Only used when `attribute_type` is `entrance_to_queue`.
  - enter_queue_start_time
    
    string — The start time when the consumer enters the queue. Only used when `attribute_type` is `entrance_to_queue`.
  - enter_queue_timezone
    
    string — The timezone when the consumer enters the queue. Only used when `attribute_type` is `entrance_to_queue`.
  - ids
    
    array — The related entity ID list for priority's attribute. `address_book_contacts` IDs - Address book contact ID list `release_to_queue` IDs - Queue ID list `skills` IDs - Skill ID list. Should under the same skill category. `address_book_variable` IDs - Address book ID list
    
    Items:
    
    string
  - max_returning_minutes
    
    integer — Maximum number of minutes from last participation to now. Only used when `attribute_type` is `returning_customer`.
  - operator
    
    string, possible values: "equal_to", "greater_than", "less_than", "contains" — The operator between global variable and `compared_value`. Only used when `attribute_type` is `global_variable`.
  - variable_id
    
    string — The variable's ID. Only used when `attribute_type` is `global_variable` or `address_book_variable`.
  - variable_values
    
    array — The optional variable's values. If variable matches any of them, it will match the priority. Only used when `attribute_type` is `address_book_variable`.
    
    Items:
    
    string

Example:

{
  "consumer_routing_profile_id": "-6JPFRKERXymVrf_h2EISQ",
  "consumer_routing_profile_name": "My consumer routing profile",
  "consumer_routing_profile_description": "This is the consumer routing profile's description.",
  "top_priorities": [
    {
      "attribute_type": "global_variable",
      "parameter": {
        "ids": [
          "mF8W-YRDRHCWyGMl4UNHWA"
        ],
        "enter_queue_start_time": "09:00 AM",
        "enter_queue_end_time": "11:00 PM",
        "enter_queue_timezone": "America/New_York",
        "max_returning_minutes": 60,
        "variable_id": "--FBpU8hSGqIPNUv4lXR4A",
        "variable_values": [
          "vip"
        ],
        "operator": "equal_to",
        "compared_value": "1"
      }
    }
  ],
  "accumulated_priorities": [
    {
      "attribute_type": "global_variable",
      "incremental_rate": 10,
      "parameter": {
        "ids": [
          "mF8W-YRDRHCWyGMl4UNHWA"
        ],
        "enter_queue_start_time": "09:00 AM",
        "enter_queue_end_time": "11:00 PM",
        "enter_queue_timezone": "America/New_York",
        "max_returning_minutes": 60,
        "variable_id": "--FBpU8hSGqIPNUv4lXR4A",
        "variable_values": [
          "vip"
        ],
        "operator": "equal_to",
        "compared_value": "1"
      }
    }
  ]
}

Status: 400 HTTP Status Code: `400` Bad Request Error Code: `4010` Number of priorities exceeds the maximum limit. Error Code: `4011` Consumer routing profile has duplicated priority attributes. Error Code: `4012` Consumer routing profile's related resource not found. Error Code: `4013` Invalid `compared_value` or operator in the consumer routing profile. Error Code: `4014` Duplicate variables in the consumer routing profile. Error Code: `300` Missing required parameter. Error Code: `303` Invalid parameter.

Status: 409 HTTP Status Code: `409` Conflict Consumer routing profile's name already exists.

Status: 429 HTTP Status Code: `429` Too Many Requests. For more information, see [rate limits](/docs/api/rate-limits/).

Get a consumer routing profile

Method: GET
Path: /contact_center/consumer_routing_profiles/{consumerRoutingProfileId}
Tags: Routing Profiles

Retrieve the consumer routing profile.

Scopes: contact_center_routing_profile:read:admin

Granular Scopes: contact_center:read:consumer_routing_profile:admin

Rate Limit Label: LIGHT

Responses

Status: 200 HTTP Status Code: `200` Consumer routing profile returned.

Content-Type: application/json

accumulated_priorities

array — The consumers' accumulated priority. Use ratings to serve consumers from the highest to lowest value, from 100 to 1, based on a consumer attribute. Consumers accumulate priority while waiting in the queue, after top priority consumers.

Items:
- attribute_type (required)
  
  string, possible values: "address_book_contacts", "entrance_to_queue", "new_customer", "returning_customer", "release_to_queue", "skills", "address_book_variable", "global_variable" — The attribute's type. * `address_book_contacts` - Address book contacts * `entrance_to_queue` - Entrance to queue * `new_customer` - New customer * `returning_customer` - Returning customer * `release_to_queue` - Release to queue * `skills` - Skills * `address_book_variable` - Address book variable * `global_variable` - Global variable
- incremental_rate (required)
  
  integer — The rate that consumers accumulate priority while waiting in line. For example, consumer A and consumer B have the same top priority. If consumer A.wait_time \* consumer A.`incremental_rate` > consumer B.wait_time \* consumer B.`incremental_rate`, consumer A will be first serviced.
- parameter
  
  object — The parameter for priority's attribute. Parameter is different for each `attribute_type`: 1. `address_book_contacts` `parameter` = { `ids`: [`contanct1_id`, `contact2_id`] // address book contact ID list } 2. `entrance_to_queue` `parameter` = { `enter_queue_start_time`: `09:00 AM`, `enter_queue_end_time`: `11:00 PM`, `enter_queue_timezone`: `America/New_York` } 3. `new_customer` `parameter` = `null` 4. `returning_customer` `parameter` = { `max_returning_minutes`: `60` } 5. `release_to_queue` `parameter` = { `ids`: [`queue1_id`, `queue2_id`] // queue ID list } 6. `skills` `parameter` = { `ids`: [`skill1_id`, `skill2_id`] // skill ID list } 7. `address_book_variable` `parameter` = { `variable_id` = `address_book_variable_id`, `ids` = [`address_book_id1`, `address_book_id2`] // address book ID list `variable_values` = [`value1`, `value2`] } 8. `global_variable` `parameter` = { `variable_id` = `global_variable_id`, `operator` = `equal_to`, `compared_value` = `value` }
  - compared_value
    
    string — Compare the specified value to the variable's value. Only used when `attribute_type` is `global_variable`.
  - enter_queue_end_time
    
    string — The end time when the consumer enters the queue. Only used when `attribute_type` is `entrance_to_queue`.
  - enter_queue_start_time
    
    string — The start time when the consumer enters the queue. Only used when `attribute_type` is `entrance_to_queue`.
  - enter_queue_timezone
    
    string — The timezone when the consumer enters the queue.
  - ids
    
    array — The related entity ID list for priority's attribute. `address_book_contacts` IDs - Address book contact ID list `release_to_queue` IDs - Queue ID list `skills` IDs - Skill ID list. Should under the same skill category. `address_book_variable` IDs - Address book ID list
    
    Items:
    
    string
  - max_returning_minutes
    
    integer — Maximum number of minutes from last participation to now. Only used when `attribute_type` is `returning_customer`.
  - operator
    
    string, possible values: "equal_to", "greater_than", "less_than", "contains" — The operator between global variable and `compared_value`. Only used when `attribute_type` is `global_variable`.
  - variable_id
    
    string — The variable's ID. Only used when `attribute_type` is `global_variable` or `address_book_variable`.
  - variable_values
    
    array — The optional variable's values. If variable matches any of them, it will match the priority. Only used when `attribute_type` is `address_book_variable`.
    
    Items:
    
    string
consumer_routing_profile_description

string — The consumer routing profile's description.
consumer_routing_profile_id

string — The consumer routing profile's ID.
consumer_routing_profile_name

string — The consumer routing profile's name.
top_priorities

array — The consumers' top priority. Decide the consumer's position in the queue. The higher the consumer's priority, the earlier the consumer will be served.

Items:
- attribute_type (required)
  
  string, possible values: "address_book_contacts", "entrance_to_queue", "new_customer", "returning_customer", "release_to_queue", "skills", "address_book_variable", "global_variable" — The attribute's type. * `address_book_contacts` - Address book contacts * `entrance_to_queue` - Entrance to queue * `new_customer` - New customer * `returning_customer` - Returning customer * `release_to_queue` - Release to queue * `skills` - Skills * `address_book_variable` - Address book variable * `global_variable` - Global variable
- parameter
  
  object — The parameter for priority's attribute. Parameter is different for each `attribute_type`: 1. `address_book_contacts` `parameter` = { `ids`: [`contanct1_id`, `contact2_id`] // address book contact ID list } 2. `entrance_to_queue` `parameter` = { `enter_queue_start_time`: `09:00 AM`, `enter_queue_end_time`: `11:00 PM`, `enter_queue_timezone`: `America/New_York` } 3. `new_customer` `parameter` = `null` 4. `returning_customer` `parameter` = { `max_returning_minutes`: `60` } 5. `release_to_queue` `parameter` = { `ids`: [`queue1_id`, `queue2_id`] // queue ID list } 6. `skills` `parameter` = { `ids`: [`skill1_id`, `skill2_id`] // skill ID list } 7. `address_book_variable` `parameter` = { `variable_id` = `address_book_variable_id`, `ids` = [`address_book_id1`, `address_book_id2`] // address book ID list `variable_values` = [`value1`, `value2`] } 8. `global_variable` `parameter` = { `variable_id` = `global_variable_id`, `operator` = `equal_to`, `compared_value` = `value` }
  - compared_value
    
    string — Compare the specified value to the variable's value. Only used when `attribute_type` is `global_variable`.
  - enter_queue_end_time
    
    string — The end time when the consumer enters the queue. Only used when `attribute_type` is `entrance_to_queue`.
  - enter_queue_start_time
    
    string — The start time when the consumer enters the queue. Only used when `attribute_type` is `entrance_to_queue`.
  - enter_queue_timezone
    
    string — The timezone when the consumer enters the queue. Only used when `attribute_type` is `entrance_to_queue`.
  - ids
    
    array — The related entity ID list for priority's attribute. `address_book_contacts` IDs - Address book contact ID list `release_to_queue` IDs - Queue ID list `skills` IDs - Skill ID list. Should under the same skill category. `address_book_variable` IDs - Address book ID list
    
    Items:
    
    string
  - max_returning_minutes
    
    integer — Maximum number of minutes from last participation to now. Only used when `attribute_type` is `returning_customer`.
  - operator
    
    string, possible values: "equal_to", "greater_than", "less_than", "contains" — The operator between global variable and `compared_value`. Only used when `attribute_type` is `global_variable`.
  - variable_id
    
    string — The variable's ID. Only used when `attribute_type` is `global_variable` or `address_book_variable`.
  - variable_values
    
    array — The optional variable's values. If variable matches any of them, it will match the priority. Only used when `attribute_type` is `address_book_variable`.
    
    Items:
    
    string

Example:

{
  "consumer_routing_profile_id": "-6JPFRKERXymVrf_h2EISQ",
  "consumer_routing_profile_name": "My consumer routing profile",
  "consumer_routing_profile_description": "This is the consumer routing profile's description.",
  "top_priorities": [
    {
      "attribute_type": "global_variable",
      "parameter": {
        "ids": [
          "mF8W-YRDRHCWyGMl4UNHWA"
        ],
        "enter_queue_start_time": "09:00 AM",
        "enter_queue_end_time": "11:00 PM",
        "enter_queue_timezone": "America/New_York",
        "max_returning_minutes": 60,
        "variable_id": "--FBpU8hSGqIPNUv4lXR4A",
        "variable_values": [
          "vip"
        ],
        "operator": "equal_to",
        "compared_value": "1"
      }
    }
  ],
  "accumulated_priorities": [
    {
      "attribute_type": "global_variable",
      "incremental_rate": 10,
      "parameter": {
        "ids": [
          "mF8W-YRDRHCWyGMl4UNHWA"
        ],
        "enter_queue_start_time": "09:00 AM",
        "enter_queue_end_time": "11:00 PM",
        "enter_queue_timezone": "America/New_York",
        "max_returning_minutes": 60,
        "variable_id": "--FBpU8hSGqIPNUv4lXR4A",
        "variable_values": [
          "vip"
        ],
        "operator": "equal_to",
        "compared_value": "1"
      }
    }
  ]
}

Status: 400 HTTP Status Code: `400` Bad Request Error Code: `4015` More than one matching consumer routing profile found.

Status: 401 HTTP Status Code: `401` Unauthorized Error Code: `124` Invalid access token. Error Code: `124` Access token has expired. Error Code: `1002` The user associated with this access token was not found or is invalid.

Status: 403 HTTP Status Code: `403` Forbidden Error Code: `1021` User account is deactivated. Error Code: `1022` User does not have a Contact Center license. Error Code: `9001` The Contact Center user associated with this bearer token is missing privileges on their role required to operate this request.

Status: 404 HTTP Status Code: `404` Not Found Consumer routing profile does not exist.

Status: 429 HTTP Status Code: `429` Too Many Requests. For more information, see [rate limits](https://developers.zoom.us/docs/api/rate-limits/). Error Code: `4001` You have reached the maximum per-second rate limit for this API. Try again later.

Delete a consumer routing profile

Method: DELETE
Path: /contact_center/consumer_routing_profiles/{consumerRoutingProfileId}
Tags: Routing Profiles

Delete a consumer routing profile.

Scopes: contact_center_routing_profile:write:admin

Granular Scopes: contact_center:delete:consumer_routing_profile:admin

Rate Limit Label: LIGHT

Responses

Status: 204 HTTP Status Code: `204` Consumer routing profile deleted.

Status: 400 HTTP Status Code: `400` Bad Request Error Code: `4015` More than one matching consumer routing profile found.

Status: 401 HTTP Status Code: `401` Unauthorized Error Code: `124` Invalid access token. Error Code: `124` Access token has expired. Error Code: `1002` The user associated with this access token was not found or is invalid.

Status: 403 HTTP Status Code: `403` Forbidden Error Code: `1021` User account is deactivated. Error Code: `1022` User does not have a Contact Center license. Error Code: `9001` The Contact Center user associated with this bearer token is missing privileges on their role required to operate this request.

Status: 404 HTTP Status Code: `404` Not Found Consumer routing profileId doesn't exist.

Status: 429 HTTP Status Code: `429` Too Many Requests. For more information, see [rate limits](https://developers.zoom.us/docs/api/rate-limits/). Error Code: `4001` You have reached the maximum per-second rate limit for this API. Try again later.

Update a consumer routing profile's details

Method: PATCH
Path: /contact_center/consumer_routing_profiles/{consumerRoutingProfileId}
Tags: Routing Profiles

Update a consumer routing profile details.

Scopes: contact_center_routing_profile:write:admin

Granular Scopes: contact_center:update:consumer_routing_profile:admin

Rate Limit Label: LIGHT

Request Body

Content-Type: application/json

accumulated_priorities

array — The consumers' accumulated priority. Use ratings to serve consumers from the highest to lowest value, from 100 to 1, based on a consumer attribute. Consumers accumulate priority while waiting in the queue, after top priority consumers.

Items:
- attribute_type (required)
  
  string, possible values: "address_book_contacts", "entrance_to_queue", "new_customer", "returning_customer", "release_to_queue", "skills", "address_book_variable", "global_variable" — The attribute's type. * `address_book_contacts` - Address book contacts * `entrance_to_queue` - Entrance to queue * `new_customer` - New customer * `returning_customer` - Returning customer * `release_to_queue` - Release to queue * `skills` - Skills * `address_book_variable` - Address book variable * `global_variable` - Global variable
- incremental_rate (required)
  
  integer — The rate that consumers accumulate priority while waiting in line. For example, consumer A and consumer B have the same top priority. If consumer A.wait_time \* consumer A.`incremental_rate` > consumer B.wait_time \* consumer B.`incremental_rate`, consumer A will be first serviced.
- parameter
  
  object — The parameter for priority's attribute. Parameter is different for each `attribute_type`: 1. `address_book_contacts` `parameter` = { `ids`: [`contanct1_id`, `contact2_id`] // address book contact ID list } 2. `entrance_to_queue` `parameter` = { `enter_queue_start_time`: `09:00 AM`, `enter_queue_end_time`: `11:00 PM`, `enter_queue_timezone`: `America/New_York` } 3. `new_customer` `parameter` = `null` 4. `returning_customer` `parameter` = { `max_returning_minutes`: `60` } 5. `release_to_queue` `parameter` = { `ids`: [`queue1_id`, `queue2_id`] // queue ID list } 6. `skills` `parameter` = { `ids`: [`skill1_id`, `skill2_id`] // skill ID list } 7. `address_book_variable` `parameter` = { `variable_id` = `address_book_variable_id`, `ids` = [`address_book_id1`, `address_book_id2`] // address book ID list `variable_values` = [`value1`, `value2`] } 8. `global_variable` `parameter` = { `variable_id` = `global_variable_id`, `operator` = `equal_to`, `compared_value` = `value` }
  - compared_value
    
    string — Compare the specified value to the variable's value. Only used when `attribute_type` is `global_variable`.
  - enter_queue_end_time
    
    string — The end time when the consumer enters the queue. Only used when `attribute_type` is `entrance_to_queue`.
  - enter_queue_start_time
    
    string — The start time when the consumer enters the queue. Only used when `attribute_type` is `entrance_to_queue`.
  - enter_queue_timezone
    
    string — The timezone when the consumer enters the queue.
  - ids
    
    array — The related entity ID list for priority's attribute. `address_book_contacts` IDs - Address book contact ID list `release_to_queue` IDs - Queue ID list `skills` IDs - Skill ID list. Should under the same skill category. `address_book_variable` IDs - Address book ID list
    
    Items:
    
    string
  - max_returning_minutes
    
    integer — Maximum number of minutes from last participation to now. Only used when `attribute_type` is `returning_customer`.
  - operator
    
    string, possible values: "equal_to", "greater_than", "less_than", "contains" — The operator between global variable and `compared_value`. Only used when `attribute_type` is `global_variable`.
  - variable_id
    
    string — The variable's ID. Only used when `attribute_type` is `global_variable` or `address_book_variable`.
  - variable_values
    
    array — The optional variable's values. If variable matches any of them, it will match the priority. Only used when `attribute_type` is `address_book_variable`.
    
    Items:
    
    string
consumer_routing_profile_description

string — The consumer routing profile's description.
consumer_routing_profile_name

string — The consumer routing profile's name.
top_priorities

array — The consumers' top priority. Decide the consumer's position in the queue. The higher the consumer's priority, the earlier the consumer will be served.

Items:
- attribute_type (required)
  
  string, possible values: "address_book_contacts", "entrance_to_queue", "new_customer", "returning_customer", "release_to_queue", "skills", "address_book_variable", "global_variable" — The attribute's type. * `address_book_contacts` - Address book contacts * `entrance_to_queue` - Entrance to queue * `new_customer` - New customer * `returning_customer` - Returning customer * `release_to_queue` - Release to queue * `skills` - Skills * `address_book_variable` - Address book variable * `global_variable` - Global variable
- parameter
  
  object — The parameter for priority's attribute. Parameter is different for each `attribute_type`: 1. `address_book_contacts` `parameter` = { `ids`: [`contanct1_id`, `contact2_id`] // address book contact ID list } 2. `entrance_to_queue` `parameter` = { `enter_queue_start_time`: `09:00 AM`, `enter_queue_end_time`: `11:00 PM`, `enter_queue_timezone`: `America/New_York` } 3. `new_customer` `parameter` = `null` 4. `returning_customer` `parameter` = { `max_returning_minutes`: `60` } 5. `release_to_queue` `parameter` = { `ids`: [`queue1_id`, `queue2_id`] // queue ID list } 6. `skills` `parameter` = { `ids`: [`skill1_id`, `skill2_id`] // skill ID list } 7. `address_book_variable` `parameter` = { `variable_id` = `address_book_variable_id`, `ids` = [`address_book_id1`, `address_book_id2`] // address book ID list `variable_values` = [`value1`, `value2`] } 8. `global_variable` `parameter` = { `variable_id` = `global_variable_id`, `operator` = `equal_to`, `compared_value` = `value` }
  - compared_value
    
    string — Compare the specified value to the variable's value. Only used when `attribute_type` is `global_variable`.
  - enter_queue_end_time
    
    string — The end time when the consumer enters the queue. Only used when `attribute_type` is `entrance_to_queue`.
  - enter_queue_start_time
    
    string — The start time when the consumer enters the queue. Only used when `attribute_type` is `entrance_to_queue`.
  - enter_queue_timezone
    
    string — The timezone when the consumer enters the queue. Only used when `attribute_type` is `entrance_to_queue`.
  - ids
    
    array — The related entity ID list for priority's attribute. `address_book_contacts` IDs - Address book contact ID list `release_to_queue` IDs - Queue ID list `skills` IDs - Skill ID list. Should under the same skill category. `address_book_variable` IDs - Address book ID list
    
    Items:
    
    string
  - max_returning_minutes
    
    integer — Maximum number of minutes from last participation to now. Only used when `attribute_type` is `returning_customer`.
  - operator
    
    string, possible values: "equal_to", "greater_than", "less_than", "contains" — The operator between global variable and `compared_value`. Only used when `attribute_type` is `global_variable`.
  - variable_id
    
    string — The variable's ID. Only used when `attribute_type` is `global_variable` or `address_book_variable`.
  - variable_values
    
    array — The optional variable's values. If variable matches any of them, it will match the priority. Only used when `attribute_type` is `address_book_variable`.
    
    Items:
    
    string

Example:

{
  "consumer_routing_profile_name": "My consumer routing profile",
  "consumer_routing_profile_description": "This is the consumer routing profile's description.",
  "top_priorities": [
    {
      "attribute_type": "global_variable",
      "parameter": {
        "ids": [
          "mF8W-YRDRHCWyGMl4UNHWA"
        ],
        "enter_queue_start_time": "09:00 AM",
        "enter_queue_end_time": "11:00 PM",
        "enter_queue_timezone": "America/New_York",
        "max_returning_minutes": 60,
        "variable_id": "--FBpU8hSGqIPNUv4lXR4A",
        "variable_values": [
          "vip"
        ],
        "operator": "equal_to",
        "compared_value": "1"
      }
    }
  ],
  "accumulated_priorities": [
    {
      "attribute_type": "global_variable",
      "incremental_rate": 10,
      "parameter": {
        "ids": [
          "mF8W-YRDRHCWyGMl4UNHWA"
        ],
        "enter_queue_start_time": "09:00 AM",
        "enter_queue_end_time": "11:00 PM",
        "enter_queue_timezone": "America/New_York",
        "max_returning_minutes": 60,
        "variable_id": "--FBpU8hSGqIPNUv4lXR4A",
        "variable_values": [
          "vip"
        ],
        "operator": "equal_to",
        "compared_value": "1"
      }
    }
  ]
}

Responses

Status: 204 HTTP Status Code: `204` Consumer routing profile's details updated.

Status: 400 HTTP Status Code: `400` Bad Request Error Code: `4010` Number of priorities exceeds the maximum limit. Error Code: `4011` The consumer routing profile has duplicated priority attributes. Error Code: `4012` The consumer routing profile's related resource not found. Error Code: `4013` Invalid `compared_value` or operator in the consumer routing profile. Error Code: `4014` Duplicate variables in the consumer routing profile. Error Code: `300` Missing required parameter. Error Code: `303` Invalid parameter. Error Code: `4015` More than one matching consumer routing profile found.

Status: 401 HTTP Status Code: `401` Unauthorized Error Code: `124` Invalid access token. Error Code: `124` Access token has expired. Error Code: `1002` The user associated with this access token was not found or is invalid.

Status: 403 HTTP Status Code: `403` Forbidden Error Code: `1021` User account is deactivated. Error Code: `1022` User does not have a Contact Center license. Error Code: `9001` The Contact Center user associated with this bearer token is missing privileges on their role required to operate this request.

Status: 404 HTTP Status Code: `404` Not Found Consumer routing profile doesn't exist.

Status: 409 HTTP Status Code: `409` Conflict Consumer routing profile's name already exists.

Status: 429 HTTP Status Code: `429` Too Many Requests. For more information, see [rate limits](https://developers.zoom.us/docs/api/rate-limits/). Error Code: `4001` You have reached the maximum per-second rate limit for this API. Try again later.

List skills

Method: GET
Path: /contact_center/skills
Tags: Skills

Return a list of a skills or a skill category's assigned skills.

Scopes: contact_center_skill:read:admin

Granular Scopes: contact_center:read:list_skills:admin

Rate Limit Label: Medium

Responses

Status: 200 HTTP Status Code: `200` Skills list returned.

Content-Type: application/json

next_page_token

string — The next page token is used to paginate through large result sets. A next page token returns whenever the set of available results exceeds the current page size. This token's expiration period is 15 minutes.
page_size

integer, default: 30 — The number of records returned within a single API call.
skills

array — Information about the skills.

Items:
- last_modified_time
  
  string, format: date-time — The date and time when the skill was last modified.
- max_proficiency_level
  
  integer, possible values: 1, 2, 3, 4, 5 — The skill category's maximum proficiency level, between `1` (low) and `5` (high). Use this value if the skill category's `type` value is `1` (a proficiency-based skill).
- modified_by
  
  string — The ID of the user who last modified the skill.
- skill_category_id
  
  string — The skill's category ID.
- skill_category_name
  
  string — The skill category's name.
- skill_id
  
  string — The skill's ID.
- skill_name
  
  string — The skill's name.
- skill_type
  
  string, possible values: "text", "proficiency" — The skill category's type: * 'text' — A text-based skill, such as a geographic location. Skills in this category do not have assigned skill levels. * 'proficiency' — A proficiency-based skill, such as a second language. Skills in this type of category have assigned proficiency levels.
- total_users
  
  integer — The total users of the skill
total_records

integer — The total number of all the records available across pages.

Example:

{
  "next_page_token": "jA5csQv1W1oXuYZLspNIZzMOXqTD9r9Rje2",
  "page_size": 1,
  "total_records": 1,
  "skills": [
    {
      "skill_id": "saaHWgVMGQU69soco456oNA",
      "skill_name": "French",
      "skill_type": "text",
      "max_proficiency_level": 5,
      "skill_category_name": "Languages",
      "skill_category_id": "rvYVEioQQduHb5iHCj7-kg",
      "total_users": 5,
      "modified_by": "IGTRVt3gQ2i-WjoUIjeZxw",
      "last_modified_time": "2022-02-15T09:27:15Z"
    }
  ]
}

Status: 429 HTTP Status Code: `429` Too Many Requests. For more information, see [rate limits](https://developers.zoom.us/docs/api/rest/rate-limits/).

Create a skill

Method: POST
Path: /contact_center/skills
Tags: Skills

Create a skill for skill-based routing. Skills are agent traits that ensure they are the right person to handle a customer interaction.

Scopes: contact_center_skill:write:admin

Granular Scopes: contact_center:write:skill:admin

Rate Limit Label: LIGHT

Request Body

Content-Type: application/json

skill_category_id

string — The skill category ID to assign the skill to.
skill_name

string — The skill's name.

Example:

{
  "skill_category_id": "OyQQjWiZQTaBX7RwSK6iRw",
  "skill_name": "French"
}

Responses

Status: 201 HTTP Status Code: `201` Skills created.

Content-Type: application/json

last_modified_time

string, format: date-time — The date and time when this data was last modified.
max_proficiency_level

integer, possible values: 1, 2, 3, 4, 5 — The skill category's maximum proficiency level, between `1` (low) and `5` (high). Use this value if the skill category's `type` value is `1` (a proficiency-based skill).
modified_by

string — The ID of the user that last modified this data.
skill_category_id

string — The skill's category ID.
skill_category_name

string — The skill category's name.
skill_id

string — The skill's ID.
skill_name

string — The skill's name.
skill_type

string, possible values: "text", "proficiency" — The skill category's type: * 'text' — A text-based skill, such as a geographic location. Skills in this category do not have assigned skill levels. * 'proficiency' — A proficiency-based skill, such as a second language. Skills in this type of category have assigned proficiency levels.
total_users

integer — The total number of users of the skill.

Example:

{
  "skill_id": "saaHWgVMGQU69soco456oNA",
  "skill_name": "French",
  "skill_type": "text",
  "max_proficiency_level": 5,
  "skill_category_name": "Languages",
  "skill_category_id": "rvYVEioQQduHb5iHCj7-kg",
  "total_users": 5,
  "modified_by": "IGTRVt3gQ2i-WjoUIjeZxw",
  "last_modified_time": "2022-02-15T09:27:15Z"
}

Status: 400 HTTP Status Code: `400` Bad Request Error Code: `1502` Skill name already exists. You must select a different name.

Status: 404 HTTP Status Code: `404` Not Found Error Code: `1501` Skill category does not exist: $skillCategoryId.

Status: 429 HTTP Status Code: `429` Too Many Requests. For more information, see [rate limits](/docs/api/rate-limits/).

List skill categories

Method: GET
Path: /contact_center/skills/categories
Tags: Skills

List all available skill categories and their information.

Scopes: contact_center_skill:read:admin

Granular Scopes: contact_center:read:list_skill_categories:admin

Rate Limit Label: MEDIUM

Responses

Status: 200 HTTP Status Code: `200` Skill categories list returned.

Content-Type: application/json

next_page_token

string — The next page token is used to paginate through large result sets. A next page token returns whenever the set of available results exceeds the current page size. This token's expiration period is 15 minutes.
page_size

integer, default: 30 — The number of records returned within a single API call.
skill_categories

array — Information about the skill categories.

Items:
- last_modified_time
  
  string, format: date-time — The date and time when the skill category was last modified.
- max_proficiency_level
  
  integer — The skill category's maximum proficiency level, between `1` (low) and system configured highest level (high). This value only returns if the skill category's `type` value is `1`, a proficiency-based skill.
- modified_by
  
  string — The ID of the user who last modified the skill category.
- skill_category_description
  
  string — The skill category's description.
- skill_category_id
  
  string — The skill category's ID.
- skill_category_name
  
  string — The skill category's name.
- skill_type
  
  string, possible values: "text", "proficiency" — The skill category's type: * 'text' — A text-based skill, such as a geographic location. Skills in this category do not have assigned skill levels. * 'proficiency' — A proficiency-based skill, such as a second language. Skills in this type of category have assigned proficiency levels.
- total_agent_routing_profiles
  
  integer — The total agent routing profiles.

Example:

{
  "next_page_token": "H13iGyIFKCICxrYDlrppjJcDvN2jcBnRzD2",
  "page_size": 1,
  "skill_categories": [
    {
      "skill_category_id": "Mu_IEZZHQZGMY9avK74kwA",
      "skill_category_name": "Languages",
      "skill_category_description": "Medium proficiency.",
      "max_proficiency_level": 25,
      "total_agent_routing_profiles": 5,
      "skill_type": "text",
      "modified_by": "IGTRVt3gQ2i-WjoUIjeZxw",
      "last_modified_time": "2022-02-15T09:27:15Z"
    }
  ]
}

Status: 429 HTTP Status Code: `429` Too Many Requests. For more information, see [rate limits](https://developers.zoom.us/docs/api/rest/rate-limits/).

Create a skill category

Method: POST
Path: /contact_center/skills/categories
Tags: Skills

Create a new skill category. Skill categories let you assign several similar skills to a category, such as language skills. You can then route French-speaking callers to contact center agents that have the highest proficiency with French.

Scopes: contact_center_skill:write:admin

Granular Scopes: contact_center:write:skill_category:admin

Rate Limit Label: LIGHT

Request Body

Content-Type: application/json

max_proficiency_level

integer — The skill category's maximum proficiency level, between `1` (low) and system configured highest level (high). Use this value if the skill category's `type` value is `1` (a proficiency-based skill).
skill_category_description

string — The skill category's description.
skill_category_name

string — The skill category's name.
skill_type

string, possible values: "text", "proficiency" — The skill category's type. * 'text' - A text-based skill, such as a geographic location. Skills in this category do not have assigned skill levels. * 'proficiency' - A proficiency-based skill, such as a second language. Skills in this type of category have assigned proficiency levels.

Example:

{
  "max_proficiency_level": 25,
  "skill_category_name": "Languages",
  "skill_category_description": "Medium proficiency.",
  "skill_type": "text"
}

Responses

Status: 201 HTTP Status Code: `201` Skill category created.

Content-Type: application/json

last_modified_time

string, format: date-time — The date and time when the skill category was last modified.
max_proficiency_level

integer — The skill category's maximum proficiency level, between `1` (low) and system configured highest level (high). Use this value if the skill category's `type` value is `1`, for a proficiency-based skill.
modified_by

string — The ID of the user who last modified the skill category.
skill_category_description

string — The skill category's description.
skill_category_id

string — The skill category's ID.
skill_category_name

string — The skill category's name.
skill_type

string, possible values: "text", "proficiency" — The skill category's type. * 'text' - A text-based skill, such as a geographic location. Skills in this category do not have assigned skill levels. * 'proficiency' - A proficiency-based skill, such as a second language. Skills in this type of category have assigned proficiency levels.

Example:

{
  "skill_category_id": "Mu_IEZZHQZGMY9avK74kwA",
  "skill_category_name": "Languages",
  "skill_category_description": "Medium proficiency.",
  "skill_type": "text",
  "max_proficiency_level": 25,
  "modified_by": "IGTRVt3gQ2i-WjoUIjeZxw",
  "last_modified_time": "2022-02-15T09:27:15Z"
}

Status: 400 HTTP Status Code: `400` Bad Request Error Code: `1502` The skill category highest proficiency level is `5`, and the lowest level is `1`.

Status: 429 HTTP Status Code: `429` Too Many Requests. For more information, see [rate limits](https://developers.zoom.us/docs/api/rest/rate-limits/).

Get a skill category

Method: GET
Path: /contact_center/skills/categories/{skillCategoryId}
Tags: Skills

Return information about a specific skill category.

Scopes: contact_center_skill:read:admin

Granular Scopes: contact_center:read:skill_category:admin

Rate Limit Label: LIGHT

Responses

Status: 200 HTTP Status Code: `200` Skill category returned.

Content-Type: application/json

last_modified_time

string, format: date-time — The date and time when this data was last modified.
max_proficiency_level

integer — The skill category's maximum proficiency level, between `1` (low) and system configured highest level (high). This value only returns if the skill category's `type` value is `1`, a proficiency-based skill.
modified_by

string — The ID of the user that last modified this data.
skill_category_description

string — The skill category's description.
skill_category_id

string — The skill category's ID.
skill_category_name

string — The skill category's name.
skill_type

string, possible values: "text", "proficiency" — The skill category's type. * 'text' - A text-based skill, such as a geographic location. Skills in this category do not have assigned skill levels. * 'proficiency' - A proficiency-based skill, such as a second language. Skills in this type of category have assigned proficiency levels.

Example:

{
  "skill_category_id": "Mu_IEZZHQZGMY9avK74kwA",
  "skill_category_name": "Languages",
  "skill_category_description": "Medium proficiency.",
  "max_proficiency_level": 25,
  "skill_type": "text",
  "modified_by": "IGTRVt3gQ2i-WjoUIjeZxw",
  "last_modified_time": "2022-02-15T09:27:15Z"
}

Status: 401 HTTP Status Code: `401` Unauthorized Error Code: `124` Invalid access token. Error Code: `124` Access token has expired. Error Code: `1002` The user associated with this access token was not found or is invalid.

Status: 403 HTTP Status Code: `403` Forbidden Error Code: `1021` User account is deactivated. Error Code: `1022` User does not have a Contact Center license. Error Code: `9001` The Contact Center user associated with this bearer token is missing privileges on their role required to operate this request.

Status: 404 HTTP Status Code: `404` Not Found Error Code: `1501` Skill category does not exist: $skillCategoryId.

Status: 429 HTTP Status Code: `429` Too Many Requests. For more information, see [rate limits](https://developers.zoom.us/docs/api/rate-limits/). Error Code: `4001` You have reached the maximum per-second rate limit for this API. Try again later.

Delete a skill category

Method: DELETE
Path: /contact_center/skills/categories/{skillCategoryId}
Tags: Skills

Delete an existing skill category.

Scopes: contact_center_skill:write:admin

Granular Scopes: contact_center:delete:skill_category:admin

Rate Limit Label: Light

Responses

Status: 204 HTTP Status Code: `204` Skill category deleted.

Status: 400 HTTP Status Code: `400` Bad Request

Status: 404 HTTP Status Code: `404` Not Found Error Code: `1501` Skill category does not exist: $skillCategoryId.

Status: 429 HTTP Status Code: `429` Too Many Requests. For more information, see [rate limits](https://developers.zoom.us/docs/api/rest/rate-limits/).

Update a skill category

Method: PATCH
Path: /contact_center/skills/categories/{skillCategoryId}
Tags: Skills

Update a skill category.

Scopes: contact_center_skill:write:admin

Granular Scopes: contact_center:update:skill_category:admin

Rate Limit Label: LIGHT

Request Body

Content-Type: application/json

max_proficiency_level

integer — The skill category's maximum proficiency level, between `1` (low) and system configured highest level (high). Use this value if the skill category's `type` value is `1`, a proficiency-based skill.
skill_category_description

string — The skill category's description.
skill_category_name

string — The skill category's name.

Example:

{
  "max_proficiency_level": 25,
  "skill_category_name": "Languages",
  "skill_category_description": "Medium proficiency."
}

Responses

Status: 204 HTTP Status Code: `204` Skill category updated.

Status: 400 HTTP Status Code: `400` Bad Request Error Code: `1502` The skill category highest proficiency level is `5`, and the lowest level is `1`.

Status: 404 HTTP Status Code: `404` Not Found Error Code: `1501` Skill category does not exist: $skillCategoryId.

Status: 429 HTTP Status Code: `429` Too Many Requests. For more information, see [rate limits](https://developers.zoom.us/docs/api/rate-limits/).

Get a skill

Method: GET
Path: /contact_center/skills/{skillId}
Tags: Skills

Return a skill's information and its usage.

Scopes: contact_center_skill:read:admin

Granular Scopes: contact_center:read:skill:admin

Rate Limit Label: LIGHT

Responses

Status: 200 HTTP Status Code: `200` Skill usage information returned.

Content-Type: application/json

last_modified_time

string, format: date-time — The date and time when this data was last modified.
max_proficiency_level

integer, possible values: 1, 2, 3, 4, 5 — The skill category's maximum proficiency level, between `1`, lowest, and `5`, highest. Use this value if the skill category's `type` value is `1`, a proficiency-based skill.
modified_by

string — The ID of the user that last modified this data.
skill_category_id

string — The skill's category ID.
skill_category_name

string — The skill category's name.
skill_id

string — The skill's ID.
skill_name

string — The skill's name.
skill_type

string, possible values: "text", "proficiency" — The skill category's type. * 'text' - A text-based skill, such as a geographic location. Skills in this category do not have assigned skill levels. * 'proficiency' - A proficiency-based skill, such as a second language. Skills in this type of category have assigned proficiency levels.
total_users

integer — The total users of the skill

Example:

{
  "skill_id": "saaHWgVMGQU69soco456oNA",
  "skill_name": "French",
  "skill_type": "text",
  "max_proficiency_level": 5,
  "skill_category_name": "Languages",
  "skill_category_id": "rvYVEioQQduHb5iHCj7-kg",
  "total_users": 5,
  "modified_by": "IGTRVt3gQ2i-WjoUIjeZxw",
  "last_modified_time": "2022-02-15T09:27:15Z"
}

Status: 400 HTTP Status Code: `400` Bad Request Error Code: `1408` More than one matching skill found.

Status: 401 HTTP Status Code: `401` Unauthorized Error Code: `124` Invalid access token. Error Code: `124` Access token has expired. Error Code: `1002` The user associated with this access token was not found or is invalid.

Status: 403 HTTP Status Code: `403` Forbidden Error Code: `1021` User account is deactivated. Error Code: `1022` User does not have a Contact Center license. Error Code: `9001` The Contact Center user associated with this bearer token is missing privileges on their role required to operate this request.

Status: 404 HTTP Status Code: `404` Not Found Error Code: `1401` Skill does not exist: $skillId.

Status: 429 HTTP Status Code: `429` Too Many Requests. For more information, see [rate limits](/docs/api/rate-limits/). Error Code: `4001` You have reached the maximum per-second rate limit for this API. Try again later.

Delete a skill

Method: DELETE
Path: /contact_center/skills/{skillId}
Tags: Skills

Delete a skill.

Scopes: contact_center_skill:write:admin

Granular Scopes: contact_center:delete:skill:admin

Rate Limit Label: LIGHT

Responses

Status: 204 HTTP Status Code: `204 ` Skill deleted.

Status: 400 HTTP Status Code: `400` Bad Request Error Code: `1408` More than one matching skill found.

Status: 401 HTTP Status Code: `401` Unauthorized Error Code: `124` Invalid access token. Error Code: `124` Access token has expired. Error Code: `1002` The user associated with this access token was not found or is invalid.

Status: 403 HTTP Status Code: `403` Forbidden Error Code: `1021` User account is deactivated. Error Code: `1022` User does not have a Contact Center license. Error Code: `9001` The Contact Center user associated with this bearer token is missing privileges on their role required to operate this request.

Status: 404 HTTP Status Code: `404` Not Found Error Code: `1401` Skill does not exist: $skillId.

Status: 429 HTTP Status Code: `429` Too Many Requests. For more information, see [rate limits](/docs/api/rate-limits/). Error Code: `4001` You have reached the maximum per-second rate limit for this API. Try again later.

Update a skill

Method: PATCH
Path: /contact_center/skills/{skillId}
Tags: Skills

Use this API to update a skill's name.

Scopes: contact_center_skill:write:admin

Granular Scopes: contact_center:update:skill:admin

Rate Limit Label: LIGHT

Request Body

Content-Type: application/json

skill_name

string — The skill's new name.

Example:

{
  "skill_name": "this is a skill name"
}

Responses

Status: 204 HTTP Status Code: `204` Skill updated.

Status: 400 HTTP Status Code: `400` Bad Request Error Code: `1408` More than one matching skill found.

Status: 401 HTTP Status Code: `401` Unauthorized Error Code: `124` Invalid access token. Error Code: `124` Access token has expired. Error Code: `1002` The user associated with this access token was not found or is invalid.

Status: 403 HTTP Status Code: `403` Forbidden Error Code: `1021` User account is deactivated. Error Code: `1022` User does not have a Contact Center license. Error Code: `9001` The Contact Center user associated with this bearer token is missing privileges on their role required to operate this request.

Status: 404 HTTP Status Code: `404` Not Found Error Code: `1401` Skill does not exist: $skillId.

Status: 429 HTTP Status Code: `429` Too Many Requests. For more information, see [rate limits](/docs/api/rate-limits/). Error Code: `4001` You have reached the maximum per-second rate limit for this API. Try again later.

List skill users

Method: GET
Path: /contact_center/skills/{skillId}/users
Tags: Skills

Retrieve a list of users assigned to a skill.

Scopes: contact_center_user:read:admin

Granular Scopes: contact_center:read:list_skill_users:admin

Rate Limit Label: MEDIUM

Responses

Status: 200 HTTP Status Code: `200` Returns a list of users assigned to a skill.

Content-Type: application/json

next_page_token

string — Use the next page token to paginate through large result sets. A next page token is returned whenever the set of available results exceeds the current page size. This token's expiration period is 15 minutes.
page_size

integer, default: 30 — The number of records returned in a single API call.
users

array — Information about the skill users.

Items:
- cc_user_id
  
  string — The Contact Center user identifier.
- display_name
  
  string — The user's display name.
- user_email
  
  string, format: email — The user's email address.
- user_id
  
  string — The Meetings user identifier.

Example:

{
  "next_page_token": "R4aF9Oj0fVM2hhezJTEmSKaBSkfesDwGy42",
  "page_size": 30,
  "users": [
    {
      "user_id": "IGTRVt3gQ2i-WjoUIjeZxw",
      "cc_user_id": "hKuMAiDdRlSwMkBxR5we7g",
      "display_name": "Jane Doe",
      "user_email": "jchill@example.com"
    }
  ]
}

Status: 400 HTTP Status Code: `400` Bad Request Error Code: `1408` More than one matching skill found.

Status: 401 HTTP Status Code: `401` Unauthorized Error Code: `124` Invalid access token. Error Code: `124` Access token has expired. Error Code: `1002` The user associated with this access token was not found or is invalid.

Status: 403 HTTP Status Code: `403` Forbidden Error Code: `1021` User account is deactivated. Error Code: `1022` User does not have a Contact Center license. Error Code: `9001` The Contact Center user associated with this bearer token is missing privileges on their role required to operate this request.

Status: 404 HTTP Status Code: `404` Not Found Error Code: `1401` Skill does not exist: {skillId}.

Status: 429 HTTP Status Code: `429` Too Many Requests. For more information, see [rate limits](/docs/api/rate-limits/). Error Code: `4001` You have reached the maximum per-second rate limit for this API. Try again later.

List teams

Method: GET
Path: /contact_center/teams
Tags: Teams

Retrieve a list of all teams with details, including supervisors and agents.

Scopes: contact_center_team:read:admin

Granular Scopes: contact_center:read:team:admin

Rate Limit Label: MEDIUM

Responses

Status: 200 HTTP Status Code: `200` Team list returned.

Content-Type: application/json

next_page_token

string — Use the next page token to paginate through large result sets. A next page token is returned whenever the set of available results exceeds the current page size. This token's expiration period is 15 minutes.
page_size

integer, default: 30 — The number of records returned within a single API call.
teams

array — Information about the teams.

Items:
- created_time
  
  string, format: date-time — The team's creation date and time.
- modify_time
  
  string, format: date-time — The team's last modified date and time.
- parent_team_id
  
  string — The team's parent team ID.
- parent_team_name
  
  string — The team's parent team name.
- team_description
  
  string — The team's description.
- team_id
  
  string — The team's ID.
- team_name
  
  string — The team's name.
total_records

integer — The total number of all the records available across pages.

Example:

{
  "next_page_token": "R4aF9Oj0fVM2hhezJTEmSKaBSkfesDwGy42",
  "page_size": 30,
  "total_records": 10,
  "teams": [
    {
      "team_id": "2mDPBg3vSYC_l6crQgeCkA",
      "team_name": "Sales Team",
      "team_description": "This is online team",
      "parent_team_id": "CDl0Wx89Tx-2XBoYVz12DF",
      "parent_team_name": "Online sale team",
      "created_time": "2025-09-09T07:21:57Z",
      "modify_time": "2025-09-09T07:21:57Z"
    }
  ]
}

Status: 400 HTTP Status Code: `400` Bad Request Error Code: `4101` This account does not have the Teams feature enabled.

Status: 403 HTTP Status Code: `403` Forbidden

Status: 404 HTTP Status Code: `404` Not Found

Status: 429 HTTP Status Code: `429` Too Many Requests For more information, see [rate limits](/docs/api/rate-limits/).

Create a team

Method: POST
Path: /contact_center/teams
Tags: Teams

Create a new team.

Scopes: contact_center_team:write:admin

Granular Scopes: contact_center:write:team:admin

Rate Limit Label: LIGHT

Request Body

Content-Type: application/json

parent_team_id (required)

string — The team's parent team ID.
team_name (required)

string — The team's name.
team_description

string — The team's description.

Example:

{
  "team_name": "Online Team",
  "team_description": "This is online team",
  "parent_team_id": "CDl0Wx89Tx-2XBoYVz12DF"
}

Responses

Status: 201 HTTP Status Code: `201` Successfully add new team.

Content-Type: application/json

created_time

string, format: date-time — The date and time when this data was created.
parent_team_id

string — The team's parent team ID.
parent_team_name

string — The team's parent team name.
team_description

string — The team's description.
team_id

string — The team's ID.
team_name

string — The team's name.

Example:

{
  "team_id": "Ikl0Wx89Tx-2XBoYVz53BQ",
  "team_name": "Online Team",
  "team_description": "This is online team",
  "parent_team_id": "CDl0Wx89Tx-2XBoYVz12DF",
  "parent_team_name": "Sales team",
  "created_time": "2022-02-15T09:27:15Z"
}

Status: 400 HTTP Status Code: `400` Bad Request Error Code: `4101` This account does not have the Teams feature enabled. Error Code: `4105` The team name can not be duplicated. Error Code: `4108` Not support concurrent modification of hierarchy operations.

Status: 429 HTTP Status Code: `429` Too Many Requests. For more information, see [rate limits](https://developers.zoom.us/docs/api/rate-limits/).

Get a team

Method: GET
Path: /contact_center/teams/{teamId}
Tags: Teams

Get information about a team.

Scopes: contact_center_team:read:admin

Granular Scopes: contact_center:read:team:admin

Rate Limit Label: LIGHT

Responses

Status: 200 HTTP Status Code: `200` Team detail returned.

Content-Type: application/json

created_time

string, format: date-time — The team's creation date and time.
modify_time

string, format: date-time — The team's last modified date and time.
parent_team_id

string — The team's parent team ID.
parent_team_name

string — The team's parent team name.
team_description

string — The team's description.
team_id

string — The team's ID.
team_name

string — The team's name.

Example:

{
  "team_id": "2mDPBg3vSYC_l6crQgeCkA",
  "team_name": "Online team",
  "parent_team_id": "CDl0Wx89Tx-2XBoYVz12DF",
  "parent_team_name": "Online sale team",
  "team_description": "This is online team",
  "created_time": "2025-06-09T07:21:57Z",
  "modify_time": "2025-06-09T07:21:57Z"
}

Status: 400 HTTP Status Code: `400` Bad Request Error Code: `4101` This account does not have the Teams feature enabled.

Status: 404 HTTP Status Code: `404` Not Found Error Code: `4102` Team does not exist.

Status: 429 HTTP Status Code: `429` Too Many Requests. For more information, see [rate limits](/docs/api/rate-limits/).

Delete a team

Method: DELETE
Path: /contact_center/teams/{teamId}
Tags: Teams

Delete a specified team.

Scopes: contact_center_team:write:admin

Granular Scopes: contact_center:delete:team:admin

Rate Limit Label: HEAVY

Responses

Status: 204 Team deleted.

Status: 400 HTTP Status Code: `400` Bad Request Error Code: `4101` This account does not have the Teams feature enabled. Error Code: `4108` This API does not support concurrent modification of hierarchy operations.

Status: 404 HTTP Status Code: `404` Not Found Error Code: `4102` Team does not exist.

Status: 429 HTTP Status Code: `429` Too Many Requests. For more information, see [rate limits](/docs/api/rate-limits/).

Update a team

Method: PATCH
Path: /contact_center/teams/{teamId}
Tags: Teams

Update a team's details.

Scopes: contact_center_team:write:admin

Granular Scopes: contact_center:update:team:admin

Rate Limit Label: LIGHT

Request Body

Content-Type: application/json

team_name (required)

string — The team's name.
team_description

string — The team's description.

Example:

{
  "team_name": "Online Team",
  "team_description": "This is online team"
}

Responses

Status: 204 Team updated.

Status: 400 HTTP Status Code: `400` Bad Request Error Code: `4101` This account does not have the Teams feature enabled.

Status: 404 HTTP Status Code: `404` Not Found Error Code: `4102` Team does not exist.

Status: 429 HTTP Status Code: `429` Too Many Requests. For more information, see [rate limits](/docs/api/rate-limits/).

List team agents

Method: GET
Path: /contact_center/teams/{teamId}/agents
Tags: Teams

Retrieve a list of a team's assigned agents.

Scopes: contact_center_team:read:admin

Granular Scopes: contact_center:read:team:admin

Rate Limit Label: MEDIUM

Responses

Status: 200 Information about team agents.

Content-Type: application/json

agents

array — A list of agents assigned to the team.

Items:
- cc_user_id
  
  string — The Contact Center user identifier.
- user_display_name
  
  string — The user's display name.
- user_email
  
  string, format: email — The user's email address.
- user_id
  
  string — The Meetings user identifier.
next_page_token

string — Use the next page token to paginate through large result sets. A next page token is returned whenever the set of available results exceeds the current page size. This token's expiration period is 15 minutes.
page_size

integer, default: 30 — The number of records returned in a single API call.
total_records

integer — The total number of all records available across pages.

Example:

{
  "next_page_token": "R4aF9Oj0fVM2hhezJTEmSKaBSkfesDwGy42",
  "page_size": 30,
  "total_records": 10,
  "agents": [
    {
      "user_id": "IGTRVt3gQ2i-WjoUIjeZxw",
      "user_display_name": "Jane Doe",
      "user_email": "jchill@example.com",
      "cc_user_id": "hKuMAiDdRlSwMkBxR5we7g"
    }
  ]
}

Status: 400 HTTP Status Code: `400` Bad Request Error Code: `4101` This account does not have the Teams feature enabled. Error Code: `4106` Unable to process team request. Error Code: `4102` The team does not exist.

Status: 401 HTTP Status Code: `401` Unauthorized Error Code: `124` Invalid access token. Error Code: `124` The access token has expired. Error Code: `1002` The user associated with this access token was not found or is invalid.

Status: 403 HTTP Status Code: `403` Forbidden Error Code: `1021` The user account is deactivated. Error Code: `1022` The user does not have a Contact Center license. Error Code: `9001` The Contact Center user associated with this bearer token lacks the required role privileges to perform this request.

Status: 429 HTTP Status Code: `429` Too Many Requests. For more information, see [rate limits](/docs/api/rate-limits/). Error Code: `4001` You have reached the maximum per-second rate limit for this API. Try again later.

Assign team agents

Method: POST
Path: /contact_center/teams/{teamId}/agents
Tags: Teams

Assign agents to a team. Assign one or more users as agents to the specified team. This API supports partial success - the response includes only the agents that were successfully assigned. Any user IDs that are invalid, unresolvable, or already assigned to the team will not appear in the response. To determine which users were not assigned, compare the returned agents list with the requested user IDs.

Scopes: contact_center_team:write:admin

Granular Scopes: contact_center:write:team:admin

Rate Limit Label: MEDIUM

Request Body

Content-Type: application/json

user_ids

array — The user identifiers. The values can be a mix of email addresses, Meetings user IDs, or Contact Center user IDs.

Items:

string

Example:

{
  "user_ids": [
    "ukAAkZKfROKMSw1bj_RDFQ"
  ]
}

Responses

Status: 201 Team agents assigned.

Content-Type: application/json

agents

array — Information about the assigned agents.

Items:
- assigned_time
  
  string, format: date-time — The date and time when the agent was successfully assigned to the team.
- cc_user_id
  
  string — The Contact Center user identifier.
- user_display_name
  
  string — The user's display name.
- user_email
  
  string, format: email — The user's email address.
- user_id
  
  string — The Meetings user identifier.

Example:

{
  "agents": [
    {
      "user_id": "IGTRVt3gQ2i-WjoUIjeZxw",
      "cc_user_id": "hKuMAiDdRlSwMkBxR5we7g",
      "user_display_name": "Jane Doe",
      "user_email": "jchill@example.com",
      "assigned_time": "2025-09-03T05:07:46Z"
    }
  ]
}

Status: 400 HTTP Status Code: `400` Bad Request Error Code: `4101` This account does not have the Teams feature enabled. Error Code: `4103` The number of user IDs exceeds 100. Error Code: `4102` The team does not exist.

Status: 401 HTTP Status Code: `401` Unauthorized Error Code: `124` Invalid access token. Error Code: `124` The access token has expired. Error Code: `1002` The user associated with this access token was not found or is invalid.

Status: 403 HTTP Status Code: `403` Forbidden Error Code: `1021` The user account is deactivated. Error Code: `1022` The user does not have a Contact Center license. Error Code: `9001` The Contact Center user associated with this bearer token lacks the required role privileges to perform this request.

Status: 429 HTTP Status Code: `429` Too Many Requests. For more information, see [rate limits](/docs/api/rate-limits/). Error Code: `4001` You have reached the maximum per-second rate limit for this API. Try again later.

Unassign team agents

Method: DELETE
Path: /contact_center/teams/{teamId}/agents
Tags: Teams

Unassign agents from a team.

The API is all-or-nothing. On success - Returns HTTP 204 No Content - all supervisors unassigned On failure - Throws an exception and returns an error response - no agents unassigned

Scopes: contact_center_team:write:admin

Granular Scopes: contact_center:delete:team:admin

Rate Limit Label: MEDIUM

Responses

Status: 204 Team agents removed.

Status: 400 HTTP Status Code: `400` Bad Request Error Code: `4101` This account does not have the Teams feature enabled. Error Code: `4108` Concurrent hierarchy modifications are not supported. Error Code: `4102` Team does not exist. Error Code: `4106` An error occurred while processing the team operation.

Status: 401 HTTP Status Code: `401` Unauthorized Error Code: `124` Invalid access token. Error Code: `124` The access token has expired. Error Code: `1002` The user associated with this access token was not found or is invalid.

Status: 403 HTTP Status Code: `403` Forbidden Error Code: `1021` The user account is deactivated. Error Code: `1022` The user does not have a Contact Center license. Error Code: `9001` The Contact Center user associated with this bearer token lacks the required role privileges to perform this request.

Status: 429 HTTP Status Code: `429` Too Many Requests. For more information, see [rate limits](https://developers.zoom.us/docs/api/rate-limits/). Error Code: `4001` You have reached the maximum per-second rate limit for this API. Try again later.

List a team's child teams

Method: GET
Path: /contact_center/teams/{teamId}/children
Tags: Teams

Get a list of a team's child teams.

Scopes: contact_center_team:read:admin

Granular Scopes: contact_center:read:team:admin

Rate Limit Label: MEDIUM

Responses

Status: 200 Team agents' information.

Content-Type: application/json

child_teams

array — The team's child teams.

Items:
- has_children
  
  boolean — Whether the team has a child team.
- level
  
  integer — The team's hierarchy level.
- parent_team_id
  
  string — The team's parent team ID.
- team_id
  
  string — The team's ID.
- team_name
  
  string — The team's name.
level

integer — The current team's hierarchy level.
next_page_token

string — Use the next page token to paginate through large result sets. A next page token is returned whenever the set of available results exceeds the current page size. This token's expiration period is 15 minutes.
page_size

integer, default: 30 — The number of records returned within a single API call.
total_records

integer — The total number of all the records available across pages.

Example:

{
  "next_page_token": "R4aF9Oj0fVM2hhezJTEmSKaBSkfesDwGy42",
  "page_size": 30,
  "total_records": 10,
  "level": 1,
  "child_teams": [
    {
      "team_id": "2mDPBg3vSYC_l6crQgeCkA",
      "team_name": "Parent team",
      "level": 1,
      "parent_team_id": "CDl0Wx89Tx-2XBoYVz12DF",
      "has_children": true
    }
  ]
}

Status: 400 HTTP Status Code: `400` Bad Request Error Code: `4101` This account does not have the Teams feature enabled. Error Code: `4106` Call team server error.

Status: 403 HTTP Status Code: `403` Forbidden

Status: 404 HTTP Status Code: `404` Not Found

Status: 429 HTTP Status Code: `429` Too Many Requests. For more information, see [rate limits](/docs/api/rate-limits/).

Move a team

Method: PATCH
Path: /contact_center/teams/{teamId}/move
Tags: Teams

Move a team's level.

Scopes: contact_center_team:write:admin

Granular Scopes: contact_center:update:team:admin

Rate Limit Label: HEAVY

Request Body

Content-Type: application/json

parent_team_id (required)

string — The parent team's ID.

Example:

{
  "parent_team_id": "CDl0Wx89Tx-2XBoYVz12DF"
}

Responses

Status: 204 Team moved.

Status: 400 HTTP Status Code: `400` Bad Request Error Code: `4101` This account does not have the Teams feature enabled. Error Code: `4108` This API does not support concurrent modification of hierarchy operations.

Status: 401 HTTP Status Code: `401` Unauthorized

Status: 403 HTTP Status Code: `403` Forbidden

Status: 404 HTTP Status Code: `404` Not Found Error Code: `4102` Team does not exist.

Status: 429 HTTP Status Code: `429` Too Many Requests. For more information, see [rate limits](/docs/api/rate-limits/).

List team's parent teams

Method: GET
Path: /contact_center/teams/{teamId}/parents
Tags: Teams

Get a list of a team's parent teams.

Scopes: contact_center_team:read:admin

Granular Scopes: contact_center:read:team:admin

Rate Limit Label: MEDIUM

Responses

Status: 200 Team parent hierarchy returned.

Content-Type: application/json

level (required)

integer — The team's hierarchy level.
team_id (required)

string — The team's ID.
team_name (required)

string — The team's name.
parent_teams

array — The team's parent teams.

Items:
- level
  
  integer — The team's hierarchy level.
- parent_team_id
  
  string — The team's parent team ID.
- team_id
  
  string — The team's ID.
- team_name
  
  string — The team's name.

Example:

{
  "team_id": "2mDPBg3vSYC_l6crQgeCkA",
  "team_name": "Test team",
  "level": 0,
  "parent_teams": [
    {
      "team_id": "2mDPBg3vSYC_l6crQgeCkA",
      "team_name": "Parent team",
      "level": -1,
      "parent_team_id": "CDl0Wx89Tx-2XBoYVz12DF"
    }
  ]
}

Status: 400 HTTP Status Code: `400` Bad Request Error Code: `4101` This account does not have the Teams feature enabled. Error Code: `4106` Call team server error.

Status: 404 HTTP Status Code: `404` Not Found Error Code: `4102` Team does not exist.

Status: 429 HTTP Status Code: `429` Too Many Requests. For more information, see [rate limits](https://developers.zoom.us/docs/api/rate-limits/).

List team supervisors

Method: GET
Path: /contact_center/teams/{teamId}/supervisors
Tags: Teams

Lists the supervisors assigned to a specific team.

Scopes: contact_center_team:read:admin

Granular Scopes: contact_center:read:team:admin

Rate Limit Label: MEDIUM

Responses

Status: 200 Team supervisor's information.

Content-Type: application/json

next_page_token

string — Use the next page token to paginate through large result sets. A next page token is returned whenever the set of available results exceeds the current page size. This token's expiration period is 15 minutes.
page_size

integer, default: 30 — The number of records returned within a single API call.
supervisors

array — A list of supervisor objects containing user information.

Items:
- cc_user_id
  
  string — The Contact Center user identifier.
- user_display_name
  
  string — The user's display name.
- user_email
  
  string, format: email — The user's email address.
- user_id
  
  string — The Meetings user identifier.
total_records

integer — The total number of all records available across pages.

Example:

{
  "next_page_token": "R4aF9Oj0fVM2hhezJTEmSKaBSkfesDwGy42",
  "page_size": 30,
  "total_records": 10,
  "supervisors": [
    {
      "user_id": "IGTRVt3gQ2i-WjoUIjeZxw",
      "user_display_name": "Jane Doe",
      "user_email": "jchill@example.com",
      "cc_user_id": "hKuMAiDdRlSwMkBxR5we7g"
    }
  ]
}

Status: 400 HTTP Status Code: `400` Bad Request Error Code: `4101` This account does not have the Teams feature enabled. Error Code: `4102` The team does not exist. Error Code: `4106` Unable to process team request.

Status: 401 HTTP Status Code: `401` Unauthorized Error Code: `124` Invalid access token. Error Code: `124` The access token has expired. Error Code: `1002` The user associated with this access token was not found or is invalid.

Status: 403 HTTP Status Code: `403` Forbidden Error Code: `1021` The user account is deactivated. Error Code: `1022` The user does not have a Contact Center license. Error Code: `9001` The Contact Center user associated with this bearer token lacks the required role privileges to perform this request.

Status: 429 HTTP Status Code: `429` Too Many Requests. For more information, see [rate limits](/docs/api/rate-limits/). Error Code: `4001` You have reached the maximum per-second rate limit for this API. Try again later.

Assign team supervisors

Method: POST
Path: /contact_center/teams/{teamId}/supervisors
Tags: Teams

Assign supervisors to a team. Assign one or more users as supervisors to the specified team. This API supports partial success - the response includes only the supervisors that were successfully assigned. Any user IDs that are invalid, unresolvable, or already assigned to the team will not appear in the response. To determine which users were not assigned, compare the returned supervisors list with the requested user IDs.

Scopes: contact_center_team:write:admin

Granular Scopes: contact_center:write:team:admin

Rate Limit Label: MEDIUM

Request Body

Content-Type: application/json

user_ids (required)

array — The user identifiers. The values can be a mix of email addresses, Meetings user IDs, or Contact Center user IDs.

Items:

string

Example:

{
  "user_ids": [
    "ukAAkZKfROKMSw1bj_RDFQ"
  ]
}

Responses

Status: 201 Successfully assigned team supervisors.

Content-Type: application/json

supervisors

array — Information about the supervisors.

Items:
- assigned_time
  
  string, format: date-time — The timestamp when the supervisor was successfully assigned.
- cc_user_id
  
  string — The Contact Center user identifier.
- user_display_name
  
  string — The user's display name.
- user_email
  
  string, format: email — The user's email address.
- user_id
  
  string — The Meetings user identifier.

Example:

{
  "supervisors": [
    {
      "user_id": "IGTRVt3gQ2i-WjoUIjeZxw",
      "cc_user_id": "hKuMAiDdRlSwMkBxR5we7g",
      "user_display_name": "Jane Doe",
      "user_email": "jchill@example.com",
      "assigned_time": "2025-09-03T05:07:46Z"
    }
  ]
}

Status: 400 HTTP Status Code: `400` Bad Request Error Code: `4101` This account does not have the Teams feature enabled. Error Code: `4103` The number of user IDs exceeds the limit of 50. Error Code: `4104` The number of supervisors cannot exceed 50. Error Code: `4102` The team does not exist.

Status: 401 HTTP Status Code: `401` Unauthorized Error Code: `124` Invalid access token. Error Code: `124` Access token has expired. Error Code: `1002` The user associated with this access token was not found or is invalid.

Status: 403 HTTP Status Code: `403` Forbidden Error Code: `1021` The user account is deactivated. Error Code: `1022` The user does not have a Contact Center license. Error Code: `9001` The Contact Center user associated with this bearer token lacks the required role privileges to perform this request.

Status: 429 HTTP Status Code: `429` Too Many Requests. For more information, see [rate limits](/docs/api/rate-limits/). Error Code: `4001` You have reached the maximum per-second rate limit for this API. Try again later.

Unassign team supervisors

Method: DELETE
Path: /contact_center/teams/{teamId}/supervisors
Tags: Teams

Unassign supervisors from a team.

The API is all-or-nothing. On success - Returns HTTP 204 No Content - all supervisors unassigned On failure - Throws an exception and returns an error response - no supervisors unassigned

Scopes: contact_center_team:write:admin

Granular Scopes: contact_center:delete:team:admin

Rate Limit Label: MEDIUM

Responses

Status: 204 Team supervisors removed.

Status: 400 HTTP Status Code: `400` Bad Request Error Code: `4101` This account does not have the Teams feature enabled. Error Code: `4102` Team does not exist. Error Code: `4106` An error occurred while processing the team operation. Error Code: `4108` Concurrent hierarchy modifications are not supported."

Status: 401 HTTP Status Code: `401` Unauthorized Error Code: `124` Invalid access token. Error Code: `124` The access token has expired. Error Code: `1002` The user associated with this access token was not found or is invalid.

Status: 403 HTTP Status Code: `403` Forbidden Error Code: `1021` The user account is deactivated. Error Code: `1022` The user does not have a Contact Center license. Error Code: `9001` The Contact Center user associated with this bearer token lacks the required role privileges to perform this request.

Status: 429 HTTP Status Code: `429` Too Many Requests. For more information, see [rate limits](https://developers.zoom.us/docs/api/rate-limits/). Error Code: `4001` You have reached the maximum per-second rate limit for this API. Try again later.

List user profiles

Method: GET
Path: /contact_center/users
Tags: Users

Returns a list of Contact Center users.

Scopes: contact_center_user:read:admin

Granular Scopes: contact_center:read:list_users:admin

Rate Limit Label: MEDIUM

Responses

Status: 200 HTTP Status Code: `200` User list returned.

Content-Type: application/json

next_page_token

string — Use the next page token to paginate through large result sets. A next page token is returned whenever the set of available results exceeds the current page size. This token's expiration period is 15 minutes.
page_size

integer, default: 30 — The number of records returned in a single API call.
total_records

integer — The total number of all records available across pages.
users

array — Information about the users.

Items:
- add_ons_plan
  
  array — This field is optional. The Contact Center plan to assign to the user. Concurrent or non-concurrent depends on the plan type purchased by the account. *`ai_expert_assist` - Contact Center AI Expert Assist or Contact Center AI Expert Assist Concurrent Package. *`zoom_contact_center_for_service_cloud_voice` - Contact Center for Salesforce Voice or Contact Center for Salesforce Voice Concurrent Package.
  
  Items:
  
  string, possible values: "ai_expert_assist"
- billing_account_id
  
  string — The ID of the Zoom Billing account to assign to the user.
- billing_account_name
  
  string — The name of the Zoom Billing account to assign to the user.
- cc_user_id
  
  string — The Contact Center user identifier.
- channel_settings
  
  object — Information about the channel settings.
  - concurrent_email_capacity
    
    integer — The maximum number of concurrent email engagements that can be assigned to a user.
  - concurrent_message_capacity
    
    integer — The maximum number of concurrent messaging engagements that can be assigned to a user.
  - multi_channel_engagements
    
    object — Information about the setting's multi-channel engagements.
    - email_max_agent_load
      
      integer — The percentage of the user's email capacity that determines availability for voice and video engagements. When `enable` is `true` and the user's current email workload is at or below this percentage of `concurrent_email_capacity`, they can receive voice and video engagements.
    - enable
      
      boolean — Whether to allow the user to receive voice or video engagements while handling messaging or email engagements.
    - max_agent_load
      
      integer — The percentage of the user's messaging capacity that determines availability for voice and video engagements. When `enable` is `true` and the user's current messaging workload is at or below this percentage of `concurrent_message_capacity`, they can receive voice and video engagements.
- client_integration
  
  string, possible values: "Default", "Salesforce", "Zendesk", "ServiceNow", "Microsoft_Dynamics_365" — The Contact Center client integration. * `Default` * `Salesforce` * `Zendesk` * `ServiceNow` * `Microsoft_Dynamics_365`
- country_iso_code
  
  string — The [ISO country code](/docs/api/rest/other-references/abbreviation-lists/#countries).
- display_name
  
  string — The user's display name.
- last_modified_time
  
  string, format: date-time — The date and time when this data was last modified.
- modified_by
  
  string — The ID of the user that last modified this data.
- package_name
  
  string, possible values: "essentials", "premium", "elite" — The Contact Center plan to assign to the user. Concurrent or non-concurrent depends on the plan type purchased by the account. *`essentials` - Zoom Contact Center Essentials or Zoom Contact Center Concurrent Essentials Package. *`premium` - Zoom Contact Center Premium or Zoom Contact Center Concurrent Premium Package. *`elite` - Zoom Contact Center Elite or Zoom Contact Center Concurrent Elite Package.
- region_id
  
  string — The Contact Center region identifier.
- region_name
  
  string — The Contact Center region name.
- role_id
  
  string — The user's Contact Center role identifier.
- role_name
  
  string — The user's Contact Center role name.
- status_id
  
  string — The user's status ID.
- status_name
  
  string, possible values: "Offline", "Ready", "Not Ready", "Occupied" — The user's [availability status](https://support.zoom.us/hc/en-us/articles/4470584918541-Setting-availability-status). * Offline * Ready * Not Ready * Occupied * A custom user status, such as "Lunch" or "Away until Monday"
- sub_status_id
  
  string — The user's reason ID when the user status is `Not Ready`.
- sub_status_name
  
  string, possible values: "Break", "End Shift", "Forced", "Meal", "Meeting", "Training" — The user's reason when the user status is `Not Ready`. To query a list of default and custom `Not Ready` reasons, call [List System Statuses](/docs/contact-center/apis/#operation/listSystemStatus) (filter by "queue_opt_out_and_not_ready_status" status_category) Default `Not Ready` reasons: * Break * End Shift * Forced * Meal * Meeting * Training
- teams
  
  array — The teams the user is assigned to.
  
  Items:
  - team_id
    
    string — The ID of the team.
  - team_name
    
    string — The dislpay name of the team.
- user_access
  
  string, possible values: "active", "inactive" — The user's access status. * `active` - The user's role permissions allow them to access the Contact Center. * `inactive` - The user cannot access the Contact Center.
- user_email
  
  string, format: email — The user's email address.
- user_id
  
  string — The Meetings user identifier.

Example:

{
  "next_page_token": "R4aF9Oj0fVM2hhezJTEmSKaBSkfesDwGy42",
  "page_size": 30,
  "total_records": 10,
  "users": [
    {
      "user_id": "IGTRVt3gQ2i-WjoUIjeZxw",
      "cc_user_id": "hKuMAiDdRlSwMkBxR5we7g",
      "display_name": "Jane Doe",
      "user_email": "jchill@example.com",
      "role_id": "0TFVsJqNS82CwkQJLqj1zA",
      "role_name": "Admin",
      "client_integration": "Salesforce",
      "status_id": "2",
      "status_name": "Not Ready",
      "sub_status_id": "21",
      "sub_status_name": "Meal",
      "user_access": "active",
      "modified_by": "IGTRVt3gQ2i-WjoUIjeZxw",
      "last_modified_time": "2022-02-15T09:27:15Z",
      "country_iso_code": "US",
      "region_id": "8f71O6rWT8KFUGQmJIFAdQ",
      "region_name": "Main Region",
      "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": "essentials",
      "add_ons_plan": [
        "ai_expert_assist"
      ],
      "teams": [
        {
          "team_id": "qlU902FoTD-dFi9QnCdZhw",
          "team_name": "Support Team"
        }
      ],
      "billing_account_id": "PEKovuAEQBu5dpeqmxwW1Q",
      "billing_account_name": "main billing account"
    }
  ]
}

Status: 400 HTTP Status Code: `400` Bad Request Error Code: `300` Invalid field: {fieldName} Error Code: `302` Invalid enum value: 'enabled' for the field: 'user_access'. The value must be one of: [active, inactive].

Status: 401 HTTP Status Code: `401` Unauthorized Error Code: `124` Invalid access token. Error Code: `124` Access token has expired. Error Code: `1002` The user associated with this access token was not found or is invalid.

Status: 403 HTTP Status Code: `403` Forbidden Error Code: `9001` The Contact Center user associated with this bearer token is missing privileges on their role required to operate this request. Error Code: `1021` User account is deactivated. Error Code: `1022` User does not have a Contact Center license.

Status: 429 HTTP Status Code: `429` Too Many Requests. For more information, see [rate limits](/docs/api/rest/rate-limits/). Error Code: `4001` You have reached the maximum per-second rate limit for this API. Try again later.

Create a user's profile

Method: POST
Path: /contact_center/users
Tags: Users

Create a Contact Center user.

Scopes: contact_center_user:write:admin

Granular Scopes: contact_center:write:user:admin

Rate Limit Label: LIGHT

Request Body

Content-Type: application/json

add_ons_plan

array — This field is optional. The Contact Center plan to assign to the user. Concurrent or non-concurrent depends on the plan type purchased by the account. *`ai_expert_assist` - Contact Center AI Expert Assist or Contact Center AI Expert Assist Concurrent Package. *`zoom_contact_center_for_service_cloud_voice` - Contact Center for Salesforce Voice or Contact Center for Salesforce Voice Concurrent Package.

Items:

string, possible values: "ai_expert_assist"
billing_account_id

string — The ID of the Zoom Billing account to assign to the user.
channel_settings

object — Information about the channel settings.
- concurrent_email_capacity
  
  integer — The maximum number of concurrent email engagements that can be assigned to a user.
- concurrent_message_capacity
  
  integer — The maximum number of concurrent messaging engagements that can be assigned to a user.
- multi_channel_engagements
  
  object — Information about the setting's multi-channel engagements.
  - email_max_agent_load
    
    integer — The percentage of the user's email capacity that determines availability for voice and video engagements. When `enable` is `true` and the user's current email workload is at or below this percentage of `concurrent_email_capacity`, they can receive voice and video engagements.
  - enable
    
    boolean — Whether to allow the user to receive voice or video engagements while handling messaging or email engagements.
  - max_agent_load
    
    integer — The percentage of the user's messaging capacity that determines availability for voice and video engagements. When `enable` is `true` and the user's current messaging workload is at or below this percentage of `concurrent_message_capacity`, they can receive voice and video engagements.
client_integration

string, possible values: "Default", "Salesforce", "Zendesk", "ServiceNow", "Microsoft_Dynamics_365" — The Contact Center client integration.
client_integration_name

string — The client integration connection name to be assigned to the user.
country_iso_code

string — The [ISO country code](/docs/api/rest/other-references/abbreviation-lists/#countries).
emergency_calling

boolean — Allow users to contact emergency services through their device's native phone system or Zoom Phone.
package_name

string, possible values: "essentials", "premium", "elite" — The Contact Center plan to assign to the user. Concurrent or non-concurrent depends on the plan type purchased by the account. *`essentials` - Zoom Contact Center Essentials or Zoom Contact Center Concurrent Essentials Package. *`premium` - Zoom Contact Center Premium or Zoom Contact Center Concurrent Premium Package. *`elite` - Zoom Contact Center Elite or Zoom Contact Center Concurrent Elite Package.
region_id

string — The Contact Center region identifier.
role_id

string — The user's Contact Center role identifier.
template_id

string — To retrieve the template ID, call the **List user templates** API. The template ID must correspond to a template with a status of `Active` and a type of `Add`. When using an `Add`-type template, omit all other fields in the request to apply the complete template configuration. If both individual field values and a template ID are provided, the individual field values take precedence over the template settings.
user_access

string, possible values: "active", "inactive" — The user's Contact Center access status. * `active` - The user's role permissions allow them to access Contact Center. * `inactive` - The user cannot access Contact Center.
user_email

string, format: email — The user's email address.
user_id

string — The Meetings user identifier.

Example:

{
  "user_id": "IGTRVt3gQ2i-WjoUIjeZxw",
  "user_email": "jchill@example.com",
  "role_id": "0TFVsJqNS82CwkQJLqj1zA",
  "country_iso_code": "US",
  "client_integration": "Salesforce",
  "client_integration_name": "integration-test",
  "user_access": "active",
  "region_id": "8f71O6rWT8KFUGQmJIFAdQ",
  "channel_settings": {
    "multi_channel_engagements": {
      "enable": true,
      "max_agent_load": 50,
      "email_max_agent_load": 50
    },
    "concurrent_message_capacity": 4,
    "concurrent_email_capacity": 4
  },
  "template_id": "OlK7lczzT_e7h6p1Q6wGdg",
  "package_name": "essentials",
  "add_ons_plan": [
    "ai_expert_assist"
  ],
  "emergency_calling": true,
  "billing_account_id": "PEKovuAEQBu5dpeqmxwW1Q"
}

Responses

Status: 201 HTTP Status Code: `201` User created.

Content-Type: application/json

add_ons_plan

array — This field is optional. The Contact Center plan to assign to the user. Concurrent or non-concurrent depends on the plan type purchased by the account. *`ai_expert_assist` - Contact Center AI Expert Assist or Contact Center AI Expert Assist Concurrent Package. *`zoom_contact_center_for_service_cloud_voice` - Contact Center for Salesforce Voice or Contact Center for Salesforce Voice Concurrent Package.

Items:

string, possible values: "ai_expert_assist"
billing_account_id

string — The ID of the Zoom Billing account.
billing_account_name

string — The name of the Zoom Billing account.
cc_user_id

string — The Contact Center user identifier.
channel_settings

object — Information about the channel settings.
- concurrent_email_capacity
  
  integer — The maximum number of concurrent email engagements that can be assigned to a user.
- concurrent_message_capacity
  
  integer — The maximum number of concurrent messaging engagements that can be assigned to a user.
- multi_channel_engagements
  
  object — Information about the setting's multi-channel engagements.
  - email_max_agent_load
    
    integer — The percentage of the user's email capacity that determines availability for voice and video engagements. When `enable` is `true` and the user's current email workload is at or below this percentage of `concurrent_email_capacity`, they can receive voice and video engagements.
  - enable
    
    boolean — Whether to allow the user to receive voice or video engagements while handling messaging or email engagements.
  - max_agent_load
    
    integer — The percentage of the user's messaging capacity that determines availability for voice and video engagements. When `enable` is `true` and the user's current messaging workload is at or below this percentage of `concurrent_message_capacity`, they can receive voice and video engagements.
client_integration

string, possible values: "Default", "Salesforce", "Zendesk", "ServiceNow", "Microsoft_Dynamics_365" — The Contact Center client integration. * `Default` * `Salesforce` * `Zendesk` * `ServiceNow` * `Microsoft_Dynamics_365`
client_integration_name

string — The client integration connection name to be assigned to the user.
country_iso_code

string — The [ISO country code](/docs/api/rest/other-references/abbreviation-lists/#countries).
display_name

string — The user's display name.
emergency_calling

boolean — Allow users to contact emergency services through their device's native phone system or Zoom Phone.
package_name

string, possible values: "essentials", "premium", "elite" — The Contact Center plan to assign to the user. Concurrent or non-concurrent depends on the plan type purchased by the account. *`essentials` - Zoom Contact Center Essentials or Zoom Contact Center Concurrent Essentials Package. *`premium` - Zoom Contact Center Premium or Zoom Contact Center Concurrent Premium Package. *`elite` - Zoom Contact Center Elite or Zoom Contact Center Concurrent Elite Package.
region_id

string — The Contact Center region identifier.
region_name

string — The Contact Center region name.
role_id

string — The user's Contact Center role identifier.
role_name

string — The user's Contact Center role name.
status_id

string — The user's availability status ID.
status_name

string, possible values: "Offline", "Ready", "Not Ready", "Occupied" — The user's [availability status](https://support.zoom.us/hc/en-us/articles/4470584918541-Setting-availability-status). * Offline * Ready * Not Ready * Occupied * A custom user status, such as `Lunch` or `Away until Monday`
user_access

string, possible values: "active", "inactive" — The user's access status. * `active` - The user's role permissions allow them to access the Contact Center. * `inactive` - The user cannot access the Contact Center.
user_email

string, format: email — The user's email address.
user_id

string — The Meetings user identifier.

Example:

{
  "user_id": "IGTRVt3gQ2i-WjoUIjeZxw",
  "cc_user_id": "hKuMAiDdRlSwMkBxR5we7g",
  "display_name": "Jane Doe",
  "user_email": "jchill@example.com",
  "role_id": "0TFVsJqNS82CwkQJLqj1zA",
  "role_name": "Admin",
  "country_iso_code": "US",
  "client_integration": "Salesforce",
  "client_integration_name": "integration-test",
  "status_id": "1",
  "status_name": "Offline",
  "user_access": "active",
  "region_id": "8f71O6rWT8KFUGQmJIFAdQ",
  "region_name": "Main Region",
  "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": "essentials",
  "add_ons_plan": [
    "ai_expert_assist"
  ],
  "emergency_calling": true,
  "billing_account_id": "PEKovuAEQBu5dpeqmxwW1Q",
  "billing_account_name": "multi billing account"
}

Status: 400 HTTP Status Code: `400` Bad Request Error Code: `1003` User creation failed. Try again later. Error Code: `1004` Invalid user ID or user email: $email. Error Code: `1007` User already exists: $email. Error Code: `1009` User ID or user email cannot be empty at the same time. Error Code: `8003` User template not found: $template_id. Error Code: `8004` User template type error: $template_id. Error Code: `8005` User template status error: $template_id. Error Code: `290010` The selected package or add-ons is not enough. Error Code: `1701` The account package does not exist: $zoom_contact_center_package. Error Code: `1702` The account addons package does not exist: $zoom_contact_center_addons_plan. Error Code: `300` Validation failed.

Status: 401 HTTP Status Code: `401` Unauthorized Error Code: `124` Invalid access token. Error Code: `124` Access token has expired. Error Code: `1002` The user associated with this access token was not found or is invalid.

Status: 403 HTTP Status Code: `403` Forbidden Error Code: `1021` User account is deactivated. Error Code: `1022` User does not have a Contact Center license. Error Code: `9001` The Contact Center user associated with this bearer token is missing privileges on their role required to operate this request.

Status: 404 HTTP Status Code: `404` Not Found Error Code: `1006` The account "$client_integration" client integration does not exist. Add it to the "Integrations" function module. Error Code: `2201` Role does not exist: $role_id. Error Code: `2202` Country ISO Code does not exist: $country_iso_code. Error Code: `1017` Region does not exist. Error Code: `1020` The account $client_integration client integration name does not exist. Add it to the Integrations function module.

Status: 429 HTTP Status Code: `429` Too Many Requests. For more information, see [rate limits](/docs/api/rest/rate-limits/). Error Code: `4001` You have reached the maximum per-second rate limit for this API. Try again later.

Batch delete user profiles

Method: DELETE
Path: /contact_center/users
Tags: Users

Batch delete Contact Center users.

Note Either user_ids or user_emails needs to be provided. If both user_ids and user_emails are provided, only user_ids will be used, while user_emails will be ignored.

Scopes: contact_center_user:write:admin

Granular Scopes: contact_center:delete:batch_users:admin

Rate Limit Label: MEDIUM

Responses

Status: 204 HTTP Status Code: `204` Users have been batch-deleted.

Status: 400 HTTP Status Code: `400` Bad Request Error Code: `1015` User IDs or user emails cannot be empty at the same time. Error Code: `1016` Users supports a maximum of 20. Error Code: `300` Invalid user ids: [user_ids].

Status: 401 HTTP Status Code: `401` Unauthorized Error Code: `124` Invalid access token. Error Code: `124` Access token has expired. Error Code: `1002` The user associated with this access token was not found or is invalid.

Status: 403 HTTP Status Code: `403` Forbidden Error Code: `1021` User account is deactivated. Error Code: `1022` User does not have a Contact Center license. Error Code: `9001` The Contact Center user associated with this bearer token is missing privileges on their role required to operate this request.

Status: 404 HTTP Status Code: `404` Not Found Error Code: `1012` User does not exist: [user_ids].

Status: 429 HTTP Status Code: `429` Too Many Requests. For more information, see [rate limits](https://developers.zoom.us/docs/api/rest/rate-limits/). Error Code: `4001` You have reached the maximum per-second rate limit for this API. Try again later.

Batch update user profiles

Method: PATCH
Path: /contact_center/users
Tags: Users

Batch update Contact Center users.

Note For each user object in the users array, you must provide either user_id or user_email. If both user_id and user_email are provided for the same user object, only user_id will be used, while user_email will be ignored.

Scopes: contact_center_user:write:admin

Granular Scopes: contact_center:update:batch_users:admin

Rate Limit Label: MEDIUM

Request Body

Content-Type: application/json

users

array — Information about the users, the maximum number of updated users is 20.

Items:
- add_ons_plan
  
  array — The Contact Center plan to assign to the user. Concurrent or non-concurrent depends on the plan type purchased by the account. *`ai_expert_assist` - Contact Center AI Expert Assist or Contact Center AI Expert Assist Concurrent Package. *`zoom_contact_center_for_service_cloud_voice` - Contact Center for Salesforce Voice or Contact Center for Salesforce Voice Concurrent Package. *`zoom_contact_center_for_epic` - Contact Center for Epic or Contact Center for Epic Concurrent Package.
  
  Items:
  
  string, possible values: "ai_expert_assist", "zoom_contact_center_for_service_cloud_voice", "zoom_contact_center_for_epic" — The Contact Center add-ons plan to assign to the user.
- billing_account_id
  
  string — The ID of the Zoom Billing account to assign to the user.
- client_integration
  
  string, possible values: "Default", "Salesforce", "Zendesk", "ServiceNow", "Microsoft_Dynamics_365" — The Contact Center's client integration.
- client_integration_name
  
  string — The client integration connection name to be assigned to the user.
- country_iso_code
  
  string — The [ISO country code](/docs/api/rest/other-references/abbreviation-lists/#countries).
- package_name
  
  string, possible values: "essentials", "premium", "elite" — The Contact Center plan to assign to the user. Concurrent or non-concurrent depends on the plan type purchased by the account. *`essentials` - Zoom Contact Center Essentials or Zoom Contact Center Concurrent Essentials Package. *`premium` - Zoom Contact Center Premium or Zoom Contact Center Concurrent Premium Package. *`elite` - Zoom Contact Center Elite or Zoom Contact Center Concurrent Elite Package.
- role_id
  
  string — The user's Contact Center role identifier.
- status_id
  
  string — The user's status ID.
- sub_status_id
  
  string — The user's reason ID when the user status is `Not Ready`.
- template_id
  
  string — To retrieve the template ID, call the **List User's Templates** API. The template ID must correspond to a template with a status of `Active` and a type of `Update`. If you provide this value, leave all other fields blank to apply the settings from the template. Only the settings from the template indicated as 'override' will be applied to the user. If you specify both individual values and a template in the request, the individual values take priority over the template settings.
- user_access
  
  string, possible values: "active", "inactive" — The user's access status. * `active` - The user's role permissions allow them to access the Contact Center. * `inactive` - The user cannot access the Contact Center.
- user_email
  
  string, format: email — The user's email address.
- user_id
  
  string — The email, Meetings user ID, or Contact Center ID used to identify the user. This value will not be modified.

Example:

{
  "users": [
    {
      "user_id": "IGTRVt3gQ2i-WjoUIjeZxw",
      "user_email": "jchill@example.com",
      "client_integration": "Salesforce",
      "client_integration_name": "integration-test",
      "role_id": "0TFVsJqNS82CwkQJLqj1zA",
      "user_access": "active",
      "country_iso_code": "US",
      "template_id": "4pPgojTBRC69wEYSlDhffA",
      "package_name": "essentials",
      "add_ons_plan": [
        "ai_expert_assist"
      ],
      "billing_account_id": "shakhajdsdasdkhas"
    }
  ]
}

Responses

Status: 204 HTTP Status Code: `204` Users updated.

Status: 400 HTTP Status Code: `400` Bad Request Error Code: `8003` User template not found: {templateId} Error Code: `8004` User template type error: {templateId} Error Code: `8005` User template status error: {templateId} Error Code: `290010` The selected package or add-ons is not enough. Error Code: `1701` The account package does not exist: $zoom_contact_center_package. Error Code: `1702` The account addons package does not exist: $zoom_contact_center_addons_plan. Error Code: `1113` The status must be 'Not Ready' when updating sub status. Error Code: `2202` Country ISO Code does not exist: {country_iso_code} Error Code: `8006` The Launch URL is invalid: {url} Error Code: `300` Invalid user email: {user_email}. Error Code: `1012` All users do not exist. Error Code: `1009` Either user_id or email is required.

Status: 401 HTTP Status Code: `401` Unauthorized Error Code: `124` Invalid access token. Error Code: `124` Access token has expired. Error Code: `1002` The user associated with this access token was not found or is invalid.

Status: 403 HTTP Status Code: `403` Forbidden Error Code: `1021` User account is deactivated. Error Code: `1022` User does not have a Contact Center license. Error Code: `9001` The Contact Center user associated with this bearer token is missing privileges on their role required to operate this request.

Status: 404 HTTP Status Code: `404` Not Found Error Code: `1001` User does not exist: {user_id}. Error Code: `1101` Status does not exist: {status_id}. Error Code: `1102` Sub status does not exist: {sub_status_id}. Error Code: `2201` Role does not exist: {roleId}. Error Code: `1006` The account {client_integration_name} client integration does not exist. Add it to the 'Integrations' function module. Error Code: `1020` The account {client_integration_name} client integration name does not exist. Add it to the 'Integrations' function module.

Status: 429 HTTP Status Code: `429` Too Many Requests. For more information, see [rate limits](/docs/api/rest/rate-limits/). Error Code: `4001` You have reached the maximum per-second rate limit for this API. Try again later.

Batch create user profiles

Method: POST
Path: /contact_center/users/batch
Tags: Users

Batch create Contact Center users.

Scopes: contact_center_user:write:admin

Granular Scopes: contact_center:write:batch_users:admin

Rate Limit Label: MEDIUM

Request Body

Content-Type: application/json

users

array — Information about the users. The maximum number of created users is 20.

Items:
- add_ons_plan
  
  array — This field is optional. The Contact Center plan to assign to the user. Concurrent or non-concurrent depends on the plan type purchased by the account. *`ai_expert_assist` - Contact Center AI Expert Assist or Contact Center AI Expert Assist Concurrent Package. *`zoom_contact_center_for_service_cloud_voice` - Contact Center for Salesforce Voice or Contact Center for Salesforce Voice Concurrent Package.
  
  Items:
  
  string, possible values: "ai_expert_assist"
- billing_account_id
  
  string — The ID of the Zoom Billing account to assign to the user.
- channel_settings
  
  object — Information about the channel settings.
  - concurrent_email_capacity
    
    integer — The maximum number of concurrent email engagements that can be assigned to a user.
  - concurrent_message_capacity
    
    integer — The maximum number of concurrent messaging engagements that can be assigned to a user.
  - multi_channel_engagements
    
    object — Information about the setting's multi-channel engagements.
    - email_max_agent_load
      
      integer — The percentage of the user's email capacity that determines availability for voice and video engagements. When `enable` is `true` and the user's current email workload is at or below this percentage of `concurrent_email_capacity`, they can receive voice and video engagements.
    - enable
      
      boolean — Whether to allow the user to receive voice or video engagements while handling messaging or email engagements.
    - max_agent_load
      
      integer — The percentage of the user's messaging capacity that determines availability for voice and video engagements. When `enable` is `true` and the user's current messaging workload is at or below this percentage of `concurrent_message_capacity`, they can receive voice and video engagements.
- client_integration
  
  string, possible values: "Default", "Salesforce", "Zendesk", "ServiceNow", "Microsoft_Dynamics_365" — The Contact Center client integration.
- client_integration_name
  
  string — The client integration connection name to be assigned to the user.
- country_iso_code
  
  string — The [ISO country code](/docs/api/rest/other-references/abbreviation-lists/#countries).
- package_name
  
  string, possible values: "essentials", "premium", "elite" — The Contact Center plan to assign to the user. Concurrent or non-concurrent depends on the plan type purchased by the account. *`essentials` - Zoom Contact Center Essentials or Zoom Contact Center Concurrent Essentials Package. *`premium` - Zoom Contact Center Premium or Zoom Contact Center Concurrent Premium Package. *`elite` - Zoom Contact Center Elite or Zoom Contact Center Concurrent Elite Package.
- role_id
  
  string — The user's Contact Center role identifier.
- template_id
  
  string — To retrieve the template ID, call the **List user templates** API. The template ID must correspond to a template with a status of `Active` and a type of `Add`. When using an `Add`-type template, omit all other fields in the request to apply the complete template configuration. If both individual field values and a template ID are provided, the individual field values take precedence over the template settings.
- user_access
  
  string, possible values: "active", "inactive" — The user's access status. * `active` - The user's role permissions allow them to access the Contact Center. * `inactive` - The user can't access the Contact Center.
- user_email
  
  string, format: email — The user's email address.
- user_id
  
  string — The Meetings user identifier.

Example:

{
  "users": [
    {
      "user_id": "IGTRVt3gQ2i-WjoUIjeZxw",
      "user_email": "jchill@example.com",
      "role_id": "0TFVsJqNS82CwkQJLqj1zA",
      "country_iso_code": "US",
      "client_integration": "Salesforce",
      "client_integration_name": "integration-test",
      "user_access": "active",
      "channel_settings": {
        "multi_channel_engagements": {
          "enable": true,
          "max_agent_load": 50,
          "email_max_agent_load": 50
        },
        "concurrent_message_capacity": 4,
        "concurrent_email_capacity": 4
      },
      "template_id": "4pPgojTBRC69wEYSlDhffA",
      "package_name": "essentials",
      "add_ons_plan": [
        "ai_expert_assist"
      ],
      "billing_account_id": "PEKovuAEQBu5dpeqmxwW1Q"
    }
  ]
}

Responses

Status: 201 HTTP Status Code: `201` Users created.

Content-Type: application/json

users

array — Information about the users.

Items:
- add_ons_plan
  
  array — This field is optional. The Contact Center plan to assign to the user. Concurrent or non-concurrent depends on the plan type purchased by the account. *`ai_expert_assist` - Contact Center AI Expert Assist or Contact Center AI Expert Assist Concurrent Package. *`zoom_contact_center_for_service_cloud_voice` - Contact Center for Salesforce Voice or Contact Center for Salesforce Voice Concurrent Package.
  
  Items:
  
  string, possible values: "ai_expert_assist"
- billing_account_id
  
  string — The IDF of the Zoom Billing account to assign to the user.
- billing_account_name
  
  string — The name of the Zoom Billing account to assign to the user.
- cc_user_id
  
  string — The Contact Center user identifier.
- channel_settings
  
  object — Information about the channel settings.
  - concurrent_email_capacity
    
    integer — The maximum number of concurrent email engagements that can be assigned to a user.
  - concurrent_message_capacity
    
    integer — The maximum number of concurrent messaging engagements that can be assigned to a user.
  - multi_channel_engagements
    
    object — Information about the setting's multi-channel engagements.
    - email_max_agent_load
      
      integer — The percentage of the user's email capacity that determines availability for voice and video engagements. When `enable` is `true` and the user's current email workload is at or below this percentage of `concurrent_email_capacity`, they can receive voice and video engagements.
    - enable
      
      boolean — Whether to allow the user to receive voice or video engagements while handling messaging or email engagements.
    - max_agent_load
      
      integer — The percentage of the user's messaging capacity that determines availability for voice and video engagements. When `enable` is `true` and the user's current messaging workload is at or below this percentage of `concurrent_message_capacity`, they can receive voice and video engagements.
- client_integration
  
  string, possible values: "Default", "Salesforce", "Zendesk", "ServiceNow", "Microsoft_Dynamics_365" — The Contact Center client integration. * `Default` * `Salesforce` * `Zendesk` * `ServiceNow` * `Microsoft_Dynamics_365`
- client_integration_name
  
  string — The client integration connection name to be assigned to the user.
- country_iso_code
  
  string — The [ISO country code](/docs/api/rest/other-references/abbreviation-lists/#countries).
- display_name
  
  string — The user's display name.
- package_name
  
  string, possible values: "essentials", "premium", "elite" — The Contact Center plan to assign to the user. Concurrent or non-concurrent depends on the plan type purchased by the account. *`essentials` - Zoom Contact Center Essentials or Zoom Contact Center Concurrent Essentials Package. *`premium` - Zoom Contact Center Premium or Zoom Contact Center Concurrent Premium Package. *`elite` - Zoom Contact Center Elite or Zoom Contact Center Concurrent Elite Package.
- role_id
  
  string — The user's Contact Center role identifier.
- role_name
  
  string — The user's Contact Center role name.
- status_id
  
  string — The user's availability status ID.
- status_name
  
  string, possible values: "Offline", "Ready", "Not Ready", "Occupied" — The user's [availability status](https://support.zoom.us/hc/en-us/articles/4470584918541-Setting-availability-status). * Offline * Ready * Not Ready * Occupied * A custom user status, such as "Lunch" or "Away until Monday"
- user_access
  
  string, possible values: "active", "inactive" — The user's access status. * `active` - The user's role permissions allow them to access the Contact Center. * `inactive` - The user cannot access the Contact Center.
- user_email
  
  string, format: email — The user's email address.
- user_id
  
  string — The Meetings user identifier.

Example:

{
  "users": [
    {
      "user_id": "IGTRVt3gQ2i-WjoUIjeZxw",
      "cc_user_id": "hKuMAiDdRlSwMkBxR5we7g",
      "display_name": "Jane Doe",
      "user_email": "jchill@example.com",
      "role_id": "0TFVsJqNS82CwkQJLqj1zA",
      "role_name": "Admin",
      "country_iso_code": "US",
      "client_integration": "Salesforce",
      "client_integration_name": "integration-test",
      "status_id": "1",
      "status_name": "Offline",
      "user_access": "active",
      "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": "essentials",
      "add_ons_plan": [
        "ai_expert_assist"
      ],
      "billing_account_id": "PEKovuAEQBu5dpeqmxwW1Q",
      "billing_account_name": "main billing account"
    }
  ]
}

Status: 400 HTTP Status Code: `400` Bad Request Error Code: `8003` User template not found: {template_id}. Error Code: `8004` User template type error: {template_id}. Error Code: `8005` User template status error: {template_id}. Error Code: `290010` The selected package or add-ons is not enough. Error Code: `1701` The account package does not exist: {package_name}.. Error Code: `1702` The account addons package does not exist: {add_ons_plan_name}. Error Code: `300` Validation failed. Error Code: `1003` User creation failed. Try again later. Error Code: `1006` The account {client_integration} client integration does not exist. Error Code: `1007` User already exists: {user_email}. Error Code: `1009` User ID or user email cannot be empty at the same time. Error Code: `2202` Country ISO Code does not exist: {country_iso_code}.

Status: 401 HTTP Status Code: `401` Unauthorized Error Code: `124` Invalid access token. Error Code: `124` Access token has expired. Error Code: `1002` The user associated with this access token was not found or is invalid.

Status: 403 HTTP Status Code: `403` Forbidden Error Code: `1021` User account is deactivated. Error Code: `1022` User does not have a Contact Center license. Error Code: `9001` The Contact Center user associated with this bearer token is missing privileges on their role required to operate this request.

Status: 404 HTTP Status Code: `404` Not Found Error Code: `2201` Role does not exist: {role_id}.

Status: 429 HTTP Status Code: `429` Too Many Requests. For more information, see [rate limits](https://developers.zoom.us/docs/api/rate-limits/). Error Code: `4001` You have reached the maximum per-second rate limit for this API. Try again later.

Batch update user status

Method: PATCH
Path: /contact_center/users/status
Tags: Users

Batch update Contact Center users' statuses.

Note Uses all-or-nothing validation - if any user fails validation, no updates are applied and all errors are returned. Only one batch request per account is allowed at a time. Concurrent requests receive a 429 error.

Scopes: contact_center_user:write:admin

Granular Scopes: contact_center:write:batch_users:admin

Rate Limit Label: MEDIUM

Request Body

Content-Type: application/json

users

array — Information about the users, the maximum number of updated users is 20.

Items:
- status_id
  
  string — The user's status ID.
- sub_status_id
  
  string — The user's reason ID when the user status is `Not Ready`.
- user_email
  
  string, format: email — The user's email address.
- user_id
  
  string — The email, Meetings user ID, or Contact Center ID used to identify the user. This value will not be modified.

Example:

{
  "users": [
    {
      "user_id": "IGTRVt3gQ2i-WjoUIjeZxw",
      "user_email": "jchill@example.com",
      "status_id": "1",
      "sub_status_id": "21"
    }
  ]
}

Responses

Status: 204 HTTP Status Code: `204` Users' statuses updated.

Status: 400 HTTP Status Code: `400` Bad Request Error Code: `301` Validation failed. Includes errors array with per-user failures. Error Code: `1009` User ID or user email cannot be empty at the same time. Error Code: `1113` The status must be `Not Ready` when updating sub status. Error Code: `1114` The status does not allow updating to {status_name}. Error Code: `1115` The sub status does not allow updating to {sub_status_name}.

Status: 401 HTTP Status Code: `401` Unauthorized Error Code: `124` Invalid access token. Error Code: `124` Access token has expired. Error Code: `1002` The user associated with this access token was not found or is invalid.

Status: 403 HTTP Status Code: `403` Forbidden Error Code: `1021` User account is deactivated. Error Code: `1022` User does not have a Contact Center license. Error Code: `9001` The Contact Center user associated with this bearer token is missing privileges on their role required to operate this request.

Status: 404 HTTP Status Code: `404` Not Found Error Code: `1012` All users do not exist. Error Code: `1001` User does not exist: {user_id}. Error Code: `1101` Status does not exist: {status_id}. Error Code: `1102` Sub status does not exist: {sub_status_id}.

Status: 429 HTTP Status Code: `429` Too Many Requests. For more information, see [rate limits](https://developers.zoom.us/docs/api/rate-limits/). Error Code: `4001` You have reached the maximum per-second rate limit for this API. Try again later. Error Code: `4001` User update failed. Try again later.

List user templates

Method: GET
Path: /contact_center/users/templates
Tags: Users

Return the user template list

Scopes: contact_center_user:read:admin

Granular Scopes: contact_center:read:user_templates:admin

Rate Limit Label: LIGHT

Responses

Status: 200 User Template list returned.

Content-Type: application/json

next_page_token

string — Use the next page token to paginate through large result sets. A next page token is returned whenever the set of available results exceeds the current page size. This token's expiration period is 15 minutes.
page_size

integer, default: 30 — The number of records returned within a single API call.
total_records

integer — The total number of all the records available across pages.
user_templates

array — Information about the user template.

Items:
- template_id
  
  string — The template ID.
- template_name
  
  string — The template name.
- template_status
  
  string, possible values: "active", "inactive", "needs_attention" — The user template status. * `active` - The user template can be used. * `inactive` - The user template cannot be used. * `needs_attention` - The user template is missing required attributes and cannot be used.
- template_type
  
  string, possible values: "add", "update" — The user template type. * `update` - Update the user type template. * `add` - Create the user type template.

Example:

{
  "next_page_token": "R4aF9Oj0fVM2hhezJTEmSKaBSkfesDwGy42",
  "page_size": 30,
  "total_records": 10,
  "user_templates": [
    {
      "template_id": "OlK7lczzT_e7h6p1Q6wGdg",
      "template_name": "template_update",
      "template_type": "update",
      "template_status": "active"
    }
  ]
}

Status: 400 HTTP Status Code: `400` Bad Request

Status: 404 HTTP Status Code: `404` Not Found

Status: 429 HTTP Status Code: `429` Too Many Requests. For more information, see [rate limits](/docs/api/rest/rate-limits/).

Create a user template

Method: POST
Path: /contact_center/users/templates
Tags: Users

Create a user template.

Scopes: contact_center_user_template:write:admin

Granular Scopes: contact_center:write:user_templates:admin

Rate Limit Label: LIGHT

Request Body

Content-Type: application/json

package (required)

object — The Contact Center plan to assign to the user. Concurrent or non-concurrent depends on the plan type purchased by the account. - `essentials` - Zoom Contact Center Essentials or Zoom Contact Center Concurrent Essentials Package. - `premium` - Zoom Contact Center Premium or Zoom Contact Center Concurrent Premium Package. - `elite` - Zoom Contact Center Elite or Zoom Contact Center Concurrent Elite Package.
- package_name (required)
  
  string, possible values: "essentials", "premium", "elite" — The Contact Center plan to assign to the user. Concurrent or non-concurrent depends on the plan type purchased by the account. - `essentials` - Zoom Contact Center Essentials or Zoom Contact Center Concurrent Essentials Package. - `premium` - Zoom Contact Center Premium or Zoom Contact Center Concurrent Premium Package. - `elite` - Zoom Contact Center Elite or Zoom Contact Center Concurrent Elite Package. When updating the template, it is not required if it is not selected to be applied.
- add_ons_plan
  
  array — The Contact Center plan to assign to the user. Whether the plan is concurrent or non-concurrent depends on the plan type purchased by the account. *`ai_expert_assist` - Contact Center AI Expert Assist or Contact Center AI Expert Assist Concurrent package. *`zoom_contact_center_for_service_cloud_voice` - Contact Center for Salesforce Voice or Contact Center for Salesforce Voice Concurrent package. *`zoom_contact_center_for_epic` - Contact Center for Epic or Contact Center for Epic Concurrent package. *`zoom_contact_center_unified_view_for_servicenow` - Contact Center Unified View for ServiceNow or Contact Center Unified View for ServiceNow Concurrent Package.
  
  Items:
  
  string, possible values: "ai_expert_assist", "zoom_contact_center_for_service_cloud_voice", "zoom_contact_center_for_epic", "zoom_contact_center_unified_view_for_servicenow" — The Contact Center add-ons plan to assign to the user.
- billing_account_id
  
  string — The ID of the Zoom Billing account to assign to the user.
role (required)

string — The role's ID. For `update` template, it is not required if it is not selected to be applied.
selected_blocks (required)

array — User template Select the settings you want to apply. It is only used for `update` type templates. We can choose which settings take effect when applying. For `update` template, it is required.

Items:

string, possible values: "role", "package", "team", "client_integration", "external_url", "user_access", "country_or_region", "region", "mobile_client", "emergency_calling", "assigned_queues", "skills", "engagement_capacity" — The template's block name.
template_name (required)

string — The user template's name.
template_type (required)

string, possible values: "add", "update" — The user template's type. * `add`: It is used to create users. * `update`: It is used to update users.
assigned_queues

object — Information about the assigned queues settings.
- agent_queue_ids
  
  array — Assign user as agent queue ids.
  
  Items:
  
  string — The queue's ID.
- default_outbound_message_queue_id
  
  string — The default message outbound queue's ID.
- default_outbound_voice_queue_id
  
  string — The default voice outbound queue's ID.
- supervisor_queue_ids
  
  array — Assign user as supervisor queue ids.
  
  Items:
  
  string — The queue's ID
client_integration

object — Information about the client integration settings.
- client_integration_application (required)
  
  string — The Contact Center's client integration application. * `Default` * `Salesforce` * `Zendesk` * `ServiceNow` * `Microsoft_Dynamics_365`
- client_integration_name
  
  string — The client integration connection name to be assigned to the user.
country_or_region

string — The [ISO country code](/docs/api/rest/other-references/abbreviation-lists/#countries).
emergency_calling

boolean — Whether to enable emergency calling.
engagement_capacity

object — Information about the engagement capacity settings.
- concurrent_email_capacity
  
  integer — The maximum concurrent email engagements.
- concurrent_message_capacity
  
  integer — The maximum concurrent messaging engagements.
- email_max_agent_load
  
  integer — This agent will receive a new voice or video engagement only when their email load is at or below this percentage.
- message_max_agent_load
  
  integer — This agent will receive a new voice or video engagement only when their messaging load is at or below this percentage.
external_url

object — Information about the external URL settings.
- enable_external_url (required)
  
  boolean — Whether to enable external url.
- external_launch_url (required)
  
  string — The external url. These parameters can be used as command line arguments: `%N` - Full name `%F` - First name `%L` - Last name `%C` - Caller ID number `%E` - Caller ID number (in E.164 format)
mobile_client

boolean — Whether to enable mobile client.
region

string — The region's ID.
skills

array — Information about the skill settings.

Items:
- skill_id (required)
  
  string — The skill's ID.
- proficiency_level
  
  integer — The maximum proficiency level in a skill.
team

object — Information about the team settings.
- team_id (required)
  
  string — The team's ID.
- team_supervisor (required)
  
  boolean — Set whether the user acts as an `agent` or `supervisor` in the team.
template_description

string — The user template's description.
user_access

boolean — The user's access status. * `true` - The user's role permissions allow them to access the Contact Center. * `false` - The user cannot access the Contact Center.

Example:

{
  "template_name": "template name",
  "template_description": "user template.",
  "template_type": "add",
  "selected_blocks": [
    "role"
  ],
  "role": "27302393-4784-11ec-a3cd-122e3e29bb87",
  "package": "essentials",
  "team": {
    "team_id": "G3AfPPKrQZWEkgUCEzUvhA",
    "team_supervisor": true
  },
  "client_integration": {
    "client_integration_application": "Salesforce",
    "client_integration_name": "my integration"
  },
  "external_url": {
    "enable_external_url": true,
    "external_launch_url": "https://www.domain.com"
  },
  "user_access": true,
  "country_or_region": "US",
  "region": "BAAfPPKrQZWEkgUCEzUvhA",
  "mobile_client": false,
  "emergency_calling": true,
  "assigned_queues": {
    "agent_queue_ids": [
      "jUthl0VaRH6mcZepV4ITMA"
    ],
    "supervisor_queue_ids": [
      "jUthl0VaRH6mcZepV4ITMA"
    ],
    "default_outbound_voice_queue_id": "jUthl0VaRH6mcZepV4ITMA",
    "default_outbound_message_queue_id": "jUthl0VaRH6mcZepV4ITMA"
  },
  "skills": [
    {
      "skill_id": "s51M536ZjSgi8o_rzmgQBrA",
      "proficiency_level": 3
    }
  ],
  "engagement_capacity": {
    "concurrent_email_capacity": 5,
    "concurrent_message_capacity": 6,
    "email_max_agent_load": 10,
    "message_max_agent_load": 10
  }
}

Responses

Status: 201 HTTP Status Code: `201` Template created.

Content-Type: application/json

template_id (required)

string — The user template identifier.
assigned_queues

object — Information about the assigned queues settings.
- agent_queue_ids
  
  array — Assign user as agent queue ids.
  
  Items:
  
  string — The queue's ID.
- default_outbound_message_queue_id
  
  string — The default message outbound queue's ID.
- default_outbound_voice_queue_id
  
  string — The default voice outbound queue's ID.
- supervisor_queue_ids
  
  array — Assign user as supervisor queue ids.
  
  Items:
  
  string — The queue's ID
client_integration

object — Information about the client integration settings.
- client_integration_application (required)
  
  string — The Contact Center's client integration application. * `Default` * `Salesforce` * `Zendesk` * `ServiceNow` * `Microsoft_Dynamics_365`
- client_integration_name
  
  string — The client integration connection name to be assigned to the user.
country_or_region

string — The [ISO country code](/docs/api/rest/other-references/abbreviation-lists/#countries).
created_by

string — The ID of the user that created this data.
created_time

string, format: date-time — The date and time when this data was created.
emergency_calling

boolean — Whether to enable emergency calling.
engagement_capacity

object — Information about the engagement capacity settings.
- concurrent_email_capacity
  
  integer — The maximum concurrent email engagements.
- concurrent_message_capacity
  
  integer — The maximum concurrent messaging engagements.
- email_max_agent_load
  
  integer — This agent will receive a new voice or video engagement only when their email load is at or below this percentage.
- message_max_agent_load
  
  integer — This agent will receive a new voice or video engagement only when their messaging load is at or below this percentage.
external_url

object — Information about the external URL settings.
- enable_external_url (required)
  
  boolean — Whether to enable external url.
- external_launch_url (required)
  
  string — The external url. These parameters can be used as command line arguments: `%N` - Full name `%F` - First name `%L` - Last name `%C` - Caller ID number `%E` - Caller ID number (in E.164 format)
last_modified_time

string, format: date-time — The date and time when this data was last modified.
mobile_client

boolean — Whether to enable mobile client.
modified_by

string — The ID of the user that last modified this data.
package

object — The Contact Center plan to assign to the user. Concurrent or non-concurrent depends on the plan type purchased by the account. - `essentials` - Zoom Contact Center Essentials or Zoom Contact Center Concurrent Essentials Package. - `premium` - Zoom Contact Center Premium or Zoom Contact Center Concurrent Premium Package. - `elite` - Zoom Contact Center Elite or Zoom Contact Center Concurrent Elite Package.
- package_name (required)
  
  string, possible values: "essentials", "premium", "elite" — The Contact Center plan to assign to the user. Concurrent or non-concurrent depends on the plan type purchased by the account. - `essentials` - Zoom Contact Center Essentials or Zoom Contact Center Concurrent Essentials Package. - `premium` - Zoom Contact Center Premium or Zoom Contact Center Concurrent Premium Package. - `elite` - Zoom Contact Center Elite or Zoom Contact Center Concurrent Elite Package. When updating the template, it is not required if it is not selected to be applied.
- add_ons_plan
  
  array — The Contact Center plan to assign to the user. Whether the plan is concurrent or non-concurrent depends on the plan type purchased by the account. *`ai_expert_assist` - Contact Center AI Expert Assist or Contact Center AI Expert Assist Concurrent package. *`zoom_contact_center_for_service_cloud_voice` - Contact Center for Salesforce Voice or Contact Center for Salesforce Voice Concurrent package. *`zoom_contact_center_for_epic` - Contact Center for Epic or Contact Center for Epic Concurrent package. *`zoom_contact_center_unified_view_for_servicenow` - Contact Center Unified View for ServiceNow or Contact Center Unified View for ServiceNow Concurrent Package.
  
  Items:
  
  string, possible values: "ai_expert_assist", "zoom_contact_center_for_service_cloud_voice", "zoom_contact_center_for_epic", "zoom_contact_center_unified_view_for_servicenow" — The Contact Center add-ons plan to assign to the user.
- billing_account_id
  
  string — The ID of the Zoom Billing account to assign to the user.
region

string — The region's ID.
role

string — The role's ID. For `update` template, it is not required if it is not selected to be applied.
selected_blocks

array — User template Select the settings you want to apply. It is only used for `update` type templates. We can choose which settings take effect when applying. For `update` template, it is required.

Items:

string, possible values: "role", "package", "team", "client_integration", "external_url", "user_access", "country_or_region", "region", "mobile_client", "emergency_calling", "assigned_queues", "skills", "engagement_capacity" — The template's block name.
skills

array — Information about the skill settings.

Items:
- skill_id (required)
  
  string — The skill's ID.
- proficiency_level
  
  integer — The maximum proficiency level in a skill.
team

object — Information about the team settings.
- team_id (required)
  
  string — The team's ID.
- team_supervisor (required)
  
  boolean — Set whether the user acts as an `agent` or `supervisor` in the team.
template_description

string — The user template's description.
template_name

string — The user template's name.
template_status

string, possible values: "active", "inactive", "needs_attention" — The template's status. - `active` - Available templates - `inactive` - Unavailable template - `needs_attention` - Unavailable template with invalid required fields
template_type

string, possible values: "add", "update" — The user template's type. * `add`: It is used to create users. * `update`: It is used to update users.
user_access

boolean — The user's access status. * `true` - The user's role permissions allow them to access the Contact Center. * `false` - The user cannot access the Contact Center.

Example:

{
  "template_id": "qmLKCot6QfSGwmPKFCgmCg",
  "template_name": "template name",
  "template_description": "user template.",
  "template_type": "add",
  "template_status": "active",
  "selected_blocks": [
    "role"
  ],
  "role": "27302393-4784-11ec-a3cd-122e3e29bb87",
  "package": "essentials",
  "team": {
    "team_id": "G3AfPPKrQZWEkgUCEzUvhA",
    "team_supervisor": true
  },
  "client_integration": {
    "client_integration_application": "Salesforce",
    "client_integration_name": "my integration"
  },
  "external_url": {
    "enable_external_url": true,
    "external_launch_url": "https://www.domain.com"
  },
  "user_access": true,
  "country_or_region": "US",
  "region": "BAAfPPKrQZWEkgUCEzUvhA",
  "mobile_client": false,
  "emergency_calling": true,
  "assigned_queues": {
    "agent_queue_ids": [
      "jUthl0VaRH6mcZepV4ITMA"
    ],
    "supervisor_queue_ids": [
      "jUthl0VaRH6mcZepV4ITMA"
    ],
    "default_outbound_voice_queue_id": "jUthl0VaRH6mcZepV4ITMA",
    "default_outbound_message_queue_id": "jUthl0VaRH6mcZepV4ITMA"
  },
  "skills": [
    {
      "skill_id": "s51M536ZjSgi8o_rzmgQBrA",
      "proficiency_level": 3
    }
  ],
  "engagement_capacity": {
    "concurrent_email_capacity": 5,
    "concurrent_message_capacity": 6,
    "email_max_agent_load": 10,
    "message_max_agent_load": 10
  },
  "modified_by": "IGTRVt3gQ2i-WjoUIjeZxw",
  "last_modified_time": "2022-02-15T09:27:15Z",
  "created_by": "IGTRVt3gQ2i",
  "created_time": "2022-02-15T09:27:15Z"
}

Status: 400 HTTP Status Code: `400` Bad Request Error Code: `640001` The template name is duplicate. Error Code: `640002` Cannot switch the template to this status. Error Code: `640003` Template name is too long. Error Code: `640004` Template description is too long. Error Code: `640005` Template name is required. Error Code: `640007` Template type is required. Error Code: `640011` Too many templates. Error Code: `640014` Invalid template setting value.

Status: 401 HTTP Status Code: `401` Unauthorized Error Code: `124` Invalid access token. Error Code: `124` Access token has expired. Error Code: `1002` The user associated with this access token was not found or is invalid.

Status: 403 HTTP Status Code: `403` Forbidden Error Code: `1021` User account is deactivated. Error Code: `1022` User does not have a Contact Center license. Error Code: `9001` The Contact Center user associated with this bearer token is missing privileges on their role required to operate this request.

Status: 429 HTTP Status Code: `429` Too Many Requests. For more information, see [rate limits](https://developers.zoom.us/docs/api/rate-limits/). Error Code: `4001` You have reached the maximum per-second rate limit for this API. Try again later.

Get a user template

Method: GET
Path: /contact_center/users/templates/{templateId}
Tags: Users

Get a user template.

Scopes: contact_center_user_template:read:admin

Granular Scopes: contact_center:read:user_templates:admin

Rate Limit Label: LIGHT

Responses

Status: 200 HTTP Status Code: `200` User template returned

Content-Type: application/json

template_id (required)

string — The user template identifier.
assigned_queues

object — Information about the assigned queues settings.
- agent_queue_ids
  
  array — Assign user as agent queue ids.
  
  Items:
  
  string — The queue's ID.
- default_outbound_message_queue_id
  
  string — The default message outbound queue's ID.
- default_outbound_voice_queue_id
  
  string — The default voice outbound queue's ID.
- supervisor_queue_ids
  
  array — Assign user as supervisor queue ids.
  
  Items:
  
  string — The queue's ID
client_integration

object — Information about the client integration settings.
- client_integration_application (required)
  
  string — The Contact Center's client integration application. * `Default` * `Salesforce` * `Zendesk` * `ServiceNow` * `Microsoft_Dynamics_365`
- client_integration_name
  
  string — The client integration connection name to be assigned to the user.
country_or_region

string — The [ISO country code](/docs/api/rest/other-references/abbreviation-lists/#countries).
created_by

string — The ID of the user that created this data.
created_time

string, format: date-time — The date and time when this data was created.
emergency_calling

boolean — Whether to enable emergency calling.
engagement_capacity

object — Information about the engagement capacity settings.
- concurrent_email_capacity
  
  integer — The maximum concurrent email engagements.
- concurrent_message_capacity
  
  integer — The maximum concurrent messaging engagements.
- email_max_agent_load
  
  integer — This agent will receive a new voice or video engagement only when their email load is at or below this percentage.
- message_max_agent_load
  
  integer — This agent will receive a new voice or video engagement only when their messaging load is at or below this percentage.
external_url

object — Information about the external URL settings.
- enable_external_url (required)
  
  boolean — Whether to enable external url.
- external_launch_url (required)
  
  string — The external url. These parameters can be used as command line arguments: `%N` - Full name `%F` - First name `%L` - Last name `%C` - Caller ID number `%E` - Caller ID number (in E.164 format)
last_modified_time

string, format: date-time — The date and time when this data was last modified.
mobile_client

boolean — Whether to enable mobile client.
modified_by

string — The ID of the user that last modified this data.
package

object — The Zoom Contact Center plan to assign to the user. Concurrent or non-concurrent depends on the plan type purchased by the account. `essentials` - Zoom Contact Center Essentials or Zoom Contact Center Concurrent Essentials Package. `premium` - Zoom Contact Center Premium or Zoom Contact Center Concurrent Premium Package. `elite` - Zoom Contact Center Elite or Zoom Contact Center Concurrent Elite Package.
- package_name (required)
  
  string, possible values: "essentials", "premium", "elite" — The Zoom Contact Center plan to assign to the user. Concurrent or non-concurrent depends on the plan type purchased by the account. `essentials` - Zoom Contact Center Essentials or Zoom Contact Center Concurrent Essentials Package. `premium` - Zoom Contact Center Premium or Zoom Contact Center Concurrent Premium Package. `elite` - Zoom Contact Center Elite or Zoom Contact Center Concurrent Elite Package. When updating the template, it is not required if it is not selected to be applied.
- add_ons_plan
  
  array — The Zoom Contact Center plan to assign to the user. Concurrent or non-concurrent depends on the plan type purchased by the account. `ai_expert_assist` - Zoom Contact Center AI Expert Assist or Zoom Contact Center AI Expert Assist Concurrent Package.
  
  Items:
  
  string — The Zoom Contact Center add-ons plan to assign to the user.
- billing_account_id
  
  string — The ID of the Zoom Billing account to assign to the user.
region

string — The region's ID.
role

string — The role's ID. For `update` template, it is not required if it is not selected to be applied.
selected_blocks

array — User template Select the settings you want to apply. It is only used for `update` type templates. We can choose which settings take effect when applying. For `update` template, it is required.

Items:

string, possible values: "role", "package", "team", "client_integration", "external_url", "user_access", "country_or_region", "region", "mobile_client", "emergency_calling", "assigned_queues", "skills", "engagement_capacity" — The template's block name.
skills

array — Information about the skill settings.

Items:
- skill_id (required)
  
  string — The skill's ID.
- proficiency_level
  
  integer — The maximum proficiency level in a skill.
team

object — Information about the team settings.
- team_id (required)
  
  string — The team's ID.
- team_supervisor (required)
  
  boolean — Set whether the user acts as an `agent` or `supervisor` in the team.
template_description

string — The user template's description.
template_name

string — The user template's name.
template_status

string, possible values: "active", "inactive", "needs_attention" — The template's status. `active` Available templates `inactive` Unavailable template `needs_attention` Unavailable template with invalid required fields
template_type

string, possible values: "add", "update" — The user template's type. * `add`: It is used to create users. * `update`: It is used to update users.
user_access

boolean — The user's access status. * `true` - The user's role permissions allow them to access the Contact Center. * `false` - The user cannot access the Contact Center.

Example:

{
  "template_id": "qmLKCot6QfSGwmPKFCgmCg",
  "template_name": "template name",
  "template_description": "user template.",
  "template_type": "add",
  "template_status": "active",
  "selected_blocks": [
    "role"
  ],
  "role": "27302393-4784-11ec-a3cd-122e3e29bb87",
  "package": "essentials",
  "team": {
    "team_id": "G3AfPPKrQZWEkgUCEzUvhA",
    "team_supervisor": true
  },
  "client_integration": {
    "client_integration_application": "Salesforce",
    "client_integration_name": "my integration"
  },
  "external_url": {
    "enable_external_url": true,
    "external_launch_url": "https://www.domain.com"
  },
  "user_access": true,
  "country_or_region": "US",
  "region": "BAAfPPKrQZWEkgUCEzUvhA",
  "mobile_client": false,
  "emergency_calling": true,
  "assigned_queues": {
    "agent_queue_ids": [
      "jUthl0VaRH6mcZepV4ITMA"
    ],
    "supervisor_queue_ids": [
      "jUthl0VaRH6mcZepV4ITMA"
    ],
    "default_outbound_voice_queue_id": "jUthl0VaRH6mcZepV4ITMA",
    "default_outbound_message_queue_id": "jUthl0VaRH6mcZepV4ITMA"
  },
  "skills": [
    {
      "skill_id": "s51M536ZjSgi8o_rzmgQBrA",
      "proficiency_level": 3
    }
  ],
  "engagement_capacity": {
    "concurrent_email_capacity": 5,
    "concurrent_message_capacity": 6,
    "email_max_agent_load": 10,
    "message_max_agent_load": 10
  },
  "modified_by": "IGTRVt3gQ2i-WjoUIjeZxw",
  "last_modified_time": "2022-02-15T09:27:15Z",
  "created_by": "IGTRVt3gQ2i",
  "created_time": "2022-02-15T09:27:15Z"
}

Status: 401 HTTP Status Code: `401` Unauthorized

Status: 403 HTTP Status Code: `403` Forbidden

Status: 404 HTTP Status Code: `404` Not Found Error Code: `640000` The user template not found.

Status: 429 HTTP Status Code: `429` Too Many Requests. For more information, see [rate limits](https://developers.zoom.us/docs/api/rate-limits/).

Delete a user template

Method: DELETE
Path: /contact_center/users/templates/{templateId}
Tags: Users

Delete a user template.

Scopes: contact_center_user_template:write:admin

Granular Scopes: contact_center:delete:user_templates:admin

Rate Limit Label: LIGHT

Responses

Status: 204 HTTP Status Code: `204` Template deleted.

Status: 400 HTTP Status Code: `400` Bad Request Error Code: `640015` More than one matching user template found.

Status: 401 HTTP Status Code: `401` Unauthorized Error Code: `124` Invalid access token. Error Code: `124` Access token has expired. Error Code: `1002` The user associated with this access token was not found or is invalid.

Status: 403 HTTP Status Code: `403` Forbidden Error Code: `1021` User account is deactivated. Error Code: `1022` User does not have a Contact Center license. Error Code: `9001` The Contact Center user associated with this bearer token is missing privileges on their role required to operate this request.

Status: 404 HTTP Status Code: `404` Not Found Error Code: `640000` The user template not found.

Status: 429 HTTP Status Code: `429` Too Many Requests. For more information, see [rate limits](https://developers.zoom.us/docs/api/rate-limits/). Error Code: `4001` You have reached the maximum per-second rate limit for this API. Try again later.

Update a user template

Method: PATCH
Path: /contact_center/users/templates/{templateId}
Tags: Users

Update a user template.

Scopes: contact_center_user_template:write:admin

Granular Scopes: contact_center:update:user_templates:admin

Rate Limit Label: MEDIUM

Request Body

Content-Type: application/json

assigned_queues

object — Information about the assigned queues settings.
- agent_queue_ids
  
  array — Assign user as agent queue IDs.
  
  Items:
  
  string — The queue's ID.
- default_outbound_message_queue_id
  
  string — The default message outbound queue's ID.
- default_outbound_voice_queue_id
  
  string — The default voice outbound queue's ID.
- supervisor_queue_ids
  
  array — Assign user as supervisor queue IDs.
  
  Items:
  
  string — The queue's ID.
client_integration

object — Information about the client integration settings.
- client_integration_application (required)
  
  string — The Contact Center's client integration application.
- client_integration_name
  
  string — The client integration connection name to be assigned to the user.
country_or_region

string — The [ISO country code](/docs/api/references/abbreviations/#countries).
emergency_calling

boolean — Whether to enable emergency calling.
engagement_capacity

object — Information about the engagement capacity settings.
- concurrent_email_capacity
  
  integer — The maximum concurrent email engagements.
- concurrent_message_capacity
  
  integer — The maximum concurrent messaging engagements.
- email_max_agent_load
  
  integer — This agent receives a new voice or video engagement only when their email load is at or below this percentage.
- message_max_agent_load
  
  integer — This agent receives a new voice or video engagement only when their messaging load is at or below this percentage.
external_url

object — Information about the external URL settings.
- enable_external_url (required)
  
  boolean — Whether to enable external URLs.
- external_launch_url (required)
  
  string — The external URL. Use these parameters as command line arguments. `%N` - Full name `%F` - First name `%L` - Last name `%C` - Caller ID number `%E` - Caller ID number in E.164 format
mobile_client

boolean — Whether to enable mobile client.
package

object — The Contact Center plan to assign to the user. Concurrent or non-concurrent depends on the plan type purchased by the account. - `essentials` - Zoom Contact Center Essentials or Zoom Contact Center Concurrent Essentials Package. - `premium` - Zoom Contact Center Premium or Zoom Contact Center Concurrent Premium Package. - `elite` - Zoom Contact Center Elite or Zoom Contact Center Concurrent Elite Package.
- package_name (required)
  
  string, possible values: "essentials", "premium", "elite" — The Contact Center plan to assign to the user. Concurrent or non-concurrent depends on the plan type purchased by the account. - `essentials` - Zoom Contact Center Essentials or Zoom Contact Center Concurrent Essentials Package. - `premium` - Zoom Contact Center Premium or Zoom Contact Center Concurrent Premium Package. - `elite` - Zoom Contact Center Elite or Zoom Contact Center Concurrent Elite Package. When updating the template, it is not required if it is not selected to be applied.
- add_ons_plan
  
  array — The Contact Center plan to assign to the user. Concurrent or non-concurrent depends on the plan type purchased by the account. - `ai_expert_assist` - Zoom Contact Center AI Expert Assist or Zoom Contact Center AI Expert Assist Concurrent Package.
  
  Items:
  
  string — The Contact Center add-ons plan to assign to the user.
- billing_account_id
  
  string — The ID of the Zoom Billing account to assign to the user.
region

string — The region's ID.
role

string — The role's ID. Not required for `update` templates if it is not selected to be applied.
selected_blocks

array — Select the user template settings to apply. Only used for `update` type templates. Choose which settings take effect when applying. **Required** for `update` template.

Items:

string, possible values: "role", "package", "team", "client_integration", "external_url", "user_access", "country_or_region", "region", "mobile_client", "emergency_calling", "assigned_queues", "skills", "engagement_capacity", "assigned_numbers", "assigned_intents" — The template's block name.
skills

array — Information about the skill settings.

Items:
- skill_id (required)
  
  string — The skill's ID.
- proficiency_level
  
  integer — The maximum proficiency level in a skill.
team

object — Information about the team settings.
- team_id (required)
  
  string — The team's ID.
- team_supervisor (required)
  
  boolean — Whether the user acts as an `agent` or `supervisor` in the team.
template_description

string — The user template's description.
template_name

string — The user template's name.
user_access

boolean — The user's access status. * `true` - The user's role permissions allow them to access the Contact Center. * `false` - The user cannot access the Contact Center.

Example:

{
  "template_name": "template name",
  "template_description": "user template.",
  "selected_blocks": [
    "role"
  ],
  "role": "27302393-4784-11ec-a3cd-122e3e29bb87",
  "package": "essentials",
  "team": {
    "team_id": "G3AfPPKrQZWEkgUCEzUvhA",
    "team_supervisor": true
  },
  "client_integration": {
    "client_integration_application": "Salesforce",
    "client_integration_name": "my integration"
  },
  "external_url": {
    "enable_external_url": true,
    "external_launch_url": "https://www.example.com"
  },
  "user_access": true,
  "country_or_region": "US",
  "region": "BAAfPPKrQZWEkgUCEzUvhA",
  "mobile_client": false,
  "emergency_calling": true,
  "assigned_queues": {
    "agent_queue_ids": [
      "jUthl0VaRH6mcZepV4ITMA"
    ],
    "supervisor_queue_ids": [
      "jUthl0VaRH6mcZepV4ITMA"
    ],
    "default_outbound_voice_queue_id": "jUthl0VaRH6mcZepV4ITMA",
    "default_outbound_message_queue_id": "jUthl0VaRH6mcZepV4ITMA"
  },
  "skills": [
    {
      "skill_id": "s51M536ZjSgi8o_rzmgQBrA",
      "proficiency_level": 3
    }
  ],
  "engagement_capacity": {
    "concurrent_email_capacity": 5,
    "concurrent_message_capacity": 6,
    "email_max_agent_load": 10,
    "message_max_agent_load": 10
  }
}

Responses

Status: 204 HTTP Status Code: `204` Template updated.

Status: 400 HTTP Status Code: `400` Bad Request Error Code: `640001` The template name is duplicate. Error Code: `640002` Cannot switch the template to this status. Error Code: `640003` Template name is too long. Error Code: `640004` Template description is too long. Error Code: `640005` Template name is required. Error Code: `640007` Template type is required. Error Code: `640011` Too many templates. Error Code: `640014` Invalid template setting value. Error Code: `640015` More than one matching user template found.

Status: 401 HTTP Status Code: `401` Unauthorized Error Code: `124` Invalid access token. Error Code: `124` Access token has expired. Error Code: `1002` The user associated with this access token was not found or is invalid.

Status: 403 HTTP Status Code: `403` Forbidden Error Code: `1021` User account is deactivated. Error Code: `1022` User does not have a Contact Center license. Error Code: `9001` The Contact Center user associated with this bearer token is missing privileges on their role required to operate this request.

Status: 404 HTTP Status Code: `404` Not Found Error Code: `640000` The user template not found.

Status: 429 HTTP Status Code: `429` Too Many Requests. For more information, see [rate limits](https://developers.zoom.us/docs/api/rate-limits/). Error Code: `4001` You have reached the maximum per-second rate limit for this API. Try again later.

Get a user's profile

Method: GET
Path: /contact_center/users/{userId}
Tags: Users

Retrieve a Contact Center user.

Scopes: contact_center_user:read:admin

Granular Scopes: contact_center:read:user:admin

Rate Limit Label: LIGHT

Responses

Status: 200 HTTP Status Code: `200` User profile returned.

Content-Type: application/json

add_ons_plan

array — The Contact Center plan to assign to the user. Concurrent or non-concurrent depends on the plan type purchased by the account. *`ai_expert_assist` - Contact Center AI Expert Assist or Contact Center AI Expert Assist Concurrent Package. *`zoom_contact_center_for_service_cloud_voice` - Contact Center for Salesforce Voice or Contact Center for Salesforce Voice Concurrent Package.

Items:

string, possible values: "ai_expert_assist"
billing_account_id

string — The ID of the Zoom Billing account to assign to the user.
billing_account_name

string — The name of the Zoom Billing account to assign to the user.
cc_user_id

string — The Contact Center user identifier.
channel_settings

object — Information about the channel settings.
- concurrent_email_capacity
  
  integer — The maximum number of concurrent email engagements that can be assigned to a user.
- concurrent_message_capacity
  
  integer — The maximum number of concurrent messaging engagements that can be assigned to a user.
- multi_channel_engagements
  
  object — Information about the setting's multi-channel engagements.
  - email_max_agent_load
    
    integer — The percentage of the user's email capacity that determines availability for voice and video engagements. When `enable` is `true` and the user's current email workload is at or below this percentage of `concurrent_email_capacity`, they can receive voice and video engagements.
  - enable
    
    boolean — Whether to allow the user to receive voice or video engagements while handling messaging or email engagements.
  - max_agent_load
    
    integer — The percentage of the user's messaging capacity that determines availability for voice and video engagements. When `enable` is `true` and the user's current messaging workload is at or below this percentage of `concurrent_message_capacity`, they can receive voice and video engagements.
client_integration

string, possible values: "Default", "Salesforce", "Zendesk", "ServiceNow", "Microsoft_Dynamics_365" — The contact center's client integration.
client_integration_name

string — The client integration connection name to be assigned to the user.
country_iso_code

string — The [ISO country code](/docs/api/rest/other-references/abbreviation-lists/#countries).
display_name

string — The user's display name.
emergency_calling

boolean — Allow users to contact emergency services through their device's native phone system or Zoom Phone.
package_name

string, possible values: "essentials", "premium", "elite" — The Contact Center plan to assign to the user. Concurrent or non-concurrent depends on the plan type purchased by the account. *`essentials` - Zoom Contact Center Essentials or Zoom Contact Center Concurrent Essentials Package. *`premium` - Zoom Contact Center Premium or Zoom Contact Center Concurrent Premium Package. *`elite` - Zoom Contact Center Elite or Zoom Contact Center Concurrent Elite Package.
region_id

string — The Contact Center region identifier.
region_name

string — The Contact Center region name.
role_id

string — The user's Contact Center role identifier.
role_name

string — The user's Contact Center role name.
status_id

string — The user's status ID.
status_name

string, possible values: "Offline", "Ready", "Not Ready", "Occupied" — The user's [availability status](https://support.zoom.us/hc/en-us/articles/4470584918541-Setting-availability-status). * Offline (ID = `0`) * Ready (ID = `1`) * Not Ready (ID = `2`) * Occupied (ID = `3`) * A custom user status (ID = `4`), such as "Lunch" or "Away until Monday"
sub_status_id

string — The user's reason ID when the user status is `Not Ready`.
sub_status_name

string, possible values: "Break", "End Shift", "Forced", "Meal", "Meeting", "Training" — The user's reason when the user status is `Not Ready`. To query a list of default and custom `Not Ready` reasons, call [List System Statuses](/docs/contact-center/apis/#operation/listSystemStatus) (filter by `queue_opt_out_and_not_ready_status` status_category) Default `Not Ready` reasons: * Break (ID = `20`) * Meal (ID = `21`) * Training (ID = `22`) * Meeting (ID = `23`) * End Shift (ID = `24`) * Forced (ID = `25`)
teams

array — The teams the user is assigned to.

Items:
- team_id
  
  string — The team's ID.
- team_name
  
  string — The team's display name.
user_access

string, possible values: "active", "inactive" — The user's access status. * `active` - The user's role permissions allow them to access the Contact Center. * `inactive` - The user cannot access the Contact Center.
user_email

string, format: email — The user's email address.
user_id

string — The Meetings user identifier.

Example:

{
  "user_id": "IGTRVt3gQ2i-WjoUIjeZxw",
  "display_name": "Jane Doe",
  "user_email": "jchill@example.com",
  "role_id": "0TFVsJqNS82CwkQJLqj1zA",
  "role_name": "Admin",
  "client_integration": "Salesforce",
  "client_integration_name": "integration-test",
  "status_id": "2",
  "status_name": "Not Ready",
  "sub_status_id": "21",
  "sub_status_name": "Meal",
  "user_access": "active",
  "country_iso_code": "US",
  "region_id": "8f71O6rWT8KFUGQmJIFAdQ",
  "region_name": "Main Region",
  "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": "essentials",
  "add_ons_plan": [
    "ai_expert_assist"
  ],
  "teams": [
    {
      "team_id": "qlU902FoTD-dFi9QnCdZhw",
      "team_name": "Support Team"
    }
  ],
  "cc_user_id": "hKuMAiDdRlSwMkBxR5we7g",
  "emergency_calling": true,
  "billing_account_id": "PEKovuAEQBu5dpeqmxwW1Q",
  "billing_account_name": "main billing account"
}

Status: 400 HTTP Status Code: `400` Bad Request Error Code: `300` Invalid user id.

Status: 401 HTTP Status Code: `401` Unauthorized Error Code: `124` Invalid access token. Error Code: `124` Access token has expired. Error Code: `1002` The user associated with this access token was not found or is invalid.

Status: 403 HTTP Status Code: `403` Forbidden Error Code: `1021` User account is deactivated. Error Code: `1022` User does not have a Contact Center license. Error Code: `9001` The Contact Center user associated with this bearer token is missing privileges on their role required to operate this request.

Status: 404 HTTP Status Code: `404` Not Found Error Code: `1001` User does not exist: {userId}.

Status: 429 HTTP Status Code: `429` Too Many Requests. For more information, see [rate limits](https://developers.zoom.us/docs/api/rate-limits/). Error Code: `4001` You have reached the maximum per-second rate limit for this API. Try again later.

Delete a user's profile

Method: DELETE
Path: /contact_center/users/{userId}
Tags: Users

Delete a Contact Center user.

Scopes: contact_center_user:write:admin

Granular Scopes: contact_center:delete:user:admin

Rate Limit Label: LIGHT

Responses

Status: 204 HTTP Status Code: `204` User profile deleted.

Status: 400 HTTP Status Code: `400` Bad Request Error Code: `300` Validation failed.

Status: 401 HTTP Status Code: `401` Unauthorized Error Code: `124` Invalid access token. Error Code: `124` Access token has expired. Error Code: `1002` The user associated with this access token was not found or is invalid.

Status: 403 HTTP Status Code: `403` Forbidden Error Code: `1021` User account is deactivated. Error Code: `1022` User does not have a Contact Center license. Error Code: `9001` The Contact Center user associated with this bearer token is missing privileges on their role required to operate this request.

Status: 404 HTTP Status Code: `404` Not Found Error Code: `1001` User does not exist: {userId}.

Status: 429 HTTP Status Code: `429` Too Many Requests. For more information, see [rate limits](https://developers.zoom.us/docs/api/rest/rate-limits/). Error Code: `4001` You have reached the maximum per-second rate limit for this API. Try again later.

Update a user's profile

Method: PATCH
Path: /contact_center/users/{userId}
Tags: Users

Update a Contact Center user.

Scopes: contact_center_user:write:admin

Granular Scopes: contact_center:update:user:admin

Rate Limit Label: LIGHT

Request Body

Content-Type: application/json

add_ons_plan

array — The Contact Center plan to assign to the user. Concurrent or non-concurrent depends on the plan type purchased by the account. *`ai_expert_assist` - Contact Center AI Expert Assist or Contact Center AI Expert Assist Concurrent Package. *`zoom_contact_center_for_service_cloud_voice` - Contact Center for Salesforce Voice or Contact Center for Salesforce Voice Concurrent Package.

Items:

string, possible values: "ai_expert_assist"
billing_account_id

string — The ID of the billing account.
channel_settings

object — Information about the channel settings.
- concurrent_email_capacity
  
  integer — The maximum number of concurrent email engagements that can be assigned to a user.
- concurrent_message_capacity
  
  integer — The maximum number of concurrent messaging engagements that can be assigned to a user.
- multi_channel_engagements
  
  object — Information about the settings' multi-channel engagements.
  - email_max_agent_load
    
    integer — The percentage of the user's email capacity that determines availability for voice and video engagements. When `enable` is `true` and the user's current email workload is at or below this percentage of `concurrent_email_capacity`, they can receive voice and video engagements.
  - enable
    
    boolean — Whether to allow the user to receive voice or video engagements while handling messaging or email engagements.
  - max_agent_load
    
    integer — The percentage of the user's messaging capacity that determines availability for voice and video engagements. When `enable` is `true` and the user's current messaging workload is at or below this percentage of `concurrent_message_capacity`, they can receive voice and video engagements.
client_integration

string, possible values: "Default", "Salesforce", "Zendesk", "ServiceNow", "Microsoft_Dynamics_365" — The Contact Center client integration.
client_integration_name

string — The client integration connection name to be assigned to the user.
country_iso_code

string — The [ISO country code](/docs/api/rest/other-references/abbreviation-lists/#countries).
emergency_calling

boolean — Allow users to contact emergency services through their device's native phone system or Zoom Phone.
package_name

string, possible values: "essentials", "premium", "elite" — The Contact Center plan to assign to the user. Concurrent or non-concurrent depends on the plan type purchased by the account. *`essentials` - Zoom Contact Center Essentials or Zoom Contact Center Concurrent Essentials Package. *`premium` - Zoom Contact Center Premium or Zoom Contact Center Concurrent Premium Package. *`elite` - Zoom Contact Center Elite or Zoom Contact Center Concurrent Elite Package.
region_id

string — The Contact Center region identifier.
role_id

string — The user's Contact Center role identifier.
status_id

string — The user's status ID. **Deprecated** Use the [Update a user's status](/docs/api/contact-center/#tag/users/patch/contact_center/users/{userId}/status) API instead.
sub_status_id

string — The user's reason ID when the user status is `Not Ready`. **Deprecated** Use the [Update a user's status](/docs/api/contact-center/#tag/users/patch/contact_center/users/{userId}/status) API instead.
template_id

string — To retrieve the template ID, call the **List User's Templates** API. The template ID must correspond to a template with a status of `Active` and a type of `Update`. If you provide this value, leave all other fields blank to apply the settings from the template. Only the settings from the template indicated as 'override' will be applied to the user. If you specify both individual values and a template in the request, the individual values take priority over the template settings.
user_access

string, possible values: "active", "inactive" — The user's access status. * `active` — The user's role permissions allow them to access the Contact Center. * `inactive` - The user cannot access the Contact Center.

Example:

{
  "client_integration": "Salesforce",
  "client_integration_name": "integration-test",
  "role_id": "0TFVsJqNS82CwkQJLqj1zA",
  "user_access": "active",
  "country_iso_code": "US",
  "region_id": "8f71O6rWT8KFUGQmJIFAdQ",
  "channel_settings": {
    "multi_channel_engagements": {
      "enable": true,
      "max_agent_load": 50,
      "email_max_agent_load": 50
    },
    "concurrent_message_capacity": 4,
    "concurrent_email_capacity": 4
  },
  "template_id": "4pPgojTBRC69wEYSlDhffA",
  "package_name": "essentials",
  "add_ons_plan": [
    "ai_expert_assist"
  ],
  "emergency_calling": true,
  "billing_account_id": "PEKovuAEQBu5dpeqmxwW1Q"
}

Responses

Status: 204 HTTP Status Code: `204` User profile updated.

Status: 400 HTTP Status Code: `400` Bad Request Error Code: `8003` User template not found: {template_id}. Error Code: `8004` User template type error: {template_id}. Error Code: `8005` User template status error: {template_id}. Error Code: `290010` The selected package or add-ons is not enough. Error Code: `1701` The account package does not exist: {package_name}. Error Code: `1702` The account addons package does not exist: {add_ons_plan_name}.

Status: 401 HTTP Status Code: `401` Unauthorized Error Code: `124` Invalid access token. Error Code: `124` Access token has expired. Error Code: `1002` The user associated with this access token was not found or is invalid.

Status: 403 HTTP Status Code: `403` Forbidden Error Code: `1021` User account is deactivated. Error Code: `1022` User does not have a Contact Center license. Error Code: `9001` The Contact Center user associated with this bearer token is missing privileges on their role required to operate this request.

Status: 404 HTTP Status Code: `404` Not Found Error Code: `300` Validation failed. Error Code: `1001` User does not exist: {userId}. Error Code: `1101` Status does not exist: {status_id}. Error Code: `1102` Sub status does not exist: {sub_status_id}. Error Code: `1006` The account {client_integration} client integration does not exist. Add it to the Integrations function module. Error Code: `2201` Role does not exist: {role_id}. Error Code: `2202` Country ISO code does not exist: {country_iso_code}. Error Code: `1017` Region does not exist. Error Code: `1020` The account {client_integration_name} client integration name does not exist. Add it to the "Integrations" function module.

Status: 429 HTTP Status Code: `429` Too Many Requests. For more information, see [rate limits](https://developers.zoom.us/docs/api/rate-limits/). Error Code: `4001` You have reached the maximum per-second rate limit for this API. Try again later.

Opt-in or opt-out a user's queues

Method: PATCH
Path: /contact_center/users/{userId}/opt_in_out_queues
Tags: Users

Change a Contact Center user's opt-in or opt-out status for queues assigned to the user. Opting out prevents the user from receiving engagements from that queue if they are an agent.

If channel_type is provided, queues are processed based on the channel_type. Otherwise, queues are processed based on queue_ids. The request is invalid if neither channel_type nor queue_ids are provided.

Scopes: contact_center_queue:write:admin

Granular Scopes: contact_center:update:queue_agent:admin

Rate Limit Label: LIGHT

Request Body

Content-Type: application/json

opt_in_out_status (required)

integer, possible values: 0, 1 — Opt-in or opt-out status. -`0` - Opt in -`1` - Opt out
channel_type

integer, possible values: 0, 4, 7, 8, 9 — The channel of queues to opt in or out. -`0` - voice -`4` - video -`7` - messaging -`8` - email -`9` - work item
queue_ids

array — The list of queues to opt in or out.

Items:

string — The queue's ID.

Example:

{
  "opt_in_out_status": 0,
  "queue_ids": [
    "IGTRVt3gQ2i-WjoUIjeZxw"
  ],
  "channel_type": 0
}

Responses

Status: 204 HTTP Status Code: `204` The user's queues opt-in / opt-out status was successfully updated.

Status: 400 HTTP Status Code: `400` Bad Request Error Code: `1010` The agent must be in an available state `Ready` to opt in to the queue. Error Code: `1011` The agent is not allowed to opt in or out of their assigned queues. Error Code: `1019` Feature OP flag is not enabled. Error Code: `1205` Queue channel type is invalid: $channel_type.

Status: 401 HTTP Status Code: `401` Unauthorized Error Code: `124` Invalid access token. Error Code: `124` Access token has expired. Error Code: `1002` The user associated with this access token was not found or is invalid.

Status: 403 HTTP Status Code: `403` Forbidden Error Code: `1021` User account is deactivated. Error Code: `1022` User does not have a Contact Center license. Error Code: `9001` The Contact Center user associated with this bearer token is missing privileges on their role required to operate this request.

Status: 404 HTTP Status Code: `404` Not Found Error Code: `1001` User does not exist: {userId}. Error Code: `1202` Queues do not exist: {queue_ids}.

Status: 429 HTTP Status Code: `429` Too Many Requests. For more information, see [rate limits](https://developers.zoom.us/docs/api/rate-limits/). Error Code: `4001` You have reached the maximum per-second rate limit for this API. Try again later.

List a user's queues

Method: GET
Path: /contact_center/users/{userId}/queues
Tags: Users

List the Contact Center queues that a user is assigned to.

Scopes: contact_center_user:read:admin

Granular Scopes: contact_center:read:list_user_queues:admin

Rate Limit Label: MEDIUM

Responses

Status: 200 HTTP Status Code: `200` The list of Contact Center queues that the user is assigned to.

Content-Type: application/json

next_page_token

string — Use the next page token to paginate through large result sets. A next page token is returned whenever the set of available results exceeds the current page size. This token's expiration period is 15 minutes.
page_size

integer, default: 30 — The number of records returned in a single API call.
queues

array — Contact Center queues.

Items:
- caller_ids
  
  array — The caller ID number that your customers will see on their phone when agents and supervisors reach out to them.
  
  Items:
  
  string — Phone number that customers will see on their phone. Phone number format E.164
- cc_queue_id
  
  string — The Contact Center queue identifier.
- channel
  
  string, possible values: "voice", "video", "messaging", "email" — The Contact Center queue's channel.
- queue_description
  
  string — The Contact Center queue description.
- queue_id
  
  string — The task queue's identifier. **Deprecated** - use the `cc_queue_id` field to reference the Contact Center queue.
- queue_name
  
  string — The Contact Center queue name.
- teams
  
  array — The teams the user is assigned to.
  
  Items:
  - team_id
    
    string — The unique identifier of the team.
  - team_name
    
    string — The display name of the team.
- user_assignment_type
  
  string, possible values: "agent", "supervisor", "both" — The user's persona assignment type to the Contact Center queue.
total_records

integer — The total number of all records available across pages.

Example:

{
  "next_page_token": "R4aF9Oj0fVM2hhezJTEmSKaBSkfesDwGy42",
  "page_size": 30,
  "total_records": 10,
  "queues": [
    {
      "cc_queue_id": "a4lCNeq2SzKbgkcDVbjCZQ",
      "queue_name": "Voice - Customer Support",
      "queue_description": "Agents assigned to this queue handle Customer Support voice calls.",
      "channel": "voice",
      "user_assignment_type": "agent",
      "caller_ids": [
        "+18667202634"
      ],
      "teams": [
        {
          "team_id": "qlU902FoTD-dFi9QnCdZhw",
          "team_name": "Support Team"
        }
      ]
    }
  ]
}

Status: 400 HTTP Status Code: `400` Bad Request Error Code: `300` User assignment type is invalid: {user_assignment_type}. Error Code: `1205` Queue channel type is invalid: {channel}.

Status: 401 HTTP Status Code: `401` Unauthorized Error Code: `124` Invalid access token. Error Code: `124` Access token has expired. Error Code: `1002` The user associated with this access token was not found or is invalid.

Status: 403 HTTP Status Code: `403` Forbidden Error Code: `1021` User account is deactivated. Error Code: `1022` User does not have a Contact Center license. Error Code: `9001` The Contact Center user associated with this bearer token is missing privileges on their role required to operate this request.

Status: 404 HTTP Status Code: `404` Not Found Error Code: `1001` User does not exist: {userId}.

Status: 429 HTTP Status Code: `429` Too Many Requests. For more information, see [rate limits](/docs/api/rate-limits/). Error Code: `4001` You have reached the maximum per-second rate limit for this API. Try again later.

List a user's recordings

Method: GET
Path: /contact_center/users/{userId}/recordings
Tags: Users

List a user's Contact Center recordings.

Note Recordings are not available before July 18th, 2022.

Scopes: contact_center_recording:read,contact_center_recording:read:admin

Granular Scopes: contact_center:read:list_recordings:admin,contact_center:read:list_recordings

Rate Limit Label: MEDIUM

Responses

Status: 200 HTTP Status Code: `200` User recordings returned.

Content-Type: application/json

from

string, format: string — The start time and date in ISO 8601 format, either yyyy-MM-dd'T'HH:mm:ss'Z' or yyyy-MM-dd'T'HH:mm:ss'TZD'. The defined date range should be a month, as the response only includes one month's worth of data. If unspecified, this parameter returns data from the past 30 days.
next_page_token

string — Use the next page token to paginate through large result sets. A next page token is returned whenever the set of available results exceeds the current page size. This token's expiration period is 15 minutes.
page_size

integer, default: 30 — The number of records returned in a single API call.
recordings

array — Information about the recordings.

Items:
- cc_queue_id
  
  string — The Contact Center queue identifier.
- channel
  
  string, possible values: "voice", "video" — The recording's channel type. * `voice` - Voice recording. * `video` - Video recording.
- channel_type
  
  string, possible values: "voice", "video" — The recording's channel type. * `voice` - Voice recording. * `video` - Video recording.
- conference_participant
  
  array — Information about the recording conference participants.
  
  Items:
  - contact_id
    
    string — The participant's contact ID.
  - contact_name
    
    string — The participant's contact name.
  - contact_number
    
    string — The participant's contact number.
  - participant_type
    
    string, possible values: "agent", "customer", "supervisor", "outbound" — The participant's type.
  - queue_id
    
    string — The participant's Contact Center queue ID.
  - queue_name
    
    string — The Contact Center queue name.
  - team_id
    
    string — The participant's team ID.
  - team_name
    
    string — The participant's team name.
  - user_id
    
    string — The participant's Contact Center user ID.
  - user_name
    
    string — The participant's username.
- consumer_name
  
  string — **Deprecated** Use `consumer_name` in `consumers` object instead. The consumer's name.
- consumer_number
  
  string — **Deprecated** Use `consumer_name` in `consumers` object instead. The consumer's phone number.
- consumers
  
  array — Information about the recording consumers.
  
  Items:
  - consumer_name
    
    string — The customer's name.
  - consumer_number
    
    string — The customer's phone number.
- direction
  
  string, possible values: "inbound", "outbound" — The recording's call direction. * `inbound` - Call in. * `outbound` - Call out.
- display_name
  
  string — The user's display name.
- download_url
  
  string — The URL to download the recording. For security purposes, you **must** provide an OAuth access token in the Authorization header to download the recording file using this URL. **Example** ```curl --request GET \ --url {download_url} \ --header 'authorization: Bearer {access_token} \ --header 'content-type: application/json' ```
- engagement_id
  
  string — The engagement event's unique ID.
- exemption
  
  boolean — Whether the recording is exempted from data retention.
- flow_id
  
  string — The recording's flow ID.
- flow_name
  
  string — The recording's flow name.
- owner_id
  
  string — The recording's owner ID, such as the queue ID or user ID.
- owner_name
  
  string — The recording's owner name, such as queue name or user name.
- owner_type
  
  string, possible values: "user", "queue" — The recording's owner type. * `user` - This recording belongs to an user. * `queue` - This recording belongs to a queue.
- playback_url
  
  string — The URL to play the recording. For security purposes, you **must** provide an OAuth access token in the authorization header to play the recording file using this URL. **Example** ```curl --request GET --url {playback_url} --header 'authorization: Bearer {access_token}' --header 'content-type: application/json' ```
- queue_id
  
  string — The task queue's identifier. **Deprecated** - use the `cc_queue_id` field to reference the Contact Center queue.
- queue_name
  
  string — The Contact Center queue name.
- reason_details
  
  string — The recording's data retention exemption reason details.
- recording_duration
  
  integer — The recording's duration in seconds.
- recording_end_time
  
  string, format: date-time — The date and time of the recording's end time in ISO 8601 format, either yyyy-MM-dd'T'HH:mm:ss'Z' or yyyy-MM-dd'T'HH:mm:ss'TZD'.
- recording_id
  
  string — The recording's unique ID.
- recording_start_time
  
  string, format: date-time — The date and time of the recording's start time in ISO 8601 format, either yyyy-MM-dd'T'HH:mm:ss'Z' or yyyy-MM-dd'T'HH:mm:ss'TZD'.
- recording_type
  
  string, possible values: "on_demand", "automatic" — The recording's type. * `on_demand` - Manually trigger recording. * `automatic` - Automatically trigger recording.
- segment_type
  
  string, possible values: "inbound", "conference" — Whether the recording is an inbound recording or a conference recording.
- team_id
  
  string — The team's ID.
- team_name
  
  string — The team's name.
- transcript_url
  
  string — The URL to download the recording transcript. For security purposes, you **must** provide an OAuth access token in the authorization header to download the recording transcript file using this URL. **Example** ```curl --request GET --url {transcript_url} --header 'authorization: Bearer {access_token}' --header 'content-type: application/json' ```
- user_email
  
  string, format: email — The user's email address.
- user_id
  
  string — The Meetings user identifier.
to

string, format: string — **Required** only when the `from` parameter is specified. The end time and date in ISO 8601 format, either yyyy-MM-dd'T'HH:mm:ss'Z' or yyyy-MM-dd'T'HH:mm:ss'TZD', the same format as the `from` parameter.

Example:

{
  "next_page_token": "R4aF9Oj0fVM2hhezJTEmSKaBSkfesDwGy42",
  "page_size": 30,
  "from": "2023-01-01T00:00:00-08:00",
  "to": "2023-01-01T01:00:00-08:00",
  "recordings": [
    {
      "recording_id": "ghyetrjj_sdfsdgfkdjfl111",
      "cc_queue_id": "a4lCNeq2SzKbgkcDVbjCZQ",
      "queue_name": "Voice - Customer Support",
      "recording_duration": 150,
      "download_url": "https://api.zoom.us/v2/contact_center/recording/download/01bdb222-9984-4f41-8141-2f760cb398aa?type=voice",
      "transcript_url": "https://api.zoom.us/v2/contact_center/recording/transcripts/download/4Q0ILNMfTA2nJolNxhg0Rw?type=voice",
      "playback_url": "https://api.zoom.us/v2/contact_center/recording/playback/4Q0ILNMfTA2nJolNxhg0Rw?type=voice",
      "recording_start_time": "2023-01-01T08:00:00Z",
      "recording_end_time": "2023-01-01T09:00:00Z",
      "user_id": "IGTRVt3gQ2i-WjoUIjeZxw",
      "display_name": "Jane Doe",
      "user_email": "jchill@example.com",
      "recording_type": "automatic",
      "channel": "voice",
      "direction": "outbound",
      "owner_id": "auiketrjj_2342353fsewkdjfl",
      "owner_name": "voice",
      "owner_type": "queue",
      "engagement_id": "3XilEfOvQEKRIWMWhX1jDg",
      "flow_name": "voice",
      "flow_id": "fsdfsd4oippe0ffewcbhjk",
      "consumers": [
        {
          "consumer_name": "Steve Rogers",
          "consumer_number": "+13128945709"
        }
      ],
      "exemption": true,
      "reason_details": "Compliance review.",
      "segment_type": "conference",
      "team_id": "edlbknHGRjq35Y5WYxb7_A",
      "team_name": "Jane Doe's team",
      "conference_participant": [
        {
          "user_id": "HljBAYkdSzqk_eXkXyEV7g",
          "user_name": "Jill Chill",
          "queue_id": "y5yK894sT4ixNaO__FO_Jg",
          "queue_name": "Voice - Customer Support",
          "team_id": "edlbknHGRjq35Y5WYxb7_A",
          "team_name": "Jill Chill's team",
          "contact_id": "edlbknHGRjq35Y5WYxb7_A",
          "contact_name": "Jill Chill",
          "contact_number": "+12058945728",
          "participant_type": "agent"
        }
      ]
    }
  ]
}

Status: 400 HTTP Status Code: `400` Bad Request Error Code: `300` Invalid user ID.

Status: 401 HTTP Status Code: `401` Unauthorized Error Code: `124` Invalid access token. Error Code: `124` Access token has expired. Error Code: `1002` The user associated with this access token was not found or is invalid.

Status: 403 HTTP Status Code: `403` Forbidden Error Code: `1021` User account is deactivated. Error Code: `1022` User does not have a Contact Center license. Error Code: `9001` The Contact Center user associated with this bearer token is missing privileges on their role required to operate this request.

Status: 404 HTTP Status Code: `404` Not Found Error Code: `1001` User does not exist: $userId

Status: 429 HTTP Status Code: `429` Too Many Requests. For more information, see [rate limits](/docs/api/rate-limits/). Error Code: `4001` You have reached the maximum per-second rate limit for this API. Try again later.

Delete a user's recordings

Method: DELETE
Path: /contact_center/users/{userId}/recordings
Tags: Users

Delete all of a user's Contact Center recordings.

Scopes: contact_center_recording:write:admin

Granular Scopes: contact_center:delete:recording:admin

Rate Limit Label: LIGHT

Responses

Status: 204 HTTP Status Code: `204` Successfully deleted the user's Contact Center recordings.

Status: 400 HTTP Status Code: `400` Bad Request Error Code: `300` Invalid user ID.

Status: 401 HTTP Status Code: `401` Unauthorized Error Code: `124` Invalid access token. Error Code: `124` Access token has expired. Error Code: `1002` The user associated with this access token was not found or is invalid.

Status: 403 HTTP Status Code: `403` Forbidden Error Code: `1021` User account is deactivated. Error Code: `1022` User does not have a Contact Center license. Error Code: `9001` The Contact Center user associated with this bearer token is missing privileges on their role required to operate this request.

Status: 404 HTTP Status Code: `404` Not Found Error Code: `2804` User recordings do not exist: $userId. Error Code: `1001` User does not exist: $userId.

Status: 409 HTTP Status Code: `409` Conflict Error Code: `2820` You cannot delete this recording because it is exempt from retention policy due to legal hold.

Status: 429 HTTP Status Code: `429` Too Many Requests. For more information, see [rate limits](/docs/api/rate-limits/). Error Code: `4001` You have reached the maximum per-second rate limit for this API. Try again later.

List a user's skills

Method: GET
Path: /contact_center/users/{userId}/skills
Tags: Users

Get a list of skills assigned to a given user.

Scopes: contact_center_skill:read:admin

Granular Scopes: contact_center:read:list_user_skills:admin

Rate Limit Label: MEDIUM

Responses

Status: 200 HTTP Status Code: `200` User's assigned skills returned.

Content-Type: application/json

next_page_token

string — Use the next page token to paginate through large result sets. A next page token is returned whenever the set of available results exceeds the current page size. This token's expiration period is 15 minutes.
page_size

integer, default: 30 — The number of records returned in a single API call.
skills

array — Information about the user's skills

Items:
- max_proficiency_level
  
  integer — The maximum proficiency level in a skill.
- skill_category_id
  
  string — The skill category's ID.
- skill_category_name
  
  string — The skill category's name.
- skill_id
  
  string — The skill's ID.
- skill_name
  
  string — The skill's name.
- skill_type
  
  string — The skill's type.
- user_proficiency_level
  
  integer — A user's proficiency level in a skill.
total_records

integer — The total number of all records available across pages.

Example:

{
  "next_page_token": "R4aF9Oj0fVM2hhezJTEmSKaBSkfesDwGy42",
  "page_size": 30,
  "total_records": 10,
  "skills": [
    {
      "skill_id": "s51M536ZjSgi8o_rzmgQBrA",
      "skill_name": "assign-skill6b6c864b-474a-4843-afed-81bd26b03952",
      "skill_type": "proficiency",
      "max_proficiency_level": 5,
      "user_proficiency_level": 3,
      "skill_category_id": "s51M536ZjSgi8o_rzmgQBrA",
      "skill_category_name": "Language"
    }
  ]
}

Status: 400 HTTP Status Code: `400` Bad Request Error Code: `300` Invalid field.

Status: 401 HTTP Status Code: `401` Unauthorized Error Code: `124` Invalid access token. Error Code: `124` Access token has expired. Error Code: `1002` The user associated with this access token was not found or is invalid.

Status: 403 HTTP Status Code: `403` Forbidden Error Code: `1021` User account is deactivated. Error Code: `1022` User does not have a Contact Center license. Error Code: `9001` The Contact Center user associated with this bearer token is missing privileges on their role required to operate this request.

Status: 404 HTTP Status Code: `404` Not Found Error Code: `1001` User does not exist: {userId}. Error Code: `1001` User does not exist. Error Code: `1501` Skill category does not exist: {categoryId}. Error Code: `1501` Skill category does not exist.

Status: 429 HTTP Status Code: `429` Too Many Requests. For more information, see [rate limits](/docs/api/rest/rate-limits/). Error Code: `4001` You have reached the maximum per-second rate limit for this API. Try again later.

Assign a user's skills

Method: POST
Path: /contact_center/users/{userId}/skills
Tags: Users

Assign skills to a user. Skills are user traits that ensure that a given agent is the best person to handle a given customer interaction. Proficiency ratings indicate the user's level of expertise or knowledge of that skill.

Scopes: contact_center_skill:write:admin

Granular Scopes: contact_center:write:user_skill:admin

Rate Limit Label: MEDIUM

Request Body

Content-Type: application/json

skills

array — Information about the skills.

Items:
- max_proficiency_level
  
  integer — The skill's assigned proficiency level.
- skill_id
  
  string — The skill ID.

Example:

{
  "skills": [
    {
      "skill_id": "1",
      "max_proficiency_level": 5
    }
  ]
}

Responses

Status: 201 HTTP Status Code: `201` Skills are assigned to the Contact Center user.

Status: 400 HTTP Status Code: `400` Bad Request Error Code: `1405` Skill assignment already exists: {skill_id}. Error Code: `300` Invalid user ID. Error Code: `1407` Invalid proficiency level for skill assignment: {skill_id}.

Status: 401 HTTP Status Code: `401` Unauthorized Error Code: `124` Invalid access token. Error Code: `124` Access token has expired. Error Code: `1002` The user associated with this access token was not found or is invalid.

Status: 403 HTTP Status Code: `403` Forbidden Error Code: `1021` User account is deactivated. Error Code: `1022` User does not have a Contact Center license. Error Code: `9001` The Contact Center user associated with this bearer token is missing privileges on their role required to operate this request.

Status: 404 HTTP Status Code: `404` Not Found Error Code: `1401` Skills do not exist: {skill_ids}. Error Code: `1001` User does not exist: {userId}.

Status: 429 HTTP Status Code: `429` Too Many Requests. For more information, see [rate limits](/docs/api/rest/rate-limits/). Error Code: `4001` You have reached the maximum per-second rate limit for this API. Try again later.

Unassign a user's skill

Method: DELETE
Path: /contact_center/users/{userId}/skills/{skillId}
Tags: Users

Remove a skill from a Contact Center user.

Scopes: contact_center_skill:write:admin

Granular Scopes: contact_center:delete:user_skill:admin

Rate Limit Label: LIGHT

Responses

Status: 204 HTTP Status Code: `204 ` The skill was removed from the user.

Status: 400 HTTP Status Code: `400` Bad Request Error Code: `300` Invalid user ID. Error Code: `1408` More than one matching skill found.

Status: 401 HTTP Status Code: `401` Unauthorized Error Code: `124` Invalid access token. Error Code: `124` Access token has expired. Error Code: `1002` The user associated with this access token was not found or is invalid.

Status: 403 HTTP Status Code: `403` Forbidden Error Code: `1021` User account is deactivated. Error Code: `1022` User does not have a Contact Center license. Error Code: `9001` The Contact Center user associated with this bearer token is missing privileges on their role required to operate this request.

Status: 404 HTTP Status Code: `404` Not Found Error Code: `1404` Skill assignment not found: {skillId}. Error Code: `1001` User does not exist: {userId}.

Status: 429 HTTP Status Code: `429` Too Many Requests. For more information, see [rate limits](/docs/api/rest/rate-limits/). Error Code: `4001` You have reached the maximum per-second rate limit for this API. Try again later.

Update a user's status

Method: PATCH
Path: /contact_center/users/{userId}/status
Tags: Users

Update a user's status.

Scopes: contact_center_user:write:admin

Granular Scopes: contact_center:update:user:admin

Rate Limit Label: LIGHT

Request Body

Content-Type: application/json

status_id

string — The user's status ID.
sub_status_id

string — The user's reason ID when the user status is `Not Ready`.

Example:

{
  "status_id": "2",
  "sub_status_id": "21"
}

Responses

Status: 204 HTTP Status Code: 204 Contact Center user status updated.

Status: 400 HTTP Status Code: `400` Bad Request Error Code: `300` The status must be "Not Ready" when updating sub status. Error Code: `300` The status does not allow updating to: {status_name}. Error Code: `300` {status_name} is disabled.

Status: 401 HTTP Status Code: `401` Unauthorized Error Code: `124` Invalid access token. Error Code: `124` Access token has expired. Error Code: `1002` The user associated with this access token was not found or is invalid.

Status: 403 HTTP Status Code: `403` Forbidden Error Code: `1021` User account is deactivated. Error Code: `1022` User does not have a Contact Center license. Error Code: `9001` The Contact Center user associated with this bearer token is missing privileges on their role required to operate this request.

Status: 404 HTTP Status Code: `404` Not Found Error Code: `1001` User does not exist: {userId}. Error Code: `1101` Status does not exist: {status_id}. Error Code: `1102` Sub status does not exist: {sub_status_id}.

Status: 429 HTTP Status Code: `429` Too Many Requests. For more information, see [rate limits](https://developers.zoom.us/docs/api/rate-limits/). Error Code: `4001` You have reached the maximum per-second rate limit for this API. Try again later.

List variable logs

Method: GET
Path: /contact_center/variable_logs
Tags: Variables

Return a list of variable logs.

Scopes: contact_center_variable_log:read:admin

Granular Scopes: contact_center:read:list_variable_logs:admin

Rate Limit Label: HEAVY

Responses

Status: 200 HTTP Status Code: `200` Variable logs returned.

Content-Type: application/json

from

string, format: date-time — The start time and date in ISO 8601 format, either `yyyy-MM-dd'T'HH:mm:ss'Z'` or `yyyy-MM-dd'T'HH:mm:ss'TZD'`. The defined date range should be a month, as the response only includes one month's worth of data. If no start date is specified, return data from the past 24 hours.
highest_watermark

string, format: date-time — The latest time among the returned records.
next_page_token

string — Use the next page token to paginate through large result sets. A next page token is returned whenever the set of available results exceeds the current page size. This token's expiration period is 15 minutes.
page_size

integer, default: 10 — The number of records returned within a single API call.
to

string, format: date-time — **Required** only when the `from` parameter is specified. The end time and date in ISO 8601 format, either `yyyy-MM-dd'T'HH:mm:ss'Z'` or `yyyy-MM-dd'T'HH:mm:ss'TZD'`, the same format as the `from` parameter.
total_records

integer — The total number of all records available across pages.
variable_logs

array — Information about the variable logs.

Items:
- created_at
  
  string, format: date-time — Creation time in `yyyy-MM-dd'T'HH:mm:ss±HH:mm` format, using the timezone derived from the input `from` parameter.
- data_type
  
  string, possible values: "boolean", "currency", "date", "email", "number", "percent", "phone", "string", "time", "url", "json", "array" — The variable data's type.
- engagement_id
  
  string — The engagement's ID
- flow_id
  
  string — The flow's ID.
- flow_name
  
  string — The flow's name.
- group_type
  
  string, possible values: "system", "custom" — The variable group's type.
- variable_log_id
  
  string — The variable log's ID
- variable_name
  
  string — The variable's name.
- variable_value
  
  string — The variable's value.
- widget_name
  
  string — The widget's name.

Example:

{
  "next_page_token": "R4aF9Oj0fVM2hhezJTEmSKaBSkfesDwGy42",
  "page_size": 10,
  "total_records": 10,
  "highest_watermark": "2021-12-10T08:15:00Z",
  "from": "2021-12-10T08:00:00Z",
  "to": "2021-12-10T08:15:00Z",
  "variable_logs": [
    {
      "variable_log_id": "ebe83be-3579-4dc9-8e6e-67dd65a010fe",
      "engagement_id": "3XilEfOvQEKRIWMWhX1jDg",
      "flow_id": "zeYjXoDOS_eV1QmTpj63PQ",
      "flow_name": "Demo",
      "widget_name": "HttpCall1",
      "variable_name": "body",
      "variable_value": "demo",
      "group_type": "system",
      "data_type": "boolean",
      "created_at": "2023-01-01T08:00:00-08:00"
    }
  ]
}

Status: 400 HTTP Status Code: `400` Bad Request Error Code: `300` The time and date must be in `yyyy-mm-dd` or ISO 8601 format, either `yyyy-MM-dd'T'HH:mm:ss'Z'` or `yyyy-MM-dd'T'HH:mm:ss'TZD'`. Error Code: `300` The requested report exceeds the 1-month limit. Error Code: `300` Timezone does not exist: {timezone}. Error Code: `300` Invalid field.

Status: 401 HTTP Status Code: `401` Unauthorized Error Code: `1002` The user associated with this access token was not found or is invalid. Error Code: `124` Invalid access token. Error Code: `124` Access token has expired.

Status: 403 HTTP Status Code: `403` Forbidden Error Code: `1021` User account is deactivated. Error Code: `1022` User does not have a Contact Center license. Error Code: `9001` The Contact Center user associated with this bearer token is missing privileges on their role required to operate this request.

Status: 404 HTTP Status Code: `404` Not Found Error Code: `2901` Engagement does not exist: {engagement_id}. Error Code: `3201` Flow does not exist: {flow_id}.

Status: 429 HTTP Status Code: `429` Too Many Requests. For more information, see [rate limits](https://developers.zoom.us/docs/api/rate-limits/). Error Code: `4001` You have reached the maximum per-second rate limit for this API. Try again later.

Get a variable log

Method: GET
Path: /contact_center/variable_logs/{variableLogId}
Tags: Variables

Get information about a variable log.

Scopes: contact_center_variable_log:read:admin

Granular Scopes: contact_center:read:variable_log:admin

Rate Limit Label: LIGHT

Responses

Status: 200 HTTP Status Code: `200` Variable log returned.

Content-Type: application/json

created_at

string, format: date-time — Creation time in `yyyy-MM-dd'T'HH:mm:ss+00:00` format (UTC).
data_type

string | null, possible values: "boolean", "currency", "date", "email", "number", "percent", "phone", "string", "url" — The variable data's type. May be `null` if the stored type cannot be mapped.
engagement_id

string — The engagement's ID
flow_id

string — The flow's ID.
flow_name

string — The flow's name.
group_type

string, possible values: "system", "custom" — The variable group's type. The type can be either system or custom.
variable_log_id

string — The variable log's ID
variable_name

string — The variable's name.
variable_value

string — The variable's value.
widget_name

string — The widget's name.

Example:

{
  "variable_log_id": "ebe83be-3579-4dc9-8e6e-67dd65a010fe",
  "engagement_id": "3XilEfOvQEKRIWMWhX1jDg",
  "flow_id": "zeYjXoDOS_eV1QmTpj63PQ",
  "flow_name": "Demo",
  "widget_name": "HttpCall1",
  "variable_name": "body",
  "variable_value": "demo",
  "group_type": "system",
  "data_type": "boolean",
  "created_at": "2023-01-01T08:00:00Z"
}

Status: 401 HTTP Status Code: `401` Unauthorized

Status: 403 HTTP Status Code: `403` Forbidden

Status: 404 HTTP Status Code: `404` Not Found Error Code: `3301` Variable log does not exist: $variableLogId

Status: 429 HTTP Status Code: `429` Too Many Requests. For more information, see [rate limits](/docs/api/rest/rate-limits/).

Delete a variable log

Method: DELETE
Path: /contact_center/variable_logs/{variableLogId}
Tags: Variables

Delete a variable log.

Scopes: contact_center_variable_log:write:admin

Granular Scopes: contact_center:delete:variable_log:admin

Rate Limit Label: LIGHT

Responses

Status: 204 HTTP Status Code: `204` Variable log deleted.

Status: 400 HTTP Status Code: `400` Bad Request

Status: 404 HTTP Status Code: `404` Not Found Error Code: `3301` Variable log does not exist: $variableLogId

Status: 429 HTTP Status Code: `429` Too Many Requests. For more information, see [rate limits](https://developers.zoom.us/docs/api/rest/rate-limits/).

List variables

Method: GET
Path: /contact_center/variables
Tags: Variables

Returns a list of variables for a specific variable group.

Scopes: contact_center_variable:read:admin

Granular Scopes: contact_center:read:list_variables:admin

Rate Limit Label: MEDIUM

Responses

Status: 200 HTTP Status Code: `200` Variables list returned

Content-Type: application/json

next_page_token

string — Use the next page token to paginate through large result sets. A next page token returns when the set of available results exceeds the current page size. This token's expiration period is 15 minutes.
page_size

integer, default: 30 — The number of records returned in a single API call.
total_records

integer — The total number of all the records available across pages.
variables

array — Information about the variables.

Items:
- data_type
  
  string, possible values: "string", "number", "boolean", "date_time", "currency", "percentage", "email", "url", "phone", "json", "array" — The data's type. * `string` * `number` * `boolean` * `date_time` * `currency` * `percentage` * `email` * `url` * `phone`
- default_value
  
  string — The variable's default value.
- mask_variable_data
  
  boolean, default: false — Mask variable data, for sensitive information.
- used_in_address_book_count
  
  integer — The number of times the address book used the variable.
- value_category
  
  string — The variable value's category. Returned only if `variable_type:global_variable` * `undefined` - Each engagement starts without a pre-set value. * `default_value` - Each engagement starts with the default value. * `linked_value` - The value links across flows, and each engagement uses the latest value.
- values
  
  array — The variable's values.
  
  Items:
  
  string
- variable_description
  
  string — The variable's description.
- variable_group_id
  
  string — The variable group's ID.
- variable_id
  
  string — The variable's unique ID.
- variable_name
  
  string — The variable's name.
- variable_type
  
  string, possible values: "global_variable", "address_book_variable" — The variable's type. * `global_variable` * `address_book_variable`

Example:

{
  "next_page_token": "R4aF9Oj0fVM2hhezJTEmSKaBSkfesDwGy42",
  "page_size": 30,
  "total_records": 1,
  "variables": [
    {
      "variable_id": "W_VATTk_Q5aW6z5rZtBxAQ",
      "variable_group_id": "afececcd-0c9f-48de-9d19-0c84e8bdfeca",
      "variable_name": "variable demo name",
      "default_value": "test_value",
      "variable_type": "address_book_variable",
      "data_type": "string",
      "variable_description": "This is a variable description",
      "mask_variable_data": true,
      "values": [
        "test_value"
      ],
      "value_category": "default_value",
      "used_in_address_book_count": 3
    }
  ]
}

Status: 400 HTTP Status Code: `400` Bad Request

Status: 429 HTTP Status Code: `429` Too Many Requests. For more information, see [rate limits](/docs/api/rest/rate-limits/).

Create a variable

Method: POST
Path: /contact_center/variables
Tags: Variables

Create a new variable.

Scopes: contact_center_variable:write:admin

Granular Scopes: contact_center:write:variable:admin

Rate Limit Label: LIGHT

Request Body

Content-Type: application/json

data_type (required)

string, possible values: "string", "number", "boolean", "date_time", "currency", "percentage", "email", "url", "phone", "json", "array" — The data's type. `variable_type:address_book_variable` only applies to data types with `*`. * `string` `*` * `number` * `boolean` `*` * `date_time` -(unix timestamp) * `currency` * `percentage` * `email` * `url` * `phone` - ([E.164 format](https://en.wikipedia.org/wiki/E.164))
variable_group_id (required)

string — The variable group's ID.
variable_name (required)

string — The variable's name.
variable_type (required)

string, possible values: "global_variable", "address_book_variable" — The variable's type. * `global_variable` * `address_book_variable`
address_book_ids

array — The address book IDs. Only valid when `variable_type` is `address_book_variable`, and cannot be empty.

Items:

string
client_show_in_client_engagement_section

boolean — Whether this variable will be shown in the Zoom client's Engagement section. Only valid if `data_type` is not `json` or `array`. * global
client_show_in_client_profile_section

boolean — Whether this variable will be shown in the Zoom client's Profile section. Only valid if `data_type` is not `json` or `array`. * global
client_show_in_inbound_call_notifications

boolean — Whether this variable will be shown as an inbound call notification on the Zoom client. Only valid if `data_type` is not `json` or `array`. * global * address book
default_value

string — The variable's default value. Only used when `variable_type` is `address_book_variable` and `data_type` is `string`.
linked_value_lock

boolean, default: false — The variable linked value's lock. Only valid when `value_category` is `linked_value`. * `true` - The variable can't be updated in a flow. It is the same for each engagement. * `false` - The variable value can be updated in a flow. Each engagement uses the latest value.
mask_variable_data

boolean, default: false — Mask variable data, for sensitive information. Only valid when `variable_type` is `global_variable` and the value of data_type is not `boolean`, `date_time`, or `percentage`.
use_as_routing_profile_parameters

boolean, default: false — Whether to use in the routing profile. Only valid when `variable_type` is `address_book_variable` and `data_type` is not `json` or `array`. * `true` - Values are used as routing profile parameters. * `false` - Not used as a value for routing configuration file parameters.
use_in_external_url_parameters

boolean — Lets you use the parameter value in defining external URLs launched for each engagement. Only valid if `data_type` is not `json` or `array`. * global * address book
use_in_reporting

boolean, default: false — Whether to use in reporting. Only valid when `variable_type` is `global_variable`.
value_category

string — The variable value's category. Only valid when `variable_type` is `global_variable`. * `undefined` - Each engagement starts without a pre-set value. * `default_value` - Each engagement starts with the default value. * `linked_value` - The value links across flows, and each engagement uses the latest value.
values

array — The variable's values. Take only the first value in the array when `variable_type` is `global_variable`. * If `variable_type` is `global_variable`, each value's max length is 4096. * If `variable_type` is `address_book_variable`, each value's maximum length is 300.

Items:

string
variable_description

string — The variable's description.

Example:

{
  "variable_group_id": "afececcd-0c9f-48de-9d19-0c84e8bdfeca",
  "variable_name": "variable demo name",
  "variable_description": "This is a variable description.",
  "variable_type": "address_book_variable",
  "address_book_ids": [
    "X2e_jsLNRkCjI0sQg2kRQQ"
  ],
  "use_in_reporting": false,
  "mask_variable_data": false,
  "use_as_routing_profile_parameters": false,
  "data_type": "number",
  "value_category": "default_value",
  "values": [
    "test-value"
  ],
  "linked_value_lock": false,
  "default_value": "test-value",
  "use_in_external_url_parameters": true,
  "client_show_in_client_profile_section": true,
  "client_show_in_client_engagement_section": true,
  "client_show_in_inbound_call_notifications": true
}

Responses

Status: 201 HTTP Status Code: `201` Variable created.

Content-Type: application/json

address_books

array — The address book list. This field is only returned when `variable_type` is `address_book_variable`.

Items:
- address_book_id
  
  string — The address book's ID.
- address_book_name
  
  string — The address book's name.
- total_contacts
  
  integer — The address book's total number of contacts.
- unit_id
  
  string — The address book's unit ID.
- unit_name
  
  string — The address book unit's name.
client_show_in_client_engagement_section

boolean — Whether this variable will be shown in the Zoom client's Engagement section. * global
client_show_in_client_profile_section

boolean — Whether this variable will be shown in the Zoom client's Profile section. * global
client_show_in_inbound_call_notifications

boolean — Whether this variable will be shown as an inbound call notification on the Zoom client. * global * address book
data_type

string, possible values: "string", "number", "boolean", "date_time", "currency", "percentage", "email", "url", "phone", "json", "array" — The data's type. * `string` * `number` * `boolean` * `date_time` * `currency` * `percentage` * `email` * `url` * `phone`
default_value

string — The variable's default value.
linked_value_lock

boolean, default: false — The variable linked value's lock. * `true` - The variable can't be updated in a flow. It is the same for each engagement. * `false` - the variable value can be updated in a flow. Each engagement will use the latest value.
mask_variable_data

boolean, default: false — Mask variable data, for sensitive information.
use_as_routing_profile_parameters

boolean, default: false — Whether to use in the routing profile. * `true` - Values used as routing profile parameters. * `false` - Not used as a value for routing configuration file parameters.
use_in_external_url_parameters

boolean — Lets you use the parameter value in defining external URLs launched for each engagement. * global * address book
use_in_reporting

boolean, default: false — Whether to use in reporting.
value_category

string — The variable value's category. Returned only if `variable_type` is `global_variable`. * `undefined` - Each engagement starts without a pre-set value. * `default_value` - Each engagement starts with the default value. * `linked_value` - The value links across flows, and each engagement uses the latest value.
values

array — The variable's values.

Items:

string
variable_description

string — The variable's description.
variable_group_id

string — The variable group's ID.
variable_id

string — The variable's unique ID.
variable_name

string — The variable's name.
variable_type

string, possible values: "global_variable", "address_book_variable" — The variable's type. * `global_variable` * `address_book_variable`

Example:

{
  "variable_id": "W_VATTk_Q5aW6z5rZtBxAQ",
  "variable_group_id": "afececcd-0c9f-48de-9d19-0c84e8bdfeca",
  "variable_name": "variable demo name",
  "variable_description": "This is a variable description",
  "variable_type": "global_variable",
  "address_books": [
    {
      "address_book_id": "X2e_jsLNRkCjI0sQg2kRQQ",
      "address_book_name": "Jill's address book",
      "unit_id": "zeYjXoDOS_eV1QmTpj63PQ",
      "unit_name": "Address Book Unit",
      "total_contacts": 3
    }
  ],
  "use_in_reporting": false,
  "mask_variable_data": true,
  "use_as_routing_profile_parameters": false,
  "data_type": "number",
  "value_category": "default_value",
  "values": [
    "X2e_jsLNRkCjI0sQg2kRQQ"
  ],
  "linked_value_lock": false,
  "default_value": "test-value",
  "use_in_external_url_parameters": true,
  "client_show_in_client_profile_section": true,
  "client_show_in_client_engagement_section": true,
  "client_show_in_inbound_call_notifications": true
}

Status: 400 HTTP Status Code: `400` Bad Request Error Code: `3402` The `address_book_ids` field cannot be empty. Error Code: `3403` The variable already exists in the current custom group: `$variable_name`. Error Code: `3404` The `values` do not match `data_type`. Error Code: `3405` Invalid date format. Error Code: `3406` This `data_type`: $data_type is not supported when `variable_type` is $variable_type. Error Code: `3407` The `values`` field cannot be empty. Error Code: `3420` The `values` field maximum length is over limit. Error Code:** `2006` Address books does not exist

Status: 404 HTTP Status Code: `404` Not Found Error Code: `3409` Variable group does not exist: $group_id.

Status: 429 HTTP Status Code: `429` Too Many Requests. For more information, see [rate limits](/docs/api/rate-limits/).

List variable groups

Method: GET
Path: /contact_center/variables/groups
Tags: Variables

Return a list of variable groups.

Scopes: contact_center_variable:read:admin

Granular Scopes: contact_center:read:list_variable_groups:admin

Rate Limit Label: MEDIUM

Responses

Status: 200 HTTP Status Code: `200` Variable groups returned.

Content-Type: application/json

next_page_token

string — Use the next page token to paginate through large result sets. A next page token is returned whenever the set of available results exceeds the current page size. This token's expiration period is 15 minutes.
page_size

integer, default: 10 — The number of records returned within a single API call.
total_records

integer — The total number of all the records available across pages.
variable_groups

array — Information about the variable groups.

Items:
- variable_group_description
  
  string — The variable group's description.
- variable_group_id
  
  string — The variable group's ID.
- variable_group_name
  
  string — The variable group's name.
- variable_group_type
  
  string, possible values: "system", "custom" — The variable group's type. The type can be either system or custom.
- variable_group_variables_count
  
  integer — The number of the variables in the group.

Example:

{
  "next_page_token": "R4aF9Oj0fVM2hhezJTEmSKaBSkfesDwGy42",
  "page_size": 10,
  "total_records": 10,
  "variable_groups": [
    {
      "variable_group_id": "71ec9348-27db-4fe6-81b9-5b8637ca299b",
      "variable_group_name": "Agent",
      "variable_group_description": "Agent's first custom group.",
      "variable_group_type": "system",
      "variable_group_variables_count": 1
    }
  ]
}

Status: 400 HTTP Status Code: `400` Bad Request

Status: 429 HTTP Status Code: `429` Too Many Requests. For more information, see [rate limits](/docs/api/rest/rate-limits/).

Create a variable group

Method: POST
Path: /contact_center/variables/groups
Tags: Variables

Create a custom variable group.

Scopes: contact_center_variable:write:admin

Granular Scopes: contact_center:write:variable_group:admin

Rate Limit Label: LIGHT

Request Body

Content-Type: application/json

variable_group_name (required)

string — The variable group's name.
variable_group_description

string — The variable group's description.
variable_group_type

string, possible values: "custom", default: "custom" — The variable group's type. The type can only be custom.

Example:

{
  "variable_group_name": "us.group",
  "variable_group_description": "The first custom group.",
  "variable_group_type": "custom"
}

Responses

Status: 201 success

Content-Type: application/json

variable_group_description

string — The variable group's description.
variable_group_id

string — The variable group's ID.
variable_group_name

string — The variable group's name.
variable_group_type

string, possible values: "custom", default: "custom" — The variable group's type. The type can only be custom.
variable_group_variables_count

integer, default: 0 — The number of variables in the created group.

Example:

{
  "variable_group_id": "71ec9348-27db-4fe6-81b9-5b8637ca299b",
  "variable_group_name": "us.group",
  "variable_group_description": "The first custom group.",
  "variable_group_type": "custom",
  "variable_group_variables_count": 0
}

Status: 400 HTTP Status Code: `400` Bad Request Error Code: `3415` The number of variable groups has reached the maximum. Error Code: `3416` The variable group already exists.

Status: 429 HTTP Status Code: `429` Too Many Requests. For more information, see [rate limits](/docs/api/rate-limits/).

Get a variable group

Method: GET
Path: /contact_center/variables/groups/{variableGroupId}
Tags: Variables

Get information about a variable group.

Scopes: contact_center_variable:read:admin

Granular Scopes: contact_center:read:variable_group:admin

Rate Limit Label: LIGHT

Responses

Status: 200 HTTP Status Code: `200` Variable group returned.

Content-Type: application/json

variable_group_description

string — The variable group's description.
variable_group_id

string — The variable group's ID.
variable_group_name

string — The variable group's name.
variable_group_type

string, possible values: "system", "custom" — The variable group's type. The type can be either system or custom.
variable_group_variables_count

integer — The number of the variables in the group.

Example:

{
  "variable_group_id": "71ec9348-27db-4fe6-81b9-5b8637ca299b",
  "variable_group_name": "Agent",
  "variable_group_description": "Agent's first custom group.",
  "variable_group_type": "system",
  "variable_group_variables_count": 1
}

Status: 400 HTTP Status Code: `400` Bad Request

Status: 401 HTTP Status Code: `401` Unauthorized Error Code: `124` Invalid access token. Error Code: `124` Access token has expired. Error Code: `1002` The user associated with this access token was not found or is invalid.

Status: 403 HTTP Status Code: `403` Forbidden Error Code: `1021` User account is deactivated. Error Code: `1022` User does not have a Contact Center license. Error Code: `9001` The Contact Center user associated with this bearer token is missing privileges on their role required to operate this request.

Status: 404 HTTP Status Code: `404` Not Found Error Code: `3409` Variable group does not exist.

Status: 429 HTTP Status Code: `429` Too Many Requests. For more information, see [rate limits](https://developers.zoom.us/docs/api/rate-limits/). Error Code: `4001` You have reached the maximum per-second rate limit for this API. Try again later.

Delete a variable group

Method: DELETE
Path: /contact_center/variables/groups/{variableGroupId}
Tags: Variables

Delete a specified variable group.

Scopes: contact_center_variable:write:admin

Granular Scopes: contact_center:delete:variable_group:admin

Rate Limit Label: LIGHT

Responses

Status: 204 HTTP Status Code: `204` Variable group deleted.

Status: 400 HTTP Status Code: `400` Bad Request Error Code: `300` Invalid variable group type. Only Custom group can be deleted or updated.

Status: 404 HTTP Status Code: `404` Not Found Error Code: `3409` Variable group does not exist.

Status: 429 HTTP Status Code: `429` Too Many Requests. For more information, see [rate limits](https://developers.zoom.us/docs/api/rest/rate-limits/).

Update a variable group

Method: PATCH
Path: /contact_center/variables/groups/{variableGroupId}
Tags: Variables

Update a variable group.

Scopes: contact_center_variable:write:admin

Granular Scopes: contact_center:update:variable_group:admin

Rate Limit Label: LIGHT

Request Body

Content-Type: application/json

variable_group_description

string — The variable group's description.
variable_group_name

string — The variable group's name.

Example:

{
  "variable_group_name": "us.group.dev",
  "variable_group_description": "Update this group."
}

Responses

Status: 204 HTTP Status Code: `204` Variable group updated.

Status: 400 HTTP Status Code: `400` Bad Request Error Code: `300` Invalid variable group type. Only custom group can be deleted or updated. Error Code: `3416` Global variable already exists.

Status: 404 HTTP Status Code: `404` Not Found Error Code: `3409` Variable group does not exist.

Status: 429 HTTP Status Code: `429` Too Many Requests. For more information, see [rate limits](/docs/api/rate-limits/).

Get a variable

Method: GET
Path: /contact_center/variables/{variableId}
Tags: Variables

Retrieve a variable.

Scopes: contact_center_variable:read:admin

Granular Scopes: contact_center:read:variable:admin

Rate Limit Label: LIGHT

Responses

Status: 200 HTTP Status Code: `200` Variable returned.

Content-Type: application/json

address_books

array — The address book list. This field is only returned when `variable_type:address_book_variable`.

Items:
- address_book_id
  
  string — The address book's ID.
- address_book_name
  
  string — The address book's name.
- total_contacts
  
  integer — The address book's total number of contacts.
- unit_id
  
  string — The address book's unit ID.
- unit_name
  
  string — The address book unit's name.
client_show_in_client_engagement_section

boolean — Whether this variable will be shown in the Zoom client's Engagement section. Variable types: global
client_show_in_client_profile_section

boolean — Whether this variable will be shown in the Zoom client's Profile section. Variable types: global
client_show_in_inbound_call_notifications

boolean — Whether this variable will be shown as an inbound call notification on the Zoom client. Variable types: global, address book
data_type

string, possible values: "string", "number", "boolean", "date_time", "currency", "percentage", "email", "url", "phone", "json", "array" — The data's type.
default_value

string — The variable's default value.
linked_value_lock

boolean, default: false — The variable linked value's lock. * `true` - The variable cannot be updated in a flow. it will be the same for each engagement. * `false` - the variable value can be updated in a flow. each engagement will use the latest value.
mask_variable_data

boolean, default: false — Mask variable data, for sensitive information.
use_as_routing_profile_parameters

boolean, default: false — Whether to use in routing profile. * `true` - Values used as routing profile parameters. * `false` - Not used as a value for routing configuration file parameters.
use_in_external_url_parameters

boolean — Lets you use the parameter value in defining external URLs launched for each engagement. Variable types: global, address book
use_in_reporting

boolean, default: false — Whether to use in reporting.
value_category

string — The variable value's category. Returned only if `variable_type:global_variable`. * `undefined` - Each engagement starts without a pre-set value. * `default_value` - Each engagement starts with the default value. * `linked_value` - The value links across flows, and each engagement uses the latest value.
values

array — The variable's values.

Items:

string
variable_description

string — The variable's description.
variable_group_id

string — The variable group's ID.
variable_id

string — The variable's unique ID.
variable_name

string — The variable's name.
variable_type

string, possible values: "global_variable", "address_book_variable" — The variable's type.

Example:

{
  "variable_id": "W_VATTk_Q5aW6z5rZtBxAQ",
  "variable_group_id": "afececcd-0c9f-48de-9d19-0c84e8bdfeca",
  "variable_name": "variable demo name",
  "variable_description": "This is a variable description",
  "variable_type": "global_variable",
  "address_books": [
    {
      "address_book_id": "X2e_jsLNRkCjI0sQg2kRQQ",
      "address_book_name": "Jill's address book",
      "unit_id": "zeYjXoDOS_eV1QmTpj63PQ",
      "unit_name": "Address Book Unit",
      "total_contacts": 3
    }
  ],
  "use_in_reporting": false,
  "mask_variable_data": true,
  "use_as_routing_profile_parameters": false,
  "data_type": "number",
  "value_category": "default_value",
  "values": [
    "X2e_jsLNRkCjI0sQg2kRQQ"
  ],
  "linked_value_lock": false,
  "default_value": "test-value",
  "use_in_external_url_parameters": true,
  "client_show_in_client_profile_section": true,
  "client_show_in_client_engagement_section": true,
  "client_show_in_inbound_call_notifications": true
}

Status: 400 HTTP Status Code: `400` Bad Request

Status: 401 HTTP Status Code: `401` Unauthorized Error Code: `124` Invalid access token. Error Code: `124` Access token has expired. Error Code: `1002` The user associated with this access token was not found or is invalid.

Status: 403 HTTP Status Code: `403` Forbidden Error Code: `1021` User account is deactivated. Error Code: `1022` User does not have a Contact Center license. Error Code: `9001` The Contact Center user associated with this bearer token is missing privileges on their role required to operate this request.

Status: 404 HTTP Status Code: `404` Not Found Error Code: `3401` Variable does not exist: $variableId.

Status: 429 HTTP Status Code: `429` Too Many Requests. For more information, see [rate limits](https://developers.zoom.us/docs/api/rate-limits/). Error Code: `4001` You have reached the maximum per-second rate limit for this API. Try again later.

Delete a variable

Method: DELETE
Path: /contact_center/variables/{variableId}
Tags: Variables

Delete a variable.

Scopes: contact_center_variable:write:admin

Granular Scopes: contact_center:delete:variable:admin

Rate Limit Label: LIGHT

Responses

Status: 204 HTTP Status Code: `204` Variable deleted.

Status: 400 HTTP Status Code: `400` Bad Request

Status: 404 HTTP Status Code: `404` Not Found Error Code: `3401` Variable does not exist: $variableId.

Status: 429 HTTP Status Code: `429` Too Many Requests. For more information, see [rate limits](https://developers.zoom.us/docs/api/rest/rate-limits/).

Update a variable

Method: PATCH
Path: /contact_center/variables/{variableId}
Tags: Variables

Update a variable.

Scopes: contact_center_variable:write:admin

Granular Scopes: contact_center:update:variable:admin

Rate Limit Label: LIGHT

Request Body

Content-Type: application/json

address_book_ids

array — The address book IDs. Only valid when `variable_type:address_book_variable`.

Items:

string
client_show_in_client_engagement_section

boolean — Whether this variable will be shown in the Zoom client's Engagement section. Only valid if `data_type` is not `json` or `array`. Variable types: global
client_show_in_client_profile_section

boolean — Whether this variable will be shown in the Zoom client's Profile section. Only valid if `data_type` is not `json` or `array`. Variable types: global
client_show_in_inbound_call_notifications

boolean — Whether this variable will be shown as an inbound call notification on the Zoom client. Only valid if `data_type` is not `json` or `array`. Variable types: global, address book
data_type

string, possible values: "string", "number", "boolean", "date_time", "currency", "percentage", "email", "url", "phone", "json", "array" — The data's type. `variable_type:address_book_variable` only applies to data types with `*` * `string` `*` * `number` * `boolean` `*` * `date_time` -(unix timestamp) * `currency` * `percentage` * `email` * `url` * `phone` - ([E.164 format](https://en.wikipedia.org/wiki/E.164))
default_value

string — The variable's default value. Only used when `variable_type:address_book_variable` and `data_type:string`.
linked_value_lock

boolean, default: false — The variable linked value's lock. Only valid when `value_category:linked_value`. * `true` - The variable cannot be updated in a flow. it will be the same for each engagement. * `false` - The variable value can be updated in a flow. each engagement will use the latest value.
mask_variable_data

boolean, default: false — Mask variable data (for sensitive information). Only valid when `variable_type:global_variable` and the value of data_type is not `boolean`, `date_time`, `percentage`.
use_as_routing_profile_parameters

boolean, default: false — Whether to use in routing profile. Only valid when `variable_type:address_book_variable` and `data_type` are now `json` or `array`. * `true` - Values used as routing profile parameters. * `false` - Not used as a value for routing configuration file parameters.
use_in_external_url_parameters

boolean — Lets you use the parameter value in defining external URLs launched for each engagement. Only valid if `data_type` is not `json` or `array`. Variable types: global, address book
use_in_reporting

boolean, default: false — Whether to use in reporting. Only valid when `variable_type:global_variable`.
value_category

string — The variable value's category. Only valid when `variable_type:global_variable`. * `undefined` - Each engagement starts without a pre-set value. * `default_value` - Each engagement starts with the default value. * `linked_value` - The value links across flows, and each engagement uses the latest value.
values

array — The variable's values. Take only the first value in the array when `variable_type` is `global_variable`. * If `variable_type` is `global_variable`, each value's max length is 4096. * If `variable_type` is `address_book_variable`, each value's max length is 300.

Items:

string
variable_description

string — The variable's description.
variable_name

string — The variable's name.

Example:

{
  "variable_name": "variable demo name",
  "variable_description": "This is a variable description",
  "address_book_ids": [
    "X2e_jsLNRkCjI0sQg2kRQQ"
  ],
  "use_in_reporting": false,
  "mask_variable_data": false,
  "use_as_routing_profile_parameters": false,
  "data_type": "number",
  "value_category": "default_value",
  "values": [
    "test-value-1"
  ],
  "linked_value_lock": false,
  "default_value": "test-value-1",
  "use_in_external_url_parameters": true,
  "client_show_in_client_profile_section": true,
  "client_show_in_client_engagement_section": true,
  "client_show_in_inbound_call_notifications": true
}

Responses

Status: 204 HTTP Status Code: `204` Variable updated.

Status: 400 HTTP Status Code: `400` Bad Request Error Code: `3403` The variable already exists in the current custom group: $variable_name. Error Code: `3404` The `values` does not match `data_type`. Error Code: `3405` Invalid date format. Error Code: `3406` This `data_type`: $data_type is not supported when `variable_type` is $variable_type. Error Code: `3420` The `values` length is over limit. Error Code: `2006` Address books do not exist.

Status: 404 HTTP Status Code: `404` Not Found Error Code: `300` Validation failed Error Code: `3401` Variable does not exist: $variableId.

Contact Center

Servers

Operations

List address books

Responses

Status: 200 **HTTP Status Code:** `200` Address books list returned.

Content-Type: application/json

Status: 400 **HTTP Status Code:** `400` <br> Bad Request **Error Code:** `1902` <br> The `unit_id` field cannot be an empty value. <br>

Status: 404 **HTTP Status Code:** `404` <br> Not Found **Error Code:** `1901` <br> Unit does not exist: $unitId. <br>

Status: 429 **HTTP Status Code:** `429` <br> Too Many Requests. For more information, see [rate limits](/docs/api/rest/rate-limits/).

Create an address book

Request Body

Content-Type: application/json

Responses

Status: 201 **HTTP Status Code:** `201` Address book created.

Content-Type: application/json

Status: 404 **HTTP Status Code:** `404` <br> Not Found **Error Code:** `1901` <br> Unit does not exist: $unitId. <br>

Status: 429 **HTTP Status Code:** `429` <br> Too Many Requests. For more information, see [rate limits](/docs/api/rest/rate-limits/).

List a contact's custom fields

Responses

Status: 200 HTTP Status Code: 200 Contact custom fields are returned.

Content-Type: application/json

Status: 400 **HTTP Status Code:** `400` <br> Bad Request

Status: 401 **HTTP Status Code:** `401` <br> Unauthorized

Status: 403 **HTTP Status Code:** `403` <br> Forbidden

Status: 404 **HTTP Status Code:** `404` <br> Not Found **Error Code:** `2101` <br> Contact does not exist: $contactId. <br>

Status: 429 **HTTP Status Code:** `429` <br> Too Many Requests. For more information, see [rate limits](/docs/api/rate-limits/).

List an address book's custom fields

Responses

Status: 200 The address book's custom fields list is returned.

Content-Type: application/json

Status: 400 **HTTP Status Code:** `400` <br> Bad Request

Status: 429 **HTTP Status Code:** `429` <br> Too Many Requests. For more information, see [rate limits](/docs/api/rate-limits/).

Create an address book custom field

Request Body

Content-Type: application/json

Responses

Status: 201 Custom field created.

Content-Type: application/json

Status: 404 **HTTP Status Code:** `404` <br> Not Found **Error Code:** `2006` <br> Address books does not exist: $addressBookIds. <br>

Status: 429 **HTTP Status Code:** `429` <br> Too Many Requests. For more information, see [rate limits](/docs/api/rate-limits/).

Get an address book's custom field

Responses

Status: 200 The address book's custom field is returned.

Content-Type: application/json

Status: 400 **HTTP Status Code:** `400` <br> Bad Request

Status: 404 **HTTP Status Code:** `404` <br> Not Found **Error Code:** `2112` <br> Custom field does not exist: $customFieldId <br>

Status: 429 **HTTP Status Code:** `429` <br> Too Many Requests. For more information, see [rate limits](https://developers.zoom.us/docs/api/rate-limits/).

Delete an address book custom field

Responses

Status: 204 Custom field deleted.

Status: 400 **HTTP Status Code:** `400` <br> Bad Request

Status: 404 **HTTP Status Code:** `404` <br> Not Found **Error Code:** `2112` <br> Custom field does not exist: $customFieldId. <br>

Status: 429 **HTTP Status Code:** `429` <br> Too Many Requests. For more information, see [rate limits](/docs/api/rate-limits/).

Update an address book custom field

Request Body

Content-Type: application/json

Responses

Status: 204 Custom field updated.

Status: 404 **HTTP Status Code:** `404` <br> Not Found **Error Code:** `2112` <br> Custom field does not exist: $customFieldId. <br> **Error Code:** `2006` <br> Address books does not exist: $addressBookIds. <br>

Status: 429 **HTTP Status Code:** `429` <br> Too Many Requests. For more information, see [rate limits](/docs/api/rate-limits/).

List address book units

Responses

Status: 200 **HTTP Status Code:** `200` Units list returned.

Content-Type: application/json

Status: 400 **HTTP Status Code:** `400` <br> Bad Request

Status: 429 **HTTP Status Code:** `429` <br> Too Many Requests. For more information, see [rate limits](/docs/api/rest/rate-limits/).

Create an address book unit

Request Body

Content-Type: application/json

Responses

Status: 201 **HTTP Status Code:** `201` Unit created.

Content-Type: application/json

Status: 400 **HTTP Status Code:** `400` <br> Bad Request **Error Code:** `1904` <br> Unit already exists. <br>

Status: 429 **HTTP Status Code:** `429` <br> Too Many Requests. For more information, see [rate limits](/docs/api/rest/rate-limits/).

Get an address book unit

Responses

Status: 200 **HTTP Status Code:** `200` Unit returned.

Content-Type: application/json

Status: 400 **HTTP Status Code:** `400` <br> Bad Request **Error Code:** `2008` <br> More than one matching address book unit found. <br>

Status: 200 HTTP Status Code: `200` Address books list returned.

Status: 400 HTTP Status Code: `400` <br> Bad Request Error Code: `1902` <br> The `unit_id` field cannot be an empty value. <br>

Status: 404 HTTP Status Code: `404` <br> Not Found Error Code: `1901` <br> Unit does not exist: $unitId. <br>

Status: 429 HTTP Status Code: `429` <br> Too Many Requests. For more information, see [rate limits](/docs/api/rest/rate-limits/).

Status: 201 HTTP Status Code: `201` Address book created.

Status: 404 HTTP Status Code: `404` <br> Not Found Error Code: `1901` <br> Unit does not exist: $unitId. <br>

Status: 429 HTTP Status Code: `429` <br> Too Many Requests. For more information, see [rate limits](/docs/api/rest/rate-limits/).

Status: 400 HTTP Status Code: `400` <br> Bad Request

Status: 401 HTTP Status Code: `401` <br> Unauthorized

Status: 403 HTTP Status Code: `403` <br> Forbidden

Status: 404 HTTP Status Code: `404` <br> Not Found Error Code: `2101` <br> Contact does not exist: $contactId. <br>

Status: 429 HTTP Status Code: `429` <br> Too Many Requests. For more information, see [rate limits](/docs/api/rate-limits/).

Status: 400 HTTP Status Code: `400` <br> Bad Request

Status: 429 HTTP Status Code: `429` <br> Too Many Requests. For more information, see [rate limits](/docs/api/rate-limits/).

Status: 404 HTTP Status Code: `404` <br> Not Found Error Code: `2006` <br> Address books does not exist: $addressBookIds. <br>

Status: 429 HTTP Status Code: `429` <br> Too Many Requests. For more information, see [rate limits](/docs/api/rate-limits/).

Status: 400 HTTP Status Code: `400` <br> Bad Request

Status: 404 HTTP Status Code: `404` <br> Not Found Error Code: `2112` <br> Custom field does not exist: $customFieldId <br>

Status: 429 HTTP Status Code: `429` <br> Too Many Requests. For more information, see [rate limits](https://developers.zoom.us/docs/api/rate-limits/).

Status: 400 HTTP Status Code: `400` <br> Bad Request

Status: 404 HTTP Status Code: `404` <br> Not Found Error Code: `2112` <br> Custom field does not exist: $customFieldId. <br>

Status: 429 HTTP Status Code: `429` <br> Too Many Requests. For more information, see [rate limits](/docs/api/rate-limits/).

Status: 404 HTTP Status Code: `404` <br> Not Found Error Code: `2112` <br> Custom field does not exist: $customFieldId. <br> Error Code: `2006` <br> Address books does not exist: $addressBookIds. <br>

Status: 429 HTTP Status Code: `429` <br> Too Many Requests. For more information, see [rate limits](/docs/api/rate-limits/).

Status: 200 HTTP Status Code: `200` Units list returned.

Status: 400 HTTP Status Code: `400` <br> Bad Request

Status: 429 HTTP Status Code: `429` <br> Too Many Requests. For more information, see [rate limits](/docs/api/rest/rate-limits/).

Status: 201 HTTP Status Code: `201` Unit created.

Status: 400 HTTP Status Code: `400` <br> Bad Request Error Code: `1904` <br> Unit already exists. <br>

Status: 429 HTTP Status Code: `429` <br> Too Many Requests. For more information, see [rate limits](/docs/api/rest/rate-limits/).

Status: 200 HTTP Status Code: `200` Unit returned.

Status: 400 HTTP Status Code: `400` <br> Bad Request Error Code: `2008` <br> More than one matching address book unit found. <br>

Status: 401 HTTP Status Code: `401` <br> Unauthorized

Status: 403 HTTP Status Code: `403` <br> Forbidden

Status: 404 HTTP Status Code: `404` <br> Not Found Error Code: `1901` <br> Unit does not exist: $unitId. <br>

Status: 429 HTTP Status Code: `429` <br> Too Many Requests. For more information, see [rate limits](/docs/api/rest/rate-limits/).

Status: 204 HTTP Status Code: `204` Unit deleted.

Status: 400 HTTP Status Code: `400` <br> Bad Request Error Code: `1905` <br> Salesforce integration unit cannot be updated and deleted. <br>

Status: 404 HTTP Status Code: `404` <br> Not Found Error Code: `1901` <br> Unit does not exist: $unitId. <br>

Status: 429 HTTP Status Code: `429` <br> Too Many Requests. For more information, see [rate limits](/docs/api/rest/rate-limits/).

Status: 204 HTTP Status Code: `204` Unit updated.

Status: 400 HTTP Status Code: `400` <br> Bad Request Error Code: `1905` <br> Salesforce integration unit cannot be updated or deleted. <br>

Status: 404 HTTP Status Code: `404` <br> Not Found Error Code: `1901` <br> Unit does not exist: $unitId. <br>

Status: 429 HTTP Status Code: `429` <br> Too Many Requests. For more information, see [rate limits](/docs/api/rest/rate-limits/).

Status: 200 HTTP Status Code: `200` Address book list returned.

Status: 400 HTTP Status Code: `400` <br> Bad Request Error Code: `2007` <br> More than one matching address book found. <br>

Status: 401 HTTP Status Code: `401` <br> Unauthorized

Status: 403 HTTP Status Code: `403` <br> Forbidden

Status: 404 HTTP Status Code: `404` <br> Not Found Error Code: `2001` <br> Address book does not exist: $addressBookId. <br>

Status: 429 HTTP Status Code: `429` <br> Too Many Requests. For more information, see [rate limits](/docs/api/rest/rate-limits/).

Status: 204 HTTP Status Code: `204` Address Book deleted.

Status: 400 HTTP Status Code: `400` <br> Bad Request

Status: 404 HTTP Status Code: `404` <br> Not Found Error Code: `1201` <br> Address book does not exist: $addressBookId <br>

Status: 429 HTTP Status Code: `429` <br> Too Many Requests. For more information, see [rate limits](/docs/api/rest/rate-limits/).

Status: 204 HTTP Status Code: `204` Address book updated.

Status: 400 HTTP Status Code: `400` <br> Bad Request Error Code: `2004` <br> Salesforce integration address book cannot be updated or deleted. <br>

Status: 404 HTTP Status Code: `404` <br> Not Found Error Code: `2001` <br> Address book does not exist: $addressBookId. <br>

Status: 429 HTTP Status Code: `429` <br> Too Many Requests. For more information, see [rate limits](/docs/api/rest/rate-limits/).

Status: 200 HTTP Status Code: `200` Contacts list returned.

Status: 401 HTTP Status Code: `401` <br> Unauthorized

Status: 403 HTTP Status Code: `403` <br> Forbidden

Status: 404 HTTP Status Code: `404` <br> Not Found Error Code: `2001` <br> Address book does not exist: $addressBookId. <br>

Status: 429 HTTP Status Code: `429` <br> Too Many Requests. For more information, see [rate limits](/docs/api/rate-limits/).

Status: 201 HTTP Status Code: `201` Contact created.

Status: 401 HTTP Status Code: `401` <br> Unauthorized Error Code: `1002` <br> The user associated with this access token was not found or is invalid. <br> Error Code: `124` <br> Invalid access token. <br> Error Code: `124` <br> Access token has expired. <br>

Status: 404 HTTP Status Code: `404` <br> Not Found Error Code: `2001` <br> Address book does not exist: $addressBookId. <br>

Status: 429 HTTP Status Code: `429` <br> Too Many Requests. For more information, see [rate limits](/docs/api/rest/rate-limits/). Error Code: `4001` <br> You have reached the maximum per-second rate limit for this API. Try again later. <br>

Status: 200 HTTP Status Code: `200` Contacts created. When some contacts fail validation, the response includes both `contacts` (successful) and `invalid_contacts` (failed with error details).