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

 Release :

    - xanadu

ft:locale :

    - en-US

ft:publication_title :

    - Xanadu API Reference

ft:clusterId :

    - crapiref

bundleId :

    - crapiref

workflow :

    - Creator


---

# AI Search External User Mapping API

# AI Search External User Mapping API {#ariaid-title1}

* Release version: Xanadu
* 
* Updated August 1, 2024
* 
* ![](https://www.servicenow.com/docs/portal-asset/ico-clock) 5 minutes to read

The AI Search External User Mapping API provides endpoints that
enable ingestion of user mapping information from external sources into the ServiceNow®
AI Search application's index.

## AI Search External User Mapping - POST
/ais/external_content/user_mapping/import_multiple/{target_table} {#ariaid-title2}

Imports a list of external user mappings into an AI Search user mapping
table. Each mapping specifies externally defined user and group aliases for a ServiceNow AI Platform user. AI Search uses these aliases to determine which
external document search results the user can view.
To learn how AI Search external content security utilizes external user
mappings, see [External content security for AI
Search](https://www.servicenow.com/docs/access?context=external-content-security-ais&version=xanadu&pubname=xanadu-platform-administration&ft:locale=en-US).

User and group names in external user mappings should match those specified in security
access permissions for external documents ingested via the External Content Ingestion API's POST /ais/external_content/ingestDocument/{schema_table_name} endpoint. For more
information on ingesting external documents with security access permissions for externally
defined users and groups, see [External Content Ingestion
API](https://servicenow-prod.fluidtopics.net/zOidWeM32xJ0JEaf7~BtdA#external-content-ingestion-api "The External Content Ingestion API provides endpoints that enable ingestion of content from sources outside of your ServiceNow instance into the ServiceNow AI Search application's index.").

To view import histories for external user mapping records imported through this endpoint,
navigate to AI SearchExternal ContentUser mapping import history. From a history record, you can view the Import Set \[sys_import_set\] and
Multi Import Set \[sys_multi_import_set\] records for an import task. Use information from
these records to verify that your external user mappings were imported correctly.

### URL format

Versioned URL:
/api/now/{api_version}/ais/external_content/user_mapping/import_multiple/{target_table}

### Supported request parameters

{#ext_user_map-POST-import_multiple__entry__2}{#ext_user_map-POST-import_multiple__version-not_optional-RESTAPI}

| Name | Description |
|-|-|
| api_version | Optional. Version of the endpoint to access. For example, <kbd class="ph userinput">v1</kbd> or <kbd class="ph userinput">v2</kbd>. Only specify this value to use an endpoint version other than the latest. Data type: String |
| target_table | The name of the AI Search user mapping table that you want the imported mappings to appear in. For example, <kbd class="ph userinput">x_snc_sharepoint_user_table</kbd>. Note: You must create the target AI Search user mapping table via the AI SearchExternal ContentCreate User Mapping module before using this endpoint. If you specify a user mapping table that does not exist, the request fails. Data type: String |
[Table 1. Path parameters]

{#ext_user_map-POST-import_multiple__entry__8}

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

{#ext_user_map-POST-import_multiple__entry__12}

| Name | Description |
|-|-|
| {object} | Required. Unnamed object. Data type: Object { "records": [Array] } |
| {object}.records | Required. Array of objects in which each object represents a user mapping to import into the specified target table. Data type: Array "records": [ { "external_group": [Array], "external_user": [Array], "mapping_value": "String" } ] |
| {object}.records.external_group | Array of strings where each string is the name of an externally defined group to set as an alias for the ServiceNow AI Platform user specified by the {object}.records.mapping_value parameter. Data type: Array Values can be in any format, depending on the names of the externally defined groups selected for the user mapping. Examples include: "external_group": [ "itil", "hr-admin", "report-dev" ] |
| {object}.records.external_user | Array of strings where each string is the name of an externally defined user to set as an alias for the ServiceNow AI Platform user specified by the {object}.records.mapping_value parameter. Data type: Array Values can be in any format, depending on the names of the externally defined user accounts selected for the user mapping. Examples include: "external_user": [ "beth-anglin", "ad\beth.anglin", "beth-anglin@sharepoint" ] |
| {object}.records.mapping_value | Email field value that uniquely identifies an existing record in the User \[sys_user\] table. All externally defined user and group aliases in the request are mapped to the ServiceNow AI Platform user with this email address. Note: The API treats this parameter as the unique identifier for the user mapping record. If you import another user mapping with the same mapping_value as an existing user mapping record, the new record overwrites the existing record. Data type: String |
[Table 3. Request body parameters (XML or JSON)]

### 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](https://servicenow-prod.fluidtopics.net/2vuQj3~2s_niNXyXhrbRZA "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_user_map-POST-import_multiple__entry__24}{#ext_user_map-POST-import_multiple__accept-JSON-only-entry-RESTAPI}{#ext_user_map-POST-import_multiple__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 4. Request headers]

{#ext_user_map-POST-import_multiple__entry__30}

| Header | Description |
|-|-|
| None |   |
[Table 5. Response 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](https://servicenow-prod.fluidtopics.net/2vuQj3~2s_niNXyXhrbRZA "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_user_map-POST-import_multiple__entry__34}{#ext_user_map-POST-import_multiple__entry-400-status-code}{#ext_user_map-POST-import_multiple__entry-500-status-code}

| Status code | Description |
|-|-|
| 201 | Successful. The request was successfully processed. |
| 400 | Bad Request. A bad request type or malformed request was detected. |
| 500 | Internal server error. An unexpected error occurred while processing the request. The response contains additional information about the error. |
[Table 6. Status codes]

### Response body parameters (JSON or XML)

{#ext_user_map-POST-import_multiple__entry__42}

| Name | Description |
|-|-|
| error | Object describing the error encountered during processing of the request. Data type: Object "error": { "detail": "String", "message": "String" } |
| error.detail | Details of the error encountered during processing of the request. Data type: String |
| error.message | Message for the error encountered during processing of the request. Data type: String |
| import_set_id | Sys_id for the new record created in the Import Set \[sys_import_set\] table by a successful request. Data type: String |
| multi_import_set_id | Sys_id for the new record created in the Multi Import Set \[sys_multi_import_set\] table by a successful request. Data type: String |
| result | Result for an unsuccessful request. Includes a message describing the reason for the request failure. Data type: String |
| status | Status of an unsuccessful request. Valid values: * failure {#ext_user_map-POST-import_multiple__ul_h5r_z54_pnb} Data type: String |
[ ]

### cURL request

Import externally defined user and group aliases for ServiceNow AI Platform users Beth
Anglin and Abel Tuter into an AI Search user mapping table named
x_snc_sharepoint_user_table.

    curl -X POST 'https://instance.servicenow.com/api/now/v1/ais/external_content/user_mapping/import_multiple/x_snc_sharepoint_user_table' \
      -H 'Accept: application/json' \
      -H 'Content-Type: application/json' \
      -u 'username':'password' \
      -d '{
        "records": [
          {
            "mapping_value": "beth.anglin@example.com",
            "external_user": [
              "ad\beth-anglin",
              "beth.anglin@sharepoint"
            ],
            "external_group": [
              "itil",
              "itil-admin",
              "itil-dev"
            ]
          },
          {
            "mapping_value": "abel.tuter@example.com",
            "external_user": [
              "ad\abel-tuter",
              "abel.tuter@sharepoint"
            ],
            "external_group": [
              "hr",
              "hr-admin",
              "hr-dev"
            ]
          }
        ]
      }'

The response shows the sys_ids for the generated Import Set and Multi Import Set
records.

    {
      "import_set_id": "6e9ddb629d987010f877878bd9f0e9dd",
      "multi_import_set_id": "269ddb629d987010f877878bd9f0e9de"
    }

### cURL request {#ext_user_map-POST-import_multiple__example_qz3_1pz_spb}

Import invalid request containing an empty mapping record.

    curl 'https://instance.servicenow.com/api/now/v1/ais/external_content/user_mapping/import_multiple/u_ext_content_user_mapping' \
      --request POST \
      --user 'username':'password' \
      --header 'Accept: application/json' \
      --header 'Content-Type: application/json' \
      --data '{
        "records": [
          {
            "mapping_value": "beth.anglin@example.com",
            "external_user": [
              "ad\beth-anglin",
              "beth.anglin@sharepoint"
            ],
            "external_group": [
              "reports",
              "reports-admin",
              "reports-dev"
            ]
          },
          {}
        ]
      }'

The request fails with status 400 and the response indicates the nature of the failure.

    {
      "result": "Error in processing the message"
    }

*[\>]: and then