{"revision":"c10276e953456835cdbb1f3a60d58ae1980be353","document":{"id":479,"path":"api-reference/rest-apis/c_ImportSetAPI.md","title":"Import Set API","bundle":null,"doc_type":null,"release":"australia","body":"\n# Import Set API\n\nThe Import Set API provides endpoints that allow you to interact with import set tables.\n\nThis 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.\n\n## Security\n\nAccess 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.\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## Import Set - GET /now/import/\\{stagingTableName\\}/\\{sys\\_id\\}\n\nRetrieves the specified import staging record and resulting transformation result.\n\n### URL format\n\nVersioned URL: `/api/now/{api_version}/import/{stagingTableName}/{sys_id}`\n\nDefault URL: `/api/now/import/{stagingTableName}/{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\nstagingTableName\n\n</td><td>\n\nName of the table from which to obtain the import data.Data type: String\n\n</td></tr><tr><td>\n\nsys\\_id\n\n</td><td>\n\nSys\\_id of the record that contains the data.Data type: String\n\n</td></tr></tbody>\n</table>|Name|Description|\n|----|-----------|\n|None| |\n\n|Name|Description|\n|----|-----------|\n|None| |\n\n### 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></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|200|Successful. The request was successfully processed.|\n|401|Unauthorized. The user credentials are incorrect or have not been passed.|\n|404|Indicates the specified resource was not available. As import set tables are deleted frequently based on a schedule, GET requests may return 404 Not Found responses if the transformation result no longer exists.|\n|500|Internal server error. An unexpected error occurred while processing the request. The response contains additional information about the error.|\n\n### Response body parameters \\(JSON or XML\\)\n\n<table id=\"table_edp_5dz_cmb\"><thead><tr><th>\n\nName\n\n</th><th>\n\nDescription\n\n</th></tr></thead><tbody><tr><td>\n\nimport\\_set\n\n</td><td>\n\nName of the import set.Data type: String\n\n</td></tr><tr><td>\n\nresult\n\n</td><td>\n\nList of objects that contain information on the data sets that were imported.Data type: Array\n\n```\n\"result\": [\n  {\n    \"display_name\": \"String\",\n    \"display_value\": \"String\",\n    \"record_link\": \"String\",\n    \"status\": \"String\",\n    \"sys_id\": \"String\",\n    \"table\": \"String\",\n    \"transform_map\": \"String\"\n  }\n]\n```\n\n</td></tr><tr><td>\n\nresult.display\\_name\n\n</td><td>\n\nDisplay name of the specific column in the table for which the display value is true. For example, `number`.Data type: String\n\n</td></tr><tr><td>\n\nresult.display\\_value\n\n</td><td>\n\nDisplay value of the **display\\_name** column. For example, `CHG0000123`.Data type: String\n\n</td></tr><tr><td>\n\nresult.record\\_link\n\n</td><td>\n\nTable API GET request for the imported record.Data type: String\n\n</td></tr><tr><td>\n\nresult.status\n\n</td><td>\n\nStatus of the import.Data type: String\n\n</td></tr><tr><td>\n\nresult.sys\\_id\n\n</td><td>\n\nSys\\_id of the import record.Data type: String\n\n</td></tr><tr><td>\n\nresult.table\n\n</td><td>\n\nName of the table in which the data was imported.Data type: String\n\n</td></tr><tr><td>\n\nresult.transform\\_map\n\n</td><td>\n\nName of the transform map.Data type: String\n\n</td></tr><tr><td>\n\nstaging\\_table\n\n</td><td>\n\nName of the import staging table.Data type: String\n\n</td></tr></tbody>\n</table>### Sample cURL request\n\n```\ncurl \"https://instance.servicenow.com/api/now/import/imp_user/e2928be64f411200adf9f8e18110c777\" \\\n--request GET \\\n--header \"Accept:application/json\" \\\n--user \"username\":\"password\"\n\n```\n\n```\n{\n  \"import_set\": \"ISET0010001\",\n  \"staging_table\": \"imp_user\",\n  \"result\": [\n    {\n      \"transform_map\": \"User\",\n      \"table\": \"sys_user\",\n      \"display_name\": \"name\",\n      \"display_value\": \"John Public\",\n      \"record_link\": \"https://instance.service-now.com/api/now/table/sys_user/ea928be64f411200adf9f8e18110c777\",\n      \"status\": \"inserted\",\n      \"sys_id\": \"ea928be64f411200adf9f8e18110c777\"\n    }\n  ]\n}\n```\n\n## Import Set - POST /now/import/\\{stagingTableName\\}\n\nInserts incoming data into a specified staging table and triggers transformation based on predefined transform maps in the import set table.\n\nTransformation occurs synchronously. For each transform map that you define, the responses include transformation results such as information on the target records.\n\n**Note:** The status\\_message and error\\_message fields on transformation scripts are processed and returned in response, along with any custom response fields.\n\n### URL format\n\nVersioned URL: `/api/now/{api_version}/import/{stagingTableName}`\n\nDefault URL: `/api/now/import/{stagingTableName}`\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**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 \"=\".\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\nstagingTableName\n\n</td><td>\n\nName of the table from which to import the data.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\nCall specific\n\n</td><td>\n\nName-value pairs to insert in the import fields.Data type: String\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|200|Successful. The request was successfully processed.|\n|201|Successful. The request was successfully created.|\n|401|Unauthorized. The user credentials are incorrect or have not been passed.|\n|500|Internal server error. An unexpected error occurred while processing the request. The response contains additional information about the error.|\n\n### Response body parameters \\(JSON or XML\\)\n\n<table id=\"table_xth_xdz_cmb\"><thead><tr><th>\n\nName\n\n</th><th>\n\nDescription\n\n</th></tr></thead><tbody><tr><td>\n\nimport\\_set\n\n</td><td>\n\nName of the import set.Data type: String\n\n</td></tr><tr><td>\n\nresult\n\n</td><td>\n\nList of objects that contain information on the data sets that were imported.Data type: Array\n\n```\n\"result\": [\n  {\n    \"display_name\": \"String\",\n    \"display_value\": \"String\",\n    \"record_link\": \"String\",\n    \"status\": \"String\",\n    \"sys_id\": \"String\",\n    \"table\": \"String\",\n    \"transform_map\": \"String\"\n  }\n]\n```\n\n</td></tr><tr><td>\n\nresult.display\\_name\n\n</td><td>\n\nDisplay name of the specific column in the table for which the display value is true. For example, `number`.Data type: String\n\n</td></tr><tr><td>\n\nresult.display\\_value\n\n</td><td>\n\nDisplay value of the **display\\_name** column. For example, `CHG0000123`.Data type: String\n\n</td></tr><tr><td>\n\nresult.record\\_link\n\n</td><td>\n\nTable API GET request for the imported record.Data type: String\n\n</td></tr><tr><td>\n\nresult.status\n\n</td><td>\n\nStatus of the import.Data type: String\n\n</td></tr><tr><td>\n\nresult.sys\\_id\n\n</td><td>\n\nSys\\_id of the import record.Data type: String\n\n</td></tr><tr><td>\n\nresult.table\n\n</td><td>\n\nName of the table in which the data was imported.Data type: String\n\n</td></tr><tr><td>\n\nresult.transform\\_map\n\n</td><td>\n\nName of the transform map.Data type: String\n\n</td></tr><tr><td>\n\nstaging\\_table\n\n</td><td>\n\nName of the import staging table.Data type: String\n\n</td></tr></tbody>\n</table>### Sample cURL request\n\n```\ncurl \"https://instance.servicenow.com/api/now/import/imp_user\" \\\n--request POST \\\n--header \"Accept:application/json\" \\\n--header \"Content-Type:application/json\" \\\n--data \"{'first_name':'John','last_name':'Public','user_id':'john.public','email':'john.public@company.com'}\" \\\n--user \"username\":\"password\"\n```\n\n```\n{\n  \"import_set\": \"ISET0010001\",\n  \"staging_table\": \"imp_user\",\n  \"result\": [\n    {\n      \"transform_map\": \"User\",\n      \"table\": \"sys_user\",\n      \"display_name\": \"name\",\n      \"display_value\": \"John Public\",\n      \"record_link\": \"https://instance.servicenow.com/api/now/table/sys_user/ea928be64f411200adf9f8e18110c777\",\n      \"status\": \"inserted\",\n      \"sys_id\": \"ea928be64f411200adf9f8e18110c777\"\n    }\n  ]\n}\n```\n\n## Import Set - POST /now/import/\\{stagingTableName\\}/insertMultiple\n\nInserts 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.\n\nTransformation 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.\n\nThis endpoint can send a request body in two possible formats.\n\n-   **Data source file format**\n\n    If you generate a staging table from a JSON data source, match the JSON format of the source file.\n\n-   **Staging table column format**\n\n    Default. Matches the staging table column request body format in key value pairs.\n\n\n### URL format\n\nVersioned URL: `/api/now/{api_version}/import/{stagingTableName}/insertMultiple`\n\nDefault URL: `/api/now/import/{stagingTableName}/insertMultiple`\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**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 \"=\".\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\nstagingTableName\n\n</td><td>\n\nName of the import set table from which to import the data. Refer to [Import sets key concepts](https://raw.githubusercontent.com/ServiceNow/ServiceNowDocs/australia/markdown/integrate-applications/c_ImportSetsKeyConcepts.md).Data type: String\n\n</td></tr></tbody>\n</table><table class=\"rest_api_query_parameters\"><thead><tr><th>\n\nName\n\n</th><th>\n\nDescription\n\n</th></tr></thead><tbody><tr><td>\n\nmulti\\_import\\_set\\_id\n\n</td><td>\n\nSys\\_id of an entry in the Multi Import Sets \\[sys\\_multi\\_import\\_set\\] table. If specified, adds the current import to this multiple import set instead of adding to a new multiple import set.Data type: String\n\nTable:\n\n</td></tr><tr><td>\n\nrun\\_after\n\n</td><td>\n\nSys\\_id of the entry to run. Enables running the current import set after the specified import set is complete. You can use this parameter to enforce the sequential order of imports.This parameter is only valid in asynchronous transformations.\n\nData type: String\n\nTable: Import Sets \\[sys\\_import\\_set\\]\n\n</td></tr></tbody>\n</table><table id=\"table_uc3_ztw_rnb\" class=\"rest_api_request_body\"><thead><tr><th>\n\nFormat\n\n</th><th>\n\nDescription\n\n</th></tr></thead><tbody><tr><td>\n\nData source file\n\n</td><td>\n\nThis request body format matches the JSON file format used to create the data source. Provide the request body in the same format as the JSON in the data source. JSON input varies depending on the properties in your data source. Refer to JSON information in [File type data source](https://raw.githubusercontent.com/ServiceNow/ServiceNowDocs/australia/markdown/integrate-applications/r_FileTypeDataSource.md).-   This option is only available if the staging table was created using a JSON data source. Refer to [Create a File type data source](https://raw.githubusercontent.com/ServiceNow/ServiceNowDocs/australia/markdown/integrate-applications/create-file-type-data-source.md).\n-   You must define the path of the data source in the Data Source \\[sys\\_data\\_source\\] table in the **Path for each row** field.\n-   To change the default behavior for the REST Insert Multiple user, create an entry in the REST Insert Multiples \\[sys\\_rest\\_insert\\_multiple\\] table.\n-   Enable the **Use data source format** in the REST insert multiple entry.\n\nData type: Object\n\n</td></tr><tr><td>\n\nStaging table column \\(default\\)\n\n</td><td>\n\nThis request body format matches staging table columns. Use the **records** array of key-value pairs matching the staging table column to insert in the import fields. Each JSON key is maps the table column to a JSON value representing the value to be inserted. JSON input varies depending on what fields are in your staging table.The column mapping default key value is to the column table.\n\n```\n{\n   \"records\":[\n      {\n         \"<ColumnLabel1>\":\"<value>\",\n         \"<ColumnLabel2>\":\"<value>\"\n      },\n      {\n         \"<ColumnLabel1>\":\"<value>\",\n         \"<ColumnLabel2>\":\"<value>\"\n      }\n   ]\n}\n```\n\nYou can modify mapping settings by adding an entry in the Rest Insert Multiples \\[sys\\_rest\\_insert\\_multiple\\] table and changing the **Column mapping** from **Label** to **Column name**.\n\n```\n{\n   \"records\":[\n      {\n         \"<column_name1>\":\"<value>\",\n         \"<column_name2>\":\"<value>\"\n      },\n      {\n         \"<column_name1>\":\"<value>\",\n         \"<column_name2>\":\"<value>\"\n      }\n   ]\n}\n```\n\nThe [Data dictionary tables](https://raw.githubusercontent.com/ServiceNow/ServiceNowDocs/australia/markdown/platform-administration/c_DataDictionaryTables.md) provides details on table fields in the system.\n\nData type: Array\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|Header|Description|\n|------|-----------|\n|Accept|Data format of the response body. Only supports **application/json**.|\n|Content-Type|Data format of the request body. Only supports **application/json**.|\n\n|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|200|Successful. The request was successfully processed.|\n|201|Successful. The request was successfully created.|\n|401|Unauthorized. The user credentials are incorrect or have not been passed.|\n|500|Internal server error. An unexpected error occurred while processing the request. The response contains additional information about the error.|\n\n### Response body \\(JSON\\)\n\n<table id=\"table_smw_4xr_lnb\"><thead><tr><th>\n\nName\n\n</th><th>\n\nDescription\n\n</th></tr></thead><tbody><tr><td>\n\nimport\\_set\\_id\n\n</td><td>\n\nSys\\_id of the added record. For asynchronous requests, you can use this value to run another import set after this import set process is complete.Data type: String\n\nTable: Import Sets \\[sys\\_import\\_set\\]\n\n</td></tr><tr><td>\n\nmulti\\_import\\_set\\_id\n\n</td><td>\n\nSys\\_id of the added record. Use this value to group multiple import sets into one set.Data type: String\n\nTable: Multi Import Sets \\[sys\\_multi\\_import\\_set\\]\n\n</td></tr></tbody>\n</table>### Sample cURL request\n\nThe following example shows how to run a transform on an import table called u\\_employee\\_import\\_set\\_table using the staging table column format.\n\n```\ncurl \"https://instance.servicenow.com/api/now/import/u_employee_import_set_table/insertMultiple\" \\\n--request POST \\\n--header \"Accept:application/json\" \\\n--header \"Content-Type:application/json\" \\\n--data \"{\n  \\\"records\\\": [\n  {\n   \\\"Address\\\": \\\"Hollywood\\\",\n   \\\"Name\\\": \\\"Tom\\\",\n   \\\"ID\\\": \\\"123\\\"\n  },\n  {\n   \\\"Address\\\": \\\"Vine\\\",\n   \\\"Name\\\": \\\"Irene\\\",\n   \\\"ID\\\": \\\"456\\\"\n  }\n  ]\n}\" \\\n--user 'username':'password'\n```\n\nResults include sys\\_ids for new records in the Import Sets \\[sys\\_import\\_set\\] and Multi Import Sets \\[sys\\_multi\\_import\\_set\\] tables.\n\n```\n{\n  \"import_set_id\": \"<import_set_sys_id>\",\n  \"multi_import_set_id\": \"<multi_import_set_sys_id>\"\n}\n```\n\n"}}