Contact Center Master API
- 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 SMS logs
- Method:
GET - Path:
/accounts/{accountId}/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:master
Granular Scopes: contact_center:read:sms_log:master
Rate Limit Label: HEAVY
Parameters
next_page_token
- In:
query
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.
string
page_size
- In:
query
The number of items returned per page.
integer, format: int32, default: 10
from
- In:
query
The start time and date in yyyy-mm-dd or ISO 8601 format, which is 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.
string, format: date
to
- In:
query
Required only when the from parameter is specified. The end time and date in yyyy-mm-dd or ISO 8601 format, which is either yyyy-MM-dd'T'HH:mm:ss'Z' or yyyy-MM-dd'T'HH:mm:ss'TZD'.
string, format: date
country_iso_codes
- In:
query
Two-letter ISO country code.
string
- Max items:
20
direction
- In:
query
The engagement's direction.
string, possible values: "inbound", "outbound"
user_id
- In:
query
The agent's ID.
string
engagement_id
- In:
query
The engagement's ID.
string
consumer_number
- In:
query
The consumer's phone number.
string
X-Zoom-Division-Id
- In:
header
Optional. The Contact Center division ID used to scope this request. The authenticated caller must be a super admin. Non super admin callers receive a DIVISION_ACCESS_DENIED error.
When provided, the request operates against the division's account context rather than the caller's primary account. If the same value is also supplied in the body field division_id or the query parameter division_id, the body takes precedence, then the query parameter, and then this header. The value must be 50 characters or fewer. If Contact Center division support is not enabled for the account, this header is silently ignored and the request proceeds against the caller's primary account.
string
accountId required
- In:
path
Unique identifier of the account.
string
Responses
Status: 200 **HTTP Status Code:** `200` Variables list returned
Content-Type: application/json
division_idstring— A Contact Center division's ID. For requests, the request is scoped to the specified division and takes precedence over the `division_id` query parameter and `X-Zoom-Division-Id` header. The caller must be a super admin. Otherwise, the request returns `DIVISION_ACCESS_DENIED`. For responses, identifies the resource's division and is omitted when no division context applies. If Contact Center division support is disabled, the request value is ignored.division_namestring— The human readable name of the Contact Center division that the resource belongs to. Returned alongside `division_id` whenever a division context was resolved for the request and omitted otherwise.fromstring, 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_tokenstring— 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_sizeinteger, default:10— The number of records returned in a single API call.smsarray— Information about the SMS.Items: agentsarray— Information about the engagement's agents.Items: display_namestring— The agent's name.user_idstring— The agent's ID.
consumer_display_namestring— The consumer's name.consumer_numberstring— The consumer's phone number.contact_center_numberstring— The agent's number. An agent used a flow or queue number and did not really have its own number.country_namestring— The country name.directionstring, possible values:"inbound", "outbound"— The engagement's direction. `inbound` | `outbound`.end_timestring, 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_idstring— The engagement's IDqueuesarray— Information about the engagement's queues.Items: cc_queue_idstring— The Contact Center queue's ID.queue_idstring— The queue's ID.queue_namestring— The queue's name.
sms_typesarray— The SMS's type.Items: string, possible values:"sms", "mms"start_timestring, 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_filesinteger, format:int64— The total number of received files.total_received_messagesinteger, format:int64— The total number of received messages.total_sent_filesinteger, format:int64— The total number of sent files.total_sent_messagesinteger, format:int64— The total number of sent messages.
tostring, 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_recordsinteger— 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
}
],
"division_name": "EMEA Operations",
"division_id": "kV9aR7Jt2QmEXfBcUz4LpA"
}Status: 400 **HTTP Status Code:** `400` <br> Bad Request
Status: 401 **HTTP Status Code:** `401` <br> Unauthorized **Error Code:** `124` <br> Invalid access token. <br> **Error Code:** `124` <br> Access token has expired. <br> **Error Code:** `1002` <br> The user associated with this access token was not found or is invalid. <br>
Status: 403 **HTTP Status Code:** `403` <br> Forbidden **Error Code:** `1021` <br> User account is deactivated. <br> **Error Code:** `1022` <br> User does not have a Contact Center license. <br> **Error Code:** `9001` <br> The Contact Center user associated with this bearer token is missing privileges on their role required to operate this request. <br>
Status: 404 **HTTP Status Code:** `404` <br> Not Found **Error Code:** `2901` <br> Engagement does not exist: $engagementId. <br> **Error Code:** `1001` <br> User does not exist: $userId. <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/). **Error Code:** `4001` <br> You have reached the maximum per-second rate limit for this API. Try again later. <br>
List voice call logs
- Method:
GET - Path:
/accounts/{accountId}/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, session_border_controller_list.session_border_controller_name, session_border_controller_list.session_border_controller_ip_address, session_border_controller_list.consumer_zoom_trunk_name and session_border_controller_list.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:master
Granular Scopes: contact_center:read:voice_call_log:master
Rate Limit Label: HEAVY
Parameters
from
- In:
query
The start time and date in either yyyy-MM-dd, yyyy-MM-dd'T'HH:mm:ss'Z', or yyyy-MM-dd'T'HH:mm:ss±HH:mm 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.
Note When using yyyy-MM-dd'T'HH:mm:ss'Z' format, the 'Z' is treated as a literal character. The timezone offset from yyyy-MM-dd'T'HH:mm:ss±HH:mm format is used for response datetime formatting.
string
to
- In:
query
Required only when the from parameter is specified. The end time and date in yyyy-MM-dd, yyyy-MM-dd'T'HH:mm:ss'Z', or yyyy-MM-dd'T'HH:mm:ss±HH:mm format, matching the format of the from parameter.
string
types
- In:
query
The call's type.
string, possible values: "external_call", "external_conference_call", "external_callback_call", "internal_call", "internal_conference_call", "internal_callback_call"
distribution
- In:
query
The engagement's distribution.
string, possible values: "acd", "non_acd"
consumer_number
- In:
query
The consumer's phone number.
string
direction
- In:
query
The engagement's direction.
string, possible values: "inbound", "outbound"
user_ids
- In:
query
A comma-separated list of agents' user IDs to query, up to 20 agent IDs.
string
- Max items:
20
engagement_id
- In:
query
The engagement's ID.
string
queue_ids deprecated
- In:
query
A comma-separated list of queue IDs to query, up to 20 queue IDs. If user provide none, filter by No queue used in the web UI.
string
- Max items:
20
cc_queue_ids
- In:
query
A comma-separated list of Contact Center queue IDs to query, up to 20 queue IDs. If a user provides none, filter by No queue used in the web UI.
string
- Max items:
20
country_iso_codes
- In:
query
Two-letter ISO country code.
string
- Max items:
20
number_types
- In:
query
The number's type.
string, possible values: "toll_free_number", "virtual_service_number", "byoc_number"
region_ids
- In:
query
A comma-separated list of region IDs to query, up to 20 region IDs.
string
- Max items:
20 - Unique items:
true
region_names
- In:
query
A comma-separated list of region names to query, up to 20 region Names.
string
- Max items:
20 - Unique items:
true
team_ids
- In:
query
A comma-separated list of team IDs to query, up to 20 team IDs.
string
- Max items:
20 - Unique items:
true
team_names
- In:
query
A comma-separated list of team names to query, up to 20 team names.
string
- Max items:
20 - Unique items:
true
sub_types
- In:
query
A comma-separated list of detailed call leg types. Allowed subtypes
external_warm_conference_callexternal_direct_conference_callexternal_warm_transfer_callexternal_direct_transfer_callinternal_warm_conference_callinternal_direct_conference_callinternal_warm_transfer_callinternal_direct_transfer_callflow_initiated_outgoing_call- flow outgoing
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"
view_type
- In:
query
By default, this API returns the summary in List voice logs. If detail is selected, it returns all the call logs' additional details.
string, possible values: "summary", "detail", default: "summary"
next_page_token
- In:
query
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.
string
page_size
- In:
query
The number of records returned within a single API call.
integer, format: int32, default: 10
X-Zoom-Division-Id
- In:
header
Optional. The Contact Center division ID used to scope this request. The authenticated caller must be a super admin. Non super admin callers receive a DIVISION_ACCESS_DENIED error.
When provided, the request operates against the division's account context rather than the caller's primary account. If the same value is also supplied in the body field division_id or the query parameter division_id, the body takes precedence, then the query parameter, and then this header. The value must be 50 characters or fewer. If Contact Center division support is not enabled for the account, this header is silently ignored and the request proceeds against the caller's primary account.
string
accountId required
- In:
path
Unique identifier of the account.
string
Responses
Status: 200 **HTTP Status Code:** `200` Variables list returned.
Content-Type: application/json
division_idstring— A Contact Center division's ID. For requests, scopes the request to the specified division and takes precedence over the `division_id` query parameter and `X-Zoom-Division-Id` header. The caller must be a super admin. Otherwise, the request returns `DIVISION_ACCESS_DENIED`. For responses, identifies the resource's division and is omitted when no division context applies. If Contact Center division support is disabled, the request value is ignored.division_namestring— The human readable name of the Contact Center division that the resource belongs to. Returned alongside `division_id` whenever a division context was resolved for the request and omitted otherwise.fromstring, 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_tokenstring— 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_sizeinteger, default:10— The number of records returned within a single API call.tostring, 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_recordsinteger— The total number of all records available across pages.voice_callsarray— Information about the voice call.Items: agentsarray— Information about the engagement's agents.Items: display_namestring— The agent's name.sip_zone_ip_addressstring, format:ipv4— The SIP zome's IP address.team_idsarray— The agent's team IDsItems: string— agent team ID listteam_namesarray— The agent's team names.Items: string— Agent team name list.user_device_mac_addressstring— MAC address of the agent's device.user_emailstring— The agent's email.user_idstring— The agent's ID.user_ip_addressstring, format:ipv4— IP address of the agent's device.user_regionstring— The agent's region nameuser_registered_sip_zonestring— The SIP zone where the agent registered.
call_legsarray— The direction of the engagement call leg.Items: string, possible values:"inbound", "outbound"callee_numberstring— The callee's phone number.callee_number_typestring, possible values:"toll_free_number", "virtual_service_number", "byoc_number"— The callee's number type.caller_idstring— The caller's number.caller_numberstring— The caller's phone number.caller_number_typestring, possible values:"toll_free_number", "virtual_service_number", "byoc_number"— The caller's number type.calling_partystring, possible values:"consumer", "agent"— The calling's party.chargestring— The bill's charge.charge_typestring, possible values:"per_minute"— The charge type.consumer_display_namestring— The consumer's name.consumer_numberstring— The consumer's phone number.country_namestring— The country name.directionstring, possible values:"inbound", "outbound"— The engagement's direction.distributionsarray— The engagement's distribution.Items: string, possible values:"acd", "non_acd"end_timestring— 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_idstring— The engagement's IDflowsarray— Information about the engagement's flows.Items: flow_idstring— The flow's ID.flow_namestring— The flow's name.
inboxboolean— Flag to determine whether a message is in the box.monitoredboolean— Flag to determine whether to monitored.queuesarray— Information about the engagement's queues.Items: cc_queue_idstring— The Contact Center queue's ID.queue_idstring— The queue's ID.queue_namestring— The queue's name.
ratesarray— The price for each sent message.Items: stringrecordedboolean— Flag to determine whether to recorded.resultstring, 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.sbcInfosarray— Information about the session border controllers. **Note** This field will be abolished, and the `sbcInfos` will be used uniformly.Items: consumer_sbc_ip_addressstring— The customer's SBC IP address.consumer_zoom_trunk_namestring— The name of the trunk between the customer SBC and Zoom SBC.session_border_controller_ip_addressstring— The SBC's IP address.session_border_controller_namestring— The session border controller's name.
session_border_controller_listarray— Information about the session border controllers.Items: consumer_sbc_ip_addressstring— The customer's SBC IP address.consumer_zoom_trunk_namestring— The name of the trunk between the customer SBC and Zoom SBC.session_border_controller_ip_addressstring— The SBC's IP address.session_border_controller_namestring— The session border controller's name.
start_timestring— 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_typesarray— 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_durationinteger, format:int64— The engagement's total duration, in seconds.typesarray— 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_detailsarray— All related call logs.Items: agentsarray— Information about the engagement's agents.Items: display_namestring— The agent's name.sip_zone_ip_addressstring, format:ipv4— The SIP zone's IP address.team_idsarray— The agent's team IDsItems: string— Agent team ID list.team_namesarray— The agent's team names.Items: string— Agent team name list.user_device_mac_addressstring— The agent's device's MAC address.user_emailstring— The agent's email.user_idstring— The agent's ID.user_ip_addressstring, format:ipv4— The agent's device's IP address.user_regionstring— The agent's region name.user_registered_sip_zonestring— The SIP zone where the agent registered.
call_legstring, possible values:"inbound", "outbound"— The direction of the engagement call log.callee_numberstring— The callee's phone number.callee_number_typestring, possible values:"toll_free_number", "virtual_service_number", "byoc_number"— The callee's number type.caller_idstring— The caller's number.caller_numberstring— The caller's phone number.caller_number_typestring, possible values:"toll_free_number", "virtual_service_number", "byoc_number"— The caller's number type.calling_partystring, possible values:"consumer", "agent"— The calling's party.chargestring— The bill's charge.charge_typestring, possible values:"per_minute"— The charge type.consumer_display_namestring— The consumer's name.consumer_numberstring— The consumer's phone number.country_namestring— The country name.distributionstring, possible values:"acd", "non_acd"— The call log's distribution.end_timestring— 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_idstring— The engagement's ID.flowobject— Information about the flow.flow_idstring— The flow's ID.flow_namestring— The flow's name.
inboxboolean— Whether a message is in the box.monitoredboolean— Whether to monitor.queueobject— Information about the queue.cc_queue_idstring— The Contact Center queue's ID.queue_namestring— The queue's name.
ratestring— The price for sent message.recordedboolean— Whether to record.resultstring, 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_timestring— 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_durationinteger, format:int64— The call log's total duration, in seconds.typestring, 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"
}
]
}
],
"division_name": "EMEA Operations",
"division_id": "kV9aR7Jt2QmEXfBcUz4LpA"
}