External ID Mapping API

  • Rversion finale: Australia
  • Mis à jour 12 mars 2026
  • 6 minutes de lecture

    • Enables external Contact Center as a Service (CCaaS) platforms to store and retrieve routing identifiers for ServiceNow records.

    As part of the Contact Center Integration Core (sn_ct_ctr_it_core) store application, this API enables CCaaS providers to get or set external IDs in the CCaaS External ID Mappings [sn_ct_ctr_it_core_ccaas_external_id_mapping] table. This API is in the sn_ct_ctr_it_core namespace and requires the sn_ct_ctr_it_core.admin role.

    This API supports multi-provider environments, enabling organizations to integrate with multiple CCaaS platforms simultaneously while maintaining separate routing ID namespaces for each provider.

    When a CCaaS platform (such as Genesys Cloud, Five9, or Amazon Connect) routes a case, task, or interaction to an external agent, it generates a unique routing ID. This API provides a centralized mechanism to map those external routing IDs to records, enabling bidirectional tracking and correlation between the CCaaS platform and ServiceNow.

    Use cases
    External routing correlation
    The CCaaS platform generates a routing ID when it routes a case to an external agent. must store this ID to correlate future events, callbacks, or status updates from the CCaaS platform.
    This API stores the external routing ID in a mapping table, associating it with the record and the provider that generated it.
    Bidirectional tracking
    You might have to track which external routing session corresponds to which case for reporting, analytics, and troubleshooting.
    You can use this API to retrieve external routing IDs for any record, enabling dashboards and reports to show the complete routing history.
    Integration flexibility
    Different CCaaS platforms might require storing routing IDs for different tables, such as cases, tasks, interactions, or custom tables.
    This API accepts any valid table name, making it extensible for future use cases. The endpoints can be called independently depending on the workflow.

    For more information about integrating with CCaaS systems, see Integrating with contact centers.

    External ID Mapping - GET /sn_ct_ctr_it_core/external_id_mapping/table/{tableName}/documentId/{documentId}

    Retrieves the external routing ID mapping for a specific record.

    This endpoint queries the mapping table to find the external routing ID that has been stored for a given record and provider. Use this endpoint to retrieve the external routing ID that was assigned to a record by a CCaaS platform.

    URL format

    Default URL: /api/sn_ct_ctr_it_core/external_id_mapping/table/{tableName}/documentId/{documentId}

    Supported request parameters

    Tableau 1. Path parameters
    Name Description
    tableName Required. The ServiceNow table name containing the record. Can be any valid table name. For example, sn_customerservice_case, sn_customerservice_task, interaction, or custom tables.

    Data type: String
    documentId Required. The sys_id of the ServiceNow record for which to retrieve the external ID mapping.

    Data type: String
    Tableau 2. Query parameters
    Name Description
    None
    Tableau 3. Request body parameters (JSON)
    Name Description
    None

    Headers

    The following request and response headers apply to this HTTP action only, or apply to this action in a distinct way. For a list of general headers used in the REST API, see Supported REST API headers.

    Tableau 4. Request headers
    Header Description
    Accept Data format of the response body. Supported types: application/json or application/xml.

    Default: application/json
    Tableau 5. Response headers
    Header Description
    None

    Status codes

    The following status codes apply to this HTTP action. For a list of possible status codes used in the REST API, see REST API HTTP response codes.

    Tableau 6. Status codes
    Status code Description
    200 Successful. The request was successfully processed.
    400 Bad Request. A bad request type or malformed request was detected.
    401 Unauthorized. The user credentials are incorrect or have not been passed.
    403 Forbidden. The user doesn't have access rights to the specified record.
    404 Not found. The requested item wasn't found.
    500 Internal server error. An unexpected error occurred while processing the request. The response contains additional information about the error.

    Response body parameters (JSON)

    Name Description
    result Result object containing information about the request.

    Data type: Object

    "result": { 
   "data": "String",
   "message": "String"
}
    result.data Data for the mapping.

    Data type: Object

    "data": { 
  "document_id": "String", 
  "document_table": "String",
  "external_id": "String",
  "external_provider": "String"
}
    result.data.document_id The sys_id of the ServiceNow AI Platform record for which to retrieve the external ID mapping.

    Data type: String
    result.data.document_table The ServiceNow AI Platform table name containing the record.

    Data type: String
    result.data.external_id The external routing ID from the CCaaS platform.

    Max characters: 200

    Data type: String
    result.data.external_provider The sys_id of the provider from the External Provider [awa_external_provider] table.

    Data type: String
    result.error.message If the request fails, message explaining why the request failed.

    Data type: String
    result.error If the request fails, message explaining why the request failed.

    Data type: String
    result.error.message If the request fails, message explaining why the request failed.

    Data type: String
    result.message Message that describes the outcome of the API request.

    Data type: String
    result.status Success or failure status of the request.
    Valid values:
    • success
    • failure

    Data type: String

    This example queries the mapping for case with sys_id f584a7b23b3d3e10c524c59a04e45a6f to find which external routing ID has been assigned by the CCaaS platform.

    curl "https://instance.service-now.com/api/sn_ct_ctr_it_core/external_id_mapping/table/sn_customerservice_case/documentId/f584a7b23b3d3e10c524c59a04e45a6f" \
--request GET \
--header "Accept:application/json" \
--user 'admin':'admin'

    Response body:

    {
  "result": {
    "data": {
      "document_table": "sn_customerservice_case",
      "document_id": "f584a7b23b3d3e10c524c59a04e45a6f",
      "external_id": "200",
      "external_provider": "8b592fb64f140210c0338ef0b1ce0b18"
    }
  }
}

    External ID Mapping - PUT /sn_ct_ctr_it_core/external_id_mapping/table/{tableName}/documentId/{documentId}

    Creates or updates an external routing ID mapping for a ServiceNow record.

    This endpoint is idempotent, so calling it multiple times with the same parameter updates the existing mapping rather than creating duplicate mappings. The endpoint automatically determines whether to insert a new mapping or update an existing one based on the combination of table name, document ID, and external provider.

    URL format

    Default URL: /api/sn_ct_ctr_it_core/external_id_mapping/table/{tableName}/documentId/{documentId}

    Supported request parameters

    Tableau 7. Path parameters
    Name Description
    tableName Required. The ServiceNow table name containing the record. Can be any valid table name. For example, sn_customerservice_case, sn_customerservice_task, interaction, or custom tables.

    Data type: String
    documentId Required. The sys_id of the ServiceNow record for which to retrieve the external ID mapping.

    Data type: String
    Tableau 8. Query parameters
    Name Description
    None
    Tableau 9. Request body parameters (JSON)
    Name Description
    external_id Required. External agent ID from the CCaaS system.

    Data type: String

    Maximum length: 200 characters
    external_provider The sys_id of the provider record from the External Provider [awa_external_provider] table. This identifies which CCaaS platform generated the external ID.

    Data type: String

    Headers

    The following request and response headers apply to this HTTP action only, or apply to this action in a distinct way. For a list of general headers used in the REST API, see Supported REST API headers.

    Tableau 10. Request headers
    Header Description
    Accept Data format of the response body. Only supports application/json.
    Content-Type Data format of the request body. Only supports application/json.
    Tableau 11. Response headers
    Header Description
    None

    Status codes

    The following status codes apply to this HTTP action. For a list of possible status codes used in the REST API, see REST API HTTP response codes.

    Tableau 12. Status codes
    Status code Description
    200 Successful. The request was successfully processed.
    201 Created. The external ID mapping was successfully created, that is, a new mapping was inserted.
    400 Bad Request. A bad request type or malformed request was detected.
    401 Unauthorized. The user credentials are incorrect or have not been passed.
    403 Forbidden.
    Possible reasons:
    • The user doesn't have the awa_integration_user role.
    • The value of the glide.awa.enabled property isn't true. This property is listed in the System Property [sys_property] table if the Advanced Work Assignment (com.glide.awa) plugin is installed. For more information, see Components installed with Advanced Work Assignment.
    404 Not found. The requested item wasn't found.
    500 Internal server error. An unexpected error occurred while processing the request. The response contains additional information about the error.

    Response body parameters (JSON)

    Name Description
    result Result object containing information about the request.

    Data type: Object

    "result": { 
   "data": "String",
   "message": "String"
}
    result.error.message If the request fails, message explaining why the request failed.

    Data type: String
    result.error If the request fails, message explaining why the request failed.

    Data type: String
    result.error.message If the request fails, message explaining why the request failed.

    Data type: String
    result.message Message that describes the outcome of the API request.

    Data type: String
    result.status Success or failure status of the request.
    Valid values:
    • success
    • failure

    Data type: String

    cURL request

    This example shows how to store an external ID from a CCaaS platform (identified by provider sys_id 8b592fb64f140210c0338ef0b1ce0b18).

    curl "https://instance.service-now.com/api/sn_ct_ctr_it_core/external_id_mapping/table/sn_customerservice_case/documentId/f584a7b23b3d3e10c524c59a04e45a6f" \
--request PUT \
--header "Accept:application/json" \
--header "Content-Type:application/json" \
--data "{
    \"external_id\": \"200\",
    \"external_provider\": \"8b592fb64f140210c0338ef0b1ce0b18\"
}" \
--user 'admin':'admin'

    Response body:

    {
  "result": {
    "message": "External ID mapping record updated for sn_customerservice_case [f584a7b23b3d3e10c524c59a04e45a6f]",
    "status": "success"
  }
}