Install Base Item API

The Install Base Item API provides endpoints to access and manage install base items records within a ServiceNow instance.

An install base item represents an instance of a product that has been configured for a customer. Install base items enable you to track all purchases made by a customer.

You can also perform CRUD operations on the Install Base Related Parties related list using this API. In addition, you can read records in other install base items related lists, such as cases, contracts, entitlements, maintenance plans, sold products, and work orders.

To access this API you must have either the sn_install_base.ib_api_write or sn_install_base.ib_api_read role depending on the type of CRUD action that you are trying to perform.

To access the various endpoints in this API the following plugins must be installed:

Customer Service Install Base Management (com.snc.install_base)
Planned Work Management (sn_fsm_planned_wm) if you want to retrieve maintenance plan and work order data.

This API runs in the sn_install_base namespace.

Note: This API only returns non-empty fields in the endpoint responses. Also, none of the system level fields (those prefaced with "sys_") are returned except the sys_id field.

For additional information on install base items, see Create an install base item.

Parent Topic:REST API reference

Disassociates a specified related parties record from a specified install base item record.

URL format

Versioned URL: /api/sn_install_base/{api_version}/integrations/installbaseitems/{id}/relatedparties/{related_party_sys_id}

Default URL: /api/sn_install_base/integrations/installbaseitems/{id}/relatedparties/{related_party_sys_id}

Note: Available versions are specified in the REST API Explorer. For scripted REST APIs there is additional version information on the Scripted REST Service form.

Supported request 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

Sys_id of the install base item record.Data type: String

Table: Install Base Item [sn_install_base_item]

related_party_sys_id

Sys_id of the related party record.Data type: String

Table: Install Base Related Party [sn_install_base_related_party]

|Name|Description| |----|-----------| |None| |

Name	Description
None

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.

Header	Description
Accept	Data format of the response body. Supported types: application/json or application/xml. Default: application/json

|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.

Status code	Description
200	Successful. The request was successfully processed.
403	Forbidden. The user doesn't have access rights to the specified record.
404	Not found. The requested item wasn't found.
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)

Name	Description
error	Details about the error that occurred when trying to process the request.Data type: Object Text `"error": { "detail": "String", "message": "String"}`
error.detail	Additional details about the associated error.Data type: String
error.message	Error message that describes the problem that occurred when trying to execute the request.Data type: String
result	Description of the endpoint results.Data type: Object
result.status	Status of the endpoint request. Possible values: SUCCESS FAILURE Data type: String

### cURL request

The following code example shows how to call this endpoint.

Shell

curl "https://instance.servicenow.com/api/sn_install_base/integrations/installbaseitems/f77c7542b7343300ece839a6ee11a991/relatedparties/2a42dfae872521100b6afc86dabb356b" \--request DELETE \--header "Accept:application/json" \--user 'username':'password'

Return results:

JSON

{  "result": {    "status": "SUCCESS"  }}

Install Base Item - GET /sn_install_base/integrations/installbaseitems

Returns all install base items. You can pass parameters within the call to filter the return results.

URL format

Versioned URL: /api/sn_install_base/{api_version}/integrations/installbaseitems

Default URL: /api/sn_install_base/integrations/installbaseitems

Note: Available versions are specified in the REST API Explorer. For scripted REST APIs there is additional version information on the Scripted REST Service form.

Supported request 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

Name	Description
field name-value pairs	Field-value pairs to use to filter the install base item records. If you specify a different table in sys_class_name, then specify the fields in that table.You can pass one or more field-value pairs to filter the return results. For example, to return only records where the state field is set to "in_use" and the status field is set to "replacement", pass the follow: `&state=in_use&status=replacement`. Data type: String Default: All fields Table: Install Base Item [sn_istall_base_item]
related_party	Sys_id of a related party record.Filters the install base item records based on the specified related party. A related party can be linked to an install base item or a sold product. Valid values: account sys_id: Located in the Account [customer_account] table. consumer sys_id: Located in the Consumer [csm_consumer] table. contact sys_id: Located in the Contact [customer-contact] table. service organization sys_id: Located in the Service Organization [sn_customer_service_organization] table. user sys_id: Located in the User [sys-user] table. Data type: String Table: Install Base Related Party [sn_install_base_related_party]
responsibility	Sys_id of the associated responsibility record. This record defines the access level for the install base information.This parameter is only valid if the related_party field is also specified. If specified, it only returns the install base items that match both the related_party and responsibility parameters. For additional information, see Configure related parties for Items Received. Data type: String
sys_class_name	If the desired records are in a table that extends the Install Base Items [sn_install_base_item] table, the name of the extended table to query.Data type: String
sysparm_limit	Maximum number of records to return. For requests that exceed this number of records, use the sysparm_offset parameter to paginate record retrieval. This limit is applied before ACL evaluation. If no records return, including records you have access to, rearrange the record order so records you have access to return first. Note: Unusually large sysparm_limit values can impact system performance. Data type: Number Default: 10000
sysparm_offset	Starting record index for which to begin retrieving records. Use this value to paginate record retrieval. This functionality enables the retrieval of all records, regardless of the number of records, in small manageable chunks. For example, the first time you call this endpoint, sysparm_offset is set to "0". To simply page through all available records, use `sysparm_offset=sysparm_offset+sysparm_limit`, until you reach the end of all records. Don't pass a negative number in the sysparm_offset parameter.Data type: Number Default: 0

|Name|Description| |----|-----------| |None| |

Headers

Header	Description
Accept	Data format of the response body. Supported types: application/json or application/xml. Default: application/json

|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.

Status code	Description
200	Successful. The request was successfully processed.
400	Bad Request. A bad request type or malformed request was detected.
403	Forbidden. The user doesn't have access rights to the specified record.
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)

The following return results only describe the return values for records returned from the Install Base Items [sn_install_base_items] table.

Name	Description
error	Details about the error that occurred when trying to process the request.Data type: Object Text `"error": { "detail": "String", "message": "String"}`
error.detail	Additional details about the associated error.Data type: String
error.message	Error message that describes the problem that occurred when trying to execute the request.Data type: String
has_more	Flag that indicates whether there are more records in the table to return.Possible values: true: More records to return. false: No more records to return. Data type: Boolean string
items	List of the install base items that matched the specified filter results.Data type: Array of Objects CSS "items":[ { "account": {Object}, "active": "String", "asset": {Object}, "configuration_item": {Object}, "consumer": {Object}, "consumer_profile": {Object}, "contact": {Object}, "health_status": {Object}, "health_status_last_updated": "String", "household": {Object}, "install_date": {Object}, "location": {Object}, "name": "String", "number": "String", "parent": {Object}, "product": {Object}, "service_context": {Object}, "service_organization" {Object}, "sys_class_name": "String", "sys_id": "String", "sys_mod_count": "String", "state": {Object}, "status": {Object}, "uninstall_date": "String" }]
items.account	Details about the customer account associated with the install base item record.Data type: Object Text `"account": { "display_value": "String", "sys_id": "String"}`
items.account.display_value	Text name of the customer account associated with the install base item record. Use this value to display the customer account name in the UI.Data type: String
items.account.sys_id	Sys_id of the customer account record associated with the install base item record.Data type: String
items.active	Flag that indicates whether the install base item is active.Possible values: true: Install base item is active. false: Install base item is inactive. Data type: Boolean String
items.asset	Details about the asset associated with the install base item record.Data type: Object Text `"asset": { "display_value": "String", "sys_id": "String"}`
items.asset.display_value	Text name of the asset associated with the install base item record. Use this value to display the asset name in the UI.Data type: String
items.asset.sys_id	Sys_id of the asset record associated with the install base item record.Data type: String
items.configuration_item	Details about the configuration item associated with the install base item record.Data type: Object Text `"configuration_item": { "display_value": "String", "sys_id": "String"}`
items.configuration_item.display_value	Text name of the configuration item associated with the install base item record. Use this value to display the configuration item name in the UI.Data type: String
items.configuration_item.sys_id	Sys_id of the configuration item record associated with the install base item record.Data type: String
items.consumer	Details about the consumer associated with the install base item record.Note: The consumer field is only available if the B2B2C plugin is installed. Data type: Object Text `"consumer": { "display_value": "String", "sys_id": "String"}`
items.consumer.display_value	Text name of the consumer associated with the install base item record. Use this value to display the consumer name in the UI.Data type: String
items.consumer.sys_id	Sys_id of the consumer record associated with the install base item record.Data type: String
items.consumer_profile	Details about the consumer profile associated with the install base item record.Note: The consumer profile field is only available if the B2B2C plugin is installed. Data type: Object Text `"consumer_profile": { "display_value": "String", "sys_id": "String"}`
items.consumer_profile.display_value	Text name of the consumer profile associated with the install base item record. Use this value to display the consumer profile name in the UI.Data type: String
items.consumer_profile.sys_id	Sys_id of the consumer profile record associated with the install base item record.Data type: String
items.contact	Details about the account contact responsible for the install base item record.Data type: Object Text `"contact": { "display_value": "String", "sys_id": "String"}`
items.contact.display_value	Text name of the account contact associated with the install base item record. Use this value to display the account contact name in the UI.Data type: String
items.contact.sys_id	Sys_id of the account contact record associated with the install base item record.Data type: String
items.health_status	Details about the current health status of the install base item. Only returned if the Proactive Customer Service Operations (com.snc.proactive_cs_itom) plugin is installed.Data type: Object Text `"health_status": { "display_value": "String", "value": "String"}`
items.health_status.display_value	Text string of the current health status of the install base item. Use this value to display the health status in the UI.Data type: String
items.health_status.value	Internal value of the health status of the install base item.Data type: String
items.health_status_last_updated	Date and time when the health status was last updated for the install base item.Data type: String
items.household	Details about the household associated with the install base item record. Only returned if the Customer Household Data Model (com.snc.household) plugin is installed.Data type: Object Text `"household": { "display_value": "String", "sys_id": "String"}`
items.household.display_value	Text name of the household associated with the install base item record. Use this value to display the household name in the UI.Data type: String
items.household.sys_id	Sys_id of the household associated with the install base item record.Data type: String
items.install_date	Details about the date when the install base item became active.Data type: Object Text `"install_date": { "display_value": "String", "value": "String"}`
items.install_date.display_value	Text install date. Use this value to display the install date in the UI.Data type: String
items.install_date.value	Internal value of the install date.Data type: String
items.location	Details about the location of the install base item.Data type: Object Text `"location": { "display_value": "String", "sys_id": "String"}`
items.location.display_value	Text name of the install base item location. Use this value to display the location name in the UI.Data type: String
items.location.sys_id	Sys_id of the location record associated with the install base item record.Data type: String
items.name	Name of the install base item.Data type: String
items.number	Unique ID of the install base item.Data type: String
items.parent	Details about the parent record of the install base item record.Data type: Object Text `"parent": { "display_value": "String", "sys_id": "String"}`
items.parent.display_value	Text name of the parent record associated with the install base item record. Use this value to display the parent name in the UI.Data type: String
items.parent.sys_id	Sys_id of the parent record associated with the install base item record.Data type: String
items.product	Details about the product model associated with the install base item record. Use this information to identify the services associated with any product model.Data type: Object Text `"product": { "display_value": "String", "sys_id": "String"}`
items.product.display_value	Text name of the product model associated with the install base item record. Use this value to display the product name in the UI.Data type: String
items.product.sys_id	Sys_id of the product model record associated with the install base item record.Data type: String
items.service_context	Details about the service context associated with the install base item record.Data type: Object Text `"service_context": { "display_value": "String", "sys_id": "String"}`
items.service_context.display_value	Text name of the service context associated with the install base item record. Use this value to display the service context name in the UI.Data type: String
items.service_context.sys_id	Sys_id of the service context record associated with the install base item record.Data type: String
items.service_organization	Details about the service organization associated with the install base item record. Only returned if the Service Organization (com.snc.service_organization) plugin is installed.Data type: Object Text `"service_organization": { "display_value": "String", "sys_id": "String"}`
items.service_organization.display_value	Text name of the service organization associated with the install base item record. Use this value to display the service organization name in the UI.Data type: String
items.service_organization.sys_id	Sys_id of the service organization record associated with the install base item record.Data type: String
items.sys_class_name	Table containing the install base item record.Data type: String
items.sys_id	Sys_id of the install base item record. Located in the table specified in the sys_class_name parameter.Data type: String
items.sys_mod_count	Number of times that the associated install base item record has been modified.Data type: String
items.state	Details about the current state of the install base item.Data type: Object Text `"state": { "display_value": "String", "value": "String"}`
items.state.display_value	Text string of the current state of the install base item. Use this value to display the state in the UI.Data type: String
items.state.value	Internal value of the state of the install base item.Data type: String
items.status	Details about the status of the install base item.Data type: Object Text `"status": { "display_value": "String", "value": "String"}`
items.status.display_value	Text string of the status of the install base item. Use this value to display the status in the UI.Data type: String
items.status.value	Internal value of the status of the install base item.Data type: String
items.uninstall_date	Details about the date when the install base item became inactive.Data type: Object Text `"uninstall_date": { "display_value": "String", "value": "String"}`
items.uninstall_date.display_value	Text uninstall date. Use this value to display the uninstall date in the UI.Data type: String
items.uninstall_date.value	Internal value of the uninstall date.Data type: String
status	Status of the endpoint call.Data type: String
sysparm_depth	Number of levels deep the returned child install base item is in the hierarchy.Data type: Integer
sysparm_limit	Number of records that were returned. If this value isn't specified in the original request, it uses the default value.Data type: Number
sysparm_offset	Offset (starting point) in the associated table from which records were evaluated and retrieved.Data type: String

### cURL request

The following code example shows a simple call that only returns a single record starting at offset 5.

Shell

curl "https://instance.servicenow.com/api/sn_install_base/v1/integrations/installbaseitems?sysparm_limit=1&sysparm_offset=5" \--request GET \--header "Accept:application/json" \--user 'username':'password'

Return results:

JSON

{  "result": {    "sysparm_offset": "5",    "sysparm_limit": 1,    "has_more": true,    "items": [      {        "sys_class_name": "sn_install_base_item",        "number": "IBITM001100",        "sys_id": "181df7ff530a1110539dddeeff7b12f4",        "state": {          "value": "in_use",          "display_value": "In Use"        },        "sys_mod_count": "2",        "active": "true",        "configuration_item": {          "sys_id": "62446ae8535e5510539dddeeff7b12db",          "display_value": "boxeoproderp"        },        "name": "boxeoproderp",        "account": {          "sys_id": "86837a386f0331003b3c498f5d3ee4ca",          "display_value": "Boxeo"        }      }    ],    "status": "SUCCESS"  }}

cURL request

The following code example shows how to search for the fields state = "in_use" and status = "replacement" within the Install Base Item table.

Shell

curl "https://instance.servicenow.com/api/sn_install_base/integrations/installbaseitems?state=in_use&status=replacement" \--request GET \--header "Accept:application/json" \--user 'username':'password'

Return results:

JSON

{  "result": {    "sysparm_offset": "0",    "sysparm_limit": "10",    "has_more": false,    "items": [      {        "parent": {          "sys_id": "ffd023f453de9910539dddeeff7b1264",          "display_value": "Point of Sale System"        },        "sys_class_name": "sn_install_base_item",        "number": "IBITM001140",        "sys_id": "a1a123745312d910539dddeeff7b127b",        "state": {          "value": "in_use",          "display_value": "In Use"        },        "install_date": {          "value": "2018-12-14 07:00:00",          "display_value": "2018-12-13 23:00:00"        },        "product": {          "sys_id": "2dd1e7b753421110539dddeeff7b12d1",          "display_value": "Stand"        },        "active": "true",        "name": "Stand",        "service_organization": {          "sys_id": "42b51f5ab3401010700b4d43c6a8dc5a",          "display_value": "LA City Center - West"        },        "status": {          "value": "replacement",          "display_value": "Replacement"        }      },      {        "parent": {          "sys_id": "ffd023f453de9910539dddeeff7b1264",          "display_value": "Point of Sale System"        },        "sys_class_name": "sn_install_base_item",        "number": "IBITM001139",        "sys_id": "d0916bb05312d910539dddeeff7b1232",        "state": {          "value": "in_use",          "display_value": "In Use"        },        "install_date": {          "value": "2018-12-14 07:00:00",          "display_value": "2018-12-13 23:00:00"        },        "product": {          "sys_id": "dfc127b753421110539dddeeff7b12ac",          "display_value": "Register"        },        "active": "true",        "name": "Register",        "service_organization": {          "sys_id": "42b51f5ab3401010700b4d43c6a8dc5a",          "display_value": "LA City Center - West"        },        "status": {          "value": "replacement",          "display_value": "Replacement"        }      },      {        "parent": {          "sys_id": "ffd023f453de9910539dddeeff7b1264",          "display_value": "Point of Sale System"        },        "sys_class_name": "sn_install_base_item",        "number": "IBITM001141",        "sys_id": "ffb123745312d910539dddeeff7b12cb",        "state": {          "value": "in_use",          "display_value": "In Use"        },        "install_date": {          "value": "2018-12-14 07:00:00",          "display_value": "2018-12-13 23:00:00"        },        "product": {          "sys_id": "59e1e7b753421110539dddeeff7b12cc",          "display_value": "Terminal"        },        "active": "true",        "name": "Terminal",        "service_organization": {          "sys_id": "42b51f5ab3401010700b4d43c6a8dc5a",          "display_value": "LA City Center - West"        },        "status": {          "value": "replacement",          "display_value": "Replacement"        }      }    ],    "status": "SUCCESS"  }}

cURL request

The following code example shows how to filter the return results using the related_party and responsibility query parameters.

Shell

curl "https://instance.servicenow.com/api/sn_install_base/integrations/installbaseitems?related_party=dc0185d94f341200025ba3618110c77c&responsibility=c009bbedb3730010700b4d43c6a8dce" \--request GET \--header "Accept:application/json" \--user 'username':'password'

Return results:

JSON

{  "result": {    "sysparm_offset": "0",    "sysparm_limit": "10",    "has_more": false,    "items": [      {        "sys_class_name": "sn_install_base_item",        "number": "IBITM0001004",        "sys_id": "3ea014a778de1110f877d304c76fdd0d",        "state": {          "value": "in_use",          "display_value": "In Use"        },        "consumer": {          "sys_id": "feb5139ab3401010700b4d43c6a8dc43",          "display_value": "Kenny Smith"        },        "product": {          "sys_id": "63c8bc9778921110f877d304c76fdd34",          "display_value": "X4 Sport Utility 4D"        },        "active": "true",        "name": "X4 Sport Utility 4D",        "status": {          "value": "original",          "display_value": "Original"        }      },      {        "sys_class_name": "sn_install_base_item",        "number": "IBITM001003",        "sys_id": "6e94e3c853500010df5dddeeff7b1234",        "contact": {          "sys_id": "4d147a386f0331003b3c498f5d3ee437",          "display_value": "Julie Lewis"        },        "active": "true",        "configuration_item": {          "sys_id": "a96a570453500010df5dddeeff7b1206",          "display_value": "boxeosandbox"        },        "name": "Boxeo - Sandbox",        "account": {          "sys_id": "86837a386f0331003b3c498f5d3ee4ca",          "display_value": "Boxeo"        }      },      {        "sys_class_name": "sn_install_base_item",        "number": "IBITM0001010",        "sys_id": "83332fde87e5a1105d0055373cbb3567",        "contact": {          "sys_id": "ddce70866f9331003b3c498f5d3ee417",          "display_value": "George Warren"        },        "state": {          "value": "in_use",          "display_value": "In Use"        },        "install_date": {          "value": "2023-02-26 18:59:52",          "display_value": "2023-02-26 10:59:52"        },        "health_status": {          "value": "not_available",          "display_value": "Not Available"        },        "product": {          "sys_id": "a9a2d0c3c6112276010db16c5ddd3461",          "display_value": "Lenovo ThinkStation S20"        },        "active": "true",        "configuration_item": {          "sys_id": "affd3c8437201000deeabfc8bcbe5dc3",          "display_value": "*BETH-IBM"        },        "name": "IB B2B",        "location": {          "sys_id": "25ab9c4d0a0a0bb300f7dabdc0ca7c1c",          "display_value": "100 South Charles Street, Baltimore,MD"        },        "asset": {          "sys_id": "bfc1fa8837f3100044e0bfc8bcbe5ddf",          "display_value": "P1000228 - Lenovo ThinkStation S20"        },        "account": {          "sys_id": "86837a386f0331003b3c498f5d3ee4ca",          "display_value": "Boxeo"        },        "status": {          "value": "original",          "display_value": "Original"        }      },      {        "sys_class_name": "sn_install_base_item",        "number": "IBITM0001011",        "sys_id": "9d766f168729a1105d0055373cbb3597",        "health_status": {          "value": "not_available",          "display_value": "Not Available"        },        "product": {          "sys_id": "8583ce8237732000158bbfc8bcbe5dd9",          "display_value": "Fujitsu 1TB Hybrid Solid State Drive"        },        "active": "true",        "name": "IBA",        "account": {          "sys_id": "86837a386f0331003b3c498f5d3ee4ca",          "display_value": "Boxeo"        }      },      {        "sys_class_name": "sn_install_base_item",        "number": "IBITM0001013",        "sys_id": "bd955a2687ada1100b6afc86dabb35fb",        "health_status": {          "value": "not_available",          "display_value": "Not Available"        },        "consumer": {          "sys_id": "59e788fbdb1b1200b6075200cf9619d2",          "display_value": "Gilly Parker"        },        "product": {          "sys_id": "1a13974053500010df5dddeeff7b122c",          "display_value": "12000XHD Digital Press"        },        "active": "true",        "name": "IBConsumer"      },      {        "sys_class_name": "sn_install_base_item",        "number": "IBITM0000901",        "sys_id": "f77c7542b7343300ece839a6ee11a991",        "product": {          "sys_id": "8583ce8237732000158bbfc8bcbe5dd9",          "display_value": "Fujitsu 1TB Hybrid Solid State Drive"        },        "active": "true",        "name": "KX Series - KX5001",        "account": {          "sys_id": "86837a386f0331003b3c498f5d3ee4ca",          "display_value": "Boxeo"        }      }    ],    "status": "SUCCESS"  }}

Install Base Item - GET /sn_install_base/integrations/installbaseitem/{id}

Returns a specified install base item record and its child hierarchy.

URL format

Versioned URL: /api/sn_install_base/{api_version}/integrations/installbaseitem/{id}

Default URL: /api/sn_install_base/integrations/installbaseitem/{id}

Note: Available versions are specified in the REST API Explorer. For scripted REST APIs there is additional version information on the Scripted REST Service form.

Supported request 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

Sys_id of the install base item record.Data type: String

Table: Install Base Item [sn_install_base_item]

Name	Description
sys_class_name	If the intended record is in a table that extends the Install Base Items [sn_install_base_item] table, the name of the extended table to query. This table must extend the sn_install_base_item table.Data type: String
sysparm_depth	Maximum depth of the child install base item's hierarchy to return.Data type: Integer Default: 7 Maximum: 10
sysparm_limit	Maximum number records to return in each child hierarchy.Data type: Integer Default: 10 Maximum: 100

Name

Description

sys_class_name

If the intended record is in a table that extends the Install Base Items [sn_install_base_item] table, the name of the extended table to query. This table must extend the sn_install_base_item table.Data type: String

sysparm_depth

Maximum depth of the child install base item's hierarchy to return.Data type: Integer

Default: 7

Maximum: 10

sysparm_limit

Maximum number records to return in each child hierarchy.Data type: Integer

Default: 10

Maximum: 100

|Name|Description| |----|-----------| |None| |

Headers

Header	Description
Accept	Data format of the response body. Supported types: application/json or application/xml. Default: application/json

|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.

Status code	Description
200	Successful. The request was successfully processed.
400	Bad Request. A bad request type or malformed request was detected.
403	Forbidden. The user doesn't have access rights to the specified record.
404	Not found. The requested item wasn't found.
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)

Name	Description
childinstallbase	List of child install base item records associated with the specified install base item.Data type: Object JavaScript `"childinstallbase": { "items": [Array], "sysparm_depth": Integer}`
childinstallbase.items	Child install base items associated with the specified install base item. The values within this array are defined under the items[] array further down in this section.
childinstallbase.sysparm_depth	Child-level of the install base item.Data type: Integer
error	Details about the error that occurred when trying to process the request.Data type: Object Text `"error": { "detail": "String", "message": "String"}`
error.detail	Additional details about the associated error.Data type: String
error.message	Error message that describes the problem that occurred when trying to execute the request.Data type: String
has_children	Flag that indicates whether the requested install base item record has child install base item records.- true: Has child install base item records. false: Doesn't have child install base item records. Data type: Boolean
item	Install base item that matched the specified filter results.Data type: Object CSS "item": { "account": {Object}, "active": "String", "asset": {Object}, "configuration_item": {Object}, "consumer": {Object}, "consumer_profile": {Object}, "contact": {Object}, "health_status": "Object", "health_status_last_updated": "String", "household": {Object}, "install_date": {Object}, "location": {Object}, "name": "String", "number": "String", "parent": {Object}, "product": {Object}, "service_context": {Object}, "service_organization" {Object}, "sys_class_name": "String", "sys_id": "String", "state": {Object}, "status": {Object}, "uninstall_date": "String"}
item.account	Details about the customer account associated with the install base item record.Data type: Object Text `"account": { "display_value": "String", "sys_id": "String"}`
item.account.display_value	Text name of the customer account associated with the install base item record. Use this value to display the customer account name in the UI.Data type: String
item.account.sys_id	Sys_id of the customer account record associated with the install base item record.Data type: String
item.active	Flag that indicates whether the install base item is active.Possible values: true: Install base item is active. false: Install base item is inactive. Data type: Boolean String
item.asset	Details about the asset associated with the install base item record.Data type: Object Text `"asset": { "display_value": "String", "sys_id": "String"}`
item.asset.display_value	Text name of the asset associated with the install base item record. Use this value to display the asset name in the UI.Data type: String
item.asset.sys_id	Sys_id of the asset record associated with the install base item record.Data type: String
item.configuration_item	Details about the configuration item associated with the install base item record.Data type: Object Text `"configuration_item": { "display_value": "String", "sys_id": "String"}`
item.configuration_item.display_value	Text name of the configuration item associated with the install base item record. Use this value to display the configuration item name in the UI.Data type: String
item.configuration_item.sys_id	Sys_id of the configuration item record associated with the install base item record.Data type: String
item.consumer	Details about the consumer associated with the install base item record.Note: The consumer field is only available if the B2B2C plugin is installed. Data type: Object Text `"consumer": { "display_value": "String", "sys_id": "String"}`
item.consumer.display_value	Text name of the consumer associated with the install base item record. Use this value to display the consumer name in the UI.Data type: String
item.consumer.sys_id	Sys_id of the consumer record associated with the install base item record.Data type: String
item.consumer_profile	Details about the consumer profile associated with the install base item record.Note: The consumer profile field is only available if the B2B2C plugin is installed. Data type: Object Text `"consumer_profile": { "display_value": "String", "sys_id": "String"}`
item.consumer_profile.display_value	Text name of the consumer profile associated with the install base item record. Use this value to display the consumer profile name in the UI.Data type: String
item.consumer_profile.sys_id	Sys_id of the consumer profile record associated with the install base item record.Data type: String
item.contact	Details about the account contact responsible for the install base item record.Data type: Object Text `"contact": { "display_value": "String", "sys_id": "String"}`
item.contact.display_value	Text name of the account contact associated with the install base item record. Use this value to display the account contact name in the UI.Data type: String
item.contact.sys_id	Sys_id of the account contact record associated with the install base item record.Data type: String
item.health_status	Details about the current health status of the install base item. Only returned if the Proactive Customer Service Operations (com.snc.proactive_cs_itom) plugin is installed.Data type: Object Text `"health_status": { "display_value": "String", "value": "String"}`
item.health_status.display_value	Text string of the current health status of the install base item. Use this value to display the health status in the UI.Data type: String
item.health_status.value	Internal value of the health status of the install base item.Data type: String
item.health_status_last_updated	Date and time when the health status was last updated for the install base item.Data type: String
item.household	Details about the household associated with the install base item record. Only returned if the Customer Household Data Model (com.snc.household) plugin is installed.Data type: Object Text `"household": { "display_value": "String", "sys_id": "String"}`
item.household.display_value	Text name of the household associated with the install base item record. Use this value to display the household name in the UI.Data type: String
item.household.sys_id	Sys_id of the household associated with the install base item record.Data type: String
item.install_date	Details about the date when the install base item became active.Data type: Object Text `"install_date": { "display_value": "String", "value": "String"}`
item.install_date.display_value	Text install date. Use this value to display the install date in the UI.Data type: String
item.install_date.value	Internal value of the install date.Data type: String
item.location	Details about the location of the install base item.Data type: Object Text `"location": { "display_value": "String", "sys_id": "String"}`
item.location.display_value	Text name of the install base item location. Use this value to display the location name in the UI.Data type: String
item.location.sys_id	Sys_id of the location record associated with the install base item record.Data type: String
item.name	Name of the install base item.Data type: String
item.number	Unique ID of the install base item.Data type: String
item.parent	Details about the parent record of the install base item record.Data type: Object Text `"parent": { "display_value": "String", "sys_id": "String"}`
item.parent.display_value	Text name of the parent record associated with the install base item record. Use this value to display the parent name in the UI.Data type: String
item.parent.sys_id	Sys_id of the parent record associated with the install base item record.Data type: String
item.product	Details about the product model associated with the install base item record. Use this information to identify the services associated with any product model.Data type: Object Text `"product": { "display_value": "String", "sys_id": "String"}`
item.product.display_value	Text name of the product model associated with the install base item record. Use this value to display the product name in the UI.Data type: String
item.product.sys_id	Sys_id of the product model record associated with the install base item record.Data type: String
item.service_context	Details about the service context associated with the install base item record.Data type: Object Text `"service_context": { "display_value": "String", "sys_id": "String"}`
item.service_context.display_value	Details about the service context associated with the install base item record.Data type: Object Text `"service_context": { "display_value": "String", "sys_id": "String"}`
item.service_context.sys_id	Sys_id of the service context record associated with the install base item record.Data type: String
item.service_organization	Details about the service organization associated with the install base item record. Only returned if the Service Organization (com.snc.service_organization) plugin is installed.Data type: Object Text `"service_organization": { "display_value": "String", "sys_id": "String"}`
item.service_organization.display_value	Text name of the service organization associated with the install base item record. Use this value to display the service organization name in the UI.Data type: String
item.service_organization.sys_id	Sys_id of the service organization record associated with the install base item record.Data type: String
item.sys_class_name	Table containing the install base item record.Data type: String
item.sys_id	Sys_id of the install base item record. Located in the table specified in the sys_class_name parameter.Data type: String
item.sys_mod_count	Number of times that the associated install base item record has been modified.Data type: String
item.state	Details about the current state of the install base item.Data type: Object Text `"state": { "display_value": "String", "value": "String"}`
item.state.display_value	Text string of the current state of the install base item. Use this value to display the state in the UI.Data type: String
item.state.value	Internal value of the state of the install base item.Data type: String
item.status	Details about the status of the install base item.Data type: Object Text `"status": { "display_value": "String", "value": "String"}`
item.status.display_value	Text string of the status of the install base item. Use this value to display the status in the UI.Data type: String
item.status.value	Internal value of the status of the install base item.Data type: String
item.uninstall_date	Details about the date when the install base item became inactive.Data type: Object Text `"uninstall_date": { "display_value": "String", "value": "String"}`
item.uninstall_date.display_value	Text uninstall date. Use this value to display the uninstall date in the UI.Data type: String
item.uninstall_date.value	Internal value of the uninstall date.Data type: String
status	Status of the endpoint call.Data type: String

### cURL request

The following code example shows how to call this endpoint. The associated install base item doesn't have any children.

Shell

curl "https://instance.servicenow.com/api/sn_install_base/integrations/installbaseitem/f77c7542b7343300ece839a6ee11a991" \--request GET \--header "Accept:application/json" \--user 'username':'password'

Return results:

JSON

{  "result": {    "status": "SUCCESS",    "item": {      "sys_class_name": "sn_install_base_item",      "number": "IBITM0000901",      "sys_id": "f77c7542b7343300ece839a6ee11a991",      "product": {        "sys_id": "8583ce8237732000158bbfc8bcbe5dd9",        "display_value": "Fujitsu 1TB Hybrid Solid State Drive"      },      "active": "true",      "name": "KX Series - KX5001",      "account": {        "sys_id": "86837a386f0331003b3c498f5d3ee4ca",        "display_value": "Boxeo"      }    },    "hasChildren": "false"  }}

cURL request

The following code example shows how to call this endpoint specifying a maximum depth of four child-levels.

Shell

curl "https://instance.servicenow.com/api/sn_install_base/integrations/installbaseitems/e0a80e4b87b521100b6afc86dabb3565?depth=4" \--request GET \--header "Accept:application/json" \--user 'username':'password'

Return results:

JSON

{  "result": {    "status": "SUCCESS",    "item": {      "sys_class_name": "sn_install_base_item",      "number": "IBITM0001073",      "sys_id": "e0a80e4b87b521100b6afc86dabb3565",      "health_status": {        "value": "not_available",        "display_value": "Not Available"      },      "active": "true",      "name": "parent",      "account": {        "sys_id": "86837a386f0331003b3c498f5d3ee4ca",        "display_value": "Boxeo"      }    },    "hasChildren": "true",    "childinstallbase": {      "sysparm_depth": 2,      "items": [        {          "parent": {            "sys_id": "e0a80e4b87b521100b6afc86dabb3565",            "display_value": "parent"          },          "sys_class_name": "sn_install_base_item",          "number": "IBITM0001074",          "sys_id": "6db80e4b87b521100b6afc86dabb356b",          "state": {            "value": "in_use",            "display_value": "In Use"          },          "health_status": {            "value": "not_available",            "display_value": "Not Available"          },          "active": "true",          "name": "child1",          "account": {            "sys_id": "86837a386f0331003b3c498f5d3ee4ca",            "display_value": "Boxeo"          },          "hasChildren": "true",          "items": {            "sysparm_depth": 3,            "items": [              {                "parent": {                  "sys_id": "6db80e4b87b521100b6afc86dabb356b",                  "display_value": "child1"                },                "sys_class_name": "sn_install_base_item",                "number": "IBITM0001075",                "sys_id": "36ecce4b87b521100b6afc86dabb3503",                "health_status": {                  "value": "not_available",                  "display_value": "Not Available"                },                "active": "true",                "name": "childL2",                "account": {                  "sys_id": "86837a386f0331003b3c498f5d3ee4ca",                  "display_value": "Boxeo"                },                "hasChildren": "false"              }            ]          }        }      ]    }  }}

Install Base Item - GET /sn_install_base/integrations/installbaseitems/{id}/cases

Returns the cases associated with a specified install base item record.

URL format

Versioned URL: /api/sn_install_base/{api_version}/integrations/installbaseitems/{id}/cases

Default URL: /api/sn_install_base/integrations/installbaseitems/{id}/cases

Note: Available versions are specified in the REST API Explorer. For scripted REST APIs there is additional version information on the Scripted REST Service form.

Supported request 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

Sys_id of the install base item record.Data type: String

Table: Install Base Item [sn_install_base_item]

Name	Description
field name-value pairs	Field-value pairs to use to filter the case records. If you specify a different table in sys_class_name, then specify the fields in that table.You can pass one or more field-value pairs to filter the return results. For example, to return only records where the approval field is set to "rejected" and the category field is set to "2", pass the follow: `&approval=rejected&category=2`. Data type: String Table: Case [sn_customerservice_case] Default: All fields
sys_class_name	If using an extended case table (not sn_customerservice_case), the name of the extended table to query.Data type: String Default: sn_customerservice_case
sysparm_limit	Maximum number of records to return. For requests that exceed this number of records, use the sysparm_offset parameter to paginate record retrieval. This limit is applied before ACL evaluation. If no records return, including records you have access to, rearrange the record order so records you have access to return first. Note: Unusually large sysparm_limit values can impact system performance. Data type: Number Default: 10000
sysparm_offset	Starting record index for which to begin retrieving records. Use this value to paginate record retrieval. This functionality enables the retrieval of all records, regardless of the number of records, in small manageable chunks. For example, the first time you call this endpoint, sysparm_offset is set to "0". To simply page through all available records, use `sysparm_offset=sysparm_offset+sysparm_limit`, until you reach the end of all records. Don't pass a negative number in the sysparm_offset parameter.Data type: Number Default: 0

|Name|Description| |----|-----------| |None| |

Headers

Header	Description
Accept	Data format of the response body. Supported types: application/json or application/xml. Default: application/json

|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.

Status code	Description
200	Successful. The request was successfully processed.
400	Bad Request. A bad request type or malformed request was detected.
403	Forbidden. The user doesn't have access rights to the specified record.
404	Not found. The requested item wasn't found.
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)

Element	Description
cases	List of cases associated with the specified install base item record.Data type: Array of Objects Shell "cases": [ { "account": "String", "active": Boolean, "active_account_escalation": "String", "active_escalation": "String", "activity_due": "String", "additional_assignee_list": "String", "approval": "String", "approval_history": "String", "approval_set": "String", "asset": "String", "assigned_on": "String", "assigned_to": "String", "assignment_group": "String", "auto_close": Boolean, "business_duration": "String", "business_impact": "String", "business_service": "String", "calendar_duration": "String", "case": "String", "case_report": "String", "category": Number, "cause": "String", "caused_by": "String", "change": "String", "child_case_creation_progress": Boolean, "closed_at": "String", "closed_by": "String", "close_notes: "String", "cmdb_ci": "String", "comments": "String", "comments_and_work_notes": "String", "company": "String", "consumer": "String", "contact": "String", "contact_local_time: "String", "contact_time_zone": "String", "contact_type": "String", "contract": "String", "contributor_groups": "String", "contributor_users": "String", "correlation_display": "String", "correlation_id": "String", "delivery_plan": "String", "delivery_task": "String", "description": "string", "due_date": "String", "entitlement": "String", "escalation": Number, "expected_start": "String", "first_response_time": "String", "follow_the_sun": Boolean, "follow_up": "String", "group_list": [Array], "impact": Number, "internal_user": "String", "initiated_as_request": Boolean, "knowledge": Boolean, "location": "String", "made_sla": Boolean, "major_case_state": "String", "needs_attention": Boolean, "notes_to_comments": Boolean, "notify": Number, "number": "String", "opened_at": "String", "opened_by": "String", "order": Number, "parent": "String", "partner": "String", "partner_contact": "String", "priority": Number, "proactive": Boolean, "probable_cause": "String", "problem": "String", "product": "String", "reassignment_count": Number, "recipient_list": "String", "rejection_goto": "String", "resolution_code": "String", "resolved_at": "String", "resolved_by": "String", "route_reason": "String", "service_offering": "String", "short_description": "String", "skills": "String", "sla_due": "String", "sn_app_cs_social_social_profile": "String", "sold_product": "String", "stage": "String", "state": Number, "subcategory": Number, "support_manager" "String", "sync_driver": Boolean, "sys_class_name": "String", "sys_domain": "String", "sys_domain_path": "String", "sys_id": "String", "task_effective_number": "String", "time_worked": "String", "universal_request": "String", "upon_approval": "String", "upon_reject": "String", "urgency": Number, "user_input": "String", "variables": "String", "watch_list": [Array], "wf_activity": "String", "work_end": "String", "work_notes": "String", "work_notes_list": [Array], "work_start": "String"
cases.account	Sys_id of the account record associated with the case. Data type: String Table: Account [customer_account]
cases.active	Flag that indicates whether the case is open and active.Possible values: true: Case is active false: Case is closed Data type: Boolean Default: true
cases.active_account_escalation	Sys_id of the active account escalation record associated with the case.Data type: String Table: Escalation [sn_customerservice_escalation]
cases.active_escalation	Sys_id of the active escalation record associated with the case.Data type: String Table: Escalation [sn_customerservice_escalation]
cases.activity_due	Date for which the associated case is expected to be completed.Data type: String
cases.additional_assignee_list	List of the sys_ids of the additional persons (other than the primary assignee) that have been assigned to the account.Data type: Array Maximum: 4,000 Table: User [sys_user]
cases.approval	String that describes the type of approval required.Possible values: approved cancelled duplicate not_required not requested rejected requested Data type: String Maximum characters: 40 Default: not requested
cases.approval_history	List of all approvals associated with the case.Data type: String Maximum characters: 4,000
cases.approval_set	Date and time that the associated action was approved.Data type: String
cases.asset	Sys_id of the asset record associated with the case.Data type: String Table: Asset [alm_asset]
cases.assigned_on	Date and time that the case was assigned to the person identified in the assigned_to parameter.Data type: String (Date) Maximum length: 40
cases.assigned_to	Sys_id of the person assigned to the case. Table: User [sys_user] Data type: String
cases.assignment_group	Sys_id of the customer service agent group assigned to the case.Data type: String Table: Group [sys_user_group]
cases.auto_close	Flag that indicates whether the case was automatically closed.Possible values: true: Case was auto closed false: Case wasn't auto closed Data type: Boolean Default: false
cases.business_duration	Length in calendar work hours, work days, and work weeks that it took to complete the case.Data type: String
cases.business_impact	Impact of the issue on the associated customer.Data type: String Maximum characters: 4,000
cases.business_service	Sys_id of the service record associated with the case.Data type: String Table: Service [cmdb_ci_service]
cases.calendar_duration	Length in calendar hours, days, and weeks that it took to complete the case.Data type: String (Duration) Maximum length: 40
cases.case	Case short description and case number.Data type: String Maximum length: 300
cases.case_report	Sys_id of the associated case report.Data type: String Table: Case Report [sn_customerservice_case_report]
cases.category	Case category.Possible values: 0: Question 1: Issue 2: Feature Data type: Number (Integer) Default: 1
cases.cause	Details about the cause of the problem.Data type: String Maximum length: 4,000
cases.caused_by	Sys_id of the change request that caused the case to be created.Data type: String Table: Change Request [change_request]
cases.change	Sys_id of the change request that caused the case to be created.Data type: String Table: Change Request [change_request]
cases.child_case_creation_progress	Flag that indicates whether the case is a child case that was created from a major case.Possible values: true: Child case created from a major case false: Not a child case Data type: Boolean
cases.closed_at	Date and time that the case was closed.Data type: String
cases.closed_by	Sys_id of the user that closed the case.Data type: String Table: User [sys_user]
cases.close_notes	Notes made when the case was closed.Data type: String Maximum length: 4,000
cases.cmdb_ci	Sys_id of the configuration item associated with the case.Data type: String Table: Configuration Item [cmdb_ci]
cases.comments	Additional comments about the case.Data type: String Maximum length: 4,000
cases.comments_and_work_notes	Comments and work notes entered for the case.Data type: String Maximum length: 4,000
cases.company	Sys_id of the company associated with the case.Data type: String Table: Company [core_company]
cases.consumer	Business-to-consumer cases only. Sys_id of the person to contact with regard to this case.Data type: String Table: Consumer [csm_consumer]
cases.contact	Business-to-business based cases only. Sys_id of the person to contact regarding this case.Data type: String Table: Contact [customer_contact]
cases.contact_local_time	Contact local time.Data type: String Maximum length: 70
cases.contact_time_zone	Time zone of the contact associated with the case.Data type: String Maximum length: 40
cases.contact_type	Method in which the case was initially reported.Possible values: chat email phone social web Data type: String Maximum length: 40
cases.contract	Sys_id of the contract associated with the case. This contract contains information about the type of support that is provided to the company associated to the case. A contract can include a company and contact and the specific assets that are covered. A contract can also include multiple service entitlements and SLAs.Data type: String Table: Contract [ast_contract]
cases.contributor_groups	List of sys_ids of the user groups that have contributed to the case.Data type: String Table: Group [sys_user_group]
cases.contributor_users	List of sys_ids of the users that have contributed to the case.Data type: String Table: User [sys_user]
cases.correlation_display	Correlation display.Data type: String Maximum length: 100
cases.correlation_id	Correlation identifier.Data type: String Maximum length: 100
cases.delivery_plan	Sys_id of the parent execution plan for this case.Data type: String Table: Execution Plan [sc_cat_item_delivery_plan]
cases.delivery_task	Sys_id of the execution plan task.Data type: String Table: Execution Plan Task [sc_cat_item_delivery_task]
cases.description	Detailed description of the problem associated with the case. Data type: String Maximum length: 4,000
cases.due_date	Date that the case is due to be closed.Data type: String
cases.entitlement	Sys_id of the entitlement record associated with the case. Entitlements define the type of support that a customer receives as well as the supported communication channels. An entitlement can be associated with a product, an asset, an account, or a contract.Data type: String Table: Entitlement [service_entitlement]
cases.escalation	Current escalation level.Possible values: 0: Normal 1: Moderate 2: High 3: Overdue Data type: Number (Integer) Default: 0
cases.expected_start	Date and time when work is scheduled to begin on the case.Data type: String
cases.first_response_time	Date and time when the first action was taken on the case.Data type: String
cases.follow_the_sun	Flag that indicates whether the case should be handed-off for global follow-up.If a customer enters additional comments on a Priority 1 - Critical or a Priority 2 - High case, or if the case is escalated, the flag is automatically set to true. Possible values: true: Case should be handed-off for global follow-up false: Case shouldn't be handed-off for global follow-up Data type: Boolean Default: false
cases.follow_up	Date and time of the next follow-up action.Data type: String
cases.group_list	List of sys_ids of the group records associated with the case.Data type: Array Table: Group [sys_user_group]
cases.impact	Impact on customer.Possible values: 1: High 2: Medium 3: Low Data type: Number (Integer) Default: 3
cases.internal_user	Sys_id of the internal user for this case.Data type: String Table: User [sys_user]
cases.initiated_as_request	Flag that indicates if this inquiry was initiated as a request by the customer.Possible values: true: Inquiry initiated by customer. false: Inquiry wasn't initiated by customer. Data type: Boolean Default: false
cases.knowledge	Flag that indicates if there is a knowledge base article available for the specified issue.Possible values: true: Knowledge base article is available for this issue false: Knowledge base article is not available for this issue Data type: Boolean Default: false
cases.location	Sys_id of the record describing the company location.Data type: String Table: Location [cmn_location]
cases.made_sla	Flag that indicates whether the case was resolved in alignment with the associated service level agreement.Possible values: true: Case was resolved in alignment with SLA false: Case wasn't resolved according to the SLA Data type: Boolean Default: true
cases.major_case_state	Current state of the major case.Possible values: accepted: Initial state when a manager creates a major case or when a manager promotes a candidate case. canceled: Case is canceled. proposed: Initial state when an agent or manager creates or proposes a candidate case. rejected: Manager rejected candidate case. Data type: String Maximum length: 40
needs_attention	Flag that indicates whether the case needs attention.Possible values: true: Case needs additional attention false: Case doesn't need additional attention Data type: Boolean Default: false
cases.notes_to_comments	Flag that indicates whether to add the resolution notes to the comments.Possible values: true: Resolutions notes, when added, are also added to the comments false: Resolution notes in comments aren't required Data type: Boolean
cases.notify	Method to use to notify contact/consumer.Possible values: 1: Do not notify 2: Send email 3: Telephone Data type: Number (Integer) Default: 1
cases.number	Case number.Data type: String Maximum length: 40
cases.opened_at	Date and time that the case was opened.Data type: String
cases.opened_by	Sys_id of the person that initially opened the case.Data type: String Table: User [sys_user]
cases.order	Order of the case.Data type: Number (Integer)
cases.parent	Sys_id of the parent case to which this case (child) is associated.Data type: String Table: Task [task]
cases.partner	Sys_id of the partner associated with the case.Data type: String Table: Account [customer_account]
cases.partner_contact	Sys_id of the partner contact associated with the case.Data type: String Table: Contact [customer_contact]
cases.priority	Priority of the case. Possible values: 1: Critical 2: High 3: Moderate 4: Low Data type: Number (Integer) Default: 4
cases.proactive	Flag that indicates whether the inquiry is being proactively monitored.Possible values: true: Being proactively monitored. false: Not being monitored. Data type: Boolean Default:false
cases.probable_cause	Possible cause of the issue associated with the case.Data type: String Maximum length: 4,000
cases.problem	Sys_id of the issue that the customer is encountering.Data type: String Table: Problem [problem]
cases.product	Sys_id of the product model of the asset associated to the case. A model is a specific version or configuration of an asset (for example, Apple Mac Book Pro).Data type: String Table: Product Model [cmdb_model]
cases.reassignment_count	Number of times that the case was reassigned to a person that is responsible for moving the case forward.Data type: Number (Integer) Default: 0
cases.recipient_list	Sys_id of the record that contains the list of recipients for communications about this case.Data type: String Table: Recipients List [sn_publications_recipients_list]
cases.rejection_goto	Sys_id of the task to execute if the case is rejected.Data type: String Table: Task [task]
cases.resolution_code	Resolution state for the case, such as "Solved - Fixed by Support/Guidance provided". Data type: String Maximum length: 40
cases.resolved_at	Date and time that the case was resolved.Data type: String
cases.resolved_by	Sys_id of the person that resolved the case.Data type: String Table: User [sys_user]
cases.route_reason	Reason that the case was routed to a different assignee.Data type: Number (Integer) Maximum length: 40
cases.service_offering	Sys_id of the service offering associated with the payment inquiry. Service offerings uniquely define the level of service in terms of availability, scope, pricing, and packaging options.Data type: String Table: Service Offering [service_offering]
cases.short_description	Concise description of the case. Data type: String Maximum length: 160
cases.skills	List of the unique identifiers (sys_id) of the skills needed to complete the case.Data type: String Table: Skill [cmn_skill]
cases.sla_due	Date/time at which the case must be closed based on the associated service level agreement.Data type: String
cases.sn_app_cs_social_social_profile	Sys_id of the social media profile associated with the case.Data type: String Table: Social Profile [sn_app_cs_social_social_profile]
cases.sold_product	Sys_id of the associated product.Data type: String Table: Sold Product [sn_install_base_sold_product]
cases.stage	Stage of the inquiry, such as Closed Complete, Closed Rejected, Document Check, Authorization, and so on.Data type: String Maximum length: 40
cases.state	Current state of the case.Possible values: 1: New 3: Closed 6: Resolved 10: Open 18: Awaiting Info Data type: Number (Integer) Default: 1
cases.subcategory	Case subcategory.Possible values: 0: QuestionData type: Number (Integer) Default: 0
cases.support_manager	Sys_id of the CSM manager assigned to the case.Data type: String Table: User [sys_user]
cases.sync_driver	Flag that indicates whether there's driver synchronization.Possible values: true: Driver is synchronized false: Driver isn't synchronized Data type: Boolean
cases.sys_class_name	Table that contains the case record.Data type: String Maximum length: 80
cases.sys_domain	Domain associated with the case.Data type: String Maximum length: 32 Default: global
cases.sys_domain_path	Domain path.Data type: String Maximum length: 255 Default: /
cases.sys_id	Unique identifier for the case.Data type: String Maximum length: 32
cases.task_effective_number	Identifying number. If the task has a Universal Request associated with it, it's the UR number. Otherwise, it's the current task number. Data type: String Maximum length: 40
cases.time_worked	Total amount of time worked on the case.Data type: String
cases.universal_request	Sys_id of a universal task that this inquiry is part of.Data type: String Table: Task [task]
cases.upon_approval	Action to take if the case is approved.Possible values: do_nothing proceed Data type: String Maximum length: 40 Default: proceed
cases.upon_reject	Action to take if the case is rejected.Possible values: cancel goto Data type: String Maximum length: 40 Default: cancel
cases.urgency	Urgency of the case.Possible values: 1: High 2: Medium 3: Low Data type: Number (Integer) Default: 3
cases.user_input	Additional user input.Data type: String Maximum length: 4,000
cases.variables	Name-value pairs of variables associated with the case.Data type: String Maximum length: 40
cases.watch_list	List of sys_ids of the users who receive notifications about this case when additional comments are added or if the state of a case is changed to Resolved or Closed.Data type: Array Table: User [sys_user]
cases.wf_activity	Sys_id of the workflow activity record associated with the case.Data type: String Table: Workflow Activity [wf_activity]
cases.work_end	Date and time work ended on the case.Data type: String
cases.work_notes	Information about how to resolve the case, or steps taken to resolve it.Data type: String Maximum length: 4,000
cases.work_notes_list	List of sys_ids of the internal users who receive notifications about this case when work notes are added.Data type: Array Table: User [sys_user]
cases.work_start	Date and time that work started on the case.Data type: String
has_more	Flag that indicates whether there are more records in the table to return.Possible values: true: More records to return. false: No more records to return. Data type: Boolean string
status	Status of the endpoint call.Data type: String
sysparm_limit	Maximum number of records to return. For requests that exceed this number of records, use the sysparm_offset parameter to paginate record retrieval. In the response, the boolean parameter hasMore is returned. It indicates whether there are more records to return that meet the filter criteria. Data type: Number Default: 10
sysparm_offset	Starting record index for which to begin retrieving records. Use this value to paginate record retrieval. This functionality enables the retrieval of all records, regardless of the number of records, in small manageable chunks. For example, the first time you call this endpoint, sysparm_offset is set to "0". To simply page through all available records, use `sysparm_offset=sysparm_offset+sysparm_limit`, until you reach the end of all records. Do not pass a negative number in the sysparm_offset parameter. Data type: Number Default: 0

### cURL request

The following code example shows how to call this endpoint.

Shell

curl "https://instance.servicenow.com/api/sn_install_base/integrations/installbaseitems/1474a3c853500010df5dddeeff7b12ec/cases" \--request GET \--header "Accept:application/json" \--user 'username':'password'

Return results:

JSON

{  "result": {    "sysparm_offset": 0,    "sysparm_limit": 10,    "has_more": false,    "cases": [      {        "upon_reject": {          "value": "cancel",          "display_value": "Cancel all future Tasks"        },        "number": "CS0001034",        "initiated_as_request": "0",        "state": "1",        "case": "Performance is impacted with latest updateCS0001034",        "knowledge": "0",        "impact": "3",        "contract": {          "sys_id": "495e16b96f0731003b3c498f5d3ee4af",          "display_value": "CNTR0000603"        },        "active": "1",        "auto_created_case": "0",        "priority": "4",        "sys_domain_path": "/",        "child_case_creation_progress": "0",        "sync_driver": "0",        "needs_attention": "0",        "short_description": "Performance is impacted with latest update",        "notify": "1",        "sys_class_name": "sn_customerservice_case",        "reassignment_count": "0",        "notes_to_comments": "0",        "hierarchical_variables": "variable_pool",        "escalation": "0",        "upon_approval": {          "value": "proceed",          "display_value": "Proceed to Next Task"        },        "made_sla": "1",        "task_effective_number": "CS0001034",        "opened_by": {          "sys_id": "ddce70866f9331003b3c498f5d3ee417",          "display_value": "George Warren"        },        "contact": {          "sys_id": "ddce70866f9331003b3c498f5d3ee417",          "display_value": "George Warren"        },        "follow_the_sun": "0",        "entitlement": {          "sys_id": "1eb7893a6f1b31003b3c498f5d3ee4dd",          "display_value": "24x7 Customer Support"        },        "opened_at": {          "value": "2023-03-20 14:53:51",          "display_value": "2023-03-20 07:53:51"        },        "case_report": {          "sys_id": "85e8604c87f521100b6afc86dabb35b9",          "display_value": "CSR0010014"        },        "subcategory": "0",        "install_base": {          "sys_id": "1474a3c853500010df5dddeeff7b12ec",          "display_value": "Boxeo - Development"        },        "proactive": "0",        "auto_close": "0",        "sys_id": "92c8684087b521105d0055373cbb357e",        "contact_type": {          "value": "web",          "display_value": "Web"        },        "urgency": "3",        "approval": {          "value": "not requested",          "display_value": "Not Yet Requested"        },        "category": "1",        "account": {          "sys_id": "86837a386f0331003b3c498f5d3ee4ca",          "display_value": "Boxeo"        }      },      {        "upon_reject": {          "value": "cancel",          "display_value": "Cancel all future Tasks"        },        "number": "CS0001008",        "initiated_as_request": "0",        "state": "1",        "case": "Test AlertCS0001008",        "knowledge": "0",        "impact": "3",        "active": "1",        "auto_created_case": "0",        "priority": "1",        "sys_domain_path": "/",        "child_case_creation_progress": "0",        "sync_driver": "0",        "needs_attention": "1",        "short_description": "Test Alert",        "notify": "1",        "sys_class_name": "sn_customerservice_case",        "reassignment_count": "0",        "notes_to_comments": "0",        "hierarchical_variables": "variable_pool",        "escalation": "0",        "upon_approval": {          "value": "proceed",          "display_value": "Proceed to Next Task"        },        "made_sla": "1",        "task_effective_number": "CS0001008",        "opened_by": {          "sys_id": "08c83021acbe7300964fca436af2bb97",          "display_value": "noc_operator "        },        "follow_the_sun": "0",        "opened_at": {          "value": "2023-03-15 08:02:58",          "display_value": "2023-03-15 01:02:58"        },        "case_report": {          "sys_id": "a4fa9d9a872d61105d0055373cbb356e",          "display_value": "CSR0010005"        },        "subcategory": "0",        "proactive": "1",        "auto_close": "0",        "sys_id": "60ea199a872d61105d0055373cbb35c9",        "contact_type": {          "value": "proactive",          "display_value": "Alert"        },        "alert": {          "sys_id": "506a559a872d61105d0055373cbb3581",          "display_value": "Alert0010008"        },        "urgency": "3",        "action_status": "4",        "approval": {          "value": "not requested",          "display_value": "Not Yet Requested"        },        "category": "1"      },      {        "upon_reject": {          "value": "cancel",          "display_value": "Cancel all future Tasks"        },        "number": "CS0001033",        "initiated_as_request": "0",        "state": "1",        "case": "System is downCS0001033",        "knowledge": "0",        "impact": "3",        "contract": {          "sys_id": "495e16b96f0731003b3c498f5d3ee4af",          "display_value": "CNTR0000603"        },        "active": "1",        "auto_created_case": "0",        "priority": "4",        "sys_domain_path": "/",        "child_case_creation_progress": "0",        "sync_driver": "0",        "needs_attention": "0",        "short_description": "System is down",        "notify": "1",        "sys_class_name": "sn_customerservice_case",        "reassignment_count": "0",        "notes_to_comments": "0",        "hierarchical_variables": "variable_pool",        "escalation": "0",        "upon_approval": {          "value": "proceed",          "display_value": "Proceed to Next Task"        },        "made_sla": "1",        "task_effective_number": "CS0001033",        "opened_by": {          "sys_id": "ddce70866f9331003b3c498f5d3ee417",          "display_value": "George Warren"        },        "contact": {          "sys_id": "ddce70866f9331003b3c498f5d3ee417",          "display_value": "George Warren"        },        "follow_the_sun": "0",        "entitlement": {          "sys_id": "1eb7893a6f1b31003b3c498f5d3ee4dd",          "display_value": "24x7 Customer Support"        },        "opened_at": {          "value": "2023-03-20 14:52:48",          "display_value": "2023-03-20 07:52:48"        },        "case_report": {          "sys_id": "64b86c0c87f521100b6afc86dabb35fc",          "display_value": "CSR0010013"        },        "subcategory": "0",        "install_base": {          "sys_id": "1474a3c853500010df5dddeeff7b12ec",          "display_value": "Boxeo - Development"        },        "proactive": "0",        "auto_close": "0",        "sys_id": "7c98a04087b521105d0055373cbb352e",        "contact_type": {          "value": "web",          "display_value": "Web"        },        "urgency": "3",        "approval": {          "value": "not requested",          "display_value": "Not Yet Requested"        },        "category": "1",        "account": {          "sys_id": "86837a386f0331003b3c498f5d3ee4ca",          "display_value": "Boxeo"        }      },      {        "upon_reject": {          "value": "cancel",          "display_value": "Cancel all future Tasks"        },        "number": "CS0001048",        "initiated_as_request": "0",        "state": "1",        "case": "AIB with Single accountCS0001048",        "knowledge": "0",        "impact": "3",        "active": "1",        "auto_created_case": "0",        "priority": "4",        "sys_domain_path": "/",        "child_case_creation_progress": "0",        "sync_driver": "0",        "needs_attention": "1",        "short_description": "AIB with Single account",        "notify": "1",        "sys_class_name": "sn_customerservice_case",        "reassignment_count": "0",        "notes_to_comments": "0",        "hierarchical_variables": "variable_pool",        "escalation": "0",        "upon_approval": {          "value": "proceed",          "display_value": "Proceed to Next Task"        },        "made_sla": "1",        "task_effective_number": "CS0001048",        "opened_by": {          "sys_id": "08c83021acbe7300964fca436af2bb97",          "display_value": "noc_operator "        },        "contact": {          "sys_id": "4d147a386f0331003b3c498f5d3ee437",          "display_value": "Julie Lewis"        },        "follow_the_sun": "0",        "opened_at": {          "value": "2023-03-24 03:28:58",          "display_value": "2023-03-23 20:28:58"        },        "case_report": {          "sys_id": "4082be81877161100b6afc86dabb35fe",          "display_value": "CSR0010023"        },        "subcategory": "0",        "proactive": "1",        "auto_close": "0",        "sys_id": "6a723e81877161100b6afc86dabb35cf",        "contact_type": {          "value": "proactive",          "display_value": "Alert"        },        "alert": {          "sys_id": "6b227681877161100b6afc86dabb35d5",          "display_value": "Alert0010094"        },        "urgency": "3",        "action_status": "4",        "approval": {          "value": "not requested",          "display_value": "Not Yet Requested"        },        "category": "1",        "account": {          "sys_id": "86837a386f0331003b3c498f5d3ee4ca",          "display_value": "Boxeo"        }      }    ],    "status": "SUCCESS"  }}

Install Base Item - GET /sn_install_base/integrations/installbaseitems/{id}/childinstallbaseitems

Returns the child install base items associated with a specified install base item record.

URL format

Versioned URL: /api/sn_install_base/{api_version}/integrations/installbaseitems/{id}/childinstallbaseitems

Default URL: /api/sn_install_base/integrations/installbaseitems/{id}/childinstallbaseitems

Note: Available versions are specified in the REST API Explorer. For scripted REST APIs there is additional version information on the Scripted REST Service form.

Supported request 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

Sys_id of the install base item record.Data type: String

Table: Install Base Item [sn_install_base_item]

Name	Description
field name-value pairs	Field-value pairs to use to filter the child install base item records.If you specify a different table in sys_class_name, then specify the fields in that table.You can pass one or more field-value pairs to filter the return results. For example, to return only records where the state field is set to "in_use" and the status field is set to "replacement", pass the follow: `&state=in_use&status=replacement`. Data type: String Default: All fields Table: Install Base Item [sn_install_base_item]
sys_class_name	If using an extended install base items table (not sn_install_base_item), the name of the extended table to query.Data type: String Default: sn_install_base_item
sysparm_limit	Maximum number of records to return. For requests that exceed this number of records, use the sysparm_offset parameter to paginate record retrieval. This limit is applied before ACL evaluation. If no records return, including records you have access to, rearrange the record order so records you have access to return first. Note: Unusually large sysparm_limit values can impact system performance. Data type: Number Default: 10000
sysparm_offset	Starting record index for which to begin retrieving records. Use this value to paginate record retrieval. This functionality enables the retrieval of all records, regardless of the number of records, in small manageable chunks. For example, the first time you call this endpoint, sysparm_offset is set to "0". To simply page through all available records, use `sysparm_offset=sysparm_offset+sysparm_limit`, until you reach the end of all records. Don't pass a negative number in the sysparm_offset parameter.Data type: Number Default: 0

|Name|Description| |----|-----------| |None| |

Headers

Header	Description
Accept	Data format of the response body. Supported types: application/json or application/xml. Default: application/json

|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.

Status code	Description
200	Successful. The request was successfully processed.
400	Bad Request. A bad request type or malformed request was detected.
403	Forbidden. The user doesn't have access rights to the specified record.
404	Not found. The requested item wasn't found.
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)

Name	Description
error	Details about the error that occurred when trying to process the request.Data type: Object Text `"error": { "detail": "String", "message": "String"}`
error.detail	Additional details about the associated error.Data type: String
error.message	Error message that describes the problem that occurred when trying to execute the request.Data type: String
has_more	Flag that indicates whether there are more records in the table to return.Possible values: true: More records to return. false: No more records to return. Data type: Boolean string
items	List of the install base items that matched the specified filter results.Data type: Array of Objects CSS "items":[ { "account": {Object}, "active": "String", "asset": {Object}, "configuration_item": {Object}, "consumer": {Object}, "consumer_profile": {Object}, "contact": {Object}, "health_status": {Object}, "health_status_last_updated": "String", "household": {Object}, "install_date": {Object}, "location": {Object}, "name": "String", "number": "String", "parent": {Object}, "product": {Object}, "service_context": {Object}, "service_organization" {Object}, "sys_class_name": "String", "sys_id": "String", "sys_mod_count": "String", "state": {Object}, "status": {Object}, "uninstall_date": "String" }]
items.account	Details about the customer account associated with the install base item record.Data type: Object Text `"account": { "display_value": "String", "sys_id": "String"}`
items.account.display_value	Text name of the customer account associated with the install base item record. Use this value to display the customer account name in the UI.Data type: String
items.account.sys_id	Sys_id of the customer account record associated with the install base item record.Data type: String
items.active	Flag that indicates whether the install base item is active.Possible values: true: Install base item is active. false: Install base item is inactive. Data type: Boolean String
items.asset	Details about the asset associated with the install base item record.Data type: Object Text `"asset": { "display_value": "String", "sys_id": "String"}`
items.asset.display_value	Text name of the asset associated with the install base item record. Use this value to display the asset name in the UI.Data type: String
items.asset.sys_id	Sys_id of the asset record associated with the install base item record.Data type: String
items.configuration_item	Details about the configuration item associated with the install base item record.Data type: Object Text `"configuration_item": { "display_value": "String", "sys_id": "String"}`
items.configuration_item.display_value	Text name of the configuration item associated with the install base item record. Use this value to display the configuration item name in the UI.Data type: String
items.configuration_item.sys_id	Sys_id of the configuration item record associated with the install base item record.Data type: String
items.consumer	Details about the consumer associated with the install base item record.Note: The consumer field is only available if the B2B2C plugin is installed. Data type: Object Text `"consumer": { "display_value": "String", "sys_id": "String"}`
items.consumer.display_value	Text name of the consumer associated with the install base item record. Use this value to display the consumer name in the UI.Data type: String
items.consumer.sys_id	Sys_id of the consumer record associated with the install base item record.Data type: String
items.consumer_profile	Details about the consumer profile associated with the install base item record.Note: The consumer profile field is only available if the B2B2C plugin is installed. Data type: Object Text `"consumer_profile": { "display_value": "String", "sys_id": "String"}`
items.consumer_profile.display_value	Text name of the consumer profile associated with the install base item record. Use this value to display the consumer profile name in the UI.Data type: String
items.consumer_profile.sys_id	Sys_id of the consumer profile record associated with the install base item record.Data type: String
items.contact	Details about the account contact responsible for the install base item record.Data type: Object Text `"contact": { "display_value": "String", "sys_id": "String"}`
items.contact.display_value	Text name of the account contact associated with the install base item record. Use this value to display the account contact name in the UI.Data type: String
items.contact.sys_id	Sys_id of the account contact record associated with the install base item record.Data type: String
items.health_status	Details about the current health status of the install base item. Only returned if the Proactive Customer Service Operations (com.snc.proactive_cs_itom) plugin is installed.Data type: Object Text `"health_status": { "display_value": "String", "value": "String"}`
items.health_status.display_value	Text string of the current health status of the install base item. Use this value to display the health status in the UI.Data type: String
items.health_status.value	Internal value of the health status of the install base item.Data type: String
items.health_status_last_updated	Date and time when the health status was last updated for the install base item.Data type: String
items.household	Details about the household associated with the install base item record. Only returned if the Customer Household Data Model (com.snc.household) plugin is installed.Data type: Object Text `"household": { "display_value": "String", "sys_id": "String"}`
items.household.display_value	Text name of the household associated with the install base item record. Use this value to display the household name in the UI.Data type: String
items.household.sys_id	Sys_id of the household associated with the install base item record.Data type: String
items.install_date	Details about the date when the install base item became active.Data type: Object Text `"install_date": { "display_value": "String", "value": "String"}`
items.install_date.display_value	Text install date. Use this value to display the install date in the UI.Data type: String
items.install_date.value	Internal value of the install date.Data type: String
items.location	Details about the location of the install base item.Data type: Object Text `"location": { "display_value": "String", "sys_id": "String"}`
items.location.display_value	Text name of the install base item location. Use this value to display the location name in the UI.Data type: String
items.location.sys_id	Sys_id of the location record associated with the install base item record.Data type: String
items.name	Name of the install base item.Data type: String
items.number	Unique ID of the install base item.Data type: String
items.parent	Details about the parent record of the install base item record.Data type: Object Text `"parent": { "display_value": "String", "sys_id": "String"}`
items.parent.display_value	Text name of the parent record associated with the install base item record. Use this value to display the parent name in the UI.Data type: String
items.parent.sys_id	Sys_id of the parent record associated with the install base item record.Data type: String
items.product	Details about the product model associated with the install base item record. Use this information to identify the services associated with any product model.Data type: Object Text `"product": { "display_value": "String", "sys_id": "String"}`
items.product.display_value	Text name of the product model associated with the install base item record. Use this value to display the product name in the UI.Data type: String
items.product.sys_id	Sys_id of the product model record associated with the install base item record.Data type: String
items.service_context	Details about the service context associated with the install base item record.Data type: Object Text `"service_context": { "display_value": "String", "sys_id": "String"}`
items.service_context.display_value	Text name of the service context associated with the install base item record. Use this value to display the service context name in the UI.Data type: String
items.service_context.sys_id	Sys_id of the service context record associated with the install base item record.Data type: String
items.service_organization	Details about the service organization associated with the install base item record. Only returned if the Service Organization (com.snc.service_organization) plugin is installed.Data type: Object Text `"service_organization": { "display_value": "String", "sys_id": "String"}`
items.service_organization.display_value	Text name of the service organization associated with the install base item record. Use this value to display the service organization name in the UI.Data type: String
items.service_organization.sys_id	Sys_id of the service organization record associated with the install base item record.Data type: String
items.sys_class_name	Table containing the install base item record.Data type: String
items.sys_id	Sys_id of the install base item record. Located in the table specified in the sys_class_name parameter.Data type: String
items.sys_mod_count	Number of times that the associated install base item record has been modified.Data type: String
items.state	Details about the current state of the install base item.Data type: Object Text `"state": { "display_value": "String", "value": "String"}`
items.state.display_value	Text string of the current state of the install base item. Use this value to display the state in the UI.Data type: String
items.state.value	Internal value of the state of the install base item.Data type: String
items.status	Details about the status of the install base item.Data type: Object Text `"status": { "display_value": "String", "value": "String"}`
items.status.display_value	Text string of the status of the install base item. Use this value to display the status in the UI.Data type: String
items.status.value	Internal value of the status of the install base item.Data type: String
items.uninstall_date	Details about the date when the install base item became inactive.Data type: Object Text `"uninstall_date": { "display_value": "String", "value": "String"}`
items.uninstall_date.display_value	Text uninstall date. Use this value to display the uninstall date in the UI.Data type: String
items.uninstall_date.value	Internal value of the uninstall date.Data type: String
status	Status of the endpoint call.Data type: String
sysparm_depth	Number of levels deep the returned child install base item is in the hierarchy.Data type: Integer
sysparm_limit	Number of records that were returned. If this value isn't specified in the original request, it uses the default value.Data type: Number
sysparm_offset	Offset (starting point) in the associated table from which records were evaluated and retrieved.Data type: String

### cURL request

The following code example shows how to call this endpoint.

Shell

curl "https://instance.servicenow.com/api/sn_install_base/integrations/installbaseitems/767f34d378d21110f877d304c76fdd2a/childinstallbaseitems?sysparm_limit=1" \--request GET \--header "Accept:application/json" \--user 'username':'password'

Return results:

JSON

{  "result": {    "sysparm_offset": 0,    "sysparm_limit": 1,    "has_more": true,    "items": [      {        "parent": {          "sys_id": "767f34d378d21110f877d304c76fdd2a",          "display_value": "X5 Sport Utility 4D"        },        "sys_class_name": "sn_install_base_item",        "number": "IBITM0001005",        "sys_id": "0704dfcc39265110f87734024cfbc222",        "state": {          "value": "in_use",          "display_value": "In Use"        },        "consumer": {          "sys_id": "bab5139ab3401010700b4d43c6a8dc41",          "display_value": "Charles Barkley"        },        "product": {          "sys_id": "56c84f0439265110f87734024cfbc233",          "display_value": "Electric Power-Assist Speed-Sensing Steering"        },        "active": "true",        "name": "Electric Power-Assist Speed-Sensing Steering",        "status": {          "value": "original",          "display_value": "Original"        }      }    ],    "status": "SUCCESS"  }}

Install Base Item - GET /sn_install_base/integrations/installbaseitems/{id}/contracts

Returns the contracts associated with a specified install base item record.

URL format

Versioned URL: /api/sn_install_base/{api_version}/integrations/installbaseitems/{id}/contracts

Default URL: /api/sn_install_base/integrations/installbaseitems/{id}/contracts

Note: Available versions are specified in the REST API Explorer. For scripted REST APIs there is additional version information on the Scripted REST Service form.

Supported request 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

Sys_id of the install base item record.Data type: String

Table: Install Base Item [sn_install_base_item]

Name	Description
field name-value pairs	Field-value pairs to use to filter the contract records. By default this references the fields in the Contract [ast_contract] table. If you specify a different table in sys_class_name, then specify the fields in that table.You can pass one or more field-value pairs to filter the return results. For example, to return only records where the renewable field is set to "true", pass the follow: `&renewable=true`. Data type: String Default: All fields
sys_class_name	If using an extended contracts table (not ast_contract), the name of the extended table to query.Data type: String Default: ast_contract
sysparm_limit	Maximum number of records to return. For requests that exceed this number of records, use the sysparm_offset parameter to paginate record retrieval. This limit is applied before ACL evaluation. If no records return, including records you have access to, rearrange the record order so records you have access to return first. Note: Unusually large sysparm_limit values can impact system performance. Data type: Number Default: 10000
sysparm_offset	Starting record index for which to begin retrieving records. Use this value to paginate record retrieval. This functionality enables the retrieval of all records, regardless of the number of records, in small manageable chunks. For example, the first time you call this endpoint, sysparm_offset is set to "0". To simply page through all available records, use `sysparm_offset=sysparm_offset+sysparm_limit`, until you reach the end of all records. Don't pass a negative number in the sysparm_offset parameter.Data type: Number Default: 0

|Name|Description| |----|-----------| |None| |

Headers

Header	Description
Accept	Data format of the response body. Supported types: application/json or application/xml. Default: application/json

|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.

Status code	Description
200	Successful. The request was successfully processed.
400	Bad Request. A bad request type or malformed request was detected.
403	Forbidden. The user doesn't have access rights to the specified record.
404	Not found. The requested item wasn't found.
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)

Name	Description
contracts	List of the contracts associated with the specified install base item record.Data type: Array of Object CSS "contracts": [ { "active": "String", "approver": {Object}, "commitment": "String", "consumer": {Object}, "cost_adjustment": "String", "cost_adjustment_percentage": "String", "cost_per_unit": "String", "contract_composite": "String", "ends": "String", "expiration": {Object}, "lifetime_cost": "String", "monthly_cost": "String", "number": "String", "payment_amount": "String", "payment_schedule": {Object}, "ratecard": "String", "renewable": "String", "sales_tax": "String", "short_description": "String", "starts": "String", "state": {Object}, "sub_total_cost": "String", "sys_class_name": "String", "sys_domain_path": "String", "sys_id": "String", "tax_cost": "String", "tax_exempt": "String", "tax_rate": "String", "total_cost": "String", "vendor_contract": "String", "yearly_cost": "String" }]
contracts.active	Flag that indicates whether the contract is active.Possible values: true: Contract is active. false: Contract is inactive. Data type: Boolean string
contracts.approver	Details about the person authorized to approve the contract.Data type: Object Text `"approver": { "display_value": "String", "sys_id": "String"}`
contracts.approver.display_value	Text name of the approver associated with the contracts record. Use this value to display the approver name in the UI.Data type: String
contracts.approver.sys_id	Sys_id of the approver record associated with the contracts record.Data type: String
contracts.consumer	Details about the consumer associated with the contracts record.Note: The consumer field is only available if the B2B2C plugin is installed. Data type: Object Text `"consumer": { "display_value": "String", "sys_id": "String"}`
contracts.consumer.display_value	Text name of the consumer associated with the contracts record. Use this value to display the consumer name in the UI.Data type: String
contracts.consumer.sys_id	Sys_id of the consumer record associated with the contracts record.Data type: String
contracts.cost_adjustment	Type of cost adjustment applied to the contract.Possible values: Fixed Manual CPI (consumer price index) Data type: String
contracts.cost_adjustment_percentage	Percentage increase or decrease in price of contract. To indicate a decrease in price, enter a negative percentage. Either a Cost adjustment or Cost adjustment percentage can be specified, but not both.Data type: String
contracts.cost_per_unit	Cost per unit from the product provider.Data type: String
contracts.ends	Date that the contract terminates.Data type: String
contracts.expiration	Details about the expiration status of the associated contract.Data type: Object Text `"expiration": { "display_value": "String", "sys_id": "String"}`
contracts.expiration.display_value	Expiration status of the associated contract. Use this value to display the expiration status in the UI.Data type: String
contracts.expiration.sys_id	Sys_id of the expiration record associated with the contracts record.Data type: String
contracts.lifetime_cost	Lifetime cost of the contract.Data type: String
contracts.monthly_cost	Monthly cost of the contract.Data type: String
contracts.number	Contract number.Data type: String
contracts.payment_amount	Amount of money that has been directly paid to the receiving party of this contract.Data type: String
contracts.payment_schedule	Details about the payment schedule associated with the contract.Data type: Object Text `"payment_schedule": { "display_value": "String", "sys_id": "String"}`
contracts.payment_schedule.display_value	Payment schedule for the associated contract. Use this value to display the payment schedule in the UI.Data type: String
contracts.payment_schedule.value	Internal value of the payment schedule for this contract, such as daily, weekly, or monthly.Data type: String
contracts.ratecard	Flag that indicates whether there's a rate card associated with this contract.Possible values: true: Rate card. false: No rate card. Data type: Boolean string Table: Rate Care [fm_contract_rate_card]
contracts.renewable	Flag that indicates whether the contract is renewable.Possible values: true: Contract is renewable. false: Contract isn't renewable. Data type: Boolean string
contracts.sales_tax	Flag that indicates whether sales tax is charged for items referenced by this contract.Possible values: true: Sales tax is charged. false: No sales tax is charged. Data type: Boolean string
contracts.short_description	Brief description of the contract.Data type: String
contracts.starts	Date that the contract begins.Data type: String
contracts.state	Details about the current state of the contract.Data type: Object Text `"state": { "display_value": "String", "value": "String"}`
contracts.state.display_value	Text string of the current state of the contract. Use this value to display the state in the UI.Data type: String
contracts.state.value	Internal value or the state of the contract.Data type: String
contracts.sub_total_cost	Subtotal of the cost of the contract.Data type: String
contracts.sys_class_name	Table containing the contract record.Data type: String
contracts.sys_domain_path	Path to the domain in which this contract is available. Data type: String Default: "/" = Global domain
contracts.sys_id	Sys_id of the associated contract record.Data type: String
contracts.tax_cost	Total tax on the contract.This field is visible only if the applicable taxes field is selected as `Sales`. Data type: String
contracts.tax_exempt	Flag that indicates whether the items associated with this contract are tax exempt.Possible values: true: Items are tax exempt. false: Items aren't tax exempt. Data type: Boolean string
contracts.tax_rate	Tax rate charged for taxable items associated with the contract.Data type: String
contracts.total_cost	Final cost of the contract after adjustments have been applied. If a contract has one or more rate cards, this field shows the combined value of all rate cards.Data type: String
contracts.vendor_contract	Vendor's contract number.Data type: String
contracts.yearly_cost	Cost per year of the contract.Data type: String
error	Details about the error that occurred when trying to process the request.Data type: Object Text `"error": { "detail": "String", "message": "String"}`
error.detail	Additional details about the associated error.Data type: String
error.message	Error message that describes the problem that occurred when trying to execute the request.Data type: String
has_more	Flag that indicates whether there are more records in the table to return.Possible values: true: More records to return. false: No more records to return. Data type: Boolean string
status	Status of the endpoint call.Data type: String
sysparm_limit	Number of records that were returned. If this value isn't specified in the original request, it uses the default value.Data type: Number
sysparm_offset	Offset (starting point) in the associated table from which records were evaluated and retrieved.Data type: String

### cURL request

The following code example shows how to call this endpoint.

Shell

curl "https://instance.servicenow.com/api/sn_install_base/integrations/installbaseitems/167e96f053961910539dddeeff7b1298/contracts" \--request GET \--header "Accept:application/json" \--user 'username':'password'

Return results:

JSON

{  "result": {    "sysparm_offset": 0,    "sysparm_limit": 10,    "has_more": false,    "contracts": [      {        "cost_adjustment_percentage": "0",        "total_cost": "0",        "cost_adjustment": "0",        "tax_rate": "7.75",        "number": "CNTR0000701",        "tax_cost": "0",        "sub_total_cost": "0",        "state": {          "value": "expired",          "display_value": "Expired"        },        "starts": "2016-07-01",        "contract_composite": "CoolMate KL300 1 year Limited Warranty\n\t\tCNTR0000701",        "tax_exempt": "false",        "yearly_cost": "0",        "active": "true",        "payment_amount": "0",        "commitment": "0",        "sys_domain_path": "/",        "payment_schedule": {          "value": "Monthly",          "display_value": "Monthly"        },        "renewable": "true",        "expiration": {          "sys_id": "c752e78ec3103000c111113e5bba8f3a",          "display_value": "Expired"        },        "short_description": "CoolMate KL300 1 year Limited Warranty\n\t\t",        "ratecard": "false",        "sys_class_name": "ast_contract",        "sys_id": "3f9db778c3302200e7c7d44d81d3ae0a",        "ends": "2017-06-30",        "consumer": {          "sys_id": "59e788fbdb1b1200b6075200cf9619d2",          "display_value": "Gilly Parker"        },        "approver": {          "sys_id": "f2c0b27247702000cdd1706eecde27c8",          "display_value": "Software Manager"        },        "monthly_cost": "0",        "vendor_contract": "CNTR0000701",        "lifetime_cost": "0",        "sales_tax": "true",        "cost_per_unit": "0"      }    ],    "status": "SUCCESS"  }}

Install Base Item - GET /sn_install_base/integrations/installbaseitems/{id}/entitlements

Returns the entitlements associated with a specified install base item record.

URL format

Versioned URL: /api/sn_install_base/{api_version}/integrations/installbaseitems/{id}/entitlements

Default URL: /api/sn_install_base/integrations/installbaseitems/{id}/entitlements

Note: Available versions are specified in the REST API Explorer. For scripted REST APIs there is additional version information on the Scripted REST Service form.

Supported request 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

Sys_id of the install base item record.Data type: String

Table: Install Base Item [sn_install_base_item]

Name	Description
field name-value pairs	Field-value pairs to use to filter the entitlements records. By default this references the fields in the Entitlement [service_entitlement] table. If you specify a different table in sys_class_name, then specify the fields in that table.You can pass one or more field-value pairs to filter the return results. For example, to return only records that are active, pass the following: `&active=true`. Data type: String Default: All fields
sys_class_name	If using an extended entitlements table (not service_entitlement), the name of the extended table to query.Data type: String Default: service_entitlement
sysparm_limit	Maximum number of records to return. For requests that exceed this number of records, use the sysparm_offset parameter to paginate record retrieval. This limit is applied before ACL evaluation. If no records return, including records you have access to, rearrange the record order so records you have access to return first. Note: Unusually large sysparm_limit values can impact system performance. Data type: Number Default: 10000
sysparm_offset	Starting record index for which to begin retrieving records. Use this value to paginate record retrieval. This functionality enables the retrieval of all records, regardless of the number of records, in small manageable chunks. For example, the first time you call this endpoint, sysparm_offset is set to "0". To simply page through all available records, use `sysparm_offset=sysparm_offset+sysparm_limit`, until you reach the end of all records. Don't pass a negative number in the sysparm_offset parameter.Data type: Number Default: 0

|Name|Description| |----|-----------| |None| |

Headers

Header	Description
Accept	Data format of the response body. Supported types: application/json or application/xml. Default: application/json

|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.

Status code	Description
200	Successful. The request was successfully processed.
400	Bad Request. A bad request type or malformed request was detected.
403	Forbidden. The user doesn't have access rights to the specified record.
404	Not found. The requested item wasn't found.
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)

Name	Description
entitlements	List of the entitlements associated with the specified install base item record.Data type: Object CSS `"entitlements": { "account": {Object}, "active": "String", "business_hour": {Object}, "contract": {Object}, "end_date": "String", "entitlement_name": "String", "install_base_item": {Object}, "per_unit": "String", "start_date": "String", "sys_id": "String", "total_units": "String", "remaining_units": "String", "unit": {Object} }`
entitlements.account	Details about the account associated with the entitlements record.Data type: Object Text `"account": { "display_value": "String", "sys_id": "String"}`
entitlements.account.display_value	Text name of the account associated with the entitlements record. Use this value to display the account name in the UI.Data type: String
entitlements.account.sys_id	Sys_id of the account record associated with the entitlements record.Data type: String
entitlements.active	Flag that indicates whether the entitlement is active.Possible values: 0: Entitlement isn't active. 1: Entitlement is active. Data type: String Default: 1
entitlements.business_hour	Details about the business hours for the entitlements record.Data type: Object Text `"business_hour": { "display_value": "String", "sys_id": "String"}`
entitlements.business_hour.display_value	Text name of the business hours record associated with the entitlements record. Use this value to display the business hours in the UI.Data type: String
entitlements.business_hour.sys_id	Sys_id of the business hours record associated with the entitlements record.Data type: String
entitlements.contract	Details about the contract associated with the entitlement record.Data type: Object Text `"contract": { "display_value": "String", "sys_id": "String"}`
entitlements.contract.display_value	Text name of the contract associated with the entitlement record. Use this value to display the contract name in the UI.Data type: String
entitlements.contract.sys_id	Sys_id of the contract record associated with the entitlement record.Data type: String
entitlements.end_date	End date of the entitlement.Data type: String
entitlements.entitlement_name	Name of the entitlement.Data type: String
entitlements.install_base_item	Details about the install base item associated with the entitlements record.Data type: Object Text `"install_base_item": { "display_value": "String", "sys_id": "String"}`
entitlements.install_base_item.display_value	Text name of the install base item associated with the entitlements record. Use this value to display the install base item name in the UI.Data type: String
entitlements.install_base_item.sys_id	Sys_id of the install base item record associated with the entitlements record.Data type: String
entitlements.per_unit	Number of products in a unit. For example, if the unit is `case`, this value would be 12 if there are 12 items per case.Data type: String
entitlements.start_date	Start date of the entitlement.Data type: String
entitlements.sys_id	Sys_id of the associated entitlements record.Data type: String
entitlements.total_units	Number of units that were originally available.Data type: String
entitlements.remaining_units	Number of units that are remaining.Data type: String
entitlements.unit	Details about the unit of the item associated with the entitlements record.Data type: Object Text `"unit": { "display_value": "String", "value": "String"}`
entitlements.unit.display_value	Text name of the unit of the item associated with the entitlements record. Use this value to display the unit name in the UI.Data type: String
entitlements.unit.value	Internal name of the unit of the item associated with the entitlements record.Data type: String
error	Details about the error that occurred when trying to process the request.Data type: Object Text `"error": { "detail": "String", "message": "String"}`
error.detail	Additional details about the associated error.Data type: String
error.message	Error message that describes the problem that occurred when trying to execute the request.Data type: String
has_more	Flag that indicates whether there are more records in the table to return.Possible values: true: More records to return. false: No more records to return. Data type: Boolean string
status	Status of the endpoint call.Data type: String
sysparm_limit	Number of records that were returned. If this value isn't specified in the original request, it uses the default value.Data type: Number
sysparm_offset	Offset (starting point) in the associated table from which records were evaluated and retrieved.Data type: String

### cURL request

The following code example shows how to call this endpoint.

Shell

curl "https://instance.servicenow.com/api/sn_install_base/integrations/installbaseitems/42746a3b876121100b6afc86dabb3597/entitlements" \--request GET \--header "Accept:application/json" \--user 'username':'password'

Return results:

JSON

{  "result": {    "sysparm_offset": 0,    "sysparm_limit": 10,    "has_more": false,    "entitlements": [      {        "end_date": "2023-04-28",        "remaining_units": "4978",        "business_hour": {          "sys_id": "08fcd0830a0a0b2600079f56b1adb9ae",          "display_value": "8-5 weekdays"        },        "entitlement_name": "Entitlement",        "sys_id": "7206095d87f121105d0055373cbb3504",        "total_units": "5000",        "start_date": "2023-03-27",        "contract": {          "sys_id": "495e16b96f0731003b3c498f5d3ee4af",          "display_value": "CNTR0000603"        },        "active": "1",        "install_base_item": {          "sys_id": "42746a3b876121100b6afc86dabb3597",          "display_value": "KX Series - KX5000"        },        "unit": {          "value": "cases",          "display_value": "Cases"        },        "per_unit": "0",        "account": {          "sys_id": "86837a386f0331003b3c498f5d3ee4ca",          "display_value": "Boxeo"        }      }    ],    "status": "SUCCESS"  }}

Install Base Item - GET /sn_install_base/integrations/installbaseitems/{id}/maintenanceplans

Returns the maintenance plans associated with a specified install base item record.

URL format

Versioned URL: /api/sn_install_base/{api_version}/integrations/installbaseitems/{id}/maintenanceplans

Default URL: /api/sn_install_base/integrations/installbaseitems/{id}/maintenanceplans

Note: Available versions are specified in the REST API Explorer. For scripted REST APIs there is additional version information on the Scripted REST Service form.

Supported request 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

Sys_id of the install base item record.Data type: String

Table: Install Base Item [sn_install_base_item]

Name	Description
field name-value pairs	Field-value pairs to use to filter the maintenance plan records. By default this references the fields in the Maintenance Plan [sm_maint_plan] table. If you specify a different table in sys_class_name, then specify the fields in that table.You can pass one or more field-value pairs to filter the return results. For example, to return only records that are active, pass the follow: `&active=true`. Data type: String Default: All fields
sys_class_name	If using an extended maintenance plans table (not maintenanceplans), the name of the extended table to query.Data type: String Default: maintenanceplans
sysparm_limit	Maximum number of records to return. For requests that exceed this number of records, use the sysparm_offset parameter to paginate record retrieval. This limit is applied before ACL evaluation. If no records return, including records you have access to, rearrange the record order so records you have access to return first. Note: Unusually large sysparm_limit values can impact system performance. Data type: Number Default: 10000
sysparm_offset	Starting record index for which to begin retrieving records. Use this value to paginate record retrieval. This functionality enables the retrieval of all records, regardless of the number of records, in small manageable chunks. For example, the first time you call this endpoint, sysparm_offset is set to "0". To simply page through all available records, use `sysparm_offset=sysparm_offset+sysparm_limit`, until you reach the end of all records. Don't pass a negative number in the sysparm_offset parameter.Data type: Number Default: 0

|Name|Description| |----|-----------| |None| |

Headers

Header	Description
Accept	Data format of the response body. Supported types: application/json or application/xml. Default: application/json

|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.

Status code	Description
200	Successful. The request was successfully processed.
400	Bad Request. A bad request type or malformed request was detected.
403	Forbidden. The user doesn't have access rights to the specified record.
404	Not found. The requested item wasn't found.
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)

Name	Description
error	Details about the error that occurred when trying to process the request.Data type: Object Text `"error": { "detail": "String", "message": "String"}`
error.detail	Additional details about the associated error.Data type: String
error.message	Error message that describes the problem that occurred when trying to execute the request.Data type: String
has_more	Flag that indicates whether there are more records in the table to return.Possible values: true: More records to return. false: No more records to return. Data type: Boolean string
maintenanceplans	List of the maintenance plans associated with the specified install base item record.Data type: Array of Object CSS `"maintenanceplans": [ { "active": "String", "apply_to_new": "String", "allow_future_wo": "String", "maintenance_override_policy": {Object}, "model": "String", "name": "String", "number": "String", "propagation_flag": "String", "sys_class_name": "String", "sys_id": "String", "table": "String", "type": {Object} }]`
maintenanceplans.active	Flag that indicates whether the maintenance plan is active.Possible values: true: Maintenance plan is active. false: Maintenance plan is inactive. Data type: String
maintenanceplans.apply_to_new	Flag that indicates whether the schedules defined for this maintenance plan are applied to all records that have been added to the specified table since the last time the plan was executed, and that they meet the conditions entered in the Filter condition. Possible values: true: Applied to all new record. false:Not applied to all new records. Data type: String
maintenanceplans.allow_future_wo	Flag that indicates whether work orders can be associated with the maintenance plan.Possible values: true: New work orders can be associated. false: No new work orders can be associated. Data type: String
maintenanceplans.maintenance_override_policy	Details about the maintenance override policy for the maintenance plan.Data type: Object Text `"maintenance_override_policy": { "display_value": "String", "value": "String"}`
maintenanceplans.maintenance_override_policy.display_value	Text string describing the override policy. Use this value to display the override policy in the UI.Data type: String
maintenanceplans.maintenance_override_policy.value	Internal value of the override policy.Data type: String
maintenanceplans.model	Sys_id of the model record associated with the maintenance plan.Data type: String
maintenanceplans.number	Maintenance plan number.Data type: String
maintenanceplans.propagation_flag	Flag that indicates whether the maintenance plan can be propagated.Possible values: true: Maintenance plan can be propagated. false: Maintenance plan can't be propagated. Data type: String
maintenanceplans.sys_class_name	Table containing the maintenance plan record.Data type: String
maintenanceplans.sys_id	Sys_id of the associated maintenance plan.Data type: String
maintenanceplans.table	Table that contains the associated install base time record.Data type: String
maintenanceplans.type	Details about the type of maintenance plan.Data type: Object Text `"type": { "display_value": "String", "value": "String"}`
maintenanceplans.type.display_value	Text string describing the maintenance plan type. Use this value to display the type in the UI.Data type: String
maintenanceplans.type.value	Internal value of the maintenance plan type.Data type: String
status	Status of the endpoint call.Data type: String
sysparm_limit	Number of records that were returned. If this value isn't specified in the original request, it uses the default value.Data type: Number
sysparm_offset	Offset (starting point) in the associated table from which records were evaluated and retrieved.Data type: String

### cURL request

The following code example shows how to call this endpoint.

Shell

curl "https://instance.servicenow.com/api/sn_install_base/integrations/installbaseitems/167e96f053961910539dddeeff7b1298/maintenanceplans" \--request GET \--header "Accept:application/json" \--user 'username':'password'

Return results:

JSON

{  "result": {    "sysparm_offset": 0,    "sysparm_limit": 1,    "has_more": true,    "maintenanceplans": [      {        "propagation_flag": "false",        "active": "true",        "type": {          "value": "install_base",          "display_value": "Install base"        },        "maintenance_override_policy": {          "value": "do_nothing",          "display_value": "Leave alone"        },        "sys_class_name": "wm_planned_work_plan",        "allow_future_wo": "true",        "sys_id": "0b809d70877561105d0055373cbb357f",        "number": "WP0001026",        "name": "Plan 10",        "model": "8583ce8237732000158bbfc8bcbe5dd9",        "apply_to_new": "true",        "table": "sn_install_base_item"      }    ],    "status": "SUCCESS"  }}

Install Base Item - GET /sn_install_base/integrations/installbaseitems/{id}/relatedparties

Returns the related parties associated with a specified install base item record.

URL format

Versioned URL: /api/sn_install_base/{api_version}/integrations/installbaseitems/{id}/relatedparties

Default URL: /api/sn_install_base/integrations/installbaseitems/{id}/relatedparties

Note: Available versions are specified in the REST API Explorer. For scripted REST APIs there is additional version information on the Scripted REST Service form.

Supported request 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

Sys_id of the install base item record.Data type: String

Table: Install Base Item [sn_install_base_item]

Name	Description
field name-value pairs	Field-value pairs to use to filter the related parties records. By default this references the fields in the Related Parties [sn_install_base_related_party] table. If you specify a different table in sys_class_name, then specify the fields in that table.You can pass one or more field-value pairs to filter the return results. For example, if you wanted to filter on a specific account and responsible party, pass the sys_ids of the two records: `&account=86837a386f0331003b3c498f5d3ee4ca&responsibility=c009bbedb3730010700b4d43c6a8dcef`. Data type: String Default: All fields
sys_class_name	If using an extended related parties table (not sn_install_base_related_party), the name of the extended table to query.Data type: String Default: sn_install_base_related_party
sysparm_limit	Maximum number of records to return. For requests that exceed this number of records, use the sysparm_offset parameter to paginate record retrieval. This limit is applied before ACL evaluation. If no records return, including records you have access to, rearrange the record order so records you have access to return first. Note: Unusually large sysparm_limit values can impact system performance. Data type: Number Default: 10000
sysparm_offset	Starting record index for which to begin retrieving records. Use this value to paginate record retrieval. This functionality enables the retrieval of all records, regardless of the number of records, in small manageable chunks. For example, the first time you call this endpoint, sysparm_offset is set to "0". To simply page through all available records, use `sysparm_offset=sysparm_offset+sysparm_limit`, until you reach the end of all records. Don't pass a negative number in the sysparm_offset parameter.Data type: Number Default: 0

|Name|Description| |----|-----------| |None| |

Headers

Header	Description
Accept	Data format of the response body. Supported types: application/json or application/xml. Default: application/json

|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.

Status code	Description
200	Successful. The request was successfully processed.
400	Bad Request. A bad request type or malformed request was detected.
403	Forbidden. The user doesn't have access rights to the specified record.
404	Not found. The requested item wasn't found.
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)

Name	Description
error	Details about the error that occurred when trying to process the request.Data type: Object Text `"error": { "detail": "String", "message": "String"}`
error.detail	Additional details about the associated error.Data type: String
error.message	Error message that describes the problem that occurred when trying to execute the request.Data type: String
has_more	Flag that indicates whether there are more records in the table to return.Possible values: true: More records to return. false: No more records to return. Data type: Boolean string
relatedparties	List of the related parties associated with the specified install base item record.Data type: Array of Objects CSS `"relatedparties": [ { "account": {Object}, "consumer": {Object}, "contact": {Object}, "install_base_item": {Object}, "responsibility": {Object}, "service_organization": {Object}, "sys_class_name": "String", "sys_id": "String", "type": {Object}, "user": {Object} }]`
relatedparties.account	Details about the account associated with the related parties record.Data type: Object Text `account": { "display_value": "String", "sys_id": "String"}`
relatedparties.account.display_value	Text name of the account associated with the related parties record. Use this value to display the account name in the UI.Data type: String
relatedparties.account.sys_id	Sys_id of the account record associated with the related parties record.Data type: String
relatedparties.consumer	Details about the consumer associated with the related parties record.Data type: Object Text `"consumer": { "display_value": "String", "sys_id": "String"}`
relatedparties.consumer.display_value	Text name of the consumer associated with the related parties record. Use this value to display the consumer name in the UI.Data type: String
relatedparties.consumer.sys_id	Sys_id of the consumer record associated with the related parties record.Data type: String
relatedparties.contact	Details about the account contact responsible for the related parties record.Data type: Object Text `"contact": { "display_value": "String", "sys_id": "String"}`
relatedparties.contact.display_value	Text name of the contact associated with the related parties record. Use this value to display the contact name in the UI.Data type: String
relatedparties.contact.sys_id	Sys_id of the contact record associated with the related parties record.Data type: String Table: Contact [customer_contact]
relatedparties.install_base_item	Details about the install base item associated with the related parties record.Data type: Object Text `"install_base_item": { "display_value": "String", "sys_id": "String"}`
relatedparties.install_base_item.display_value	Text name of the install base item associated with the related parties record. Use this value to display the install base item name in the UI.Data type: String
relatedparties.install_base_item.sys_id	Sys_id of the install base item record associated with the related parties record.Data type: String
relatedparties.responsibility	Details about the access level for the install base information. Data type: Object Text `"responsibility": { "display_value": "String", "sys_id": "String"}`
relatedparties.responsibility.display_value	Text display value for the access level for the install base information.Data type: String
relatedparties.responsibility.sys_id	Sys_id of the associated responsibility record. This record defines the access level for the install base information.This parameter is only valid if the related_party field is also specified. If specified, it only returns the install base items that match both the related_party and responsibility parameters. For additional information, see Configure related parties for Items Received Data type: String Table: Responsibility Definition [sn_customerservice_responsibility_def]
relatedparties.service_organization	Details about the service organization associated with the related parties record.Data type: Object Text `"service_organization": { "display_value": "String", "sys_id": "String"}`
relatedparties.service_organization.display_value	Text name of the service organization associated with the related parties record. Use this value to display the service organization name in the UI.Data type: String
relatedparties.service_organization.sys_id	Sys_id of the service organization record associated with the related parties record.Data type: String Table: Service Organization [sn_customer_service_organization]
relatedparties.sys_class_name	Table containing the related parties record.Data type: String Default: sn_install_base_related_party
relatedparties.sys_id	Sys_id of the associated related parties record.Data type: String
relatedparties.type	Details about the type of contact associated with the related parties record.Data type: Object Text `"type": { "display_value": "String", "sys_id": "String"}`
relatedparties.type.display_value	Text name of the type of contact associated with the related parties record. Use this value to display the type of contact in the UI. For additional information, see Create related party configurations.Possible types: Authorized Account Authorized Consumer Authorized Contact Authorized Contributor Authorized Member Authorized Service Organization Listed Account Listed Consumer Listed Contact Listed Contributor Listed Member Listed Service Organization Data type: String
relatedparties.type.sys_id	Sys_id of the type record associated with the related parties record.Data type: String
relatedparties.user	Details about the user associated with the related parties record.Data type: Object Text `"user": { "display_value": "String", "sys_id": "String"}`
relatedparties.user.display_value	Text name of the user associated with the related parties record. Use this value to display the user name in the UI.Data type: String
relatedparties.user.sys_id	Sys_id of the user record associated with the related parties record. Data type: String Table: User [sys_user]
status	Status of the endpoint call.Data type: String
sysparm_limit	Number of records that were returned. If this value isn't specified in the original request, it uses the default value.Data type: Number
sysparm_offset	Offset (starting point) in the associated table from which records were evaluated and retrieved.Data type: String

### cURL request

The following code example shows how to call this endpoint.

Shell

curl "https://instance.servicenow.com/api/sn_install_base/integrations/installbaseitems/42746a3b876121100b6afc86dabb3597/relatedparties" \--request GET \--header "Accept:application/json" \--user 'username':'password'

Return results:

JSON

  "result": {    "sysparm_offset": 0,    "sysparm_limit": 10,    "has_more": false,    "relatedparties": [      {        "type": {          "sys_id": "68ec8b2965e99110f87764df53db779f",          "display_value": "Authorized Contact"        },        "install_base_item": {          "sys_id": "42746a3b876121100b6afc86dabb3597",          "display_value": "KX Series - KX5000"        },        "sys_class_name": "sn_install_base_related_party",        "sys_id": "8547774087f561100b6afc86dabb351a",        "responsibility": {          "sys_id": "c009bbedb3730010700b4d43c6a8dcef",          "display_value": "Authorized Representative"        },        "contact": {          "sys_id": "dc0185d94f341200025ba3618110c77c",          "display_value": "Cindy Contact"        },        "account": {          "sys_id": "86837a386f0331003b3c498f5d3ee4ca",          "display_value": "Boxeo"        }      }    ],    "status": "SUCCESS"  }}

Install Base Item - GET /sn_install_base/integrations/installbaseitems/{id}/soldproducts

Returns the sold products records associated with a specified install base item record.

URL format

Versioned URL: /api/sn_install_base/{api_version}/integrations/installbaseitems/{id}/soldproducts

Default URL: /api/sn_install_base/integrations/installbaseitems/{id}/soldproducts

Note: Available versions are specified in the REST API Explorer. For scripted REST APIs there is additional version information on the Scripted REST Service form.

Supported request 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

Sys_id of the install base item record.Data type: String

Table: Install Base Item [sn_install_base_item]

Name	Description
field name-value pairs	Field-value pairs to use to filter the related parties records. By default this references the fields in the Sold Products [sn_install_base_sold_product] table. If you specify a different table in sys_class_name, specify the fields in that table.You can pass one or more field-value pairs to filter the return results. For example, if you wanted to filter on the products sold to a specific account, pass something similar to the following, where the passed value is the sys_id of the account: `&account=86837a386f0331003b3c498f5d3ee4ca`. Data type: String Default: All fields
sys_class_name	If using an extended sold products table (not sn_install_base_sold_product), the name of the extended table to query.Data type: String Default: sn_install_base_sold_product
sysparm_limit	Maximum number of records to return. For requests that exceed this number of records, use the sysparm_offset parameter to paginate record retrieval. This limit is applied before ACL evaluation. If no records return, including records you have access to, rearrange the record order so records you have access to return first. Note: Unusually large sysparm_limit values can impact system performance. Data type: Number Default: 10000
sysparm_offset	Starting record index for which to begin retrieving records. Use this value to paginate record retrieval. This functionality enables the retrieval of all records, regardless of the number of records, in small manageable chunks. For example, the first time you call this endpoint, sysparm_offset is set to "0". To simply page through all available records, use `sysparm_offset=sysparm_offset+sysparm_limit`, until you reach the end of all records. Don't pass a negative number in the sysparm_offset parameter.Data type: Number Default: 0

|Name|Description| |----|-----------| |None| |

Headers

Header	Description
Accept	Data format of the response body. Supported types: application/json or application/xml. Default: application/json

|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.

Status code	Description
200	Successful. The request was successfully processed.
400	Bad Request. A bad request type or malformed request was detected.
403	Forbidden. The user doesn't have access rights to the specified record.
404	Not found. The requested item wasn't found.
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)

Name	Description
error	Details about the error that occurred when trying to process the request.Data type: Object Text `"error": { "detail": "String", "message": "String"}`
error.detail	Additional details about the associated error.Data type: String
error.message	Error message that describes the problem that occurred when trying to execute the request.Data type: String
has_more	Flag that indicates whether there are more records in the table to return.Possible values: true: More records to return. false: No more records to return. Data type: Boolean string
soldproducts	List of the sold products associated with the specified install base item record.Data type: Array of Objects CSS `"soldproducts":[ { "account": {Object}, "contact": {Object}, "name": "String", "number": "String", "product": {Object}, "sys_class_name": "String", "sys_id": "String", "state": {Object} }]`
soldproducts.account	Details about the account associated with the product record.Data type: Object Text `account": { "display_value": "String", "sys_id": "String"}`
soldproducts.account.display_value	Text name of the account associated with the product record. Use this value to display the account name in the UI.Data type: String
soldproducts.account.sys_id	Sys_id of the account record associated with the product record.Data type: String
soldproducts.contact	Details about the account contact responsible for the product.Data type: Object Text `"contact": { "display_value": "String", "sys_id": "String"}`
soldproducts.contact.display_value	Text name of the contact associated with the product. Use this value to display the contact name in the UI.Data type: String
soldproducts.contact.sys_id	Sys_id of the contact record associated with the product record.Data type: String
soldproducts.name	Name of the product.Data type: String
soldproducts.number	Product number.Data type: String
soldproducts.sys_class_name	Table containing the product record.Data type: String
soldproducts.sys_id	Sys_id of the associated product.Data type: String
soldproducts.state	Details about the current state of the product.Data type: Object Text `"state": { "display_value": "String", "value": "String"}`
soldproducts.state.display_value	Text string of the current state of the product. Use this value to display the state in the UI.Data type: String
soldproducts.state.value	Internal value of the state of the product.Data type: String
status	Status of the endpoint call.Data type: String
sysparm_limit	Number of records that were returned. If this value isn't specified in the original request, it uses the default value.Data type: Number
sysparm_offset	Offset (starting point) in the associated table from which records were evaluated and retrieved.Data type: String

### cURL request

The following code example shows how to call this endpoint.

Shell

curl "https://instance.servicenow.com/api/sn_install_base/integrations/installbaseitems/f77c7542b7343300ece839a6ee11a991/soldproducts?sysparm_limit=1" \--request GET \--header "Accept:application/json" \--user 'username':'password'

Return results:

JSON

{  "result": {    "sysparm_offset": 0,    "sysparm_limit": 1,    "has_more": true,    "soldproducts": [      {        "product": {          "sys_id": "a9a2d0c3c6112276010db16c5ddd3461",          "display_value": "Lenovo ThinkStation S20"        },        "sys_class_name": "sn_install_base_sold_product",        "number": "SLPRD0001008",        "sys_id": "17a3a7128729a1105d0055373cbb35fb",        "contact": {          "sys_id": "ddce70866f9331003b3c498f5d3ee417",          "display_value": "George Warren"        },        "name": "SP B2B",        "state": {          "value": "active",          "display_value": "Active"        },        "account": {          "sys_id": "86837a386f0331003b3c498f5d3ee4ca",          "display_value": "Boxeo"        }      }    ],    "status": "SUCCESS"  }}

Install Base Item - GET /sn_install_base/integrations/installbaseitems/{id}/workorders

Returns the work orders associated with a specified install base item record.

URL format

Versioned URL: /api/sn_install_base/{api_version}/integrations/installbaseitems/{id}/workorders

Default URL: /api/sn_install_base/integrations/installbaseitems/{id}/workorders

Note: Available versions are specified in the REST API Explorer. For scripted REST APIs there is additional version information on the Scripted REST Service form.

Supported request 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

Sys_id of the install base item record.Data type: String

Table: Install Base Item [sn_install_base_item]

Name	Description
field name-value pairs	Field-value pairs to use to filter the related parties records. By default this references the fields in the Sold Products [sn_install_base_sold_product] table. If you specify a different table in sys_class_name, then specify the fields in that table.You can pass one or more field-value pairs to filter the return results. For example, if you wanted to filter on the products sold to a specific account, pass something similar to the following where the passed value is the sys_id of the account: `&account=86837a386f0331003b3c498f5d3ee4ca`. Data type: String Default: All fields
sys_class_name	If using an extended sold products table (not sn_install_base_sold_product), the name of the extended table to query.Data type: String Default: sn_install_base_sold_product
sysparm_limit	Maximum number of records to return. For requests that exceed this number of records, use the sysparm_offset parameter to paginate record retrieval. Note: Unusually large sysparm_limit values can impact system performance. Data type: Number Default: 10
sysparm_offset	Starting record index for which to begin retrieving records. Use this value to paginate record retrieval. This functionality enables the retrieval of all records, regardless of the number of records, in small manageable chunks. For example, the first time you call this endpoint, sysparm_offset is set to "0". To simply page through all available records, use `sysparm_offset=sysparm_offset+sysparm_limit`, until you reach the end of all records. Don't pass a negative number in the sysparm_offset parameter.Data type: Number Default: 0

|Name|Description| |----|-----------| |None| |

Headers

Header	Description
Accept	Data format of the response body. Supported types: application/json or application/xml. Default: application/json

|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.

Status code	Description
200	Successful. The request was successfully processed.
400	Bad Request. A bad request type or malformed request was detected.
403	Forbidden. The user doesn't have access rights to the specified record.
404	Not found. The requested item wasn't found.
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)

Name	Description
error	Details about the error that occurred when trying to process the request.Data type: Object Text `"error": { "detail": "String", "message": "String"}`
error.detail	Additional details about the associated error.Data type: String
error.message	Error message that describes the problem that occurred when trying to execute the request.Data type: String
has_more	Flag that indicates whether there are more records in the table to return.Possible values: true: More records to return. false: No more records to return. Data type: Boolean string
status	Status of the endpoint call.Data type: String
sysparm_limit	Number of records that were returned. If this value isn't specified in the original request, it uses the default value.Data type: Number
sysparm_offset	Offset (starting point) in the associated table from which records were evaluated and retrieved.Data type: String
workorders	List of the work orders associated with the specified install base item record.Data type: Array of Objects CSS "workorders":[ { "active": "String", "approval": {Object}, "billable": "String", "escalation": "String", "has_appointment": "String", "hierarchical_variables": "String", "impact": "String", "install_base_item": {Object}, "is_catalog": "String", "knowledge": "String", "location": {Object}, "made_sla": "String", "needs_attention": "String", "number": "String", "opened_at": {Object}, "opened_by": {Object}, "opened_for": {Object}, "priority": "String", "reassignment_count": "String", "reschedule_maintenance_if_canceled": "String", "short_description": "String", "sla_suspended": "String", "state": "String", "sys_class_name": "String", "sys_domain_path": "String" "sys_id": "String", "task_created": "String", "task_effective_number": "String", "template_workflow_invoked": "String", "upon_approval": {Object}, "upon_reject": {Object}, "urgency": "String" }]
workorders.active	Flag that indicates whether the work order is active.Possible values: true: Work order is active. false: Work order is inactive. Data type: Boolean string
workorders.approval	Details about the current approval process for the work order.Data type: Object Text `"approval": { "display_value": "String", "value": "String"}`
workorders.approval.display_value	Text string of the current state of the approval process. Use this value to display the approval state in the UI.Data type: String
workorders.approval.value	Internal value of the state of the approval process.Data type: String
workorders.billable	Flag that indicates whether the work order is billable.Possible values: true: Work order is billable. false: Work order isn't billable Data type: Boolean string
workorders.escalation	Level of escalation of the work order.Data type: String
workorders.has_appointment	Flag that indicates whether the work order has a scheduled appointment.Possible values: true: Work order has an appointment. false: Work order doesn't have an appointment. Data type: Boolean string
workorders.install_base_item	Details about the install base item associated with the work order record.Data type: Object Text `"install_base_item": { "display_value": "String", "sys_id": "String"}`
workorders.install_base_item.display_value	Text name of the install base item associated with the work order record. Use this value to display the install base item name in the UI.Data type: String
workorders.install_base_item.sys_id	Sys_id of the install base item record associated with the work order record.Data type: String
workorders.is_catalog	Flag that indicates whether is part of a catalog.Possible values: true: Work order is part of a catalog. false: Work order isn't part of a catalog. Data type: Boolean string
workorders.knowledge	Flag that indicates if there's a knowledge base article available for the specified work order issue.Possible values: true: Knowledge base article is available for this issue. false: Knowledge base article isn't available for this issue. Data type: Boolean string
workorders.location	Details about the location of the item that needs to be worked on.Data type: Object Text `"location": { "display_value": "String", "sys_id": "String"}`
workorders.location.display_value	Text name of the location of the item to be worked on. Use this value to display the location in the UI.Data type: String
workorders.location.sys_id	Sys_id of the location record associated with the work order record.Data type: String
workorders.made_sla	Flag that indicates whether the work associated with the work order met the associated Service Level Agreement (SLA).Possible values: true: SLA was met. false: SLA wasn't met. Data type: Boolean string
workorders.needs_attention	Flag that indicates whether this work order needs attention.Possible values: true: Work order needs attention. false: Work order doesn't need attention. Data type: Boolean string
workorders.number	Unique number used to identify the work order.Data type: String
workorders.opened_at	Details about when the work order was opened.Data type: Object Text `"opened_at": { "display_value": "String", "value": "String"}`
workorders.opened_at.display_value	Date and time that the work order was opened. Use this value to display the value in the UI.Data type: String
workorders.opened_at.value	Date and time that the work order was opened.Data type: String
workorders.opened_by	Details about the person that opened the work order.Data type: Object Text `"opened_by": { "display_value": "String", "sys_id": "String"}`
workorders.opened_by.display_value	Text name of the person that opened the work order. Use this value to display this name in the UI.Data type: String
workorders.opened_by.sys_id	Sys_id of the user record of the person that opened the work order. Data type: String
workorders.opened_for	Details about the person that the work order was opened for if different than the opened_by person.Data type: Object Text `"opened_for": { "display_value": "String", "sys_id": "String"}`
workorders.opened_for.display_value	Text name of the person that the work order was opened for. Use this value to display this name in the UI.Data type: String
workorders.opened_for.sys_id	Sys_id of the user record of the person that the work order was opened for. Data type: String
workorders.priority	Priority of the work order.Data type: String
workorders.reassignment_count	Number of times that the work order was reassigned to a person that is responsible for moving the work order forward.Data type: String
workorders.reschedule_maintenance_if_canceled	Flag that indicates whether the work should be rescheduled if the associated work order is canceled.Possible values: true: Reschedule the work. false: Check before rescheduling the work. Data type: Boolean string
workorders.short_description	Brief text that describes the work associated with the work order.Data type: String
workorders.sla_suspended	Flag that indicates whether the SLA associated with the work order has been suspended.Valid values: true: SLA has been suspended. false: SLA hasn't been suspended. Data type: Boolean string
workorders.state	Current state of the work order.Data type: String
workorders.sys_class_name	Table containing the work order record.Data type: String
workorders.sys_domain_path	Domain path.Data type: String
workorders.sys_id	Sys_id of the associated work order record.Data type: String
workorders.task_created	Flag that indicates whether a task has been created for this work order.Possible values: true: Task has been created for this work order. false: Task hasn't been created for this work order. Data type: Boolean string
workorders.task_effective_number	Unique number used to identify the work order.Data type: String
workorders.template_workflow_invoked	Flag that indicates whether the associated workflow has been invoked for this work order.Possible values: true: Workflow has been invoked. false: Worflow hasn't been invoked. Data type: Boolean string
workorders.upon_approval	Details about the next action to take if the work order is approved.Data type: Object Text `"upon_approval": { "display_value": "String", "value": "String"}`
workorders.upon_approval.display_value	Text string of the action to take if the work order is approved. Use this value to display this information in the UI.Data type: String
workorders.upon_approval.value	Action to take if the work order is approved.Possible values: do_nothing proceed Data type: String
workorders.upon_reject	Details about the next action to take if the work order is rejected.Data type: Object Text `"upon_reject": { "display_value": "String", "value": "String"}`
workorders.upon_reject.display_value	Text string of the action to take if the work order is rejected. Use this value to display this information in the UI.Data type: String
workorders.upon_reject.value	Action to take if the work order is rejected.Possible values: cancel goto Data type: String
workorders.urgency	Urgency of the work order.Data type: String

### cURL request

The following code example shows how to call this endpoint.

Shell

curl "https://instance.servicenow.com/api/sn_install_base/integrations/installbaseitems/f77c7542b7343300ece839a6ee11a991/workorders?sysparm_limit=1" \--request GET \--header "Accept:application/json" \--user 'username':'password'

Return results:

JSON

{  "result": {    "sysparm_offset": 0,    "sysparm_limit": 10,    "has_more": false,    "workorders": [      {        "upon_reject": {          "value": "cancel",          "display_value": "Cancel all future Tasks"        },        "number": "WO0010372",        "state": "1",        "template_workflow_invoked": "false",        "knowledge": "false",        "impact": "3",        "active": "true",        "priority": "4",        "sys_domain_path": "/",        "sla_suspended": "false",        "needs_attention": "false",        "short_description": "Test WO1",        "sys_class_name": "wm_order",        "reschedule_maintenance_if_canceled": "true",        "reassignment_count": "0",        "hierarchical_variables": "variable_pool",        "opened_for": {          "sys_id": "85453c616fc331003b3c498f5d3ee4fa",          "display_value": "Jodi Seals"        },        "install_base_item": {          "sys_id": "42746a3b876121100b6afc86dabb3597",          "display_value": "KX Series - KX5000"        },        "has_appointment": "false",        "escalation": "0",        "upon_approval": {          "value": "proceed",          "display_value": "Proceed to Next Task"        },        "spam": "false",        "made_sla": "true",        "is_catalog": "false",        "task_effective_number": "WO0010372",        "opened_by": {          "sys_id": "85453c616fc331003b3c498f5d3ee4fa",          "display_value": "Jodi Seals"        },        "opened_at": {          "value": "2023-03-20 13:33:22",          "display_value": "2023-03-20 06:33:22"        },        "task_created": "false",        "sys_id": "19761cc087b521100b6afc86dabb352f",        "urgency": "3",        "approval": {          "value": "not requested",          "display_value": "Not Yet Requested"        },        "billable": "false",        "location": {          "sys_id": "1cd145bc23070110766713d1d7bf654f",          "display_value": "2866 Stevens Creek Blvd,Santa Clara,CA"        }      }    ],    "status": "SUCCESS"  }}

Install Base Item - PATCH /sn_install_base/integrations/installbaseitems/{id}

Updates a specified install base item record with specified field values.

URL format

Versioned URL: /api/sn_install_base/{api_version}/integrations/installbaseitems/{id}

Default URL: /api/sn_install_base/integrations/installbaseitems/{id}

Note: Available versions are specified in the REST API Explorer. For scripted REST APIs there is additional version information on the Scripted REST Service form.

Supported request 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

|Name|Description| |----|-----------| |None| |

Name	Description
account	Required when creating an install base item for an account.Sys_id of the account to associate with the install base item. Note: If you pass the account parameter, you can't also pass the consumer parameter. Data type: String Table: Account [customer_account]
active	Flag that indicates whether the install base item is active.Valid values: true, "true", or "0": Item is active. false, "false", or "1": Item isn't active. Data type: Boolean Default: true
asset	Sys_id of the asset associated with the install base item record.Data type: String Table: Asset [alm_asset]
child_install_base_items	List of the child install base items associated with this install base item.Note: The following child install base item fields can't be different from its parent: account consumer contact service organization Data type: Array of Objects Text `"child_install_base_items": [ { "name": "String", "product": "String" }]`
child_install_base_items.name	Name of the child install base item.Data type: String
child_install_base_items.product	Sys_id of the associated child base item record.Data type: String Table: Install Base Item [sn_install_base_item]
configuration_item	Sys_id of the configuration item associated with the install base item record.Data type: String Table: Configuration Item [cmdb_ci]
consumer	Required when creating an install base item for a consumer.Sys_id of the consumer associated with the install base item record. Note: If you pass the consumer parameter, you can't also pass the account parameter. In addition, you can only associate a consumer with an install base item if the B2B2C plugin is installed on your instance. Data type: String Table: Consumer [csm_consumer]
consumer_profile	Sys_id of the consumer profile associated with the install base item record.Data type: String Table: Consumer Profile [sn_csm_consumer_profile]
contact	Sys_id of the account contact record that is primarily responsible for the install base item. Note: Contacts can only be specified for account install base items. Data type: String Table: Contact [customer_contact]
household	Sys_id of the household associated with the install base item record.Note: This field is only valid when the Customer Household Data Model (com.snc.household) plugin is installed. Data type: String Table: Household [csm_household]
install_date	Date on which the install base item becomes active.Data type: String Format: yyyy-MM-dd HH:mm:ss
location	Sys_id of the location of the associated product.Data type: String Table: Location [cmn_location]
name	Name of the install base item.Data type: String
number	Unique identifier for the install base item.Data type: String Default: Automatically generated by the endpoint.
parent	Sys_id of the parent record for this install base item record.Data type: String Table: Install Base Item [sn_install_base_item]
product_model	Sys_id of the product model associated with the install base item record.Data type: String Table: Product Model [cmdb_model]
quantity	Number of items installed.Data type: Integer
service_context	Sys_id of the service that is associated to the underlying CI for calculating the impact severity from Event Management. For more information, see Service health status for install base.Note: This field is only valid if the Proactive Customer Service Operations with Event Management plugin is installed. Data type: String
service_organization	Required when creating an install base item for a service organization.Sys_id of the service organization record that is involved in providing service to the customer. Note: If you pass this parameter, you shouldn't also pass the account, contact, or consumer parameters. The service_organization parameter is only available when the Service Organization (com.snc.service_organization) plugin is installed on your instance. Data type: String Table: Service Organization [sn_customer_service_organization]
state	Current state of the install base item.Valid values: in_use inactive Data type: String
status	Status of the product.Valid values: original replacement Data type: String
sys_class_name	Name of the extended install base table in which to update the install base item record.Data type: String
uninstall_date	Date on which the install base becomes inactive.Data type: String Format: yyyy-MM-dd HH:mm:ss

### Headers

Header	Description
Accept	Data format of the response body. Supported types: application/json or application/xml. Default: application/json
Content-Type	Data format of the request body. Supported types: application/json or application/xml. Default: application/json

|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.

Status code	Description
200	Successful. The request was successfully processed.
400	Bad Request. A bad request type or malformed request was detected.
403	Forbidden. The user doesn't have access rights to the specified record.
404	Not found. The requested item wasn't found.
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)

Name	Description
error	Details about the error that occurred when trying to process the request.Data type: Object Text `"error": { "detail": "String", "message": "String"}`
error.detail	Additional details about the associated error.Data type: String
error.message	Error message that describes the problem that occurred when trying to execute the request.Data type: String
item	Details about the install base item that was updated.Data type: Object JavaScript `"item": { "account": {Object}, "active": Boolean, "name": "String", "number": "String", "state": {Object}, "sys_class_name": {Object}, "sys_id": "String"}`
item.account	Details about the customer account associated with the install base item record.Data type: Object Text `"account": { "display_value": "String", "sys_id": "String"}`
item.account.display_value	Text name of the customer account associated with the install base item record. Use this value to display the customer account name in the UI.Data type: String
item.account.sys_id	Sys_id of the customer account record associated with the install base item record.Data type: String
item.active	Flag that indicates whether the install base item is active.Possible values: true: Install base item is active. false: Install base item is inactive. Data type: Boolean String
item.name	Name of the install base item.Data type: String
item.number	Unique ID of the install base item.Data type: String
item.state	Details about the current state of the install base item.Data type: Object Text `"state": { "display_value": "String", "value": "String"}`
item.state.display_value	Text string of the current state of the install base item. Use this value to display the state in the UI.Data type: String
item.state.value	Internal value of the state of the install base item.Data type: String
item.sys_class_name	Details about the table that contains the install base item.Data type: Object Text `"sys_class_name": { "display_value": "String", "value": "String"}`
item.sys_class_name.display_value	Text string of the name of the table that contains the install base item. Use this value to display the table name in the UI.Data type: String
item.sys_class_name.value	Internal value of the table that contains the install base itemData type: String
item.sys_id	Sys_id of the install base item record. Located in the table specified in the sys_class_name parameter.Data type: String
status	Status of the endpoint call.Data type: String

### cURL request

The following code example shows how to update the name and active fields in the install base item record.

Shell

curl "https://instance.servicenow.com/api/sn_install_base/integrations/installbaseitems/f77c7542b7343300ece839a6ee11a991" \--request PATCH \--header "Accept:application/json" \--header "Content-Type:application/json" \--data "{  \"name\": \"KX Series - KX5001\",  \"active\":true}" \--user 'username':'password'

Return results:

JSON

{  "result": {    "status": "SUCCESS",    "item": {      "sys_class_name": {        "value": "sn_install_base_item",        "display_value": "Install Base Item"      },      "number": "IBITM0001001",      "sys_id": "bc610d38cb76211050501ebfe8076d8b",      "state": {        "value": "inactive",        "display_value": "Inactive"      },      "active": "false",      "name": "NewTestIB",      "account": {        "sys_id": "8637a386f0331003b3c498f5d3ee4ca",        "display_value": "Boxeo"      }    }  }}      }

Updates the specified related party record, associated with a specified install base item, with the values in the request body.

If you need to modify the type of related party associated with an Install Base Item, you must remove the type-specific fields for the current related party type and replace them with the type-specific fields of the new related party type. For example, to change from a type of Authorized Account to Authorized Consumer, pass the following:

type = "Authorized Consumer"
account = ""
consumer = "<sys_id of consumer record>"
responsibility = "<sys_id of responsibility of consumer>"

URL format

Versioned URL: /api/sn_install_base/{api_version}/integrations/installbaseitems/{id}/relatedparties/{related_party_sys_id}

Default URL: /api/sn_install_base/integrations/installbaseitems/{id}/relatedparties/{related_party_sys_id}

Note: Available versions are specified in the REST API Explorer. For scripted REST APIs there is additional version information on the Scripted REST Service form.

Supported request 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

Sys_id of the install base item record.Data type: String

Table: Install Base Item [sn_install_base_item]

related_party_sys_id

Sys_id of the related party record.Data type: String

Table: Install Base Related Party [sn_install_base_related_party]

|Name|Description| |----|-----------| |None| |

Name	Description
account	Required if the type parameter is one of the following: - `Authorized Account` `Authorized Contact` `Listed Account` `Listed Contact` Sys_id of the account to associate with the install base item. Note: If you pass the account parameter, you can't also pass the consumer parameter. Data type: String Table: Account [customer_account]
consumer	Required if the type parameter is `Authorized Consumer` or `Listed Consumer`. Sys_id of the consumer associated with the install base item record. Note: If you pass the consumer parameter, you can't also pass the account parameter. In addition, you can only associate a consumer with an install base item if the B2B2C plugin is installed on your instance. Data type: String Table: Consumer [csm_consumer]
contact	Sys_id of the contact record associated with the related parties record.Data type: String Table: Contact [customer_contact]
responsibility	Sys_id of the associated responsibility record. This record defines the access level for the install base information.This parameter is only valid if the related_party field is also specified. If specified, it only returns the install base items that match both the related_party and responsibility parameters. For additional information, see Configure related parties for Items Received Data type: String Table: Responsibility Definition [sn_customerservice_responsibility_def]
service_organization	Required if the type parameter is one of the following: - `Authorized Member` `Authorized Service Organization` `Listed Member` `Listed Service Organization` Sys_id of the service organization record that is involved in providing service to the customer. Note: If you pass this parameter, you shouldn't also pass the account, contact, or consumer parameters. The service_organization parameter is only available when the Service Organization (com.snc.service_organization) plugin is installed on your instance. Data type: String Table: Service Organization [sn_customer_service_organization]
sys_class_name	Table containing the related parties record.Data type: String Default: sn_install_base_related_party
type	Required. Sys_id of the type of related party to create.Possible types: Authorized Account Authorized Consumer Authorized Contact Authorized Contributor Authorized Member Authorized Service Organization Listed Account Listed Consumer Listed Contact Listed Contributor Listed Member Listed Service Organization Data type: String Table: Related Party Configuration [sn_customerservice_related_party_configuration]
user	Required if the type parameter is one of the following related party types: - `Authorized Contributor` `Authorized Member` `Listed Contributor` `Listed Member` Sys_id of the user record associated with the related parties record. Data type: String Table: User [sys_user] For `Authorized Member` and `Listed Member`, this user must be associated with the specified service_organization record.

### Headers

Header	Description
Accept	Data format of the response body. Supported types: application/json or application/xml. Default: application/json
Content-Type	Data format of the request body. Supported types: application/json or application/xml. Default: application/json

|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.

Status code	Description
200	Successful. The request was successfully processed.
400	Bad Request. A bad request type or malformed request was detected.
403	Forbidden. The user doesn't have access rights to the specified record.
404	Not found. The requested item wasn't found.
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)

Name	Description
error	Details about the error that occurred when trying to process the request.Data type: Object Text `"error": { "detail": "String", "message": "String"}`
error.detail	Additional details about the associated error.Data type: String
error.message	Error message that describes the problem that occurred when trying to execute the request.Data type: String
item	Details about the related parties record.Data type: Array CSS `"item": { "account": {Object}, "consumer": {Object}, "contact": {Object}, "install_base_item": {Object}, "responsibility": {Object}, "service_organization": {Object}, "sys_class_name": "String", "sys_id": "String", "type": {Object}, "user": {Object}}`
item.account	Details about the account associated with the related parties record.Data type: Object Text `account": { "display_value": "String", "sys_id": "String"}`
item.account.display_value	Text name of the account associated with the related parties record. Use this value to display the account name in the UI.Data type: String
item.account.sys_id	Sys_id of the account record associated with the related parties record.Data type: String
item.consumer	Details about the consumer associated with the related parties record.Data type: Object Text `"consumer": { "display_value": "String", "sys_id": "String"}`
item.consumer.display_value	Text name of the consumer associated with the related parties record. Use this value to display the consumer name in the UI.Data type: String
item.consumer.sys_id	Sys_id of the consumer record associated with the related parties record.Data type: String
item.contact	Details about the account contact responsible for the related parties record.Data type: Object Text `"contact": { "display_value": "String", "sys_id": "String"}`
item.contact.display_value	Text name of the contact associated with the related parties record. Use this value to display the contact name in the UI.Data type: String
item.contact.sys_id	Sys_id of the contact record associated with the related parties record.Data type: String Table: Contact [customer_contact]
item.install_base_item	Details about the install base item associated with the related parties record.Data type: Object Text `"install_base_item": { "display_value": "String", "sys_id": "String"}`
item.install_base_item.display_value	Text name of the install base item associated with the related parties record. Use this value to display the install base item name in the UI.Data type: String
item.install_base_item.sys_id	Sys_id of the install base item record associated with the related parties record.Data type: String
item.responsibility	Details about the access level for the install base information. Data type: Object Text `"responsibility": { "display_value": "String", "sys_id": "String"}`
item.responsibility.display_value	Text display value for the access level for the install base information.Data type: String
item.responsibility.sys_id	Sys_id of the associated responsibility record. This record defines the access level for the install base information.This parameter is only valid if the related_party field is also specified. If specified, it only returns the install base items that match both the related_party and responsibility parameters. For additional information, see Configure related parties for Items Received Data type: String Table: Responsibility Definition [sn_customerservice_responsibility_def]
item.sys_class_name	Table containing the related parties record.Data type: String Default: sn_install_base_related_party
item.sys_id	Sys_id of the associated related parties record.Data type: String
item.type	Details about the type of contact associated with the related parties record.Data type: Object Text `"type": { "display_value": "String", "sys_id": "String"}`
item.type.display_value	Text name of the type of contact associated with the related parties record. Use this value to display the type of contact in the UI. For additional information, see Create related party configurations.Possible types: Authorized Account Authorized Consumer Authorized Contact Authorized Contributor Authorized Member Authorized Service Organization Listed Account Listed Consumer Listed Contact Listed Contributor Listed Member Listed Service Organization Data type: String
item.type.sys_id	Sys_id of the type record associated with the related parties record.Data type: String
item.user	Details about the user associated with the related parties record.Data type: Object Text `"user": { "display_value": "String", "sys_id": "String"}`
item.user.display_value	Text name of the user associated with the related parties record. Use this value to display the user name in the UI.Data type: String
item.user.sys_id	Sys_id of the user record associated with the related parties record. Data type: String Table: User [sys_user]
status	Status of the endpoint call.Data type: String
sysparm_limit	Number of records that were returned. If this value isn't specified in the original request, it uses the default value.Data type: Number
sysparm_offset	Offset (starting point) in the associated table from which records were evaluated and retrieved.Data type: String

### cURL request

The following code example shows how to call this endpoint to update the contact record associated with the related party.

Shell

curl "https://instance.servicenow.com/api/sn_install_base/integrations/relatedparties/f77c7542b7343300ece839a6ee11a991" \--request PATCH \--header "Accept:application/json" \--header "Content-Type:application/json" \--data "{\"contact\": \"dc0185d94f341200025ba3618110c77c\"}" \--user 'username':'password'

Return results:

JSON

{"result":  {    "type": {      "display_value":"Authorized Contact",      "sys_id":"68ec8b2965e99110f87764df53db779f"    },    "install_base_item": {      "display_value":"KX Series - KX5000",      "sys_id":"f77c7542b7343300ece839a6ee11a991"    },    "sys_class_name":"sn_install_base_related_party",    "sys_id":"4659539814ac6910f877ae314c1fb43a",    "responsibility": {      "display_value":"Authorized Representative",      "sys_id":"c009bbedb3730010700b4d43c6a8dcef"    },    "contact": {      "display_value":"Cindy Contact",      "sys_id":"dc0185d94f341200025ba3618110c77c"    },    "account": {      "display_value":"Boxeo",      "value":"86837a386f0331003b3c498f5d3ee4ca"    },    "status":"SUCCESS",  }}

Install Base Item - PATCH /sn_install_base/integrations/installbaseitems/{id}/uninstall

Uninstalls the specified install base item.

An uninstall consists of setting the active field to false and setting the unistall_date field to a specified date. Empty if a date value isn't provided.

URL format

Versioned URL: /api/sn_install_base/{api_version}/integrations/installbaseitems/{id}/uninstall

Default URL: /api/sn_install_base/integrations/installbaseitems/{id}/uninstall

Note: Available versions are specified in the REST API Explorer. For scripted REST APIs there is additional version information on the Scripted REST Service form.

Supported request 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

Sys_id of the install base item record.Data type: String

Table: Install Base Item [sn_install_base_item]

|Name|Description| |----|-----------| |None| |

Name

Description

uninstall_date

Date on which to uninstall the specified install base item. If not specified, it's uninstalled immediately.Data type: String

Format: yyyy-mm-dd hh:mm:ss

### Headers

Header	Description
Accept	Data format of the response body. Supported types: application/json or application/xml. Default: application/json
Content-Type	Data format of the request body. Supported types: application/json or application/xml. Default: application/json

|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.

Status code	Description
200	Successful. The request was successfully processed.
400	Bad Request. A bad request type or malformed request was detected.
403	Forbidden. The user doesn't have access rights to the specified record.
404	Not found. The requested item wasn't found.
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)

Name	Description
error	Details about the error that occurred when trying to process the request.Data type: Object Text `"error": { "detail": "String", "message": "String"}`
error.detail	Additional details about the associated error.Data type: String
error.message	Error message that describes the problem that occurred when trying to execute the request.Data type: String
item	Description of the uninstalled item.Data type: Object CSS "item": { "account": {Object}, "active": "String", "asset": {Object}, "configuration_item": {Object}, "consumer": {Object}, "consumer_profile": {Object}, "contact": {Object}, "health_status": {Object}, "health_status_last_updated": "String", "household": {Object}, "install_date": {Object}, "location": {Object}, "name": "String", "number": "String", "parent": {Object}, "product": {Object}, "service_context": {Object}, "service_organization" {Object}, "sys_class_name": "String", "sys_id": "String", "state": {Object}, "status": {Object}, "uninstall_date": "String"}
item.account	Details about the customer account associated with the install base item record.Data type: Object Text `"account": { "display_value": "String", "sys_id": "String"}`
item.account.display_value	Text name of the customer account associated with the install base item record. Use this value to display the customer account name in the UI.Data type: String
item.account.sys_id	Sys_id of the customer account record associated with the install base item record.Data type: String
item.active	Flag that indicates whether the install base item is active.Possible values: true: Install base item is active. false: Install base item is inactive. Data type: Boolean String
item.asset	Details about the asset associated with the install base item record.Data type: Object Text `"asset": { "display_value": "String", "sys_id": "String"}`
item.asset.display_value	Text name of the asset associated with the install base item record. Use this value to display the asset name in the UI.Data type: String
item.asset.sys_id	Sys_id of the asset record associated with the install base item record.Data type: String
item.child_install_base_items	List of the child install base items associated with this install base item.Note: The following child install base item fields can't be different from its parent: account consumer contact service organization Data type: Array of Objects Text `"child_install_base_items": [ { "name": "String", "product": "String" }]`
item.child_install_base_items.name	Name of the child install base item.Data type: String
item.child_install_base_items.product	Sys_id of the associated child base item record.Data type: String Table: Install Base Item [sn_install_base_item]
item.configuration_item	Details about the configuration item associated with the install base item record.Data type: Object Text `"configuration_item": { "display_value": "String", "sys_id": "String"}`
item.configuration_display_value	Text name of the configuration item associated with the install base item record. Use this value to display the configuration item name in the UI.Data type: String
item.configuration_sys_id	Sys_id of the configuration item record associated with the install base item record.Data type: String
item.consumer	Details about the consumer associated with the install base item record.Note: The consumer field is only available if the B2B2C plugin is installed. Data type: Object Text `"consumer": { "display_value": "String", "sys_id": "String"}`
item.consumer.display_value	Text name of the consumer associated with the install base item record. Use this value to display the consumer name in the UI.Data type: String
item.consumer.sys_id	Sys_id of the consumer record associated with the install base item record.Data type: String
item.consumer_profile	Details about the consumer profile associated with the install base item record.Note: The consumer profile field is only available if the B2B2C plugin is installed. Data type: Object Text `"consumer_profile": { "display_value": "String", "sys_id": "String"}`
item.consumer_profile.display_value	Text name of the consumer profile associated with the install base item record. Use this value to display the consumer profile name in the UI.Data type: String
item.consumer_profile.sys_id	Sys_id of the consumer profile record associated with the install base item record.Data type: String
item.contact	Details about the account contact responsible for the install base item record.Data type: Object Text `"contact": { "display_value": "String", "sys_id": "String"}`
item.contact.display_value	Text name of the account contact associated with the install base item record. Use this value to display the account contact name in the UI.Data type: String
item.contact.sys_id	Sys_id of the account contact record associated with the install base item record.Data type: String
item.health_status	Details about the current health status of the install base item. Only returned if the Proactive Customer Service Operations (com.snc.proactive_cs_itom) plugin is installed.Data type: Object Text `"health_status": { "display_value": "String", "value": "String"}`
item.health_status.display_value	Text string of the current health status of the install base item. Use this value to display the health status in the UI.Data type: String
item.health_status.value	Internal value of the health status of the install base item.Data type: String
item.health_status_last_updated	Date and time when the health status was last updated for the install base item.Data type: String
item.household	Details about the household associated with the install base item record. Only returned if the Customer Household Data Model (com.snc.household) plugin is installed.Data type: Object Text `"household": { "display_value": "String", "sys_id": "String"}`
item.household.display_value	Text name of the household associated with the install base item record. Use this value to display the household name in the UI.Data type: String
item.household.sys_id	Sys_id of the household associated with the install base item record.Data type: String
item.install_date	Details about the date when the install base item became active.Data type: Object Text `"install_date": { "display_value": "String", "value": "String"}`
item.install_date.display_value	Text install date. Use this value to display the install date in the UI.Data type: String
item.install_date.value	Internal value of the install date.Data type: String
item.location	Details about the location of the install base item.Data type: Object Text `"location": { "display_value": "String", "sys_id": "String"}`
item.location.display_value	Text name of the install base item location. Use this value to display the location name in the UI.Data type: String
item.location.sys_id	Sys_id of the location record associated with the install base item record.Data type: String
item.name	Name of the install base item.Data type: String
item.number	Unique ID of the install base item.Data type: String
item.parent	Details about the parent record of the install base item record.Data type: Object Text `"parent": { "display_value": "String", "sys_id": "String"}`
item.parent.display_value	Text name of the parent record associated with the install base item record. Use this value to display the parent name in the UI.Data type: String
item.parent.sys_id	Sys_id of the parent record associated with the install base item record.Data type: String
item.product	Details about the product model associated with the install base item record. Use this information to identify the services associated with any product model.Data type: Object Text `"product": { "display_value": "String", "sys_id": "String"}`
item.product.display_value	Text name of the product model associated with the install base item record. Use this value to display the product name in the UI.Data type: String
item.product.sys_id	Sys_id of the product model record associated with the install base item record.Data type: String
item.quantity	Number of items installed.Data type: Integer
item.service_context	Details about the service context associated with the install base item record.Data type: Object Text `"service_context": { "display_value": "String", "sys_id": "String"}`
item.service_context.display_value	Details about the service context associated with the install base item record.Data type: Object Text `"service_context": { "display_value": "String", "sys_id": "String"}`
item.service_context.sys_id	Sys_id of the service context record associated with the install base item record.Data type: String
item.service_organization	Details about the service organization associated with the install base item record. Only returned if the Service Organization (com.snc.service_organization) plugin is installed.Data type: Object Text `"service_organization": { "display_value": "String", "sys_id": "String"}`
item.service_organization.display_value	Text name of the service organization associated with the install base item record. Use this value to display the service organization name in the UI.Data type: String
item.service_organization.sys_id	Sys_id of the service organization record associated with the install base item record.Data type: String
item.sys_class_name	Table containing the install base item record.Data type: String
item.sys_id	Sys_id of the install base item record. Located in the table specified in the sys_class_name parameter.Data type: String
item.state	Details about the current state of the install base item.Data type: Object Text `"state": { "display_value": "String", "value": "String"}`
item.state.display_value	Text string of the current state of the install base item. Use this value to display the state in the UI.Data type: String
item.state.value	Internal value of the state of the install base item.Data type: String
item.status	Details about the status of the install base item.Data type: Object Text `"status": { "display_value": "String", "value": "String"}`
item.status.display_value	Text string of the status of the install base item. Use this value to display the status in the UI.Data type: String
item.status.value	Internal value of the status of the install base item.Data type: String
item.uninstall_date	Details about the date when the install base item became inactive.Data type: Object Text `"uninstall_date": { "display_value": "String", "value": "String"}`
item.uninstall_date.display_value	Text uninstall date. Use this value to display the uninstall date in the UI.Data type: String
item.uninstall_date.value	Internal value of the uninstall date.Data type: String
status	Status of the endpoint call.Data type: String

### cURL request

The following code example shows how to call this endpoint.

Shell

curl "https://instance.servicenow.com/api/sn_install_base/integrations/installbaseitems/42746a3b876121100b6afc86dabb3597/uninstall" \--request PATCH \--header "Accept:application/json" \--user 'username':'password'

Return results:

JSON

{  "result": {    "status": "SUCCESS",    "item": {      "sys_class_name": {        "value": "sn_install_base_item",        "display_value": "Install Base Item"      },      "number": "IBITM0000901",      "sys_id": "f77c7542b7343300ece839a6ee11a991",      "contact": {        "sys_id": "4d147a386f0331003b3c498f5d3ee437",        "display_value": "Julie Lewis"      },      "state": {        "value": "inactive",        "display_value": "Inactive"      },      "active": "false",      "configuration_item": {        "sys_id": "e5a28e07c30202001efd5cb981d3aedb",        "display_value": "KX Series - KX5000"      },      "name": "KX Series - KX5000",      "account": {        "sys_id": "86837a386f0331003b3c498f5d3ee4ca",        "display_value": "Boxeo"      }    }  }}

Install Base Item - POST /sn_install_base/integrations/installbaseitems

Creates one or more install base item records in the default Install Base Item table, or in its extended table if specified, and populates them with the specified field values.

When creating a single install base item record, you pass an object in the request body that contains all of the fields to include in the request body. When you create multiple install base item records in a single call, you pass an array of objects in the request body that contains all of the records to create. The endpoint processes and reports on each of the record creation objects individually. If one or more of the records fail to be created, it doesn't affect the creation of other record.

URL format

Versioned URL: /api/sn_install_base/{api_version}/integrations/installbaseitems

Default URL: /api/sn_install_base/integrations/installbaseitems

Note: Available versions are specified in the REST API Explorer. For scripted REST APIs there is additional version information on the Scripted REST Service form.

Supported request 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

|Name|Description| |----|-----------| |None| |

Name	Description
account	Required when creating an install base item for an account.Sys_id of the account to associate with the install base item. Note: If you pass the account parameter, you can't also pass the consumer parameter. Data type: String Table: Account [customer_account]
active	Flag that indicates whether the install base item is active.Valid values: true, "true", or "0": Item is active. false, "false", or "1": Item isn't active. Data type: Boolean Default: true
asset	Sys_id of the asset associated with the install base item record.Data type: String Table: Asset [alm_asset]
child_install_base_items	List of the child install base items associated with this install base item.Note: The following child install base item fields can't be different from its parent: account consumer contact service organization Data type: Array of Objects Text `"child_install_base_items": [ { "name": "String", "product": "String" }]`
child_install_base_items.name	Name of the child install base item.Data type: String
child_install_base_items.product	Sys_id of the associated child base item record.Data type: String Table: Install Base Item [sn_install_base_item]
configuration_item	Sys_id of the configuration item associated with the install base item record.Data type: String Table: Configuration Item [cmdb_ci]
consumer	Required when creating an install base item for a consumer.Sys_id of the consumer associated with the install base item record. Note: If you pass the consumer parameter, you can't also pass the account parameter. In addition, you can only associate a consumer with an install base item if the B2B2C plugin is installed on your instance. Data type: String Table: Consumer [csm_consumer]
consumer_profile	Sys_id of the consumer profile associated with the install base item record.Data type: String Table: Consumer Profile [sn_csm_consumer_profile]
contact	Sys_id of the account contact record that is primarily responsible for the install base item. Note: Contacts can only be specified for account install base items. Data type: String Table: Contact [customer_contact]
household	Sys_id of the household associated with the install base item record.Note: This field is only valid when the Customer Household Data Model (com.snc.household) plugin is installed. Data type: String Table: Household [csm_household]
install_date	Date on which the install base item becomes active.Data type: String Format: yyyy-MM-dd HH:mm:ss
location	Sys_id of the location of the associated product.Data type: String Table: Location [cmn_location]
name	Name of the install base item.Data type: String
number	Unique identifier for the install base item.Data type: String Default: Automatically generated by the endpoint.
parent	Sys_id of the parent record for this install base item record.Data type: String Table: Install Base Item [sn_install_base_item]
product_model	Sys_id of the product model associated with the install base item record.Data type: String Table: Product Model [cmdb_model]
quantity	Number of items installed.Data type: Integer
service_context	Sys_id of the service that is associated to the underlying CI for calculating the impact severity from Event Management. For more information, see Service health status for install base.Note: This field is only valid if the Proactive Customer Service Operations with Event Management plugin is installed. Data type: String
service_organization	Required when creating an install base item for a service organization.Sys_id of the service organization record that is involved in providing service to the customer. Note: If you pass this parameter, you shouldn't also pass the account, contact, or consumer parameters. The service_organization parameter is only available when the Service Organization (com.snc.service_organization) plugin is installed on your instance. Data type: String Table: Service Organization [sn_customer_service_organization]
state	Current state of the install base item.Valid values: in_use inactive Data type: String
status	Status of the product.Valid values: original replacement Data type: String
sys_class_name	Name of the extended install base table in which to create the install base item record.Data type: String Default: Install Base Item [sn_install_base_item] table
uninstall_date	Date on which the install base becomes inactive.Data type: String Format: yyyy-MM-dd HH:mm:ss

### Headers

Header	Description
Accept	Data format of the response body. Supported types: application/json or application/xml. Default: application/json
Content-Type	Data format of the request body. Supported types: application/json or application/xml. Default: application/json

|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.

Status code	Description
200	Successful. The request was successfully processed.
400	Bad Request. A bad request type or malformed request was detected.
403	Forbidden. The user doesn't have access rights to the specified record.
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)

Name	Description
error	Details about the error that occurred when trying to process the request.Data type: Object Text `"error": { "detail": "String", "message": "String"}`
error.detail	Additional details about the associated error.Data type: String
error.message	Error message that describes the problem that occurred when trying to execute the request.Data type: String
item	Install base item that matched the specified filter results. Only non-empty fields are returned.Data type: Array of Objects CSS "item": { "account": {Object}, "active": "String", "asset": {Object}, "child_install_base_items": {Object}, "condition": "String", "configuration_item": {Object}, "consumer": {Object}, "consumer_profile": {Object}, "contact": {Object}, "health_status": {Object}, "health_status_last_updated": "String", "household": {Object}, "install_date": {Object}, "location": {Object}, "name": "String", "number": "String", "parent": {Object}, "product": {Object}, "quantity": Integer, "service_context": {Object}, "service_organization" {Object}, "sys_id": "String", "state": {Object}, "status": {Object}, "uninstall_date": "String"}
item.account	Details about the customer account associated with the install base item record.Data type: Object Text `"account": { "display_value": "String", "sys_id": "String"}`
item.account.display_value	Text name of the customer account associated with the install base item record. Use this value to display the customer account name in the UI.Data type: String
item.account.sys_id	Sys_id of the customer account record associated with the install base item record.Data type: String
item.active	Flag that indicates whether the install base item is active.Possible values: true: Install base item is active. false: Install base item is inactive. Data type: Boolean String
item.asset	Details about the asset associated with the install base item record.Data type: Object Text `"asset": { "display_value": "String", "sys_id": "String"}`
item.asset.display_value	Text name of the asset associated with the install base item record. Use this value to display the asset name in the UI.Data type: String
item.asset.sys_id	Sys_id of the asset record associated with the install base item record.Data type: String
item.child_install_base_items	List of the child install base items associated with this install base item.Note: The following child install base item fields can't be different from its parent: account consumer contact service organization Data type: Array of Objects Text `"child_install_base_items": [ { "name": "String", "product": "String" }]`
item.child_install_base_items.name	Name of the child install base item.Data type: String
item.child_install_base_items.product	Sys_id of the associated child base item record.Data type: String Table: Install Base Item [sn_install_base_item]
item.configuration_item	Details about the configuration item associated with the install base item record.Data type: Object Text `"configuration_item": { "display_value": "String", "sys_id": "String"}`
item.configuration_item.display_value	Text name of the configuration item associated with the install base item record. Use this value to display the configuration item name in the UI.Data type: String
item.configuration_item.sys_id	Sys_id of the configuration item record associated with the install base item record.Data type: String
item.consumer	Details about the consumer associated with the install base item record.Note: The consumer field is only available if the B2B2C plugin is installed. Data type: Object Text `"consumer": { "display_value": "String", "sys_id": "String"}`
item.consumer.display_value	Text name of the consumer associated with the install base item record. Use this value to display the consumer name in the UI.Data type: String
item.consumer.sys_id	Sys_id of the consumer record associated with the install base item record.Data type: String
item.consumer_profile	Details about the consumer profile associated with the install base item record.Note: The consumer profile field is only available if the B2B2C plugin is installed. Data type: Object Text `"consumer_profile": { "display_value": "String", "sys_id": "String"}`
item.consumer_profile.display_value	Text name of the consumer profile associated with the install base item record. Use this value to display the consumer profile name in the UI.Data type: String
item.consumer_profile.sys_id	Sys_id of the consumer profile record associated with the install base item record.Data type: String
item.contact	Details about the account contact responsible for the install base item record.Data type: Object Text `"contact": { "display_value": "String", "sys_id": "String"}`
item.contact.display_value	Text name of the account contact associated with the install base item record. Use this value to display the account contact name in the UI.Data type: String
item.contact.sys_id	Sys_id of the account contact record associated with the install base item record.Data type: String
item.health_status	Details about the current health status of the install base item. Only returned if the Proactive Customer Service Operations (com.snc.proactive_cs_itom) plugin is installed.Data type: Object Text `"health_status": { "display_value": "String", "value": "String"}`
item.health_status.display_value	Text string of the current health status of the install base item. Use this value to display the health status in the UI.Data type: String
item.health_status.value	Internal value of the health status of the install base item.Data type: String
item.health_status_last_updated	Date and time when the health status was last updated for the install base item.Data type: String
item.household	Details about the household associated with the install base item record. Only returned if the Customer Household Data Model (com.snc.household) plugin is installed.Data type: Object Text `"household": { "display_value": "String", "sys_id": "String"}`
item.household.display_value	Text name of the household associated with the install base item record. Use this value to display the household name in the UI.Data type: String
item.household.sys_id	Sys_id of the household associated with the install base item record.Data type: String
item.install_date	Details about the date when the install base item became active.Data type: Object Text `"install_date": { "display_value": "String", "value": "String"}`
item.install_date.display_value	Text install date. Use this value to display the install date in the UI.Data type: String
item.install_date.value	Internal value of the install date.Data type: String
item.location	Details about the location of the install base item.Data type: Object Text `"location": { "display_value": "String", "sys_id": "String"}`
item.location.display_value	Text name of the install base item location. Use this value to display the location name in the UI.Data type: String
item.location.sys_id	Sys_id of the location record associated with the install base item record.Data type: String
item.name	Name of the install base item.Data type: String
item.number	Unique ID of the install base item.Data type: String
item.parent	Details about the parent record of the install base item record.Data type: Object Text `"parent": { "display_value": "String", "sys_id": "String"}`
item.parent.display_value	Text name of the parent record associated with the install base item record. Use this value to display the parent name in the UI.Data type: String
item.parent.sys_id	Sys_id of the parent record associated with the install base item record.Data type: String
item.product	Details about the product model associated with the install base item record. Use this information to identify the services associated with any product model.Data type: Object Text `"product": { "display_value": "String", "sys_id": "String"}`
item.product.display_value	Text name of the product model associated with the install base item record. Use this value to display the product name in the UI.Data type: String
item.product.sys_id	Sys_id of the product model record associated with the install base item record.Data type: String
item.quantity	Number of items installed.Data type: Integer
item.service_context	Details about the service context associated with the install base item record.Data type: Object Text `"service_context": { "display_value": "String", "sys_id": "String"}`
item.service_context.display_value	Details about the service context associated with the install base item record.Data type: Object Text `"service_context": { "display_value": "String", "sys_id": "String"}`
item.service_context.sys_id	Sys_id of the service context record associated with the install base item record.Data type: String
item.service_organization	Details about the service organization associated with the install base item record. Only returned if the Service Organization (com.snc.service_organization) plugin is installed.Data type: Object Text `"service_organization": { "display_value": "String", "sys_id": "String"}`
item.service_organization.display_value	Text name of the service organization associated with the install base item record. Use this value to display the service organization name in the UI.Data type: String
item.service_organization.sys_id	Sys_id of the service organization record associated with the install base item record.Data type: String
item.sys_class_name	Table containing the install base item record.Data type: String
item.sys_id	Sys_id of the install base item record. Located in the table specified in the sys_class_name parameter.Data type: String
item.state	Details about the current state of the install base item.Data type: Object Text `"state": { "display_value": "String", "value": "String"}`
item.state.display_value	Text string of the current state of the install base item. Use this value to display the state in the UI.Data type: String
item.state.value	Internal value of the state of the install base item.Data type: String
item.status	Details about the status of the install base item.Data type: Object Text `"status": { "display_value": "String", "value": "String"}`
item.status.display_value	Text string of the status of the install base item. Use this value to display the status in the UI.Data type: String
item.status.value	Internal value of the status of the install base item.Data type: String
item.uninstall_date	Details about the date when the install base item became inactive.Data type: Object Text `"uninstall_date": { "display_value": "String", "value": "String"}`
item.uninstall_date.display_value	Text uninstall date. Use this value to display the uninstall date in the UI.Data type: String
item.uninstall_date.value	Internal value of the uninstall date.Data type: String
status	Status of the endpoint call.Data type: String

### cURL request

The following code example shows how to create a single Install Base Item record.

Shell

curl "https://instance.servicenow.com/api/sn_install_base/integrations/installbaseitems" \--request POST \--header "Accept:application/json" \--header "Content-Type:application/json" \--data "{  \"name\":\"Base Monitor\",  \"quantity\": 4,  \"account\":\"86837a386f0331003b3c498f5d3ee4ca\",  \"contact\": \"dc0185d94f341200025ba3618110c77c\",  \"configuration_item\":\"0c43baaac61122750182c132ee74bcf0\",  \"state\":\"in_use\"}" \--user 'username':'password'

Return results: Only non-empty fields are returned.

JSON

{  "result": {    "status": "SUCCESS",    "item": {      "sys_class_name": "sn_install_base_item",      "number": "IBITM0001003",      "sys_id": "27cb093114c66910f877324710112fd6",      "contact": {        "sys_id": "dc0185d94f341200025ba3618110c77c",        "display_value": "Cindy Contact"      },      "state": {        "value": "in_use",        "display_value": "In Use"      },      "quantity": "4",      "active": "true",      "configuration_item": {        "sys_id": "0c43baaac61122750182c132ee74bcf0",        "display_value": "3D Pinball"      },      "name": "Base Monitor",      "account": {        "sys_id": "86837a386f0331003b3c498f5d3ee4ca",        "display_value": "Boxeo"      }    }  }}

cURL request

The following code example shows how to create multiple Install Base Item records.

Shell

curl "https://instance.servicenow.com/api/sn_install_base/integrations/installbaseitems" \--request POST \--header "Accept:application/json" \--header "Content-Type:application/json" \--data "[  {    \"name\":\"AST4 Laptop\",    \"consumer\":\"b119803fdb1b1200b6075200cf961917\",    \"status\":\"replacement\",    \"install_date\":\"2023-05-18 12:00:00\",    \"uninstall_date\":\"2023-09-28 12:00:00\"  },{    \"name\":\"Base Monitor\",    \"quantity\": 4,    \"account\":\"86837a386f0331003b3c498f5d3ee4ca\",    \"contact\": \"dc0185d94f341200025ba3618110c77c\",    \"configuration_item\":\"0c43baaac61122750182c132ee74bcf0\",    \"state\":\"in_use\"  }]" \--user 'username':'password'

Return results: Only non-empty fields are returned.

JSON

{  "result": {    "status": "SUCCESS",    "items": [      {        "status": "SUCCESS",        "item": {          "sys_class_name": "sn_install_base_item",          "number": "IBITM0001018",          "sys_id": "16fe91b1140a6910f877324710112f40",          "uninstall_date": {            "value": "2023-09-28 12:00:00",            "display_value": "2023-09-28 05:00:00"          },          "install_date": {            "value": "2023-05-18 12:00:00",            "display_value": "2023-05-18 05:00:00"          },          "consumer": {            "sys_id": "b119803fdb1b1200b6075200cf961917",            "display_value": "Silvester Erik"          },          "active": "true",          "name": "AST4 Laptop",          "status": {            "value": "replacement",            "display_value": "Replacement"          }        }      },      {        "status": "SUCCESS",        "item": {          "sys_class_name": "sn_install_base_item",          "number": "IBITM0001019",          "sys_id": "5efe91b1140a6910f877324710112f40",          "contact": {            "sys_id": "dc0185d94f341200025ba3618110c77c",            "display_value": "Cindy Contact"          },          "state": {            "value": "in_use",            "display_value": "In Use"          },          "quantity": "4",          "active": "true",          "configuration_item": {            "sys_id": "0c43baaac61122750182c132ee74bcf0",            "display_value": "3D Pinball"          },          "name": "Base Monitor",          "account": {            "sys_id": "86837a386f0331003b3c498f5d3ee4ca",            "display_value": "Boxeo"          }        }      }    ]  }}

Install Base Item - POST /sn_install_base/integrations/installbaseitems/{id}/relatedparties

Creates a related party record and associates it with a specified install base item record. The values specified in the request parameters are stored in the newly created related party record.

URL format

Versioned URL: /api/sn_install_base/{api_version}/integrations/installbaseitems/{id}/relatedparties

Default URL: /api/sn_install_base/integrations/installbaseitems/{id}/relatedparties

Note: Available versions are specified in the REST API Explorer. For scripted REST APIs there is additional version information on the Scripted REST Service form.

Supported request 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

Sys_id of the install base item record.Data type: String

Table: Install Base Item [sn_install_base_item]

|Name|Description| |----|-----------| |None| |

Name	Description
account	Required if the type parameter is one of the following: - `Authorized Account` `Authorized Contact` `Listed Account` `Listed Contact` Sys_id of the account to associate with the install base item. Note: If you pass the account parameter, you can't also pass the consumer parameter. Data type: String Table: Account [customer_account]
consumer	Required if the type parameter is `Authorized Consumer` or `Listed Consumer`. Sys_id of the consumer associated with the install base item record. Note: If you pass the consumer parameter, you can't also pass the account parameter. In addition, you can only associate a consumer with an install base item if the B2B2C plugin is installed on your instance. Data type: String Table: Consumer [csm_consumer]
contact	Sys_id of the contact record associated with the related parties record.Data type: String Table: Contact [customer_contact]
install_base_item	Sys_id of the install base item record associated with the related parties record.Data type: String
responsibility	Sys_id of the associated responsibility record. This record defines the access level for the install base information.This parameter is only valid if the related_party field is also specified. If specified, it only returns the install base items that match both the related_party and responsibility parameters. For additional information, see Configure related parties for Items Received Data type: String Table: Responsibility Definition [sn_customerservice_responsibility_def]
service_organization	Required if the type parameter is one of the following: - `Authorized Member` `Authorized Service Organization` `Listed Member` `Listed Service Organization` Sys_id of the service organization record that is involved in providing service to the customer. Note: If you pass this parameter, you shouldn't also pass the account, contact, or consumer parameters. The service_organization parameter is only available when the Service Organization (com.snc.service_organization) plugin is installed on your instance. Data type: String Table: Service Organization [sn_customer_service_organization]
sys_class_name	Table containing the related parties record.Data type: String Default: sn_install_base_related_party
type	Required. Sys_id of the type of related party to create.Possible types: Authorized Account Authorized Consumer Authorized Contact Authorized Contributor Authorized Member Authorized Service Organization Listed Account Listed Consumer Listed Contact Listed Contributor Listed Member Listed Service Organization Data type: String Table: Related Party Configuration [sn_customerservice_related_party_configuration]
user	Required if the type parameter is one of the following related party types: - `Authorized Contributor` `Authorized Member` `Listed Contributor` `Listed Member` For `Authorized Member` and `Listed Member`, this user must be associated with the specified service_organization record. Sys_id of the user record associated with the related parties record. Data type: String Table: User [sys_user]

### Headers

Header	Description
Accept	Data format of the response body. Supported types: application/json or application/xml. Default: application/json
Content-Type	Data format of the request body. Supported types: application/json or application/xml. Default: application/json

|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.

Status code	Description
200	Successful. The request was successfully processed.
400	Bad Request. A bad request type or malformed request was detected.
403	Forbidden. The user doesn't have access rights to the specified record.
404	Not found. The requested item wasn't found.
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)

Name	Description
account	Details about the account associated with the related parties record.Data type: Object Text `account": { "display_value": "String", "sys_id": "String"}`
account.display_value	Text name of the account associated with the related parties record. Use this value to display the account name in the UI.Data type: String
account.sys_id	Sys_id of the account record associated with the related parties record.Data type: String
consumer	Details about the consumer associated with the related parties record.Data type: Object Text `"consumer": { "display_value": "String", "sys_id": "String"}`
consumer.display_value	Text name of the consumer associated with the related parties record. Use this value to display the consumer name in the UI.Data type: String
consumer.sys_id	Sys_id of the consumer record associated with the related parties record.Data type: String
contact	Details about the account contact responsible for the related parties record.Data type: Object Text `"contact": { "display_value": "String", "sys_id": "String"}`
contact.display_value	Text name of the contact associated with the related parties record. Use this value to display the contact name in the UI.Data type: String
contact.sys_id	Sys_id of the contact record associated with the related parties record.Data type: String Table: Contact [customer_contact]
error	Details about the error that occurred when trying to process the request.Data type: Object Text `"error": { "detail": "String", "message": "String"}`
error.detail	Additional details about the associated error.Data type: String
error.message	Error message that describes the problem that occurred when trying to execute the request.Data type: String
install_base_item	Details about the install base item associated with the related parties record.Data type: Object Text `"install_base_item": { "display_value": "String", "sys_id": "String"}`
install_base_item.display_value	Text name of the install base item associated with the related parties record. Use this value to display the install base item name in the UI.Data type: String
install_base_item.sys_id	Sys_id of the install base item record associated with the related parties record.Data type: String
responsibility	Details about the access level for the install base information. Data type: Object Text `"responsibility": { "display_value": "String", "sys_id": "String"}`
responsibility.display_value	Text display value for the access level for the install base information.Data type: String
responsibility.sys_id	Sys_id of the associated responsibility record. This record defines the access level for the install base information.This parameter is only valid if the related_party field is also specified. If specified, it only returns the install base items that match both the related_party and responsibility parameters. For additional information, see Configure related parties for Items Received Data type: String Table: Responsibility Definition [sn_customerservice_responsibility_def]
status	Status of the endpoint call.Data type: String
sys_class_name	Table containing the related parties record.Data type: String Default: sn_install_base_related_party
sys_id	Sys_id of the associated related parties record.Data type: String
sysparm_limit	Number of records that were returned. If this value isn't specified in the original request, it uses the default value.Data type: Number
sysparm_offset	Offset (starting point) in the associated table from which records were evaluated and retrieved.Data type: String
type	Details about the type of contact associated with the related parties record.Data type: Object Text `"type": { "display_value": "String", "sys_id": "String"}`
type.display_value	Text name of the type of contact associated with the related parties record. Use this value to display the type of contact in the UI. For additional information, see Create related party configurations.Possible types: Authorized Account Authorized Consumer Authorized Contact Authorized Contributor Authorized Member Authorized Service Organization Listed Account Listed Consumer Listed Contact Listed Contributor Listed Member Listed Service Organization Data type: String
type.sys_id	Sys_id of the type record associated with the related parties record.Data type: String
user	Details about the user associated with the related parties record.Data type: Object Text `"user": { "display_value": "String", "sys_id": "String"}`
user.display_value	Text name of the user associated with the related parties record. Use this value to display the user name in the UI.Data type: String
user.sys_id	Sys_id of the user record associated with the related parties record. Data type: String Table: User [sys_user]

### cURL request

The following code example shows how to call this endpoint to create an Authorized Account related record and associate it with an install base item.

Shell

curl "https://instance.servicenow.com/api/sn_install_base/integrations/relatedparties/f77c7542b7343300ece839a6ee11a991" \--request POST \--header "Accept:application/json" \--header "Content-Type:application/json" \--data "{  "contact":"0a232a0013691200042ab3173244b075",  "type":"68ec8b2965e99110f87764df53db779f",  "account":"86837a386f0331003b3c498f5d3ee4ca",  "install_base_item":"f77c7542b7343300ece839a6ee11a991",  "responsibility":"c009bbedb3730010700b4d43c6a8dcef",  "sys_class_name":"sn_install_base_related_party"}" \--user 'username':'password'

Return results:

JSON

{"result":  {    "type": {      "display_value":"Authorized Contact",      "sys_id":"68ec8b2965e99110f87764df53db779f"    },    "install_base_item": {      "display_value":"KX Series - KX5000",      "sys_id":"f77c7542b7343300ece839a6ee11a991"    },    "sys_class_name":"sn_install_base_related_party",    "sys_id":"4659539814ac6910f877ae314c1fb43a",    "responsibility": {      "display_value":"Authorized Representative",      "sys_id":"c009bbedb3730010700b4d43c6a8dcef"    },    "contact": {      "display_value":"Cindy Contact",      "sys_id":"dc0185d94f341200025ba3618110c77c"    },    "account": {      "display_value":"Boxeo",      "value":"86837a386f0331003b3c498f5d3ee4ca"    },    "status":"SUCCESS",  }}

Install Base Item - DELETE /sn_install_base/integrations/installbaseitems/{id}/relatedparties/{related_party_sys_id}

URL format

Supported request parameters

Headers

Status codes

Response body parameters (JSON or XML)

Install Base Item - GET /sn_install_base/integrations/installbaseitems

URL format

Supported request parameters

Headers

Status codes

Response body parameters (JSON or XML)

cURL request

cURL request

Install Base Item - GET /sn_install_base/integrations/installbaseitem/{id}

URL format

Supported request parameters

Headers

Status codes

Response body parameters (JSON or XML)

cURL request

Install Base Item - GET /sn_install_base/integrations/installbaseitems/{id}/cases

URL format

Supported request parameters

Headers

Status codes

Response body parameters (JSON or XML)

Install Base Item - GET /sn_install_base/integrations/installbaseitems/{id}/childinstallbaseitems

URL format

Supported request parameters

Headers

Status codes

Response body parameters (JSON or XML)

Install Base Item - GET /sn_install_base/integrations/installbaseitems/{id}/contracts

URL format

Supported request parameters

Headers

Status codes

Response body parameters (JSON or XML)

Install Base Item - GET /sn_install_base/integrations/installbaseitems/{id}/entitlements

URL format

Supported request parameters

Headers

Status codes

Response body parameters (JSON or XML)

Install Base Item - GET /sn_install_base/integrations/installbaseitems/{id}/maintenanceplans

URL format

Supported request parameters

Headers

Status codes

Response body parameters (JSON or XML)

Install Base Item - GET /sn_install_base/integrations/installbaseitems/{id}/relatedparties

URL format

Supported request parameters

Headers

Status codes

Response body parameters (JSON or XML)

Install Base Item - GET /sn_install_base/integrations/installbaseitems/{id}/soldproducts

URL format

Supported request parameters

Headers

Status codes

Response body parameters (JSON or XML)

Install Base Item - GET /sn_install_base/integrations/installbaseitems/{id}/workorders

URL format

Supported request parameters

Headers

Status codes

Response body parameters (JSON or XML)

Install Base Item - PATCH /sn_install_base/integrations/installbaseitems/{id}

URL format

Supported request parameters

Status codes

Response body parameters (JSON or XML)

Install Base Item - PATCH /sn_install_base/integrations/installbaseitems/{id}/relatedparties/{related_party_sys_id}

URL format

Supported request parameters

Status codes

Response body parameters (JSON or XML)