---
sourceDocument: Australia API Reference
sourceDocumentLink: https://servicenow-prod.fluidtopics.net/r/api-reference

 Release :

    - australia

ft:locale :

    - en-US

ft:publication_title :

    - Australia API Reference

ft:clusterId :

    - crapiref

bundleId :

    - crapiref

workflow :

    - Creator


---

# External ID Mapping API

# External ID Mapping API {#ariaid-title1}

Release version: Australia  
Updated March 12, 2026  
![](https://www.servicenow.com/docs/portal-asset/ico-clock) 6 minutes to read  
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](https://www.servicenow.com/docs/access?context=contactcenter-integration&version=australia&pubname=australia-customer-service-management&ft:locale=en-US).

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

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 {#ext_id_map-GET-id__section_dgq_r2t_c3c}

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

### Supported request parameters {#ext_id_map-GET-id__section_a4p_1vg_yhc}

{#ext_id_map-GET-id__table_b4p_1vg_yhc__entry__2}

| 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 |
[Table 1. Path parameters]

{#ext_id_map-GET-id__table_b4p_1vg_yhc} {#ext_id_map-GET-id__table_c4p_1vg_yhc__entry__2}

| Name | Description |
|-|-|
| None |   |
[Table 2. Query parameters]

{#ext_id_map-GET-id__table_c4p_1vg_yhc} {#ext_id_map-GET-id__table_d4p_1vg_yhc__entry__2}

| Name | Description |
|-|-|
| None |   |
[Table 3. Request body parameters (JSON)]

{#ext_id_map-GET-id__table_d4p_1vg_yhc}

### Headers {#ext_id_map-GET-id__section_e4p_1vg_yhc}

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](https://servicenow-prod.fluidtopics.net/qh7RcF0RI6a~i9u3octdlg "REST (REpresentational State Transfer) is a simple stateless architecture that provides standards between computer systems on the web, making it easier for them to communicate with each other.").
{#ext_id_map-GET-id__table_f4p_1vg_yhc__entry__2}{#ext_id_map-GET-id__accept-RESTAPI}

| Header | Description |
|-|-|
| Accept | Data format of the response body. Supported types: application/json or application/xml. Default: application/json |
[Table 4. Request headers]

{#ext_id_map-GET-id__table_f4p_1vg_yhc} {#ext_id_map-GET-id__table_g4p_1vg_yhc__entry__2}

| Header | Description |
|-|-|
| None |   |
[Table 5. Response headers]

{#ext_id_map-GET-id__table_g4p_1vg_yhc}

### Status codes {#ext_id_map-GET-id__section_h4p_1vg_yhc}

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](https://servicenow-prod.fluidtopics.net/qh7RcF0RI6a~i9u3octdlg "REST (REpresentational State Transfer) is a simple stateless architecture that provides standards between computer systems on the web, making it easier for them to communicate with each other.").
{#ext_id_map-GET-id__table_i4p_1vg_yhc__entry__2}{#ext_id_map-GET-id__entry-200-status-code}{#ext_id_map-GET-id__entry-400-status-code}{#ext_id_map-GET-id__entry-401-status-code}{#ext_id_map-GET-id__entry-403-status-code}{#ext_id_map-GET-id__entry-404-status-code}{#ext_id_map-GET-id__entry-500-status-code}

| 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. |
[Table 6. Status codes]

{#ext_id_map-GET-id__table_i4p_1vg_yhc}

### Response body parameters (JSON) {#ext_id_map-GET-id__section_j4p_1vg_yhc}

{#ext_id_map-GET-id__table_k4p_1vg_yhc__entry__2}{#ext_id_map-GET-id__message}{#ext_id_map-GET-id__omni-response-result.status-entry}

| 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 |
[ ]

{#ext_id_map-GET-id__table_k4p_1vg_yhc}  
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} {#ariaid-title3}

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 {#ext_id_map-PUT-id__section_dgq_r2t_c3c}

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

### Supported request parameters {#ext_id_map-PUT-id__section_egq_r2t_c3c}

{#ext_id_map-PUT-id__table_fgq_r2t_c3c__entry__2}

| 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 |
[Table 7. Path parameters]

{#ext_id_map-PUT-id__table_fgq_r2t_c3c} {#ext_id_map-PUT-id__table_ggq_r2t_c3c__entry__2}

| Name | Description |
|-|-|
| None |   |
[Table 8. Query parameters]

{#ext_id_map-PUT-id__table_ggq_r2t_c3c} {#ext_id_map-PUT-id__table_hgq_r2t_c3c__entry__2}

| 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 |
[Table 9. Request body parameters (JSON)]

{#ext_id_map-PUT-id__table_hgq_r2t_c3c}

### Headers {#ext_id_map-PUT-id__section_igq_r2t_c3c}

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](https://servicenow-prod.fluidtopics.net/qh7RcF0RI6a~i9u3octdlg "REST (REpresentational State Transfer) is a simple stateless architecture that provides standards between computer systems on the web, making it easier for them to communicate with each other.").
{#ext_id_map-PUT-id__table_jgq_r2t_c3c__entry__2}{#ext_id_map-PUT-id__accept-JSON-only-entry-RESTAPI}{#ext_id_map-PUT-id__content_type-JSON-only-entry-RESTAPI}

| 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. |
[Table 10. Request headers]

{#ext_id_map-PUT-id__table_jgq_r2t_c3c} {#ext_id_map-PUT-id__table_kgq_r2t_c3c__entry__2}

| Header | Description |
|-|-|
| None |   |
[Table 11. Response headers]

{#ext_id_map-PUT-id__table_kgq_r2t_c3c}

### Status codes {#ext_id_map-PUT-id__section_lgq_r2t_c3c}

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](https://servicenow-prod.fluidtopics.net/qh7RcF0RI6a~i9u3octdlg "REST (REpresentational State Transfer) is a simple stateless architecture that provides standards between computer systems on the web, making it easier for them to communicate with each other.").
{#ext_id_map-PUT-id__table_mgq_r2t_c3c__entry__2}{#ext_id_map-PUT-id__entry-200-status-code}{#ext_id_map-PUT-id__entry-400-status-code}{#ext_id_map-PUT-id__entry-401-status-code}{#ext_id_map-PUT-id__entry-403-status-code-awa}{#ext_id_map-PUT-id__entry-404-status-code}{#ext_id_map-PUT-id__entry-500-status-code}

| 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.{#ext_id_map-PUT-id__li-403-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](https://www.servicenow.com/docs/access?context=installed-with-awa&version=australia&pubname=australia-conversational-interfaces&ft:locale=en-US).{#ext_id_map-PUT-id__li-403-awa-disabled} {#ext_id_map-PUT-id__ul_gch_n34_tsb} |
| 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. |
[Table 12. Status codes]

{#ext_id_map-PUT-id__table_mgq_r2t_c3c}

### Response body parameters (JSON) {#ext_id_map-PUT-id__section_ngq_r2t_c3c}

{#ext_id_map-PUT-id__table_ogq_r2t_c3c__entry__2}{#ext_id_map-PUT-id__message}{#ext_id_map-PUT-id__omni-response-result.status-entry}

| 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 |
[ ]

{#ext_id_map-PUT-id__table_ogq_r2t_c3c}  

### cURL request {#ext_id_map-PUT-id__example_pgq_r2t_c3c}

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"
      }
    }