The Identification and Reconciliation API uses the Identification and Reconciliation engine (IRE) to minimize creation of duplicate Configuration Items (CIs) and to reconcile CI attributes by only accepting information from authorized sources when updating the Configuration Management Database (CMDB).

Users must have the itil or asset role to use this API.

For more information on the IRE, see Identification and Reconciliation engine (IRE).

Identification and Reconciliation - POST /now/identifyreconcile

Inserts or updates configuration items (CIs) in the CMDB by applying identification and reconciliation rules to the specified payload (request body). Use this API instead of updating the CMDB directly.

Use the Identification and Reconciliation - POST /now/identifyreconcile/query endpoint to simulate submission of a payload to this endpoint without committing changes to the database.

Use the Identification and Reconciliation - POST /now/identifyreconcile/enhanced endpoint instead if you need to specify Enhanced IRE options. For more on Enhanced IRE options, see Identification and Reconciliation engine (IRE).

URL format

Versioned URL: /api/now/{api_version}/identifyreconcile

Default URL: /api/now/identifyreconcile

Supported request parameters

Table 1. Path parameters
Name Description
api_version Optional. 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
Table 2. Query parameters
Name Description
sysparm_data_source Identifies the source of the CI information. This must be one of the choice values defined for the discovery_source field of the Configuration Item [cmdb_ci] table.

Data type: String

Default: Insert the API payload into the incomplete payloads table.

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.

Table 4. Request headers
Header Description
Accept Data format of the response body. Only supports application/json.
Content-Type Data format of the request body. Only supports application/json.
Table 5. Response headers
Header Description
None

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.

Table 6. Status codes
Status code Description
200 Successful. The request was successfully processed.
401 Unauthorized. The user credentials are incorrect or have not been passed.
500 Internal server error. An unexpected error occurred while processing the request. The response contains additional information about the error.

Response body parameters (JSON or XML)

Example: cURL request

Submit a payload containing a Linux server (with serial number and network adapter related-item lookups) and an IP switch, with an IP Connection dependent relationship between them.

curl "https://instance.servicenow.com/api/now/identifyreconcile" \
--request POST \
--header "Accept: application/json" \
--header "Content-Type: application/json" \
--user "username:password" \
--data '{ \
  "items": [{ \
    "className": "cmdb_ci_linux_server", \
    "values": { \
      "sys_class_name": "cmdb_ci_linux_server", \
      "name": "lnux101", \
      "host_name": "lnux101.servicenow.com", \
      "ip_address": "10.11.12.173", \
      "os_name": "Linux Red Hat" \
    }, \
    "lookup": [{ \
      "className": "cmdb_serial_number", \
      "values": { \
        "serial_number": "lnux101", \
        "serial_number_type": "uuid", \
        "valid": "true" \
      } \
    }, { \
      "className": "cmdb_ci_network_adapter", \
      "values": { \
        "name": "eth0", \
        "ip_address": "10.11.12.173", \
        "mac_address": "00:55:51:21:26:2f" \
      } \
    }] \
  }, { \
    "className": "cmdb_ci_ip_switch", \
    "values": { \
      "name": "IP-Switch-1", \
      "serial_number": "Switch23587", \
      "serial_number_type": "uuid" \
    } \
  }], \
  "relations": [{ \
    "parent": 0, \
    "child": 1, \
    "type": "IP Connection::IP Connection" \
  }]
}'

The Linux server CI is identified via a Hardware Rule search for its name on the Hardware [cmdb_ci_hardware] table and is processed as an update to an existing CI in the Linux Server [cmdb_ci_linux_server] table. The IP switch is similarly identified via a Hardware Rule search for its name on the Hardware table and updates an existing CI in the IP Switch [cmdb_ci_ip_switch] table. Finally, the IP Connection dependent relationship between the server and the switch is inserted as a new record in the CI Relationship [cmdb_rel_ci] table.

{
  "result": {
    "items": [{
      "className": "cmdb_ci_linux_server",
      "operation": "UPDATE",
      "sysId": "539747cac0a801640163e60735fbbf6e",
      "relatedSysIds": [null, null],
      "relatedItems": [{
        "markers": [],
        "inputIndices": [{
          "mainIndex": 0,
          "subIndex": 0
        }],
        "mergedPayloadIds": [],
        "className": "cmdb_serial_number"
      }, {
        "markers": [],
        "inputIndices": [{
          "mainIndex": 0,
          "subIndex": 1
        }],
        "mergedPayloadIds": [],
        "className": "cmdb_ci_network_adapter"
      }],
      "additionalRelatedItems": [],
      "identifierEntrySysId": "556eb250c3400200d8d4bea192d3ae92",
      "identificationAttempts": [{
        "identifierName": "Hardware Rule",
        "attemptResult": "NO_MATCH",
        "attributes": ["serial_number", "serial_number_type"],
        "searchOnTable": "cmdb_serial_number",
        "hybridEntryCiAttributes": []
      }, {
        "identifierName": "Hardware Rule",
        "attemptResult": "SKIPPED",
        "attributes": ["serial_number"],
        "searchOnTable": "cmdb_ci_hardware",
        "hybridEntryCiAttributes": []
      }, {
        "identifierName": "Hardware Rule",
        "attemptResult": "MATCHED",
        "attributes": ["name"],
        "searchOnTable": "cmdb_ci_hardware",
        "hybridEntryCiAttributes": []
      }],
      "markers": [],
      "inputIndices": [0],
      "mergedPayloadIds": [],
      "errorCount": 0
    }, {
      "className": "cmdb_ci_ip_switch",
      "operation": "UPDATE",
      "sysId": "304481257f701200bee45f19befa915b",
      "identifierEntrySysId": "556eb250c3400200d8d4bea192d3ae92",
      "identificationAttempts": [{
        "identifierName": "Hardware Rule",
        "attemptResult": "SKIPPED",
        "attributes": ["serial_number", "serial_number_type"],
        "searchOnTable": "cmdb_serial_number",
        "hybridEntryCiAttributes": []
      }, {
        "identifierName": "Hardware Rule",
        "attemptResult": "NO_MATCH",
        "attributes": ["serial_number"],
        "searchOnTable": "cmdb_ci_hardware",
        "hybridEntryCiAttributes": []
      }, {
        "identifierName": "Hardware Rule",
        "attemptResult": "MATCHED",
        "attributes": ["name"],
        "searchOnTable": "cmdb_ci_hardware",
        "hybridEntryCiAttributes": []
      }],
      "markers": [],
      "inputIndices": [1],
      "mergedPayloadIds": [],
      "errorCount": 0
    }],
    "additionalCommittedItems": [],
    "relations": [{
      "className": "cmdb_rel_ci",
      "operation": "INSERT",
      "markers": [],
      "inputIndices": [0],
      "mergedPayloadIds": [],
      "errorCount": 0
    }],
    "additionalCommittedRelations": []
  }
}

Identification and Reconciliation - POST /now/identifyreconcile/enhanced

Inserts or updates configuration items (CIs) in the CMDB by applying identification and reconciliation rules to the specified payload (request body). Use this API instead of updating the CMDB directly.

Use the Identification and Reconciliation - POST /now/identifyreconcile/queryEnhanced endpoint to simulate submission of a payload to this endpoint without committing changes to the database.

This method is similar to the Identification and Reconciliation - POST /now/identifyreconcile method, but adds the following functionality:
  • Partial payloads
    • In case of an item having a warning or error, indicates if an item operation is INSERT_AS_PARTIAL or INSERT_INCOMPLETE.
    • Returns the sys_ids of partial payloads that were merged with existing partial payloads.
  • Supports payload deduplicate feature.
  • Generates a summary.

URL format

Versioned URL: /api/now/{api_version}/identifyreconcile/enhanced

Default URL: /api/now/identifyreconcile/enhanced

Supported request parameters

Table 7. Path parameters
Name Description
api_version Optional. 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
Table 8. Query parameters
Name Description
options Comma-separated list of name-value pairs representing Enhanced IRE options applied for the request.

As an example, to override the default values for the partial payloads, partial commits, deduplicate payloads, and generate summary Enhanced IRE options:

partial_payloads:false,partial_commits:false,deduplicate_payloads:false,generate_summary:true
Note: By default or if partial_payloads is set to true, both partial_commits and deduplicate_payloads are enabled, even if they are set to false, as those features are essential for partial payloads functionality.

For more on Enhanced IRE options, see Identification and Reconciliation engine (IRE).

Valid values for each name-value pair:
  • true: Enable this Enhanced IRE option.
  • false: Disable this Enhanced IRE option.

Data type: String
sysparm_data_source Identifies the source of the CI information. This must be one of the choice values defined for the discovery_source field of the Configuration Item [cmdb_ci] table.

Data type: String

Default: Insert the API payload into the incomplete payloads table.
Table 9. Request body parameters (XML or JSON)
NameDescription
items Array of objects in which each object describes a CI to create or update.

Data type: Array

"items": [
  {
    "className": "String",
    "internal_id": "String",
    "lookup": [Array],
    "related": [Array],
    "settings": {Object},
    "sys_object_source_info": {Object},
    "values": {Object}
  }
]
items.className Required. The sys_class_name (class/table name) of the CI to create or update. This value can be any CMDB table, such as cmdb_ci_linux_server or cmdb_ci_win_server.

Data type: String
items.internal_id Unique identifier for this item in this payload. Can be any value, but must be unique within the payload.

Data type: String
items.lookup Array of objects in which each object describes a lookup-based identification record. These records are used to identify the top-level configuration item based on a lookup table that has a reference back to the Configuration Item [cmdb_ci] table.

Data type: Array

"lookup": [
  {
    "className": "String",
    "internal_id": "String",
    "sys_object_source_info": {Object},
    "values": {Object}
  }
]
items.lookup.className Required. The sys_class_name or class/table name of the CI to create or update. This value can be any CMDB class/table, such as cmdb_serial_number or cmdb_ci_network_adapter, or a non-CMDB hierarchy class.

Data type: String
items.lookup.internal_id Unique identifier for this lookup record in this payload. Can be any value, but must be unique within the payload.

Data type: String
items.lookup.sys_object_source_info Object describing a unique CI identifier for a specified data source. Different sources may have different name-value pairs for the same CI.

Data type: Object

"sys_object_source_info": {
  "source_feed": "String",
  "source_name": "String",  
  "source_native_key": "String",
  "source_recency_timestamp": "String"
}
items.lookup.sys_object_source_info.source_feed Name that uniquely identifies the feed sending this CI. Use if the source can have multiple feeds.

Data type: String
items.lookup.sys_object_source_info.source_name Data source for the CI information. This value must be one of the choice values defined for the discovery_source field of the Configuration Item [cmdb_ci] table.

Data type: String
items.lookup.sys_object_source_info.source_native_key Unique key/id from the source for the CI. Can be any string that is unique to the item.

Data type: String
items.lookup.sys_object_source_info.source_recency_timestamp UTC date and time that the CI was scanned.

Data type: String

Format: YYYY-MM-DD hh:mm:ss
items.lookup.values Object describing fields for this lookup item as name/value pairs, where the name is the field name.

Data type: Object

Field names and types depend on the fields selected by the user, such as:

"values": {
  "ip_address": "String",
  "mac_address": "String",
  "serial_number": "String",
  "serial_number_type": "String",
  "valid": "String"
}
items.related Array of objects in which each object describes an item record to create or update, based on a related table that has a reference to the top-level CI that is being identified. Rules in the Related Entry [cmdb_related_entry] table define what type of records can be in this array.

The related table may or may not extend the Configuration Item [cmdb_ci] table. These records are not used to identify the configuration item.

Data type: Array

"related": [
  {
    "className": "String",
    "internal_id": "String",
    "sys_object_source_info": {Object},
    "values": {Object}
  }
]
items.related.className Required. The sys_class_name or class/table name of the related item to create or update.

Data type: String
items.related.internal_id Unique identifier for this related item in this payload. Can be any value, but must be unique within the payload.

Data type: String
items.related.sys_object_source_info Object describing a unique CI identifier for a specified data source. Different sources may have different name-value pairs for the same CI.

Data type: Object

"sys_object_source_info": {
  "source_feed": "String",
  "source_name": "String",  
  "source_native_key": "String",
  "source_recency_timestamp": "String"
}
items.related.sys_object_source_info.source_feed Name that uniquely identifies the feed sending this related item. Use if the source can have multiple feeds.

Data type: String
items.related.sys_object_source_info.source_name Data source for the related item information. This value must be one of the choice values defined for the discovery_source field of the Configuration Item [cmdb_ci] table.

Data type: String
items.related.sys_object_source_info.source_native_key Unique key/id from the source for the related item. Can be any string that is unique to the item.

Data type: String
items.related.sys_object_source_info.source_recency_timestamp UTC date and time that the related item was scanned.

Data type: String

Format: YYYY-MM-DD hh:mm:ss
items.related.values Object describing fields to create or update for this related item as name/value pairs, where the name is the field name. For a reference field, the value must be the referenced sys_id.

Data type: Object

Field names and types depend on the fields selected by the user, such as:

"values": {
  "host_name": "String",
  "ip_address": "String",
  "name": "String",
  "os_name": "String",
  "sys_class_name": "String"
}
items.settings Object containing parameters defining the types of updates that are permitted.

Data type: Object

"settings": {
  "skipReclassificationRestrictionRules": Boolean,
  "updateWithoutDowngrade": Boolean,
  "updateWithoutSwitch": Boolean,
  "updateWithoutUpgrade": Boolean
}
items.settings.skipReclassificationRestrictionRules Flag that indicates whether IRE should skip running the Reclassification Restriction rule that matches the class for the payload item.
Valid values:
  • true: Skip running the rule.
  • false: Run the rule.

Default: false
items.settings.updateWithoutDowngrade Indicates whether update and downgrade are both permitted for this CI.
Valid values:
  • true: Update the item but downgrade is not permitted.
  • false: Both item update and downgrade are permitted.

Data type: Boolean

Default: false
items.settings.updateWithoutSwitch Indicates whether this CI can be updated and its class switched.
Valid values:
  • true: Update the item but class switching is not permitted.
  • false: Both item update and class switching are permitted.

Data type: Boolean

Default: false
items.settings.updateWithoutUpgrade Indicates whether update and upgrade are both permitted for this CI.
Valid values:
  • true: Update the item but upgrade is not permitted.
  • false: Both item update and upgrade are permitted.

Data type: Boolean

Default: false
items.sys_object_source_info Object describing a unique CI identifier.

Data type: Object

"sys_object_source_info": {
  "source_feed": "String",
  "source_name": "String",  
  "source_native_key": "String",
  "source_recency_timestamp": "String"
}
items.sys_object_source_info.source_feed Name that uniquely identifies the feed sending this CI. Use if the source can have multiple feeds.

Data type: String
items.sys_object_source_info.source_name Data source for the CI information. This value must be one of the choice values defined for the discovery_source field of the Configuration Item [cmdb_ci] table.

Data type: String
items.sys_object_source_info.source_native_key Unique key/id from the source for the CI. Can be any string that is unique to the item.

Data type: String
items.sys_object_source_info.source_recency_timestamp UTC date and time that the CI was scanned.

Data type: String

Format: YYYY-MM-DD hh:mm:ss
items.values Object describing fields to create or update for this CI as name/value pairs, where the name is the field name. For a reference field, the value must be the referenced sys_id.

Data type: Object

Field names and types depend on the fields selected by the user, such as:

"values": {
  "host_name": "String",
  "ip_address": "String",
  "name": "String",
  "os_name": "String",
  "sys_class_name": "String"
}
referenceItems Array of objects in which each object describes a reference between two items in the payload.

Data type: Array

"referenceItems": [
  {
    "referenced": "String",
    "referencedBy": "String",
    "referenceField": "String"
  }
]
referenceItems.referenced The internal_id defined for the item being referenced by another item.

Data type: String
referenceItems.referencedBy The internal_id defined for the item that references another item.

Data type: String
referenceItems.referenceField Name of the reference field in the class/table for the referencedBy item.

Data type: String
relations Array of objects in which each object describes a relationship between two items defined in the payload.
An object in this array can use either of two formats:
  • The object can define a relationship between two top-level items (only) using parent and child name-value pairs, with values representing item indexes from the payload items array.
  • The object can define a relationship between any two items, including top-level, related, or lookup items, using parent_id and child_id key/value pairs, with values representing internal_id values defined for those items.

Data type: Array

"relations": [
  {
    "child": Number,
    "parent": Number,
    "sys_rel_source_info": {Object},
    "type": "String"
  }
]
"relations": [
  {
    "child_id": "String",
    "parent_id": "String",
    "sys_rel_source_info": {Object},
    "type": "String"
  }
]
relations.child The integer index of the CI object in the items array that represents the child in the relationship.

Data type: Number
relations.child_id The internal_id of the child item in the relationship.

Data type: String
relations.parent The integer index of the CI object in the items array that represents the parent in the relationship.

Data type: Number
relations.parent_id The internal_id of the parent item in the relationship.

Data type: String
relations.sys_rel_source_info Discovery source information for the relationship. For non-dependency relationships, this information is in the Relationship Sources [sys_rel_source] table.

Data type: Object

"sys_rel_source_info": { 
  "source_name": "String", 
  "source_feed": "String" 
}
relations.sys_rel_source_info.source_name Discovery source name.

Default: Discovery source passed in the API method parameter.
relations.sys_rel_source_info.source_feed Any string that is a sub-discovery/scan within the discovery source.

Default: ‘UNKNOWN’ is stored in the source_feed column when creating a record in sys_rel_source table.
relations.type The type of relationship existing between the parent and child items. This must be a name field value from the CI Relationship Type [cmdb_rel_type] table.

Data type: String

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.

Table 10. Request headers
Header Description
Accept Data format of the response body. Only supports application/json.
Content-Type Data format of the request body. Only supports application/json.
Table 11. Response headers
Header Description
None

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.

Table 12. Status codes
Status code Description
200 Successful. The request was successfully processed.
401 Unauthorized. The user credentials are incorrect or have not been passed.
500 Internal server error. An unexpected error occurred while processing the request.

Error message detail "Chunk […] is not a valid entry" indicates that the options query parameter is not in the correct name-value pair format.

For example, specifying an options parameter of partial produces a 500 status code with "Chunk [partial] is not a valid entry" in the message detail.

Response body parameters (JSON or XML)

NameDescription
result Array of results produced by the query.

Data type: Array

"result": [
  "additionalCommittedItems": [Array],
  "additionalCommittedRelations": [Array],
  "items": [Array],
  "relations": [Array]
]
result.additionalCommittedItems Array of objects in which each object describes a CI not included in the request body items array to insert or update.

Data type: Array

"additionalCommittedItems": [
  {
    "className": "String",
    "errorCount": Number,
    "identificationAttempts": [Array],
    "inputIndices": [Array],
    "markers": [Array],
    "mergedPayloads": [Array],
    "operation": "String",
    "sysId": "String"
  }
]
result.additionalCommittedItems.className The sys_class_name of this additional CI.

Data type: String
result.additionalCommittedItems.errorCount The number of errors encountered while processing this additional CI.

Data type: Number
result.additionalCommittedItems.errors Array of objects in which each object describes an error encountered while processing this additional CI.

Data type: Array

"errors": [
  {
    "error": "String",
    "message": "String"
  }
]
result.additionalCommittedItems.errors.error The type of error encountered while processing this additional CI.

Data type: String
result.additionalCommittedItems.errors.message The error message encountered while processing this additional CI.

Data type: String
result.additionalCommittedItems.identificationAttempts Array of objects in which each object describes an attempt made to identify this additional CI.
Data type: Array
"identificationAttempts": [
  {
    "attemptResult": "String",
    "attributes": [Array],
    "hybridEntryCiAttributes": [Array],
    "identiferName": "String",
    "searchOnTable": [Array]
  }
]
result.additionalCommittedItems.identificationAttempts.attemptResult The outcome of this additional CI identification attempt.
Possible values:
  • MATCHED: Identification succeeded. A unique CI was found in the identifier rule table which exactly matched the specified attributes.
  • MULTI_MATCH: Identification failed with an error. Duplicate CIs were found in the identifier rule table when matching against the specified attributes.
  • NO_MATCH: Identification failed. No CI was found in the identifier rule table which matched the specified attributes.
  • SKIPPED: Identification not attempted. The attributes required for this identifier rule table search were not provided, so the rule was not applied.

Data type: String
result.additionalCommittedItems.identificationAttempts.attributes Array of CI identifier entry attributes used during this additional CI identification attempt.

Data type: Array

Attribute names and types depend on the request body data and the identifier in use, such as:

"attributes": [
  "serial_number": "String",
  "serial_number_type": "String",
]
result.additionalCommittedItems.identificationAttempts.hybridEntryCiAttributes Array of CI identifier entry attributes used during this additional CI identification attempt.

Data type: Array

Attribute names and types depend on the request body data and the identifier in use, such as:

"hybridEntryCiAttributes": [
  "name": "String",
  "serial_number": "String"
]
result.additionalCommittedItems.identificationAttempts.identifierName The identifier rule used for this additional CI identification attempt.

Data type: String
result.additionalCommittedItems.identificationAttempts.searchOnTable The name of the table searched for this additional CI identification attempt.

Data type: String
result.additionalCommittedItems.identifierEntrySysId The sys_id for the identifier rule used to identify this additional CI.
Notable values:
  • Unknown: Identification of this additional CI failed. See errors for details.

Data type: String
result.additionalCommittedItems.inputIndices Array of index values for CIs from the request body items array that correspond to this additional CI.

Data type: Array

"inputIndices": [
  {
    Number
  }
]
result.additionalCommittedItems.markers Array of marker values for internal use.

Data type: Array

"markers": []
result.additionalCommittedItems.mergedPayloads Array of sys_id values for partial payloads from the CMDB IRE Partial Payloads [cmdb_ire_partial_payloads] table that were merged during processing of this additional CI.

Data type: Array

"mergedPayloadIds": [
  "String"
]
result.additionalCommittedItems.operation The operation performed for this additional CI.
Possible values:
  • DELETE: An existing CI is removed from the target table.
  • INSERT: The additional CI is inserted into the target table as a new record.
  • NO_CHANGE: No operation is performed for the additional CI.
  • UPDATE: An existing CI in the target table is updated.
  • UPDATE_WITH_DOWNGRADE: An existing CI in the target table is updated and its class is changed to a more generic class (ancestor class).
  • UPDATE_WITH_SWITCH: An existing CI in the target table is updated and its class is changed to another class which is not an ancestor or descendent class.
  • UPDATE_WITH_UPGRADE: An existing CI in the target table is updated and its class is changed to a more specialized class (descendent class).

Data type: String
result.additionalCommittedItems.sysId The sys_id found for this additional CI through identification.
Notable values:
  • Unknown: Identification of this additional CI failed. See errors for details.

Data type: String
result.additionalCommittedItems.warnings Array of objects in which each object describes a warning encountered while processing this additional CI.

Data type: Array

"warnings": [
  {
    "error": "String",
    "message": "String"
  }
]
result.additionalCommittedItems.warnings.error The type of warning encountered while processing this additional CI.

Data type: String
result.additionalCommittedItems.warnings.message The warning message encountered while processing this additional CI.

Data type: String
result.additionalCommittedRelations Array of objects in which each object describes a dependent relationship CI not included in the request body relations list to insert or update.

Data type: Array

"additionalCommittedRelations": [
  {
    "className": "String",
    "operation": "String",
    "markers": [Array],
    "inputIndices": [Array],
    "mergedPayloadIds": [Array]
  }
]
result.additionalCommittedRelations.className The sys_class_name of this additional dependent relationship CI.
Only supported value:
  • cmdb_rel_ci: The CI Relationship table.

Data type: String
result.additionalCommittedRelations.errorCount The number of errors encountered while processing this additional dependent relationship CI.

Data type: Number
result.additionalCommittedRelations.errors Array of objects in which each object describes an error encountered while processing this additional dependent relationship CI.

Data type: Array

"errors": [
  {
    "error": "String",
    "message": "String"
  }
]
result.additionalCommittedRelations.errors.error The type of error encountered while processing this additional dependent relationship CI.

Data type: String
result.additionalCommittedRelations.errors.message The error message encountered while processing this additional dependent relationship CI.

Data type: String
result.additionalCommittedRelations.inputIndices Array of index values for dependent relationship CI objects in the request body relations array that correspond to this additional dependent relationship CI.

Data type: Array

"inputIndices": [
  Number
]
result.additionalCommittedRelations.markers Array of marker values for internal use.

Data type: Array

"markers": []
result.additionalCommittedRelations.mergedPayloadIds Array of sys_id values for partial payloads from the CMDB IRE Partial Payloads [cmdb_ire_partial_payloads] table that were merged during processing of this additional dependent relationship CI.

Data type: Array

"mergedPayloadIds": [
  "String"
]
result.additionalCommittedRelations.operation The operation performed for this additional dependent relationship CI.
Possible values:
  • INSERT: The dependent relationship CI is inserted into the target table as a new record.
  • INSERT_AS_INCOMPLETE: The dependent relationship CI had errors and is inserted into the CMDB IRE Incomplete Payloads [cmdb_ire_incomplete_payloads] table.
  • INSERT_AS_PARTIAL: The dependent relationship CI had errors and is inserted into the CMDB IRE Partial Payloads [cmdb_ire_partial_payloads] table.
  • NO_CHANGE: No operation is performed for the dependent relationship CI.
  • UPDATE: An existing dependent relationship CI in the target table is updated.

Data type: String
result.items Array of objects in which each object describes a CI included in the request body items array.

Data type: Array

"items": [
  {
    "additionalRelatedItems": [Array],
    "className": "String",
    "duplicateLookupIndices": {Object},
    "errorCount": Number,
    "errors": [Array],
    "identificationAttempts": [Array],
    "identifierEntrySysId": "String",
    "info": [Array],
    "inputIndices": [Array],
    "markers": [Array],
    "mergedPayloadIds": [Array],
    "operation": "String",
    "relatedItems": [Array],
    "relatedSysIds": [Array],
    "sysId": "String",
    "warnings": [Array]
  }
]
result.items.additionalRelatedItems Array of objects in which each object describes a related CI (table lookup CI) from the CMDB IRE Partial Payloads [cmdb_ire_partial_payloads] table.

Data type: Array

"additionalRelatedItems": [
  {
    "className": "String",
    "inputIndices": [Array],
    "markers": [Array],
    "mergedPayloadIds": [Array],
    "sysId": "String"
  }
]
result.items.additionalRelatedItems.className The sys_class_name of the related item.

Data type: String
result.items.additionalRelatedItems.inputIndices Array of index values for CIs from the request body items array that correspond to this related item.

Data type: Array

"inputIndices": [
    Number
]
result.items.additionalRelatedItems.markers Array of marker values for internal use.

Data type: Array

"markers": []
result.items.additionalRelatedItems.mergedPayloadIds Array of sys_id values for partial payloads from the CMDB IRE Partial Payloads [cmdb_ire_partial_payloads] table that were merged during processing of this related item.

Data type: Array

"mergedPayloadIds": [
  "String"
]
result.items.additionalRelatedItems.sysId The sys_id of this related CI.

Data type: String
result.items.className The sys_class_name of this CI.

Data type: String
result.items.duplicateLookupIndices Object containing arrays of index values for items.lookup array elements that reference the same related CI.

The array name indicates the first element from the request body items.lookup array that references a given related CI. Its values are the set of additional elements from the same array that reference the same related CI.

Data type: Object

This example shows a case where the second element in the items.lookup array references the same related CI as a later element from that array:

"duplicateLookupIndices": [
  "2": [Array]
]
result.items.errorCount The number of errors encountered while processing this CI.

Data type: Number
result.items.errors Array of objects in which each object describes an error encountered while processing this CI.

Data type: Array

"errors": [
  {
    "error": "String",
    "message": "String"
  }
]
result.items.errors.error The type of error encountered while processing this CI.

Data type: String
result.items.errors.message The error message encountered while processing this CI.

Data type: String
result.items.identificationAttempts Array of objects in which each object describes an attempt made to identify this CI.
Data type: Array
"identificationAttempts": [
  {
    "attemptResult": "String",
    "attributes": [Array],
    "hybridEntryCiAttributes": [Array],
    "identiferName": "String",
    "searchOnTable": [Array]
  }
]
result.items.identificationAttempts.attemptResult The outcome of this CI identification attempt.
Possible values:
  • MATCHED: Identification succeeded. A unique CI was found in the identifier rule table which exactly matched the specified attributes.
  • MULTI_MATCH: Identification failed with an error. Duplicate CIs were found in the identifier rule table when matching against the specified attributes.
  • NO_MATCH: Identification failed. No CI was found in the identifier rule table which matched the specified attributes.
  • SKIPPED: Identification not attempted. The attributes required for this identifier rule table search were not provided, so the rule was not applied.

Data type: String
result.items.identificationAttempts.attributes Array of CI identifier entry attributes used during this CI identification attempt.

Data type: Array

Attribute names and types depend on the request body data and the identifier in use, such as:

"attributes": [
  "serial_number": "String",
  "serial_number_type": "String",
]
result.items.identificationAttempts.hybridEntryCiAttributes Array of CI identifier entry attributes used during this CI identification attempt.

Data type: Array

Attribute names and types depend on the request body data and the identifier in use, such as:

"hybridEntryCiAttributes": [
  "name": "String",
  "serial_number": "String"
]
result.items.identificationAttempts.identifierName The identifier rule used for this CI identification attempt.

Data type: String
result.items.identificationAttempts.searchOnTable The name of the table searched for this CI identification attempt.

Data type: String
result.items.identifierEntrySysId The sys_id for the identifier rule used to identify this CI.
Notable values:
  • Unknown: Identification of this CI failed. See errors for details.

Data type: String
result.items.info List of objects that contains additional information about the processing of the item.

Data type: Array

"info": [
  {
    "code": "String",
    "message": "String",
    "ruleSysId": "String"
  }
]
result.items.info.code Reclassification type that was skipped.
Possible values:
  • SKIPPED_CLASS_SWITCH
  • SKIPPED_CLASS_DOWNGRADE
  • SKIPPED_CLASS_UPGRADE
result.items.info.message Message that provides additional insights into the reason for skipping the reclassification.

Data type: String
result.items.info.ruleSysId Sys_id of the reclassification restriction rule that was matched. Applicable only when IRE skips reclassification due to reclassification restriction rule. This value is empty if the reclassification is skipped due to a payload or global flag.

Data type: String
result.items.inputIndices Array of index values for CIs from the request body items array that correspond to this CI.

Data type: Array

"inputIndices": [
  {
    Number
  }
]
result.items.markers Array of marker values for internal use.

Data type: Array

"markers": []
result.items.mergedPayloadIds Array of sys_id values for partial payloads from the CMDB IRE Partial Payloads [cmdb_ire_partial_payloads] table that were merged during processing of this CI.

Data type: Array

"mergedPayloadIds": [
  "String"
]
result.items.operation The operation performed for this CI.
Possible values:
  • DELETE: An existing CI is removed from the target table.
  • INSERT: The CI is inserted into the target table as a new record.
  • NO_CHANGE: No operation is performed for the CI.
  • UPDATE: An existing CI in the target table is updated.
  • UPDATE_WITH_DOWNGRADE: An existing CI in the target table is updated and its class is changed to a more generic class (ancestor class).
  • UPDATE_WITH_SWITCH: An existing CI in the target table is updated and its class is changed to another class which is not an ancestor or descendent class.
  • UPDATE_WITH_UPGRADE: An existing CI in the target table is updated and its class is changed to a more specialized class (descendent class).

Data type: String
result.items.relatedItems Array of objects in which each object describes a related CI (table lookup CI) from the request body items.lookup array.

Data type: Array

"relatedItems": [
  {
    "className": "String",
    "inputIndices": [Array],
    "markers": [Array],
    "mergedPayloadIds": [Array],
    "sysId": "String"
  }
]
result.items.relatedItems.className The sys_class_name of the related item.

Data type: String
result.items.relatedItems.inputIndices Array of index values for CIs and lookup items from the request body items and items.lookup arrays that correspond to this related item.

Data type: Array

"inputIndices": [
  {
    "mainIndex": Number,
    "subIndex": Number
  }
]
result.items.relatedItems.inputIndices.mainIndex Index value from the request body items array that corresponds to the CI parent of the related item.

Data type: Number
result.items.relatedItems.inputIndices.subIndex Index value from the request body items.lookup array that corresponds to the related item.

Data type: Number
result.items.relatedItems.markers Array of marker values for internal use.

Data type: Array

"markers": []
result.items.relatedItems.mergedPayloadIds Array of sys_id values for entries in the CMDB IRE Partial Payloads [cmdb_ire_partial_payloads] table that were merged into this CI during processing.

Data type: Array

"mergedPayloadIds": [
  "String"
]
result.items.relatedSysIds Array of sys_id values for related items (table lookup items) from the request body items.lookup array.

Data type: Array

Notable values:
  • null: No sys_id was identified for this related item.
"relatedSysIds": [
    Number,
    Number
]
result.items.sysId The sys_id found for this CI through identification.
Notable values:
  • Unknown: Identification of this CI failed. See errors for details.

Data type: String
result.items.warnings Array of objects in which each object describes a warning encountered while processing this CI.

Data type: Array

"warnings": [
  {
    "error": "String",
    "message": "String"
  }
]
result.items.warnings.error The type of warning encountered while processing this CI.

Data type: String
result.items.warnings.message The warning message encountered while processing this CI.

Data type: String
result.logContextId Context ID reported for this payload.

Data type: String
result.relations Array of objects in which each object describes a dependent relationship CI from the request body relations array.

Data type: Array

"relations": [
  {
    "className": "String",
    "errorCount": Number,
    "errors": [Array],
    "inputIndices": [Array],
    "markers": [Array],
    "mergedPayloadIds": [Array],
    "operation": "String",
    "warnings": [Array]
  }
]
result.relations.className The sys_class_name of this dependent relationship CI.
Only supported value:
  • cmdb_rel_ci: The CI Relationship table.

Data type: String
result.relations.errorCount The number of errors encountered while processing this dependent relationship CI.

Data type: Number
result.relations.errors Array of objects in which each object describes an error encountered while processing this dependent relationship CI.

Data type: Array

"errors": [
  {
    "error": "String",
    "message": "String"
  }
]
result.relations.errors.error The type of error encountered while processing this dependent relationship CI.

Data type: String
result.relations.errors.message The error message encountered while processing this dependent relationship CI.

Data type: String
result.relations.inputIndices Array of index values for the dependent relationship CI objects in the request body relations array that correspond to this dependent relationship CI.

Data type: Array

"inputIndices": [
  Number
]
result.relations.markers Array of marker values for internal use.

Data type: Array

"markers": []
result.relations.mergedPayloadIds Array of sys_id values for partial payloads from the CMDB IRE Partial Payloads [cmdb_ire_partial_payloads] table that were merged during processing of this dependent relationship CI.

Data type: Array

"mergedPayloadIds": [
  "String"
]
result.relations.operation The operation performed for this dependent relationship CI.
Possible values:
  • INSERT: The dependent relationship CI was inserted into the target table as a new record.
  • INSERT_AS_INCOMPLETE: The dependent relationship CI had errors and was inserted into the CMDB IRE Incomplete Payloads [cmdb_ire_incomplete_payloads] table.
  • INSERT_AS_PARTIAL: The dependent relationship CI had errors and was inserted into the CMDB IRE Partial Payloads [cmdb_ire_partial_payloads] table.
  • NO_CHANGE: No operation was performed for the dependent relationship CI.
  • UPDATE: An existing dependent relationship CI in the target table was updated.

Data type: String
result.relations.warnings Array of objects in which each object describes a warning encountered while processing this dependent relationship CI.

Data type: Array

"warnings": [
  {
    "error": "String",
    "message": "String"
  }
]
result.relations.warnings.error The type of warning encountered while processing this dependent relationship CI.

Data type: String
result.relations.warnings.message The warning message encountered while processing this dependent relationship CI.

Data type: String

Example: cURL request

Submit a partial payload for a computer CI.

curl "https://instance.servicenow.com/api/now/identifyreconcile/enhanced" \
--request POST \
--header "Accept: application/json" \
--header "Content-Type: application/json" \
--user "username":"password" \
--data '{ \
  "items" : [ \
    { \
      "className" : "cmdb_ci_computer", \
      "sys_object_source_info" : { \
        "source_name" : "ServiceNow", \
        "source_native_key" : "ncomputer3367" \
      }, \
      "values" : { \
        "cpu_core_count" : "6", \
        "ram" : "8192", \
        "manufacturer" : "DELL", \
        "company" : "My Company" \
      } \
    } \
  ] \
}'

The response shows that the payload has been inserted into the CMDB IRE Partial Payloads [cmdb_ire_partial_payloads] table.

{
  "result": {
    "items": [{
      "className": "cmdb_ci_computer",
      "operation": "INSERT_AS_PARTIAL",
      "sysId": "Unknown",
      "partialSysIds": ["1aec79151bb45010593876a61a4bcb28"],
      "identifierEntrySysId": "Unknown",
      "errors": [],
      "warnings": [{
        "error": "MISSING_MATCHING_ATTRIBUTES",
        "message": "In payload missing minimum set of input values for criterion (matching) attributes from identify rule for table [cmdb_ci_hardware]. Add these input values in payload item '{\"className\":\"cmdb_ci_computer\",\"values\":{\"discovery_source\":\"ServiceNow\",\"company\":\"My Company\",\"cpu_core_count\":\"6\",\"ram\":\"8192\",\"manufacturer\":\"DELL\"},\"sys_object_source_info\":{\"source_name\":\"ServiceNow\",\"source_native_key\":\"ncomputer3367\"},\"settings\":{},\"sys_ire_info\":{\"ire_received_time\":\"2020-05-14 20:14:51\"}}'"
      }],
      "identificationAttempts": [{
        "info": "sys_object_source NO_MATCH",
        "identifierName": "",
        "attemptResult": "NO_MATCH",
        "attributes": [],
        "hybridEntryCiAttributes": []
      }, {
        "identifierName": "Hardware Rule",
        "attemptResult": "SKIPPED",
        "attributes": ["serial_number", "serial_number_type"],
        "searchOnTable": "cmdb_serial_number",
        "hybridEntryCiAttributes": []
      }, {
        "identifierName": "Hardware Rule",
        "attemptResult": "SKIPPED",
        "attributes": ["serial_number"],
        "searchOnTable": "cmdb_ci_hardware",
        "hybridEntryCiAttributes": []
      }, {
        "identifierName": "Hardware Rule",
        "attemptResult": "SKIPPED",
        "attributes": ["name"],
        "searchOnTable": "cmdb_ci_hardware",
        "hybridEntryCiAttributes": []
      }, {
        "identifierName": "Hardware Rule",
        "attemptResult": "SKIPPED",
        "attributes": ["mac_address", "name"],
        "searchOnTable": "cmdb_ci_network_adapter",
        "hybridEntryCiAttributes": []
      }],
      "errorCount": 0,
      "markers": [],
      "warningCount": 1,
      "mergedPayloadIds": ["7ddcb9551bb45010593876a61a4bcb08"],
      "inputIndices": [0]
    }],
    "additionalCommittedItems": [],
    "relations": [],
    "additionalCommittedRelations": []
  }
}

Submit a second partial payload that completes the description of the computer CI, with the summary generation Enhanced IRE option enabled.

curl "https://instance.servicenow.com/api/now/identifyreconcile/enhanced?options=generate_summary:true" \
--request POST \
--header "Accept: application/json" \
--header "Content-Type: application/json" \
--user "username":"password" \
--data '{ \
}'

The response shows that the computer CI is inserted, and displays a summary of operations performed.

{
  "result": {
    "relations": [],
    "hasError": false,
    "additionalCommittedItems": [],
    "hasWarning": false,
    "items": [
      {
        "relatedSysIds": [
          "735c79151bb45010593876a61a4bcb67"
        ],
        "identifierEntrySysId": "Unknown",
        "sysId": "ff5c79151bb45010593876a61a4bcb64",
        "errorCount": 0,
        "markers": [],
        "className": "cmdb_ci_computer",
        "inputIndices": [
          0
        ],
        "operation": "INSERT",
        "relatedItems": [
          {
            "operation": "INSERT",
            "warningCount": 0,
            "errors": [],
            "sysId": "735c79151bb45010593876a61a4bcb67",
            "className": "cmdb_ci_network_adapter",
            "errorCount": 0,
            "markers": [],
            "inputIndices": [
              {
                "subIndex": 0,
                "mainIndex": 0
              }
            ],
            "mergedPayloadIds": []
          }
        ],
        "mergedPayloadIds": [
          "fe4c39151bb45010593876a61a4bcbd3"
        ],
        "identificationAttempts": [
          {
            "info": "sys_object_source NO_MATCH",
            "attemptResult": "NO_MATCH",
            "identifierName": "",
            "attributes": [],
            "hybridEntryCiAttributes": []
          },
          {
            "attemptResult": "SKIPPED",
            "identifierName": "Hardware Rule",
            "attributes": [
              "serial_number",
              "serial_number_type"
            ],
            "hybridEntryCiAttributes": [],
            "searchOnTable": "cmdb_serial_number"
          },
          {
            "attemptResult": "SKIPPED",
            "identifierName": "Hardware Rule",
            "attributes": [
              "serial_number"
            ],
            "hybridEntryCiAttributes": [],
            "searchOnTable": "cmdb_ci_hardware"
          },
          {
            "attemptResult": "SKIPPED",
            "identifierName": "Hardware Rule",
            "attributes": [
              "name"
            ],
            "hybridEntryCiAttributes": [],
            "searchOnTable": "cmdb_ci_hardware"
          },
          {
            "attemptResult": "NO_MATCH",
            "identifierName": "Hardware Rule",
            "attributes": [
              "mac_address",
              "name"
            ],
            "hybridEntryCiAttributes": [],
            "searchOnTable": "cmdb_ci_network_adapter"
          }
        ],
        "warningCount": 0
      }
    ],
    "additionalCommittedRelations": [],
    "summary": {
      "cmdb_ci_network_adapter": {
        "mergedPartialPayloads": 0,
        "inserted": 1,
        "partial": 0,
        "warnings": 0,
        "incomplete": 0,
        "additionalInserted": 0,
        "unchanged": 0,
        "skipped": 0,
        "updated": 0,
        "errors": 0
      },
      "cmdb_ci_computer": {
        "mergedPartialPayloads": 1,
        "inserted": 1,
        "partial": 0,
        "warnings": 0,
        "incomplete": 0,
        "additionalInserted": 0,
        "unchanged": 0,
        "skipped": 0,
        "updated": 0,
        "errors": 0
      }
    }
  }
}

Identification and Reconciliation - POST /now/identifyreconcile/query

Determines the CMDB operation (insert/update) to perform with the specified payload (request body), without committing the operations in the database.

Use this endpoint to simulate submission of a payload (request body) to the Identification and Reconciliation - POST /now/identifyreconcile endpoint.

Use the Identification and Reconciliation - POST /now/identifyreconcile/enhanced endpoint instead if you need to specify Enhanced IRE options. For more on Enhanced IRE options, see Identification and Reconciliation engine (IRE).

URL format

Versioned URL: /api/now/{api_version}/identifyreconcile/query

Default URL: /api/now/identifyreconcile/query

Supported request parameters

Table 13. Path parameters
Name Description
api_version Optional. 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
Table 14. Query parameters
Name Description
sysparm_data_source Identifies the source of the CI information. This must be one of the choice values defined for the discovery_source field of the Configuration Item [cmdb_ci] table.

Data type: String

Default: Insert the API payload into the incomplete payloads table.

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.

Table 16. Request headers
Header Description
Accept Data format of the response body. Only supports application/json.
Content-Type Data format of the request body. Only supports application/json.
Table 17. Response headers
Header Description
None

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.

Table 18. Status codes
Status code Description
200 Successful. The request was successfully processed.
401 Unauthorized. The user credentials are incorrect or have not been passed.
500 Internal server error. An unexpected error occurred while processing the request. The response contains additional information about the error.

Response body parameters (JSON or XML)

Example: cURL request

Simulate submission of a payload containing a Linux server (with serial number and network adapter related-item lookups) and an IP switch, with an IP Connection relationship between them.

curl "https://instance.servicenow.com/api/now/identifyreconcile/query" \
--request POST \
--header "Accept: application/json" \
--header "Content-Type: application/json" \
--user "username":"password" \
--data '{ \
  "items": [{ \
    "className": "cmdb_ci_linux_server", \
    "values": { \
      "sys_class_name": "cmdb_ci_linux_server", \
      "name": "lnux101", \
      "host_name": "lnux101.servicenow.com", \
      "ip_address": "10.11.12.173", \
      "os_name": "Linux Red Hat" \
    }, \
    "lookup": [{ \
      "className": "cmdb_serial_number", \
      "values": { \
        "serial_number": "lnux101", \
        "serial_number_type": "uuid", \
        "valid": "true" \
      } \
    }, { \
      "className": "cmdb_ci_network_adapter", \
      "values": { \
        "name": "eth0", \
        "ip_address": "10.11.12.173", \
        "mac_address": "00:55:51:21:26:2f" \
      } \
    }] \
  }, { \
    "className": "cmdb_ci_ip_switch", \
    "values": { \
      "name": "IP-Switch-1", \
      "serial_number": "Switch23587", \
      "serial_number_type": "uuid" \
    } \
  }], \
  "relations": [{ \
    "parent": 0, \
    "child": 1, \
    "type": "IP Connection::IP Connection" \
  }] \
}'

The Linux server CI is identified via a Hardware Rule search for its name on the Hardware [cmdb_ci_hardware] table and is processed as an update to an existing CI in the Linux Server [cmdb_ci_linux_server] table. The IP switch is similarly identified via a Hardware Rule search for its name on the Hardware table and updates an existing CI in the IP Switch [cmdb_ci_ip_switch] table. Finally, the IP Connection relationship between the server and the switch is inserted as a new record in the CI Relationship [cmdb_rel_ci] table.

{
  "result": {
    "relations": [
      {
        "operation": "INSERT",
        "mergedPayloadIds": [],
        "className": "cmdb_rel_ci",
        "errorCount": 0,
        "markers": [],
        "inputIndices": [
          0
        ]
      }
    ],
    "items": [
      {
        "relatedSysIds": [
          null,
          null
        ],
        "identifierEntrySysId": "556eb250c3400200d8d4bea192d3ae92",
        "sysId": "539747cac0a801640163e60735fbbf6e",
        "errorCount": 0,
        "markers": [],
        "identificationAttempts": [
          {
            "attemptResult": "NO_MATCH",
            "identifierName": "Hardware Rule",
            "attributes": [
              "serial_number",
              "serial_number_type"
            ],
            "hybridEntryCiAttributes": [],
            "searchOnTable": "cmdb_serial_number"
          },
          {
            "attemptResult": "SKIPPED",
            "identifierName": "Hardware Rule",
            "attributes": [
              "serial_number"
            ],
            "hybridEntryCiAttributes": [],
            "searchOnTable": "cmdb_ci_hardware"
          },
          {
            "attemptResult": "MATCHED",
            "identifierName": "Hardware Rule",
            "attributes": [
              "name"
            ],
            "hybridEntryCiAttributes": [],
            "searchOnTable": "cmdb_ci_hardware"
          }
        ],
        "inputIndices": [
          0
        ],
        "additionalRelatedItems": [],
        "operation": "UPDATE",
        "relatedItems": [
          {
            "markers": [],
            "mergedPayloadIds": [],
            "inputIndices": [
              {
                "subIndex": 0,
                "mainIndex": 0
              }
            ],
            "className": "cmdb_serial_number"
          },
          {
            "markers": [],
            "mergedPayloadIds": [],
            "inputIndices": [
              {
                "subIndex": 1,
                "mainIndex": 0
              }
            ],
            "className": "cmdb_ci_network_adapter"
          }
        ],
        "mergedPayloadIds": [],
        "className": "cmdb_ci_linux_server"
      },
      {
        "operation": "UPDATE",
        "identifierEntrySysId": "556eb250c3400200d8d4bea192d3ae92",
        "mergedPayloadIds": [],
        "sysId": "304481257f701200bee45f19befa915b",
        "identificationAttempts": [
          {
            "attemptResult": "SKIPPED",
            "identifierName": "Hardware Rule",
            "attributes": [
              "serial_number",
              "serial_number_type"
            ],
            "hybridEntryCiAttributes": [],
            "searchOnTable": "cmdb_serial_number"
          },
          {
            "attemptResult": "NO_MATCH",
            "identifierName": "Hardware Rule",
            "attributes": [
              "serial_number"
            ],
            "hybridEntryCiAttributes": [],
            "searchOnTable": "cmdb_ci_hardware"
          },
          {
            "attemptResult": "MATCHED",
            "identifierName": "Hardware Rule",
            "attributes": [
              "name"
            ],
            "hybridEntryCiAttributes": [],
            "searchOnTable": "cmdb_ci_hardware"
          }
        ],
        "errorCount": 0,
        "markers": [],
        "className": "cmdb_ci_ip_switch",
        "inputIndices": [
          1
        ]
      }
    ],
    "additionalCommittedRelations": [],
    "additionalCommittedItems": []
  }
}

Identification and Reconciliation - POST /now/identifyreconcile/queryEnhanced

Determines the CMDB operation (insert/update) to perform with the specified payload (request body), without committing the operations in the database.

Use this endpoint to simulate submission of a payload (request body) to the Identification and Reconciliation - POST /now/identifyreconcile/enhanced endpoint.

This method is similar to the Identification and Reconciliation - POST /now/identifyreconcile/query method, but adds the following functionality:
  • Partial payloads
    • In case of an item having a warning or error, indicates if an item operation is INSERT_AS_PARTIAL or INSERT_INCOMPLETE.
    • Returns the sys_ids of partial payloads that were merged with existing partial payloads.
  • Supports payload deduplicate feature.
  • Generates a summary.

URL format

Versioned URL: /api/now/{api_version}/identifyreconcile/queryEnhanced

Default URL: /api/now/identifyreconcile/queryEnhanced

Supported request parameters

Table 19. Path parameters
Name Description
api_version Optional. 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
Table 20. Query parameters
Name Description
options Comma-separated list of name-value pairs representing Enhanced IRE options applied for the request.

As an example, to override the default values for the partial payloads, partial commits, deduplicate payloads, and generate summary Enhanced IRE options:

partial_payloads:false,partial_commits:false,deduplicate_payloads:false,generate_summary:true
Note: By default or if partial_payloads is set to true, both partial_commits and deduplicate_payloads are enabled, even if they are set to false, as those features are essential for partial payloads functionality.

For more on Enhanced IRE options, see Identification and Reconciliation engine (IRE).

Valid values for each name-value pair:
  • true: Enable this Enhanced IRE option.
  • false: Disable this Enhanced IRE option.

Data type: String
sysparm_data_source Identifies the source of the CI information. This must be one of the choice values defined for the discovery_source field of the Configuration Item [cmdb_ci] table.

Data type: String

Default: Insert the API payload into the incomplete payloads table.
Table 21. Request body parameters (XML or JSON)
NameDescription
items Array of objects in which each object describes a CI to create or update.

Data type: Array

"items": [
  {
    "className": "String",
    "internal_id": "String",
    "lookup": [Array],
    "related": [Array],
    "settings": {Object},
    "sys_object_source_info": {Object},
    "values": {Object}
  }
]
items.className Required. The sys_class_name (class/table name) of the CI to create or update. This value can be any CMDB table, such as cmdb_ci_linux_server or cmdb_ci_win_server.

Data type: String
items.internal_id Unique identifier for this item in this payload. Can be any value, but must be unique within the payload.

Data type: String
items.lookup Array of objects in which each object describes a lookup-based identification record. These records are used to identify the top-level configuration item based on a lookup table that has a reference back to the Configuration Item [cmdb_ci] table.

Data type: Array

"lookup": [
  {
    "className": "String",
    "internal_id": "String",
    "sys_object_source_info": {Object},
    "values": {Object}
  }
]
items.lookup.className Required. The sys_class_name or class/table name of the CI to create or update. This value can be any CMDB class/table, such as cmdb_serial_number or cmdb_ci_network_adapter, or a non-CMDB hierarchy class.

Data type: String
items.lookup.internal_id Unique identifier for this lookup record in this payload. Can be any value, but must be unique within the payload.

Data type: String
items.lookup.sys_object_source_info Object describing a unique CI identifier for a specified data source. Different sources may have different name-value pairs for the same CI.

Data type: Object

"sys_object_source_info": {
  "source_feed": "String",
  "source_name": "String",  
  "source_native_key": "String",
  "source_recency_timestamp": "String"
}
items.lookup.sys_object_source_info.source_feed Name that uniquely identifies the feed sending this CI. Use if the source can have multiple feeds.

Data type: String
items.lookup.sys_object_source_info.source_name Data source for the CI information. This value must be one of the choice values defined for the discovery_source field of the Configuration Item [cmdb_ci] table.

Data type: String
items.lookup.sys_object_source_info.source_native_key Unique key/id from the source for the CI. Can be any string that is unique to the item.

Data type: String
items.lookup.sys_object_source_info.source_recency_timestamp UTC date and time that the CI was scanned.

Data type: String

Format: YYYY-MM-DD hh:mm:ss
items.lookup.values Object describing fields for this lookup item as name/value pairs, where the name is the field name.

Data type: Object

Field names and types depend on the fields selected by the user, such as:

"values": {
  "ip_address": "String",
  "mac_address": "String",
  "serial_number": "String",
  "serial_number_type": "String",
  "valid": "String"
}
items.related Array of objects in which each object describes an item record to create or update, based on a related table that has a reference to the top-level CI that is being identified. Rules in the Related Entry [cmdb_related_entry] table define what type of records can be in this array.

The related table may or may not extend the Configuration Item [cmdb_ci] table. These records are not used to identify the configuration item.

Data type: Array

"related": [
  {
    "className": "String",
    "internal_id": "String",
    "sys_object_source_info": {Object},
    "values": {Object}
  }
]
items.related.className Required. The sys_class_name or class/table name of the related item to create or update.

Data type: String
items.related.internal_id Unique identifier for this related item in this payload. Can be any value, but must be unique within the payload.

Data type: String
items.related.sys_object_source_info Object describing a unique CI identifier for a specified data source. Different sources may have different name-value pairs for the same CI.

Data type: Object

"sys_object_source_info": {
  "source_feed": "String",
  "source_name": "String",  
  "source_native_key": "String",
  "source_recency_timestamp": "String"
}
items.related.sys_object_source_info.source_feed Name that uniquely identifies the feed sending this related item. Use if the source can have multiple feeds.

Data type: String
items.related.sys_object_source_info.source_name Data source for the related item information. This value must be one of the choice values defined for the discovery_source field of the Configuration Item [cmdb_ci] table.

Data type: String
items.related.sys_object_source_info.source_native_key Unique key/id from the source for the related item. Can be any string that is unique to the item.

Data type: String
items.related.sys_object_source_info.source_recency_timestamp UTC date and time that the related item was scanned.

Data type: String

Format: YYYY-MM-DD hh:mm:ss
items.related.values Object describing fields to create or update for this related item as name/value pairs, where the name is the field name. For a reference field, the value must be the referenced sys_id.

Data type: Object

Field names and types depend on the fields selected by the user, such as:

"values": {
  "host_name": "String",
  "ip_address": "String",
  "name": "String",
  "os_name": "String",
  "sys_class_name": "String"
}
items.settings Object containing parameters defining the types of updates that are permitted.

Data type: Object

"settings": {
  "skipReclassificationRestrictionRules": Boolean,
  "updateWithoutDowngrade": Boolean,
  "updateWithoutSwitch": Boolean,
  "updateWithoutUpgrade": Boolean
}
items.settings.skipReclassificationRestrictionRules Flag that indicates whether IRE should skip running the Reclassification Restriction rule that matches the class for the payload item.
Valid values:
  • true: Skip running the rule.
  • false: Run the rule.

Default: false
items.settings.updateWithoutDowngrade Indicates whether update and downgrade are both permitted for this CI.
Valid values:
  • true: Update the item but downgrade is not permitted.
  • false: Both item update and downgrade are permitted.

Data type: Boolean

Default: false
items.settings.updateWithoutSwitch Indicates whether this CI can be updated and its class switched.
Valid values:
  • true: Update the item but class switching is not permitted.
  • false: Both item update and class switching are permitted.

Data type: Boolean

Default: false
items.settings.updateWithoutUpgrade Indicates whether update and upgrade are both permitted for this CI.
Valid values:
  • true: Update the item but upgrade is not permitted.
  • false: Both item update and upgrade are permitted.

Data type: Boolean

Default: false
items.sys_object_source_info Object describing a unique CI identifier.

Data type: Object

"sys_object_source_info": {
  "source_feed": "String",
  "source_name": "String",  
  "source_native_key": "String",
  "source_recency_timestamp": "String"
}
items.sys_object_source_info.source_feed Name that uniquely identifies the feed sending this CI. Use if the source can have multiple feeds.

Data type: String
items.sys_object_source_info.source_name Data source for the CI information. This value must be one of the choice values defined for the discovery_source field of the Configuration Item [cmdb_ci] table.

Data type: String
items.sys_object_source_info.source_native_key Unique key/id from the source for the CI. Can be any string that is unique to the item.

Data type: String
items.sys_object_source_info.source_recency_timestamp UTC date and time that the CI was scanned.

Data type: String

Format: YYYY-MM-DD hh:mm:ss
items.values Object describing fields to create or update for this CI as name/value pairs, where the name is the field name. For a reference field, the value must be the referenced sys_id.

Data type: Object

Field names and types depend on the fields selected by the user, such as:

"values": {
  "host_name": "String",
  "ip_address": "String",
  "name": "String",
  "os_name": "String",
  "sys_class_name": "String"
}
referenceItems Array of objects in which each object describes a reference between two items in the payload.

Data type: Array

"referenceItems": [
  {
    "referenced": "String",
    "referencedBy": "String",
    "referenceField": "String"
  }
]
referenceItems.referenced The internal_id defined for the item being referenced by another item.

Data type: String
referenceItems.referencedBy The internal_id defined for the item that references another item.

Data type: String
referenceItems.referenceField Name of the reference field in the class/table for the referencedBy item.

Data type: String
relations Array of objects in which each object describes a relationship between two items defined in the payload.
An object in this array can use either of two formats:
  • The object can define a relationship between two top-level items (only) using parent and child name-value pairs, with values representing item indexes from the payload items array.
  • The object can define a relationship between any two items, including top-level, related, or lookup items, using parent_id and child_id key/value pairs, with values representing internal_id values defined for those items.

Data type: Array

"relations": [
  {
    "child": Number,
    "parent": Number,
    "sys_rel_source_info": {Object},
    "type": "String"
  }
]
"relations": [
  {
    "child_id": "String",
    "parent_id": "String",
    "sys_rel_source_info": {Object},
    "type": "String"
  }
]
relations.child The integer index of the CI object in the items array that represents the child in the relationship.

Data type: Number
relations.child_id The internal_id of the child item in the relationship.

Data type: String
relations.parent The integer index of the CI object in the items array that represents the parent in the relationship.

Data type: Number
relations.parent_id The internal_id of the parent item in the relationship.

Data type: String
relations.sys_rel_source_info Discovery source information for the relationship. For non-dependency relationships, this information is in the Relationship Sources [sys_rel_source] table.

Data type: Object

"sys_rel_source_info": { 
  "source_name": "String", 
  "source_feed": "String" 
}
relations.sys_rel_source_info.source_name Discovery source name.

Default: Discovery source passed in the API method parameter.
relations.sys_rel_source_info.source_feed Any string that is a sub-discovery/scan within the discovery source.

Default: ‘UNKNOWN’ is stored in the source_feed column when creating a record in sys_rel_source table.
relations.type The type of relationship existing between the parent and child items. This must be a name field value from the CI Relationship Type [cmdb_rel_type] table.

Data type: String

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.

Table 22. Request headers
Header Description
Accept Data format of the response body. Only supports application/json.
Content-Type Data format of the request body. Only supports application/json.
Table 23. Response headers
Header Description
None

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.

Table 24. Status codes
Status code Description
200 Successful. The request was successfully processed.
401 Unauthorized. The user credentials are incorrect or have not been passed.
500 Internal server error. An unexpected error occurred while processing the request.

Error message detail "Chunk […] is not a valid entry" indicates that the options query parameter is not in the correct name-value pair format.

For example, specifying an options parameter of partial produces a 500 status code with "Chunk [partial] is not a valid entry" in the message detail.

Response body parameters (JSON or XML)

NameDescription
result Array of results produced by the query.

Data type: Array

"result": [
  "additionalCommittedItems": [Array],
  "additionalCommittedRelations": [Array],
  "items": [Array],
  "relations": [Array]
]
result.additionalCommittedItems Array of objects in which each object describes a CI not included in the request body items array to insert or update.

Data type: Array

"additionalCommittedItems": [
  {
    "className": "String",
    "errorCount": Number,
    "identificationAttempts": [Array],
    "inputIndices": [Array],
    "markers": [Array],
    "mergedPayloads": [Array],
    "operation": "String",
    "sysId": "String"
  }
]
result.additionalCommittedItems.className The sys_class_name of this additional CI.

Data type: String
result.additionalCommittedItems.errorCount The number of errors encountered while processing this additional CI.

Data type: Number
result.additionalCommittedItems.errors Array of objects in which each object describes an error encountered while processing this additional CI.

Data type: Array

"errors": [
  {
    "error": "String",
    "message": "String"
  }
]
result.additionalCommittedItems.errors.error The type of error encountered while processing this additional CI.

Data type: String
result.additionalCommittedItems.errors.message The error message encountered while processing this additional CI.

Data type: String
result.additionalCommittedItems.identificationAttempts Array of objects in which each object describes an attempt made to identify this additional CI.
Data type: Array
"identificationAttempts": [
  {
    "attemptResult": "String",
    "attributes": [Array],
    "hybridEntryCiAttributes": [Array],
    "identiferName": "String",
    "searchOnTable": [Array]
  }
]
result.additionalCommittedItems.identificationAttempts.attemptResult The outcome of this additional CI identification attempt.
Possible values:
  • MATCHED: Identification succeeded. A unique CI was found in the identifier rule table which exactly matched the specified attributes.
  • MULTI_MATCH: Identification failed with an error. Duplicate CIs were found in the identifier rule table when matching against the specified attributes.
  • NO_MATCH: Identification failed. No CI was found in the identifier rule table which matched the specified attributes.
  • SKIPPED: Identification not attempted. The attributes required for this identifier rule table search were not provided, so the rule was not applied.

Data type: String
result.additionalCommittedItems.identificationAttempts.attributes Array of CI identifier entry attributes used during this additional CI identification attempt.

Data type: Array

Attribute names and types depend on the request body data and the identifier in use, such as:

"attributes": [
  "serial_number": "String",
  "serial_number_type": "String",
]
result.additionalCommittedItems.identificationAttempts.hybridEntryCiAttributes Array of CI identifier entry attributes used during this additional CI identification attempt.

Data type: Array

Attribute names and types depend on the request body data and the identifier in use, such as:

"hybridEntryCiAttributes": [
  "name": "String",
  "serial_number": "String"
]
result.additionalCommittedItems.identificationAttempts.identifierName The identifier rule used for this additional CI identification attempt.

Data type: String
result.additionalCommittedItems.identificationAttempts.searchOnTable The name of the table searched for this additional CI identification attempt.

Data type: String
result.additionalCommittedItems.identifierEntrySysId The sys_id for the identifier rule used to identify this additional CI.
Notable values:
  • Unknown: Identification of this additional CI failed. See errors for details.

Data type: String
result.additionalCommittedItems.inputIndices Array of index values for CIs from the request body items array that correspond to this additional CI.

Data type: Array

"inputIndices": [
  {
    Number
  }
]
result.additionalCommittedItems.markers Array of marker values for internal use.

Data type: Array

"markers": []
result.additionalCommittedItems.mergedPayloads Array of sys_id values for partial payloads from the CMDB IRE Partial Payloads [cmdb_ire_partial_payloads] table that were merged during processing of this additional CI.

Data type: Array

"mergedPayloadIds": [
  "String"
]
result.additionalCommittedItems.operation The operation performed for this additional CI.
Possible values:
  • DELETE: An existing CI is removed from the target table.
  • INSERT: The additional CI is inserted into the target table as a new record.
  • NO_CHANGE: No operation is performed for the additional CI.
  • UPDATE: An existing CI in the target table is updated.
  • UPDATE_WITH_DOWNGRADE: An existing CI in the target table is updated and its class is changed to a more generic class (ancestor class).
  • UPDATE_WITH_SWITCH: An existing CI in the target table is updated and its class is changed to another class which is not an ancestor or descendent class.
  • UPDATE_WITH_UPGRADE: An existing CI in the target table is updated and its class is changed to a more specialized class (descendent class).

Data type: String
result.additionalCommittedItems.sysId The sys_id found for this additional CI through identification.
Notable values:
  • Unknown: Identification of this additional CI failed. See errors for details.

Data type: String
result.additionalCommittedItems.warnings Array of objects in which each object describes a warning encountered while processing this additional CI.

Data type: Array

"warnings": [
  {
    "error": "String",
    "message": "String"
  }
]
result.additionalCommittedItems.warnings.error The type of warning encountered while processing this additional CI.

Data type: String
result.additionalCommittedItems.warnings.message The warning message encountered while processing this additional CI.

Data type: String
result.additionalCommittedRelations Array of objects in which each object describes a dependent relationship CI not included in the request body relations list to insert or update.

Data type: Array

"additionalCommittedRelations": [
  {
    "className": "String",
    "operation": "String",
    "markers": [Array],
    "inputIndices": [Array],
    "mergedPayloadIds": [Array]
  }
]
result.additionalCommittedRelations.className The sys_class_name of this additional dependent relationship CI.
Only supported value:
  • cmdb_rel_ci: The CI Relationship table.

Data type: String
result.additionalCommittedRelations.errorCount The number of errors encountered while processing this additional dependent relationship CI.

Data type: Number
result.additionalCommittedRelations.errors Array of objects in which each object describes an error encountered while processing this additional dependent relationship CI.

Data type: Array

"errors": [
  {
    "error": "String",
    "message": "String"
  }
]
result.additionalCommittedRelations.errors.error The type of error encountered while processing this additional dependent relationship CI.

Data type: String
result.additionalCommittedRelations.errors.message The error message encountered while processing this additional dependent relationship CI.

Data type: String
result.additionalCommittedRelations.inputIndices Array of index values for dependent relationship CI objects in the request body relations array that correspond to this additional dependent relationship CI.

Data type: Array

"inputIndices": [
  Number
]
result.additionalCommittedRelations.markers Array of marker values for internal use.

Data type: Array

"markers": []
result.additionalCommittedRelations.mergedPayloadIds Array of sys_id values for partial payloads from the CMDB IRE Partial Payloads [cmdb_ire_partial_payloads] table that were merged during processing of this additional dependent relationship CI.

Data type: Array

"mergedPayloadIds": [
  "String"
]
result.additionalCommittedRelations.operation The operation performed for this additional dependent relationship CI.
Possible values:
  • INSERT: The dependent relationship CI is inserted into the target table as a new record.
  • INSERT_AS_INCOMPLETE: The dependent relationship CI had errors and is inserted into the CMDB IRE Incomplete Payloads [cmdb_ire_incomplete_payloads] table.
  • INSERT_AS_PARTIAL: The dependent relationship CI had errors and is inserted into the CMDB IRE Partial Payloads [cmdb_ire_partial_payloads] table.
  • NO_CHANGE: No operation is performed for the dependent relationship CI.
  • UPDATE: An existing dependent relationship CI in the target table is updated.

Data type: String
result.items Array of objects in which each object describes a CI included in the request body items array.

Data type: Array

"items": [
  {
    "additionalRelatedItems": [Array],
    "className": "String",
    "duplicateLookupIndices": {Object},
    "errorCount": Number,
    "errors": [Array],
    "identificationAttempts": [Array],
    "identifierEntrySysId": "String",
    "info": [Array],
    "inputIndices": [Array],
    "markers": [Array],
    "mergedPayloadIds": [Array],
    "operation": "String",
    "relatedItems": [Array],
    "relatedSysIds": [Array],
    "sysId": "String",
    "warnings": [Array]
  }
]
result.items.additionalRelatedItems Array of objects in which each object describes a related CI (table lookup CI) from the CMDB IRE Partial Payloads [cmdb_ire_partial_payloads] table.

Data type: Array

"additionalRelatedItems": [
  {
    "className": "String",
    "inputIndices": [Array],
    "markers": [Array],
    "mergedPayloadIds": [Array],
    "sysId": "String"
  }
]
result.items.additionalRelatedItems.className The sys_class_name of the related item.

Data type: String
result.items.additionalRelatedItems.inputIndices Array of index values for CIs from the request body items array that correspond to this related item.

Data type: Array

"inputIndices": [
    Number
]
result.items.additionalRelatedItems.markers Array of marker values for internal use.

Data type: Array

"markers": []
result.items.additionalRelatedItems.mergedPayloadIds Array of sys_id values for partial payloads from the CMDB IRE Partial Payloads [cmdb_ire_partial_payloads] table that were merged during processing of this related item.

Data type: Array

"mergedPayloadIds": [
  "String"
]
result.items.additionalRelatedItems.sysId The sys_id of this related CI.

Data type: String
result.items.className The sys_class_name of this CI.

Data type: String
result.items.duplicateLookupIndices Object containing arrays of index values for items.lookup array elements that reference the same related CI.

The array name indicates the first element from the request body items.lookup array that references a given related CI. Its values are the set of additional elements from the same array that reference the same related CI.

Data type: Object

This example shows a case where the second element in the items.lookup array references the same related CI as a later element from that array:

"duplicateLookupIndices": [
  "2": [Array]
]
result.items.errorCount The number of errors encountered while processing this CI.

Data type: Number
result.items.errors Array of objects in which each object describes an error encountered while processing this CI.

Data type: Array

"errors": [
  {
    "error": "String",
    "message": "String"
  }
]
result.items.errors.error The type of error encountered while processing this CI.

Data type: String
result.items.errors.message The error message encountered while processing this CI.

Data type: String
result.items.identificationAttempts Array of objects in which each object describes an attempt made to identify this CI.
Data type: Array
"identificationAttempts": [
  {
    "attemptResult": "String",
    "attributes": [Array],
    "hybridEntryCiAttributes": [Array],
    "identiferName": "String",
    "searchOnTable": [Array]
  }
]
result.items.identificationAttempts.attemptResult The outcome of this CI identification attempt.
Possible values:
  • MATCHED: Identification succeeded. A unique CI was found in the identifier rule table which exactly matched the specified attributes.
  • MULTI_MATCH: Identification failed with an error. Duplicate CIs were found in the identifier rule table when matching against the specified attributes.
  • NO_MATCH: Identification failed. No CI was found in the identifier rule table which matched the specified attributes.
  • SKIPPED: Identification not attempted. The attributes required for this identifier rule table search were not provided, so the rule was not applied.

Data type: String
result.items.identificationAttempts.attributes Array of CI identifier entry attributes used during this CI identification attempt.

Data type: Array

Attribute names and types depend on the request body data and the identifier in use, such as:

"attributes": [
  "serial_number": "String",
  "serial_number_type": "String",
]
result.items.identificationAttempts.hybridEntryCiAttributes Array of CI identifier entry attributes used during this CI identification attempt.

Data type: Array

Attribute names and types depend on the request body data and the identifier in use, such as:

"hybridEntryCiAttributes": [
  "name": "String",
  "serial_number": "String"
]
result.items.identificationAttempts.identifierName The identifier rule used for this CI identification attempt.

Data type: String
result.items.identificationAttempts.searchOnTable The name of the table searched for this CI identification attempt.

Data type: String
result.items.identifierEntrySysId The sys_id for the identifier rule used to identify this CI.
Notable values:
  • Unknown: Identification of this CI failed. See errors for details.

Data type: String
result.items.info List of objects that contains additional information about the processing of the item.

Data type: Array

"info": [
  {
    "code": "String",
    "message": "String",
    "ruleSysId": "String"
  }
]
result.items.info.code Reclassification type that was skipped.
Possible values:
  • SKIPPED_CLASS_SWITCH
  • SKIPPED_CLASS_DOWNGRADE
  • SKIPPED_CLASS_UPGRADE
result.items.info.message Message that provides additional insights into the reason for skipping the reclassification.

Data type: String
result.items.info.ruleSysId Sys_id of the reclassification restriction rule that was matched. Applicable only when IRE skips reclassification due to reclassification restriction rule. This value is empty if the reclassification is skipped due to a payload or global flag.

Data type: String
result.items.inputIndices Array of index values for CIs from the request body items array that correspond to this CI.

Data type: Array

"inputIndices": [
  {
    Number
  }
]
result.items.markers Array of marker values for internal use.

Data type: Array

"markers": []
result.items.mergedPayloadIds Array of sys_id values for partial payloads from the CMDB IRE Partial Payloads [cmdb_ire_partial_payloads] table that were merged during processing of this CI.

Data type: Array

"mergedPayloadIds": [
  "String"
]
result.items.operation The operation performed for this CI.
Possible values:
  • DELETE: An existing CI is removed from the target table.
  • INSERT: The CI is inserted into the target table as a new record.
  • NO_CHANGE: No operation is performed for the CI.
  • UPDATE: An existing CI in the target table is updated.
  • UPDATE_WITH_DOWNGRADE: An existing CI in the target table is updated and its class is changed to a more generic class (ancestor class).
  • UPDATE_WITH_SWITCH: An existing CI in the target table is updated and its class is changed to another class which is not an ancestor or descendent class.
  • UPDATE_WITH_UPGRADE: An existing CI in the target table is updated and its class is changed to a more specialized class (descendent class).

Data type: String
result.items.relatedItems Array of objects in which each object describes a related CI (table lookup CI) from the request body items.lookup array.

Data type: Array

"relatedItems": [
  {
    "className": "String",
    "inputIndices": [Array],
    "markers": [Array],
    "mergedPayloadIds": [Array],
    "sysId": "String"
  }
]
result.items.relatedItems.className The sys_class_name of the related item.

Data type: String
result.items.relatedItems.inputIndices Array of index values for CIs and lookup items from the request body items and items.lookup arrays that correspond to this related item.

Data type: Array

"inputIndices": [
  {
    "mainIndex": Number,
    "subIndex": Number
  }
]
result.items.relatedItems.inputIndices.mainIndex Index value from the request body items array that corresponds to the CI parent of the related item.

Data type: Number
result.items.relatedItems.inputIndices.subIndex Index value from the request body items.lookup array that corresponds to the related item.

Data type: Number
result.items.relatedItems.markers Array of marker values for internal use.

Data type: Array

"markers": []
result.items.relatedItems.mergedPayloadIds Array of sys_id values for entries in the CMDB IRE Partial Payloads [cmdb_ire_partial_payloads] table that were merged into this CI during processing.

Data type: Array

"mergedPayloadIds": [
  "String"
]
result.items.relatedSysIds Array of sys_id values for related items (table lookup items) from the request body items.lookup array.

Data type: Array

Notable values:
  • null: No sys_id was identified for this related item.
"relatedSysIds": [
    Number,
    Number
]
result.items.sysId The sys_id found for this CI through identification.
Notable values:
  • Unknown: Identification of this CI failed. See errors for details.

Data type: String
result.items.warnings Array of objects in which each object describes a warning encountered while processing this CI.

Data type: Array

"warnings": [
  {
    "error": "String",
    "message": "String"
  }
]
result.items.warnings.error The type of warning encountered while processing this CI.

Data type: String
result.items.warnings.message The warning message encountered while processing this CI.

Data type: String
result.logContextId Context ID reported for this payload.

Data type: String
result.relations Array of objects in which each object describes a dependent relationship CI from the request body relations array.

Data type: Array

"relations": [
  {
    "className": "String",
    "errorCount": Number,
    "errors": [Array],
    "inputIndices": [Array],
    "markers": [Array],
    "mergedPayloadIds": [Array],
    "operation": "String",
    "warnings": [Array]
  }
]
result.relations.className The sys_class_name of this dependent relationship CI.
Only supported value:
  • cmdb_rel_ci: The CI Relationship table.

Data type: String
result.relations.errorCount The number of errors encountered while processing this dependent relationship CI.

Data type: Number
result.relations.errors Array of objects in which each object describes an error encountered while processing this dependent relationship CI.

Data type: Array

"errors": [
  {
    "error": "String",
    "message": "String"
  }
]
result.relations.errors.error The type of error encountered while processing this dependent relationship CI.

Data type: String
result.relations.errors.message The error message encountered while processing this dependent relationship CI.

Data type: String
result.relations.inputIndices Array of index values for the dependent relationship CI objects in the request body relations array that correspond to this dependent relationship CI.

Data type: Array

"inputIndices": [
  Number
]
result.relations.markers Array of marker values for internal use.

Data type: Array

"markers": []
result.relations.mergedPayloadIds Array of sys_id values for partial payloads from the CMDB IRE Partial Payloads [cmdb_ire_partial_payloads] table that were merged during processing of this dependent relationship CI.

Data type: Array

"mergedPayloadIds": [
  "String"
]
result.relations.operation The operation performed for this dependent relationship CI.
Possible values:
  • INSERT: The dependent relationship CI was inserted into the target table as a new record.
  • INSERT_AS_INCOMPLETE: The dependent relationship CI had errors and was inserted into the CMDB IRE Incomplete Payloads [cmdb_ire_incomplete_payloads] table.
  • INSERT_AS_PARTIAL: The dependent relationship CI had errors and was inserted into the CMDB IRE Partial Payloads [cmdb_ire_partial_payloads] table.
  • NO_CHANGE: No operation was performed for the dependent relationship CI.
  • UPDATE: An existing dependent relationship CI in the target table was updated.

Data type: String
result.relations.warnings Array of objects in which each object describes a warning encountered while processing this dependent relationship CI.

Data type: Array

"warnings": [
  {
    "error": "String",
    "message": "String"
  }
]
result.relations.warnings.error The type of warning encountered while processing this dependent relationship CI.

Data type: String
result.relations.warnings.message The warning message encountered while processing this dependent relationship CI.

Data type: String

Example: cURL request

Simulate submission of a partial payload for a computer CI.

curl "https://instance.servicenow.com/api/now/identifyreconcile/queryEnhanced" \
--request POST \
--header "Accept: application/json" \
--header "Content-Type: application/json" \
--user "username":"password" \
--data '{ \
  "items" : [ \
    { \
      "className" : "cmdb_ci_computer", \
      "sys_object_source_info" : { \
        "source_name" : "ServiceNow", \
        "source_native_key" : "ncomputer3367" \
      }, \
      "values" : { \
        "cpu_core_count" : "6", \
        "ram" : "8192", \
        "manufacturer" : "DELL", \
        "company" : "My Company" \
      } \
    } \
  ] \
}'

The response shows that the payload would be inserted into the CMDB IRE Partial Payloads [cmdb_ire_partial_payloads] table.

{
  "result": {
    "relations": [],
    "items": [
      {
        "identifierEntrySysId": "Unknown",
        "partialSysIds": [
          "1aec79151bb45010593876a61a4bcb28"
        ],
        "sysId": "Unknown",
        "errorCount": 0,
        "markers": [],
        "className": "cmdb_ci_computer",
        "inputIndices": [
          0
        ],
        "operation": "INSERT_AS_PARTIAL",
        "errors": [],
        "identificationAttempts": [
          {
            "info": "sys_object_source NO_MATCH",
            "attemptResult": "NO_MATCH",
            "identifierName": "",
            "attributes": [],
            "hybridEntryCiAttributes": []
          },
          {
            "attemptResult": "SKIPPED",
            "identifierName": "Hardware Rule",
            "attributes": [
              "serial_number",
              "serial_number_type"
            ],
            "hybridEntryCiAttributes": [],
            "searchOnTable": "cmdb_serial_number"
          },
          {
            "attemptResult": "SKIPPED",
            "identifierName": "Hardware Rule",
            "attributes": [
              "serial_number"
            ],
            "hybridEntryCiAttributes": [],
            "searchOnTable": "cmdb_ci_hardware"
          },
          {
            "attemptResult": "SKIPPED",
            "identifierName": "Hardware Rule",
            "attributes": [
              "name"
            ],
            "hybridEntryCiAttributes": [],
            "searchOnTable": "cmdb_ci_hardware"
          },
          {
            "attemptResult": "SKIPPED",
            "identifierName": "Hardware Rule",
            "attributes": [
              "mac_address",
              "name"
            ],
            "hybridEntryCiAttributes": [],
            "searchOnTable": "cmdb_ci_network_adapter"
          }
        ],
        "warningCount": 1,
        "warnings": [
          {
            "message": "In payload missing minimum set of input values for criterion (matching) attributes from identify rule for table [cmdb_ci_hardware]. Add these input values in payload item '{\"className\":\"cmdb_ci_computer\",\"values\":{\"discovery_source\":\"ServiceNow\",\"company\":\"My Company\",\"cpu_core_count\":\"6\",\"ram\":\"8192\",\"manufacturer\":\"DELL\"},\"sys_object_source_info\":{\"source_name\":\"ServiceNow\",\"source_native_key\":\"ncomputer3367\"},\"settings\":{},\"sys_ire_info\":{\"ire_received_time\":\"2020-05-14 20:14:51\"}}'",
            "error": "MISSING_MATCHING_ATTRIBUTES"
          }
        ],
        "mergedPayloadIds": [
          "7ddcb9551bb45010593876a61a4bcb08"
        ]
      }
    ],
    "additionalCommittedRelations": [],
    "additionalCommittedItems": []
  }
}

Simulate submission of a second partial payload that would complete the description of the computer CI, with the summary generation Enhanced IRE option enabled.

curl "https://instance.servicenow.com/api/now/identifyreconcile/queryEnhanced?options=generate_summary:true" \
--request POST \
--header "Accept: application/json" \
--header "Content-Type: application/json" \
--user "username:password" \
--data '{ \
}'

The response shows that the computer CI would be inserted, and displays a summary of operations that would be performed.

{
  "result": {
    "relations": [],
    "hasError": false,
    "additionalCommittedItems": [],
    "hasWarning": false,
    "items": [
      {
        "relatedSysIds": [
          "735c79151bb45010593876a61a4bcb67"
        ],
        "identifierEntrySysId": "Unknown",
        "sysId": "ff5c79151bb45010593876a61a4bcb64",
        "errorCount": 0,
        "markers": [],
        "className": "cmdb_ci_computer",
        "inputIndices": [
          0
        ],
        "operation": "INSERT",
        "relatedItems": [
          {
            "operation": "INSERT",
            "warningCount": 0,
            "errors": [],
            "sysId": "735c79151bb45010593876a61a4bcb67",
            "className": "cmdb_ci_network_adapter",
            "errorCount": 0,
            "markers": [],
            "inputIndices": [
              {
                "subIndex": 0,
                "mainIndex": 0
              }
            ],
            "mergedPayloadIds": []
          }
        ],
        "mergedPayloadIds": [
          "fe4c39151bb45010593876a61a4bcbd3"
        ],
        "identificationAttempts": [
          {
            "info": "sys_object_source NO_MATCH",
            "attemptResult": "NO_MATCH",
            "identifierName": "",
            "attributes": [],
            "hybridEntryCiAttributes": []
          },
          {
            "attemptResult": "SKIPPED",
            "identifierName": "Hardware Rule",
            "attributes": [
              "serial_number",
              "serial_number_type"
            ],
            "hybridEntryCiAttributes": [],
            "searchOnTable": "cmdb_serial_number"
          },
          {
            "attemptResult": "SKIPPED",
            "identifierName": "Hardware Rule",
            "attributes": [
              "serial_number"
            ],
            "hybridEntryCiAttributes": [],
            "searchOnTable": "cmdb_ci_hardware"
          },
          {
            "attemptResult": "SKIPPED",
            "identifierName": "Hardware Rule",
            "attributes": [
              "name"
            ],
            "hybridEntryCiAttributes": [],
            "searchOnTable": "cmdb_ci_hardware"
          },
          {
            "attemptResult": "NO_MATCH",
            "identifierName": "Hardware Rule",
            "attributes": [
              "mac_address",
              "name"
            ],
            "hybridEntryCiAttributes": [],
            "searchOnTable": "cmdb_ci_network_adapter"
          }
        ],
        "warningCount": 0
      }
    ],
    "additionalCommittedRelations": [],
    "summary": {
      "cmdb_ci_network_adapter": {
        "mergedPartialPayloads": 0,
        "inserted": 1,
        "partial": 0,
        "warnings": 0,
        "incomplete": 0,
        "additionalInserted": 0,
        "unchanged": 0,
        "skipped": 0,
        "updated": 0,
        "errors": 0
      },
      "cmdb_ci_computer": {
        "mergedPartialPayloads": 1,
        "inserted": 1,
        "partial": 0,
        "warnings": 0,
        "incomplete": 0,
        "additionalInserted": 0,
        "unchanged": 0,
        "skipped": 0,
        "updated": 0,
        "errors": 0
      }
    }
  }
}