External ID Mapping API

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.

• 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.

Parent Topic:REST API reference

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

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.

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.

Response body parameters (JSON)

"result": { 
   "data": "String",
   "message": "String"
}

"data": { 
  "document_id": "String", 
  "document_table": "String",
  "external_id": "String",
  "external_provider": "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

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.

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.

Response body parameters (JSON)

"result": { 
   "data": "String",
   "message": "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"
  }
}