Import Set API

The Import Set API provides endpoints that allow you to interact with import set tables.

This API transforms incoming data based on associated transform maps. The import set API supports synchronous transforms. The Import Set API mirrors the existing SOAP interface.

Security

Access to tables via the REST API is restricted by BasicAuth. To allow access to tables without any authentication or authorization, add the table name to sys_public.list. ACLs defined on tables are still enforced, and it is the administrator's responsibility to deactivate ACLs.

Parent Topic:REST API reference

Import Set - GET /now/import/{stagingTableName}/{sys_id}

Retrieves the specified import staging record and resulting transformation result.

URL format

Versioned URL: /api/now/{api_version}/import/{stagingTableName}/{sys_id}

Default URL: /api/now/import/{stagingTableName}/{sys_id}

Note: Available versions are specified in the REST API Explorer. For scripted REST APIs there is additional version information on the Scripted REST Service form.

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 or XML)

"result": [
  {
    "display_name": "String",
    "display_value": "String",
    "record_link": "String",
    "status": "String",
    "sys_id": "String",
    "table": "String",
    "transform_map": "String"
  }
]

Sample cURL request

curl "https://instance.servicenow.com/api/now/import/imp_user/e2928be64f411200adf9f8e18110c777" \
--request GET \
--header "Accept:application/json" \
--user "username":"password"

{
  "import_set": "ISET0010001",
  "staging_table": "imp_user",
  "result": [
    {
      "transform_map": "User",
      "table": "sys_user",
      "display_name": "name",
      "display_value": "John Public",
      "record_link": "https://instance.service-now.com/api/now/table/sys_user/ea928be64f411200adf9f8e18110c777",
      "status": "inserted",
      "sys_id": "ea928be64f411200adf9f8e18110c777"
    }
  ]
}

Import Set - POST /now/import/{stagingTableName}

Inserts incoming data into a specified staging table and triggers transformation based on predefined transform maps in the import set table.

Transformation occurs synchronously. For each transform map that you define, the responses include transformation results such as information on the target records.

Note: The status_message and error_message fields on transformation scripts are processed and returned in response, along with any custom response fields.

URL format

Versioned URL: /api/now/{api_version}/import/{stagingTableName}

Default URL: /api/now/import/{stagingTableName}

Note: Available versions are specified in the REST API Explorer. For scripted REST APIs there is additional version information on the Scripted REST Service form.

Supported request parameters

Note: The Import Set POST method accepts only name-value pairs of String data types in request body parameters. If any other data type is provided, the resulting value stored in the import set table might not conform to the intended format. For example, the ":" notion of the nested JSON object is changed to "=".

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 or XML)

"result": [
  {
    "display_name": "String",
    "display_value": "String",
    "record_link": "String",
    "status": "String",
    "sys_id": "String",
    "table": "String",
    "transform_map": "String"
  }
]

Sample cURL request

curl "https://instance.servicenow.com/api/now/import/imp_user" \
--request POST \
--header "Accept:application/json" \
--header "Content-Type:application/json" \
--data "{'first_name':'John','last_name':'Public','user_id':'john.public','email':'john.public@company.com'}" \
--user "username":"password"

{
  "import_set": "ISET0010001",
  "staging_table": "imp_user",
  "result": [
    {
      "transform_map": "User",
      "table": "sys_user",
      "display_name": "name",
      "display_value": "John Public",
      "record_link": "https://instance.servicenow.com/api/now/table/sys_user/ea928be64f411200adf9f8e18110c777",
      "status": "inserted",
      "sys_id": "ea928be64f411200adf9f8e18110c777"
    }
  ]
}

Import Set - POST /now/import/{stagingTableName}/insertMultiple

Inserts multiple records into a specified staging table and triggers transformation based on predefined transform maps or Robust Transform Engine (RTE) configurations in a single request.

Transformation is asynchronous by default. To set synchronous transformation, create a new record in the Rest Insert Multiples [sys_rest_insert_multiple] table, select the source table, and set the transformation to synchronous.

This endpoint can send a request body in two possible formats.

• Data source file format

  If you generate a staging table from a JSON data source, match the JSON format of the source file.

• Staging table column format

  Default. Matches the staging table column request body format in key value pairs.

URL format

Versioned URL: /api/now/{api_version}/import/{stagingTableName}/insertMultiple

Default URL: /api/now/import/{stagingTableName}/insertMultiple

Note: Available versions are specified in the REST API Explorer. For scripted REST APIs there is additional version information on the Scripted REST Service form.

Supported request parameters

Note: The Import Set POST method accepts only name-value pairs of String data types in request body parameters. If any other data type is provided, the resulting value stored in the import set table might not conform to the intended format. For example, the ":" notion of the nested JSON object is changed to "=".

{
   "records":[
      {
         "<ColumnLabel1>":"<value>",
         "<ColumnLabel2>":"<value>"
      },
      {
         "<ColumnLabel1>":"<value>",
         "<ColumnLabel2>":"<value>"
      }
   ]
}

{
   "records":[
      {
         "<column_name1>":"<value>",
         "<column_name2>":"<value>"
      },
      {
         "<column_name1>":"<value>",
         "<column_name2>":"<value>"
      }
   ]
}

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 (JSON)

Sample cURL request

The following example shows how to run a transform on an import table called u_employee_import_set_table using the staging table column format.

curl "https://instance.servicenow.com/api/now/import/u_employee_import_set_table/insertMultiple" \
--request POST \
--header "Accept:application/json" \
--header "Content-Type:application/json" \
--data "{
  \"records\": [
  {
   \"Address\": \"Hollywood\",
   \"Name\": \"Tom\",
   \"ID\": \"123\"
  },
  {
   \"Address\": \"Vine\",
   \"Name\": \"Irene\",
   \"ID\": \"456\"
  }
  ]
}" \
--user 'username':'password'

Results include sys_ids for new records in the Import Sets [sys_import_set] and Multi Import Sets [sys_multi_import_set] tables.

{
  "import_set_id": "<import_set_sys_id>",
  "multi_import_set_id": "<multi_import_set_sys_id>"
}