Upsert Configuration Items

Submit a bulk operation to create or update one or more configuration items (CIs).

Special Access Rules

To upsert configuration items, you must have the following user permissions:

IT Service Configuration Item Type Manager
IT Service Configuration Item Owner

See Also

Request

JSON example

This example shows a sample request to upsert configuration items in bulk, including parent and relationship details.

1mutation UpsertConfigurationItems {
2  upsertConfigurationItems(
3    input: {
4      configurationItemRecords: [
5        {
6          cnfgItemTypeDeveloperName: "F5LoadBalancer"
7          parentCnfgItemId: "6780001"
8          relationshipType: "runs_on"
9          SD_AsNa: "LB-PROD-F5-01"
10          SD_St: "Active"
11          SD_IpAd: "10.0.2.10"
12          cnfgItemTags: [
13            {
14              key: "abcdef"
15              value: "checking"
16            }
17          ]
18        }
19      ]
20    }
21  ) {
22    id
23    status
24    lastModifiedOn
25    details
26    totalRecordCount
27    successRecordCount
28    failureRecordCount
29  }
30}

Properties

Name	Type	Description	Required or Optional	Available Version
`configurationItemRecords`	ConfigurationItemRecords	An object that contains the payload array containing one or more configuration item objects.	Required	67.0

ConfigurationItemRecords Input

Defines the structure for a single configuration item within the mutation payload.

Name	Type	Description	Required or Optional	Available Version
`cnfgItemTypeDevelopername`	String	The developer namer of the configuration item type.	Required	67.0
`parentCnfgItemId`	String	The ID of the parent configuration item for which a component configuration item is created.	Optional	67.0
`relationshipType`	String	Developer name of the CI Relationship.	Optional	67.0
`cnfgItemTags`	CnfgItemTags[]	Tags to assign to the configuration item.	Optional	67.0
`discoverySourceDeveloperName`	String	The discovery source developer name.	Optional	67.0

CnfgItemTags

Configuration item tags to associate with the configuration item.

Field	Type	Description	Available Version
`key`	BigInteger	The tag key name.	67.0
`value`	String	The tag value.	67.0

Response

JSON example

This example is a sample response from the uupsertConfigurationItemspsertCI mutation.

1{
2  "data": {
3    "upsertConfigurationItems": {
4      "id": 108,
5      "status": "Processing",
6      "lastModifiedOn": "2025-11-14T10:15:00.123456Z",
7      "details": "Job queued - Upsert CI - Canonical API (1 items)",
8      "totalRecordCount": 100,
9      "successRecordCount": 90,
10      "failureRecordCount": 10
11    }
12  }
13}

Properties

Name	Type	Description	Available Version
`id`	Integer	The unique identifier of the asynchronous job. Use this ID with the `getStatus` query to check the operation progress.	67.0
`status`	String	The initial status of the asynchronous job.	67.0
`lastModifiedOn`	String	The date and time when the job was last modified. Valid format: `YYYY-MM-DDTHH:MM:SSZ`.	67.0
`details`	String	A message indicating the job has been queued and is being processed.	67.0
`totalRecordCount`	Integer	The total records in the request.	67.0
`successRecordCount`	Integer	The total records processed successfully.	67.0
`failureRecordCount`	Integer	The total records that failed.	67.0

After submitting the upsertConfigurationItems mutation, use the returned job id with the getOperationStatus query to check the operation progress and completion status.
When using the uupsertConfigurationItemspsertCI operation, you can request any available attribute to be included in the response. The attributes you can include:
- Standard Attributes—Attributes are available out-of-the-box.
- Custom Attributes—Create and include custom attributes using the sObject API.
Add any attribute using its Developer Name. For example, SD_AsNa—Asset Name to specify exactly which information you want to receive for your Configuration Items (CIs).

Note