The ServiceNow Import Set API allows external systems to push data into ServiceNow import set tables, which can then be synchronously or asynchronously transformed and loaded into target tables. It is commonly used for integrating external data sources with ServiceNow using transform maps.
openapi: 3.1.0
info:
title: ServiceNow Import Set API
description: >-
The ServiceNow Import Set API allows external systems to push data into
ServiceNow import set staging tables, which can then be synchronously or
asynchronously transformed and loaded into target tables using transform
maps. It is commonly used for integrating external data sources with
ServiceNow for bulk data loading and ETL workflows.
version: 'Yokohama'
contact:
name: ServiceNow Support
url: https://support.servicenow.com
termsOfService: https://www.servicenow.com/terms-of-use.html
externalDocs:
description: ServiceNow Import Set API Documentation
url: https://www.servicenow.com/docs/bundle/yokohama-api-reference/page/integrate/inbound-rest/concept/c_ImportSetAPI.html
servers:
- url: https://{instance}.service-now.com/api/now
description: ServiceNow Instance
variables:
instance:
default: instance
description: Your ServiceNow instance name
tags:
- name: Import Sets
description: >-
Operations for inserting records into import set staging tables and
triggering transform map processing.
security:
- basicAuth: []
- oauth2: []
paths:
/import/{stagingTableName}:
post:
operationId: insertImportSetRecord
summary: Servicenow Insert a Record Into an Import Set Staging Table
description: >-
Inserts a single record into the specified import set staging table.
If an active transform map exists for the staging table, the record
is synchronously transformed and loaded into the target table. The
response includes the transformation result indicating whether the
record was inserted, updated, or encountered an error.
tags:
- Import Sets
parameters:
- name: stagingTableName
in: path
required: true
description: >-
The name of the import set staging table. This table must extend
sys_import_set_row and have an associated transform map configured.
schema:
type: string
example: u_import_incidents
requestBody:
required: true
description: >-
The field name-value pairs to insert into the staging table. Field
names must match the column names defined on the staging table.
content:
application/json:
schema:
$ref: '#/components/schemas/ImportSetInput'
examples:
InsertimportsetrecordRequestExample:
summary: Default insertImportSetRecord request
x-microcks-default: true
value: {}
application/xml:
schema:
$ref: '#/components/schemas/ImportSetInput'
examples:
InsertimportsetrecordRequestExample:
summary: Default insertImportSetRecord request
x-microcks-default: true
value: {}
responses:
'201':
description: >-
Record successfully inserted into the staging table and
transformation completed.
content:
application/json:
schema:
type: object
properties:
result:
type: array
items:
$ref: '#/components/schemas/ImportSetResult'
examples:
Insertimportsetrecord201Example:
summary: Default insertImportSetRecord 201 response
x-microcks-default: true
value:
result:
- transform_map: example_value
table: example_value
display_name: example_value
display_value: example_value
record_link: https://www.example.com
status: inserted
status_message: example_value
sys_id: '500123'
target_sys_id: '500123'
import_set: example_value
'400':
description: >-
Bad request. The staging table name is invalid or the request body
contains malformed data.
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
examples:
Insertimportsetrecord400Example:
summary: Default insertImportSetRecord 400 response
x-microcks-default: true
value:
error:
message: example_value
detail: example_value
'401':
description: Unauthorized. Authentication credentials are missing or invalid.
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
examples:
Insertimportsetrecord401Example:
summary: Default insertImportSetRecord 401 response
x-microcks-default: true
value:
error:
message: example_value
detail: example_value
'403':
description: >-
Forbidden. The user does not have the import_transformer role or
ACL access to the staging table.
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
examples:
Insertimportsetrecord403Example:
summary: Default insertImportSetRecord 403 response
x-microcks-default: true
value:
error:
message: example_value
detail: example_value
x-microcks-operation:
delay: 0
dispatcher: FALLBACK
/import/{stagingTableName}/insertMultiple:
post:
operationId: insertMultipleImportSetRecords
summary: Servicenow Insert Multiple Records Into an Import Set Staging Table
description: >-
Inserts multiple records into the specified import set staging table
in a single request. Each record is individually transformed if an
active transform map exists.
tags:
- Import Sets
parameters:
- name: stagingTableName
in: path
required: true
description: >-
The name of the import set staging table.
schema:
type: string
example: example_value
requestBody:
required: true
content:
application/json:
schema:
type: object
properties:
records:
type: array
description: An array of records to insert into the staging table.
items:
$ref: '#/components/schemas/ImportSetInput'
examples:
InsertmultipleimportsetrecordsRequestExample:
summary: Default insertMultipleImportSetRecords request
x-microcks-default: true
value:
records:
- {}
responses:
'201':
description: Records successfully inserted and transformed.
content:
application/json:
schema:
type: object
properties:
result:
type: array
items:
$ref: '#/components/schemas/ImportSetResult'
examples:
Insertmultipleimportsetrecords201Example:
summary: Default insertMultipleImportSetRecords 201 response
x-microcks-default: true
value:
result:
- transform_map: example_value
table: example_value
display_name: example_value
display_value: example_value
record_link: https://www.example.com
status: inserted
status_message: example_value
sys_id: '500123'
target_sys_id: '500123'
import_set: example_value
'400':
description: Bad request. The request body is malformed.
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
examples:
Insertmultipleimportsetrecords400Example:
summary: Default insertMultipleImportSetRecords 400 response
x-microcks-default: true
value:
error:
message: example_value
detail: example_value
'401':
description: Unauthorized. Authentication credentials are missing or invalid.
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
examples:
Insertmultipleimportsetrecords401Example:
summary: Default insertMultipleImportSetRecords 401 response
x-microcks-default: true
value:
error:
message: example_value
detail: example_value
x-microcks-operation:
delay: 0
dispatcher: FALLBACK
components:
securitySchemes:
basicAuth:
type: http
scheme: basic
description: >-
Basic authentication with ServiceNow credentials. The user must have
the import_transformer role or appropriate staging table ACLs.
oauth2:
type: oauth2
description: OAuth 2.0 authentication using ServiceNow's OAuth provider.
flows:
password:
tokenUrl: https://{instance}.service-now.com/oauth_token.do
scopes: {}
schemas:
ImportSetInput:
type: object
description: >-
The field name-value pairs corresponding to columns in the import set
staging table.
additionalProperties:
type: string
ImportSetResult:
type: object
description: >-
The result of processing an import set record including the
transformation outcome.
properties:
transform_map:
type: string
description: The name of the transform map used to process the record.
example: example_value
table:
type: string
description: The target table into which the record was transformed.
example: example_value
display_name:
type: string
description: The display name of the transform map.
example: example_value
display_value:
type: string
description: The display value of the target record created or updated.
example: example_value
record_link:
type: string
format: uri
description: A link to the target record in ServiceNow.
example: https://www.example.com
status:
type: string
description: >-
The transformation status. Common values include inserted, updated,
error, and ignored.
enum:
- inserted
- updated
- error
- ignored
example: inserted
status_message:
type: string
description: >-
A descriptive message about the transformation result, especially
useful when the status is error.
example: example_value
sys_id:
type: string
description: >-
The sys_id of the import set row record in the staging table.
example: '500123'
target_sys_id:
type: string
description: >-
The sys_id of the record created or updated in the target table.
example: '500123'
import_set:
type: string
description: The sys_id of the parent import set.
example: example_value
Error:
type: object
properties:
error:
type: object
properties:
message:
type: string
description: A human-readable error message.
detail:
type: string
description: Detailed information about the error.
example: example_value