{"revision":"c10276e953456835cdbb1f3a60d58ae1980be353","document":{"id":493,"path":"api-reference/rest-apis/cmdb-ingest-api.md","title":"CMDB Data Ingestion API","bundle":null,"doc_type":null,"release":"australia","body":"\n# CMDB Data Ingestion API\n\nThe CMDB Data Ingestion API provides endpoints that enable the batch ingestion of an array of objects into an Import Set table.\n\n**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](https://raw.githubusercontent.com/ServiceNow/ServiceNowDocs/australia/markdown/australia/api-reference/rest-apis/c_ImportSetAPI.md) 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.\n\nIn addition, this API won't work by default for zbooted instances.\n\nThis API is activated through the Configuration Management Database \\(CMDB\\) \\(com.snc.cmdb\\) plugin and requires the cmdb\\_import\\_api\\_admin role.\n\n**Parent Topic:**[REST API reference](https://raw.githubusercontent.com/ServiceNow/ServiceNowDocs/australia/markdown/australia/api-reference/rest-apis/api-rest.md)\n\n## CMDB Data Ingestion - POST /cmdb/ingest/\\{data\\_source\\_sys\\_id\\}\n\nInserts records into the Import Set table associated with the data source record identified by the passed-in sys\\_id.\n\n**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](https://raw.githubusercontent.com/ServiceNow/ServiceNowDocs/australia/markdown/australia/api-reference/rest-apis/c_ImportSetAPI.md) 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.\n\nIn addition, this API won't work by default for zbooted instances.\n\nThe 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.\n\nIf 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](https://raw.githubusercontent.com/ServiceNow/ServiceNowDocs/australia/markdown/integrate-applications/c_DataSources.md).\n\nIf 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.\n\nYou must have the cmdb\\_import\\_api\\_admin role to access this endpoint.\n\n### URL format\n\nVersioned URL: `/api/now/{api_version}/cmdb/ingest/{data_source_sys_id}`\n\nDefault URL: `/api/now/cmdb/ingest/{data_source_sys_id}`\n\n**Note:** Available versions are specified in the [REST API Explorer](https://raw.githubusercontent.com/ServiceNow/ServiceNowDocs/australia/markdown/australia/api-reference/rest-api-explorer/use-REST-API-Explorer.md). For scripted REST APIs there is additional version information on the [Scripted REST Service form](https://raw.githubusercontent.com/ServiceNow/ServiceNowDocs/australia/markdown/australia/api-reference/rest-api-explorer/c_CustomWebServices.md).\n\n### Supported request parameters\n\n<table class=\"rest_api_path_parameters\"><thead><tr><th>\n\nName\n\n</th><th>\n\nDescription\n\n</th></tr></thead><tbody><tr><td>\n\napi\\_version\n\n</td><td id=\"version-entry-RESTAPI\">\n\nOptional. Version of the endpoint to access. For example, `v1` or `v2`. Only specify this value to use an endpoint version other than the latest. Data type: String\n\n</td></tr><tr><td>\n\ndata\\_source\\_sys\\_id\n\n</td><td>\n\nSys\\_id of the data source record.Data type: String\n\n</td></tr></tbody>\n</table>|Name|Description|\n|----|-----------|\n|None| |\n\n<table class=\"rest_api_request_body\"><thead><tr><th>\n\nName\n\n</th><th>\n\nDescription\n\n</th></tr></thead><tbody><tr><td>\n\nArray\n\n</td><td>\n\nFree-form array of objects that describe the data to append to the associated Import Set table. Each object in the array defines a row in the Import Sets table; each name-value pair a column. **Note:** This array must be named, such as `\"{\\\"records\\\":[{\\\"hostname\\\": \\\"Hostname1\\\", \\\"serialnumber\\\": \\\"2acd3873-7fc5-454c-8844-e7769e4d6cfc\\\", \\\"model\\\": \\\"Model Id\"},{\\\"vendor\\\": \\\"ABC Co\\\"}]}\"`.\n\nData type: Array of Objects\n\n</td></tr></tbody>\n</table>### Headers\n\nThe 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://raw.githubusercontent.com/ServiceNow/ServiceNowDocs/australia/markdown/australia/api-reference/rest-api-explorer/c_RESTAPI.md).\n\n<table class=\"rest_api_request_headers\"><thead><tr><th>\n\nHeader\n\n</th><th>\n\nDescription\n\n</th></tr></thead><tbody><tr><td>\n\nAccept\n\n</td><td id=\"accept-entry-RESTAPI\">\n\nData format of the response body. Supported types: **application/json** or **application/xml**. Default: **application/json**\n\n</td></tr><tr><td>\n\nContent-Type\n\n</td><td id=\"content_type-entry-RESTAPI\">\n\nData format of the request body. Supported types: **application/json** or **application/xml**. Default: **application/json**\n\n</td></tr></tbody>\n</table>|Header|Description|\n|------|-----------|\n|None| |\n\n### Status codes\n\nThe 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://raw.githubusercontent.com/ServiceNow/ServiceNowDocs/australia/markdown/australia/api-reference/rest-api-explorer/c_RESTAPI.md).\n\n|Status code|Description|\n|-----------|-----------|\n|201|Created. An attachment was added to the data source.|\n|202|Accepted. Rows were added to the Import Set table.|\n|400|Bad Request. A bad request type or malformed request was detected.|\n|404|Not found. The requested item wasn't found.|\n|409|Conflict. Attachment already exists on the data source.|\n|500|Internal server error. An unexpected error occurred while processing the request. The response contains additional information about the error.|\n|501|Not Implemented. Request format isn't supported.|\n\n### Response body parameters \\(JSON or XML\\)\n\n<table><thead><tr><th>\n\nName\n\n</th><th>\n\nDescription\n\n</th></tr></thead><tbody><tr><td>\n\nerror\n\n</td><td>\n\nDescribes an encountered error.Data type: Object\n\n```\n\"error\": {\n  \"details\": \"String\",\n  \"message\": \"String\"\n}\n```\n\n</td></tr><tr><td>\n\nerror.details\n\n</td><td>\n\nAdditional information about the error.Data type: String\n\n</td></tr><tr><td>\n\nerror.message\n\n</td><td>\n\nMessage describing the error.Data type: String\n\n</td></tr><tr><td>\n\nimport\\_set\n\n</td><td>\n\nName of the Import Set table to which the payload was appended.Data type: String\n\n</td></tr><tr><td>\n\nstaged\\_row\\_count\n\n</td><td>\n\nNumber of rows appended to the Import Set table.Data type: Number\n\n</td></tr><tr><td>\n\nstaging\\_table\n\n</td><td>\n\nName of the data source record used to stage the payload.Data type: String\n\n</td></tr><tr><td>\n\nstatus\n\n</td><td>\n\nError status.Data type: String\n\n</td></tr></tbody>\n</table>### Sample cURL request\n\n```\ncurl \"instance.service-now.com/api/now/cmdb/ingest/4dd9686d1b9800103d374087bc4bcb3d\" \\\n--request POST \\\n--header \"Accept: application/json\" \\\n--header \"Content-Type:application/json\" \\\n--data \"{\\\"records\\\":[{\\\"hostname\\\": \\\"Hostname1\\\", \\\"serialnumber\\\": \\\"2acd3873-7fc5-454c-8844-e7769e4d6cfc\\\", \\\"model\\\": \\\"Model 5100\"},{\\\"vendor\\\": \\\"ABC Co\\\"},\n{\\\"hostname\\\": \\\"Hostname2\\\", \\\"serialnumber\\\": \\\"3adb3873-7fc5-564d-8844-e7769e4d6ded\\\", \\\"model\\\": \\\"Model 5200\"},{\\\"vendor\\\": \\\"ACME Co\\\"}]}\"\n--user \"username\":\"password\"\n```\n\nSuccessful response:\n\n```\n{\n  \"result\": {\n    \"staged_row_count\": 2,\n    \"import_set\": \"ISET0010010\",\n    \"staging_table\": \"sn_my_demo_integra_demo_data_source_01\"\n  }\n}\n```\n\n"}}