Getting started with the Webex Contact Center APIs
Webex Contact Center
Verified 2026-09-30 · 55 sources · tier 2–5 · 3 disputed
For Developers and contact center admins building their first integration against a multi-tenant Webex Contact Center org..
Webex Contact Center API integrations are authorized with the OAuth 2.0 grant flow 18. This guide takes you through app registration, token acquisition, and fetching contact data via Search API polling or webhook subscriptions 34 46.
Before you start
Contact Center configuration APIs need an admin scope 11. Sources disagree on whether the Subscriptions API requires the cjp:config_read or cjp:config_write scope 47. Webhook destination URLs must be publicly reachable from the Webex cloud, as field reports suggest 55.
What changes by situation
Pick your answers to see only your path. Nothing is sent anywhere until you make a plan.
Two questions. One permanent page you can send to your manager.
Step 1 Find your region code and API host
Do
Identify your org's region code from the supported list: us1 (North America), ca1 (Canada), eu1 (UK), eu2 (EU), anz1 (APJC), jp1 (Japan), and sg1 (Singapore) 29. Cisco's Postman environment stores this in a datacenter variable configured with us1 for ProdUS1, eu1 and eu2 for ProdEU1 and ProdEU2, or anz1 for ProdANZ1 12. For the us1 region, APIs are served from https://api.wxcc-us1.cisco.com 53. WarmTransfer's reading of the sources is that tenants in other regions most likely use https://api.wxcc-<region code>.cisco.com, substituting their code for us1 3.
Verify
Suggested check: verify that the chosen host URL is reachable.
Step 2 Register the app on the developer portal
A person signs in: a user-authorized OAuth integration that acts as the admin or supervisor who granted it
Do
Register the integration at developer.webex.com 20. Since May 2025 the Webex Contact Center and Webex Suite developer portals are one portal at developer.webex.com, so developers no longer sign into two portals 20. In 2022, Cisco directed users to create integrations at developer.webex-cx.com 15, but WarmTransfer's reading of the sources is that instructions pointing to developer.webex-cx.com are probably out of date and new Contact Center apps should be registered in developer.webex.com 14. When setting up the integration, provide your redirect URI, such as https://oauth.pstmn.io/v1/callback or https://oauth.pstmn.io/v1/browser-callback for browser-based Postman 21. Store the integration's client ID and client secret 28.
Verify
Suggested check: verify that the integration is listed on the developer portal and displays its assigned client ID.
An admin approves it: an org-wide service app (machine account) that a Full Admin authorizes in Control Hub
Do
Register the service app at developer.webex.com 20. A Contact Center service app requests data for users across the whole organization and does not break when the authorizing user leaves or changes password 42. A Contact Center service app may request any integration scope except spark:applications_token and spark:kms 43. Store the client ID and client secret 44.
Verify
Suggested check: verify that the service app is visible in the developer portal with its assigned client ID.
Step 3 Configure scopes
Polling: query the Search API (and the Captures API) on a schedule
Do
Cisco advises developers to select only the minimal set of scopes their Contact Center integration needs 17. Contact Center scope options include cjp:config, cjp:config_read, and cjp:user 13. For read-only polling, assign cjp:config_read, which provides access to administrator APIs such as Get Agent Activities and the List Captures API 10 8.
Verify
Suggested check: verify that the app configuration lists cjp:config_read among its saved scopes.
Push: register webhook subscriptions and receive events
Do
Cisco advises selecting only the minimal set of scopes needed 17. Include cjp:config_read to call the List Event Types API to retrieve the resource version 16. For creating subscriptions, sources disagree on the exact scopes: one source states the Subscriptions API requires cjp:config_read or cjp:config_write 47, while cjp:user is documented as providing agent-level access such as agent WebSocket connections 10.
Verify
Suggested check: verify that cjp:config_read and any required subscription scopes are enabled on the app.
Step 4 Obtain the initial access token
A person signs in: a user-authorized OAuth integration that acts as the admin or supervisor who granted it
Do
Initiate authorization by directing the admin or supervisor to https://webexapis.com/v1/authorize 5. In the integration flow the user signs in and grants permissions, Webex returns an authorization code to the redirect URI, and the integration exchanges that code server-to-server for an access token at https://webexapis.com/v1/access_token 4 52.
Verify
Sources disagree on token lifespans: one source indicates an access token is valid for 14 days (1,209,599 seconds) and its refresh token 90 days 50, whereas an earlier source stated an access token was valid for 12 hours and its refresh token for 60 days 49.
An admin approves it: an org-wide service app (machine account) that a Full Admin authorizes in Control Hub
Do
Have an administrator authorize the Contact Center service app in Control Hub before initiating the token process 39. While service apps and integrations both use OAuth 2.0, a service app gets its access token through administrator approval rather than user browser sign-in 45. Fetch the service app access token by sending a POST request to https://webexapis.com/v1/applications/{appId}/token containing the clientId, clientSecret, and targetOrgId 44. To automate service app token retrieval, you can create a separate token manager OAuth integration with the spark:applications_token scope 51.
Verify
Suggested check: verify that the token response returns an access token field.
Step 5 Extract the organization ID
A person signs in: a user-authorized OAuth integration that acts as the admin or supervisor who granted it
Do
A Webex Contact Center access token has the form accessToken_ciCluster_orgID, where the org ID is the segment after the final underscore 19.
Verify
Suggested check: verify that the parsed org ID matches the organization ID found in Control Hub.
An admin approves it: an org-wide service app (machine account) that a Full Admin authorizes in Control Hub
Do
Retain the targetOrgId value passed in the token request payload for use in subsequent Contact Center API calls 44.
Verify
Suggested check: verify that the targetOrgId value corresponds to your intended target organization.
Step 6 Make a first test call
Do
Send a GET request to https://api.wxcc-<region code>.cisco.com/v1/tasks including the organization ID and a start datetime in epoch milliseconds 48. Contact Center API requests carry the token in an Authorization: Bearer <access token> header 6. Cisco provides working sample implementations in the webex-contact-center-api-samples repository, including an OAuth2 app-auth sample 30.
Verify
Suggested check: verify that the API returns a task list or an empty JSON array.
Step 7 Query historical data using the Search API
Do
Send queries to the Contact Center Search API, which is a GraphQL-powered REST API that exposes historical and real-time raw data, including Analyzer reporting fields 34. Use one of its 3 GraphQL queries: taskDetails over CSR and CAR records, agentSession over ASR and AAR records, or taskLegDetails over CLR data (early access) 37. Supply from and to arguments as epoch timestamps in milliseconds 33. When querying CAR or AAR data, do not span more than 30 days between from and to 32. Note that raw-data pages hold up to 250 to 500 records for taskDetails, 250 for agentSession, and 1000 for aggregations, with taskDetails returning at most 100,000 records in total 36. Search API aggregations may group by no more than 10 fields 35.
Verify
Suggested check: verify that the GraphQL endpoint returns a data object containing the requested task or session entities.
Step 8 Collect ongoing event data
Polling: query the Search API (and the Captures API) on a schedule
Do
Fetch task records using the GraphQL Search API, ensuring queries involving CAR or AAR data span 30 days or less 32 34. To retrieve recording and task metadata, query the List Captures API at /v1/captures/query, which accepts cjp:config_read or cjp-analyzer:read 8.
Verify
Suggested check: verify that scheduled runs successfully return newly completed tasks and capture records.
Rollback
Suggested rollback: disable or terminate scheduled polling jobs in the orchestration environment.
Push: register webhook subscriptions and receive events
Do
Fetch the required resource version by calling the List Event Types API, which requires cjp:config_read 16. Next, register your webhook using POST https://api.wxcc-us1.cisco.com/v2/subscriptions (substituting your region host), specifying a name, the target event types, the orgId, and the resource version 46. Contact Center webhooks span real-time, task, and agent webhooks 54. Agent webhooks fire on agent login, agent logout, and agent state change 1. The capture:available event fires when a new recording is ready and provides the taskId and a download link 7. Webhook destination URLs must be publicly reachable from the Webex cloud, as field reports suggest 55.
Verify
Trigger an agent state transition or complete a call to verify that inbound event payloads arrive at your receiver 1 7.
Step 9 Manage API rate limits
Do
When a Webex API rate limit is exceeded, the gateway returns HTTP 429 with a Retry-After header giving the number of seconds to wait 23. Cisco recommends waiting the full Retry-After time as soon as the first 429 arrives 26. WarmTransfer's reading of the sources is that Contact Center APIs probably use the same 429 and Retry-After throttling as other Webex APIs, so the same backoff handling applies 24. In the field, reports suggest that Contact Center rate limits are enforced per client ID, and that Cisco can raise them for high-volume cases on request 25.
Verify
In a test that forces a 429, the client waits for the Retry-After period and then succeeds 23.
Step 10 Maintain token validity
A person signs in: a user-authorized OAuth integration that acts as the admin or supervisor who granted it
Do
Refresh the token before the access token expires by sending a POST to https://webexapis.com/v1/access_token with grant_type=refresh_token, client_id, client_secret, and refresh_token 28. Using a Webex Contact Center refresh token resets its 90-day lifetime, so an integration that refreshes regularly keeps access indefinitely 27.
Verify
Suggested check: verify that the refresh call returns a new access token and test it with a call to the /v1/tasks endpoint.
An admin approves it: an org-wide service app (machine account) that a Full Admin authorizes in Control Hub
Do
Refresh the access token using POST https://webexapis.com/v1/access_token with grant_type=refresh_token, client_id, client_secret, and refresh_token 28. Alternatively, request a new token via the Applications token API using a dedicated token manager integration configured with spark:applications_token 44 51.
Verify
Suggested check: verify that the newly obtained token successfully authorizes requests against /v1/tasks.
Applicability
Applies to: Cisco Webex Contact Center, Cisco Webex platform APIs, and Cisco Webex platform. Deployments: multi-tenant. Sources checked 2026-09-30.
What remains uncertain
The exact procedure to delete or unregister a webhook subscription is not covered by the sources below. The specific process to delete an integration or service app registration from the converged developer portal is not covered by the sources below. Whether webhook payloads include cryptographic signature headers for verification is not covered by the sources below. The specific numeric rate limits enforced across Contact Center endpoints are not covered by the sources below.
See also
Referenced by
- Calling an external API from a Webex Contact Center flow — Sibling guide on Webex Contact Center API integration; the Webex Contact Center connector overlaps.
- Setting up callbacks in Webex Contact Center — Web callback is created through the Tasks API with outboundType CALLBACK
Sources
- 1Agent webhooks fire on agent login, agent logout and agent state change.The A-Z of Webex Contact Center APIs: Agents · webhooks section · Checked 2026-09-30
- 2Agent webhooks require the cjp:config and cjp:user scopes.disputedThe A-Z of Webex Contact Center APIs: Agents · webhooks section · Checked 2026-09-30
- 3Tenants in other regions most likely use https://api.wxcc-<region code>.cisco.com, substituting their code for us1.inferredConfigure Webex Contact Center APIs with Postman as an Application · environment variables, datacenter value, read with the us1 host examples · Checked 2026-09-30
- 4In the integration flow the user signs in and grants permissions, Webex returns an authorization code to the integration's redirect URI, and the integration exchanges that code server-to-server for an access token.Navigating Webex Contact Center API Authentication with Ease · OAuth flow steps list · Checked 2026-09-30
- 6Contact Center API requests carry the token in an Authorization: Bearer <access token> header.Lab 8: Webex Contact Center APIs (Tech Summit 2021) · API request header section · Checked 2026-09-30
- 7The capture:available event fires when a new recording is available, and its payload includes the taskId and a download link for the recording.The A-Z of Webex Contact Center APIs: Capture APIs · capture:available section · Checked 2026-09-30
- 8The List Captures API (/v1/captures/query) returns recording and task data and is typically called after a capture webhook, or to fetch historical recordings; it takes cjp:config_read or cjp-analyzer:read.The A-Z of Webex Contact Center APIs: Capture APIs · List Captures API section · Checked 2026-09-30
- 9Cisco offers a Contact Center developer sandbox, requested from the developer portal, that gives administrator access to a licensed Webex Contact Center org with up to 10 licensed users.Contact Center Sandbox · overview and request steps (from search excerpt) · Checked 2026-09-30
- 10The cjp:user scope is used for agent-level access such as agent WebSocket connections, while administrator APIs such as Get Agent Activities need an administrator token with cjp:config_read.The A-Z of Webex Contact Center APIs: Agents · Get Agent Activities and Subscribe Notification sections · Checked 2026-09-30
- 11Contact Center configuration APIs (entry points, queues, teams, users, profiles and similar) need an admin scope.Introducing the Webex Contact Center APIs and Developer Portal · authentication and configuration APIs sections · Checked 2026-09-30
- 12Cisco's Postman setup has a datacenter variable alongside client_id, client_secret and org_id, listing us1 for ProdUS1, eu1 and eu2 for ProdEU1 and ProdEU2, and anz1 for ProdANZ1.Configure Webex Contact Center APIs with Postman as an Application · Configure section, environment variables · Checked 2026-09-30
- 13Scopes offered to a Contact Center integration include cjp:config, cjp:config_read, cjp:user, cjds:admin_org_read, cjds:admin_org_write and spark:people_read.Navigating Webex Contact Center API Authentication with Ease · scopes section example list · Checked 2026-09-30
- 14Instructions that send readers to developer.webex-cx.com are probably out of date: new Contact Center apps should be registered in the converged developer.webex.com portal.inferredPresenting the Converged Webex and Contact Center Developer Portal · announcement body, read with the 2022 technote's Configure section · Checked 2026-09-30
- 15Cisco's 2022 Postman technote tells readers to create the integration with Create a New App on the Contact Center for Developers portal at developer.webex-cx.com.Configure Webex Contact Center APIs with Postman as an Application · Configure section, first step · Checked 2026-09-30
- 16The resource version needed in a subscription request comes from the List Event Types API, which requires cjp:config_read.The A-Z of Webex Contact Center APIs: Capture APIs · Subscriptions API section, resource version · Checked 2026-09-30
- 17Cisco advises developers to select only the minimal set of scopes their Contact Center integration needs.Navigating Webex Contact Center API Authentication with Ease · scopes section · Checked 2026-09-30
- 18Webex Contact Center API integrations are authorized with the OAuth 2.0 grant flow.Navigating Webex Contact Center API Authentication with Ease · opening section on the OAuth2 grant flow · Checked 2026-09-30
- 19A Webex Contact Center access token has the form accessToken_ciCluster_orgID, so the org ID is the segment after the final underscore.Navigating Webex Contact Center API Authentication with Ease · section on the orgID parameter · Checked 2026-09-30
- 20Since May 2025 the Webex Contact Center and Webex Suite developer portals are one portal at developer.webex.com, so developers no longer sign into two portals.Presenting the Converged Webex and Contact Center Developer Portal · announcement body · Checked 2026-09-30
- 21For Postman the integration's redirect URI is https://oauth.pstmn.io/v1/callback, or https://oauth.pstmn.io/v1/browser-callback for browser-based Postman.Configure Webex Contact Center APIs with Postman as an Application · Configure section, redirect URI · Checked 2026-09-30
- 22Cisco's Postman technote configures the integration with the scope string cjp:config cjp:config_read cjp:config_write.Configure Webex Contact Center APIs with Postman as an Application · Configure section, authorization scope · Checked 2026-09-30
- 23When a Webex API rate limit is exceeded the gateway returns HTTP 429 with a Retry-After header giving the number of seconds to wait.Rate Limiting and the Webex API · section on 429 and Retry-After · Checked 2026-09-30
- 24Contact Center APIs probably use the same 429 and Retry-After throttling as other Webex APIs, so the same backoff handling applies.inferredRate Limiting and the Webex API · section on 429 and Retry-After, read with the independent primer's rate-limit section · Checked 2026-09-30
- 25Practitioners report that Contact Center rate limits are enforced per client ID, and that Cisco can raise them for high-volume cases on request.field reportWebex Contact Center API Primer · rate limits section · Checked 2026-09-30
- 26Cisco recommends waiting the full Retry-After time as soon as the first 429 arrives.Rate Limiting and the Webex API · handling guidance and Python example · Checked 2026-09-30
- 27Using a Webex Contact Center refresh token resets its 90-day lifetime, so an integration that refreshes regularly keeps access indefinitely.Navigating Webex Contact Center API Authentication with Ease · section on refresh tokens · Checked 2026-09-30
- 28A new access token is obtained with POST https://webexapis.com/v1/access_token using grant_type=refresh_token plus client_id, client_secret and refresh_token.Service App Token Management: A Developer's Guide to Automation · refresh token section · Checked 2026-09-30
- 29Webex Contact Center region codes are us1 (North America), ca1 (Canada), eu1 (UK), eu2 (EU), anz1 (APJC), jp1 (Japan) and sg1 (Singapore).Integrate Webex Contact Center with ServiceNow (Version 2-New) · Openframe Configuration property customizations, region key · Checked 2026-09-30
- 30Cisco's webex-contact-center-api-samples repository has an OAuth2 app-auth sample, a GraphQL /search sample, a webhook sample and a token management service sample.WebexSamples/webex-contact-center-api-samples · README sample list · Checked 2026-09-30
- 31In a Search API query the from value cannot be more than 36 months in the past, and a future to value is treated as the current time.Search | Webex for Developers · mandatory parameters section (from search excerpt) · Checked 2026-09-30
- 32A Search API query that fetches CAR or AAR data may not span more than 30 days between from and to.GraphQL sample README (reporting-samples/graphql-sample) · README constraints section · Checked 2026-09-30
- 33Every Search API query requires from and to arguments as epoch timestamps in milliseconds; taskDetails compares on createdTime by default and agentSession on startTime.GraphQL sample README (reporting-samples/graphql-sample) · README taskDetails and agentSession argument sections · Checked 2026-09-30
- 34The Contact Center Search API is a GraphQL-powered REST API that exposes historical and real-time raw data, including the fields Analyzer reporting uses.Introducing the Webex Contact Center APIs and Developer Portal · reporting APIs section · Checked 2026-09-30
- 35A Search API aggregation may group by no more than 10 fields.GraphQL sample README (reporting-samples/graphql-sample) · README constraints section · Checked 2026-09-30
- 36Search API raw-data pages hold up to 250 to 500 records for taskDetails, 250 for agentSession and 1000 for aggregations, and taskDetails can return at most 100,000 records in total.GraphQL sample README (reporting-samples/graphql-sample) · README pagination section · Checked 2026-09-30
- 37The Search API offers three GraphQL queries: taskDetails over CSR and CAR records, agentSession over ASR and AAR records, and taskLegDetails over CLR data (early access).GraphQL sample README (reporting-samples/graphql-sample) · README query sections · Checked 2026-09-30
- 38The Search API requires the cjp:config or cjp:config_read scope and an Administrator or Supervisor role.Search | Webex for Developers · authorization section (from search excerpt) · Checked 2026-09-30
- 39An administrator must authorize a Contact Center service app in Control Hub before the service app token process can start.Introducing Service Apps for Webex Contact Center · authorization section · Checked 2026-09-30
- 41A Contact Center service app must be authorized in Control Hub by a Full Admin whose permissions match the scopes the developer selected.Contact Center Service Apps (developer guide) · admin authorization section (from search excerpt) · Checked 2026-09-30
- 42A Contact Center service app requests data for users across the whole organization and, unlike a user-authorized integration, does not break when the authorizing user leaves or changes password.Introducing Service Apps for Webex Contact Center · introduction · Checked 2026-09-30
- 43A Contact Center service app may request any integration scope except spark:applications_token and spark:kms.Introducing Service Apps for Webex Contact Center · scopes section · Checked 2026-09-30
- 44A service app token can be fetched with POST https://webexapis.com/v1/applications/{appId}/token, sending the service app's clientId, clientSecret and targetOrgId.Service App Token Management: A Developer's Guide to Automation · Applications API section · Checked 2026-09-30
- 45Service apps and integrations both use OAuth 2.0, but a service app gets its access token differently: an administrator approves it rather than a user completing a browser sign-in.Introducing Service Apps for Webex Contact Center · section comparing service apps and integrations · Checked 2026-09-30
- 46A webhook is registered with POST https://api.wxcc-us1.cisco.com/v2/subscriptions; the body gives a name, the event types to subscribe to, the orgId and a resource version.The A-Z of Webex Contact Center APIs: Capture APIs · Subscriptions API section · Checked 2026-09-30
- 47The Subscriptions API requires the cjp:config_read or cjp:config_write scope.disputedThe A-Z of Webex Contact Center APIs: Capture APIs · Subscriptions API section, scopes · Checked 2026-09-30
- 48GET https://api.wxcc-us1.cisco.com/v1/tasks returns tasks and needs the organization ID and a start datetime in epoch milliseconds.Lab 8: Webex Contact Center APIs (Tech Summit 2021) · Get Tasks exercise · Checked 2026-09-30
- 49By default a Webex Contact Center access token is valid for 12 hours and the refresh token for 60 days.disputedLab 8: Webex Contact Center APIs (Tech Summit 2021) · token validity note in the OAuth section · Checked 2026-09-30
- 50A Webex Contact Center integration access token lives 14 days (1,209,599 seconds) and its refresh token 90 days.disputedNavigating Webex Contact Center API Authentication with Ease · section on access and refresh token expiry · Checked 2026-09-30
- 51To automate service app token retrieval you create a separate OAuth integration, a token manager, that has the spark:applications_token scope.Service App Token Management: A Developer's Guide to Automation · token manager integration section · Checked 2026-09-30
- 52The OAuth token URL for Webex Contact Center integrations is https://webexapis.com/v1/access_token.Configure Webex Contact Center APIs with Postman as an Application · Configure section, Postman authorization settings · Checked 2026-09-30
- 53For the us1 region Contact Center APIs are served from https://api.wxcc-us1.cisco.com, for example /v2/subscriptions and /v1/captures/query.The A-Z of Webex Contact Center APIs: Capture APIs · Subscriptions API and List Captures API sections · Checked 2026-09-30
- 54Contact Center webhooks were introduced in three families: real-time, task and agent webhooks.Introducing the Webex Contact Center APIs and Developer Portal · webhooks section · Checked 2026-09-30
- 55Practitioners note that a Contact Center webhook destination URL must be publicly reachable from the Webex cloud.field reportWebex Contact Center API Primer · subscriptions section · Checked 2026-09-30
Documents
Configure Webex Contact Center APIs with Postman as an Application
Contact Center Sandbox
Contact Center Service Apps (developer guide)
Integrate Webex Contact Center with ServiceNow (Version 2-New)
Introducing Service Apps for Webex Contact Center
Introducing the Webex Contact Center APIs and Developer Portal
Navigating Webex Contact Center API Authentication with Ease
Presenting the Converged Webex and Contact Center Developer Portal
Rate Limiting and the Webex API
Search | Webex for Developers
Service App Token Management: A Developer's Guide to Automation
The A-Z of Webex Contact Center APIs: Agents
The A-Z of Webex Contact Center APIs: Capture APIs
Using Webex Service Apps
GraphQL sample README (reporting-samples/graphql-sample)
Lab 8: Webex Contact Center APIs (Tech Summit 2021)
WebexSamples/webex-contact-center-api-samples
Webex Contact Center API Primer
Cite this page
APA
WarmTransfer. (2026, September 30). Getting started with the Webex Contact Center APIs. WarmTransfer. https://warmtransfer.net/guides/wxcc-api-integration-setup
BibTeX
@misc{warmtransfer-wxcc-api-integration-setup,
title = {Getting started with the Webex Contact Center APIs},
author = {{WarmTransfer}},
year = {2026},
url = {https://warmtransfer.net/guides/wxcc-api-integration-setup},
note = {Verified 2026-09-30}
}