ServiceNow Import Sets API

openapi: 3.2.0
info:
  title: ServiceNow Import Set Import Sets 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
servers:
- url: https://{instance}.service-now.com/api/now
  description: ServiceNow Instance
  variables:
    instance:
      default: instance
      description: Your ServiceNow instance name
security:
- basicAuth: []
- oauth2: []
tags:
- name: Import Sets
  description: Operations for inserting records into import set staging tables and triggering transform map processing.
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:
  schemas:
    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
    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
    ImportSetInput:
      type: object
      description: The field name-value pairs corresponding to columns in the import set staging table.
      additionalProperties:
        type: string
  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: {}
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