CMDB Data Ingestion API

The CMDB Data Ingestion API provides endpoints that enable the batch ingestion of an array of objects into an Import Set table.

Warning: This API is no longer recommended. For the same functionality with improved scalability and stability, use the Import Set - POST /now/import/{stagingTableName}/insertMultiple endpoint. From the Quebec release onward, any usage of the CMDB Data Ingestion API should be migrated to use the Import Set – insertMultiple endpoint instead.

In addition, this API won't work by default for zbooted instances.

This API is activated through the Configuration Management Database (CMDB) (com.snc.cmdb) plugin and requires the cmdb_import_api_admin role.

Parent Topic:REST API reference

CMDB Data Ingestion - POST /cmdb/ingest/{data_source_sys_id}

Inserts records into the Import Set table associated with the data source record identified by the passed-in sys_id.

Warning: This API is no longer recommended. For the same functionality with improved scalability and stability, use the Import Set - POST /now/import/{stagingTableName}/insertMultiple endpoint. From the Quebec release onward, any usage of the CMDB Data Ingestion API should be migrated to use the Import Set – insertMultiple endpoint instead.

In addition, this API won't work by default for zbooted instances.

The request body must contain the JSON array of objects (payload) to insert in the Import Set table. Each object equates to a row in the table, each name-value pair equates to a column. The JSON payload must leverage the field names from the import set without the "u_" prefix. For example, the field name "u_matching_record" should be "matching_record" in the request body payload. If the Import Set table exists, the endpoint appends the rows (objects) to the existing Import Set table. No checking for duplicates or updating of existing records is performed.

If you are initially building an application, you must first create the associated data source record in your instance before calling this endpoint. If you are just using this endpoint to add records to an existing Import Set table, you don't need to create the data source record, but you must know its sys_id. The data source record describes the Import Set table in which to insert the specified payload. This table must extend the Import Set Rows [sys_import_set_row] table. Also, the data source must be set to Attachment and the format set to JSON. For more information on data sources, see Data sources.

If the Import Set table defined in the data source record doesn't exist, the endpoint attaches the passed-in payload to the data source record. To create the initial Import Set table, you must manually import the data into the Import Set table. To import the data, on the associated Data Source form, click the Test Load 20 Records or Load All Records link in the Related Links section. Once the Import Set table is created, you can't add columns to the table using this endpoint. If name-value pairs are later passed in that don't exist in the Import Set table, they are ignored without warning. If you need to modify the columns within the Import Set table, you can manually add them to the table. You can also delete or rename the Import Set table, and call the endpoint again using the new payload.

You must have the cmdb_import_api_admin role to access this endpoint.

URL format

Versioned URL: /api/now/{api_version}/cmdb/ingest/{data_source_sys_id}

Default URL: /api/now/cmdb/ingest/{data_source_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)

"error": {
  "details": "String",
  "message": "String"
}

Sample cURL request

curl "instance.service-now.com/api/now/cmdb/ingest/4dd9686d1b9800103d374087bc4bcb3d" \
--request POST \
--header "Accept: application/json" \
--header "Content-Type:application/json" \
--data "{\"records\":[{\"hostname\": \"Hostname1\", \"serialnumber\": \"2acd3873-7fc5-454c-8844-e7769e4d6cfc\", \"model\": \"Model 5100"},{\"vendor\": \"ABC Co\"},
{\"hostname\": \"Hostname2\", \"serialnumber\": \"3adb3873-7fc5-564d-8844-e7769e4d6ded\", \"model\": \"Model 5200"},{\"vendor\": \"ACME Co\"}]}"
--user "username":"password"

Successful response:

{
  "result": {
    "staged_row_count": 2,
    "import_set": "ISET0010010",
    "staging_table": "sn_my_demo_integra_demo_data_source_01"
  }
}