Install Base Item API

  • Release version: Xanadu
  • Updated August 1, 2024
  • 136 minutes to read

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

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

    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}

    Supported request parameters

    Table 1. Path parameters
    Name Description
    api_version Optional. Version of the endpoint to access. For example, v1 or v2. Only specify this value to use an endpoint version other than the latest.

    Data type: String
    id Sys_id of the install base item record. Located in the Install Base Item [sn_install_base_item] table.

    Data type: String
    related_party_sys_id Sys_id of the related party record. By default, this is located in the Install Base Related Party [sn_install_base_related_party] table.

    Data type: String
    Table 2. Query parameters
    Name Description
    None
    Table 3. Request body parameters (XML or JSON)
    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.

    Table 4. Request headers
    Header Description
    Accept Data format of the response body. Supported types: application/json or application/xml.

    Default: application/json
    Table 5. Response headers
    Header Description
    None

    Status codes

    The following status codes apply to this HTTP action. For a list of possible status codes used in the REST API, see REST API HTTP response codes.

    Table 6. Status codes
    Status code Description
    200 Successful. The request was successfully processed.
    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

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

    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:

    {
  "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

    Supported request parameters

    Table 7. Path parameters
    Name Description
    api_version Optional. Version of the endpoint to access. For example, v1 or v2. Only specify this value to use an endpoint version other than the latest.

    Data type: String
    Table 8. Query parameters
    Name Description
    field name-value pairs Field-value pairs to use to filter the install base item records. Located in the Install Base Item [sn_istall_base_item] 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 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
    related_party Sys_id of a related party record. Located in the Install Base Related Party [sn_install_base_related_party] table.

    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
    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
    Table 9. Request body parameters (XML or JSON)
    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.

    Table 10. Request headers
    Header Description
    Accept Data format of the response body. Supported types: application/json or application/xml.

    Default: application/json
    Table 11. Response headers
    Header Description
    None

    Status codes

    The following status codes apply to this HTTP action. For a list of possible status codes used in the REST API, see REST API HTTP response codes.

    Table 12. Status codes
    Status code Description
    200 Successful. The request was successfully processed.
    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

    "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

    "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

    "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

    "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

    "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

    "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

    "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

    "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

    "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 Service Household (com.snc.household) plugin is installed.

    Data type: Object

    "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

    "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

    "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

    "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

    "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

    "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

    "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

    "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

    "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

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

    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:

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

    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:

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

    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:

    {
  "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}

    Supported request parameters

    Table 13. Path parameters
    Name Description
    api_version Optional. Version of the endpoint to access. For example, v1 or v2. Only specify this value to use an endpoint version other than the latest.

    Data type: String
    id Sys_id of the install base item record. Located in the Install Base Item [sn_install_base_item] table.

    Data type: String
    Table 14. Query parameters
    Name Description
    sys_class_name If the desired 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
    Table 15. Request body parameters (XML or JSON)
    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.

    Table 16. Request headers
    Header Description
    Accept Data format of the response body. Supported types: application/json or application/xml.

    Default: application/json
    Table 17. Response headers
    Header Description
    None

    Status codes

    The following status codes apply to this HTTP action. For a list of possible status codes used in the REST API, see REST API HTTP response codes.

    Table 18. Status codes
    Status code Description
    200 Successful. The request was successfully processed.
    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

    "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

    "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: Array of Objects

    "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

    "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

    "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

    "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

    "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

    "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

    "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

    "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 Service Household (com.snc.household) plugin is installed.

    Data type: Object

    "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

    "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

    "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

    "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

    "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

    "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

    "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

    "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

    "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

    "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

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

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

    Return results:

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

    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:

    {
  "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

    Supported request parameters

    Table 19. Path parameters
    Name Description
    api_version Optional. Version of the endpoint to access. For example, v1 or v2. Only specify this value to use an endpoint version other than the latest.

    Data type: String
    id Sys_id of the install base item record. Located in the Install Base Item [sn_install_base_item] table.

    Data type: String
    Table 20. Query parameters
    Name Description
    field name-value pairs Field-value pairs to use to filter the case records. By default this references the fields in the Case [sn_customerservice_case] 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 approval field is set to "rejected" and the category field is set to "2", pass the follow: &approval=rejected&category=2.

    Data type: String

    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
    Table 21. Request body parameters (XML or JSON)
    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.

    Table 22. Request headers
    Header Description
    Accept Data format of the response body. Supported types: application/json or application/xml.

    Default: application/json
    Table 23. Response headers
    Header Description
    None

    Status codes

    The following status codes apply to this HTTP action. For a list of possible status codes used in the REST API, see REST API HTTP response codes.

    Table 24. Status codes
    Status code Description
    200 Successful. The request was successfully processed.
    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

    "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. Located in the Account [customer_account] table.

    Data type: String
    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. Located in the Escalation [sn_customerservice_escalation] table.

    Data type: String
    cases.active_escalation Sys_id of the active escalation record associated with the case. Located in the Escalation [sn_customerservice_escalation] table.

    Data type: String
    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. Located in the User [sys_user] table.

    Data type: Array

    Maximum: 4,000
    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. Located in the Asset [alm_asset] table.

    Data type: String
    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. Located in the User [sys_user] table.

    Data type: String
    cases.assignment_group Sys_id of the customer service agent group assigned to the case. Located in the Group [sys_user_group] table.

    Data type: String
    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. Located in the Service [cmdb_ci_service] table.

    Data type: String
    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. Located in the Case Report [sn_customerservice_case_report] table.

    Data type: String
    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. Located in the Change Request [change_request] table.

    Data type: String
    cases.change Sys_id of the change request that caused the case to be created. Located in the Change Request [change_request] table.

    Data type: String
    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. Located in the User [sys_user] table.

    Data type: String
    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. Located in the Configuration Item [cmdb_ci] table.

    Data type: String
    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. Located in the Company [core_company] table.

    Data type: String
    cases.consumer Business-to-consumer cases only. Sys_id of the person to contact with regard to this case. Located in the Consumer [csm_consumer] table.

    Data type: String
    cases.contact Business-to-business based cases only. Sys_id of the person to contact regarding this case. Located in the Contact [customer_contact] table.

    Data type: String
    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. Located in the Contract [ast_contract] table. 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
    cases.contributor_groups List of sys_ids of the user groups that have contributed to the case. Located in the Group [sys_user_group] table.

    Data type: String
    cases.contributor_users List of sys_ids of the users that have contributed to the case. Located in the User [sys_user] table.

    Data type: String
    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. Located in the Execution Plan [sc_cat_item_delivery_plan] table.

    Data type: String
    cases.delivery_task Sys_id of the execution plan task. Located in the Execution Plan Task [sc_cat_item_delivery_task] table.

    Data type: String
    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. Located in the Entitlement [service_entitlement] table. 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
    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. Located in the Group [sys_user_group] table.

    Data type: Array
    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. Located in the User [sys_user] table.

    Data type: String
    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. Located in the Location [cmn_location] table.

    Data type: String
    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 was not 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 does not 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 are not 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. Located in the User [sys_user] table.

    Data type: String
    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. Located in the Task [task] table.

    Data type: String
    cases.partner Sys_id of the partner associated with the case. Located in the Account [customer_account] table.

    Data type: String
    cases.partner_contact Sys_id of the partner contact associated with the case. Located in the Contact [customer_contact] table.

    Data type: String
    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. Located in the Problem [problem] table.

    Data type: String
    cases.product Sys_id of the product model of the asset associated to the case. Located in the Product Model [cmdb_model] table. A model is a specific version or configuration of an asset (for example, Apple Mac Book Pro).

    Data type: String
    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. Located in the Recipients List [sn_publications_recipients_list] table.

    Data type: String
    cases.rejection_goto Sys_id of the task to execute if the case is rejected. Located in the Task [task] table.

    Data type: String
    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. Located in the User [sys_user] table.

    Data type: String
    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. Located in the Service Offering [service_offering] table.

    Data type: String
    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. Located in the Skill [cmn_skill] table.

    Data type: String
    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. Located in the Social Profile [sn_app_cs_social_social_profile] table.

    Data type: String
    cases.sold_product Sys_id of the associated product. Located in the Sold Product [sn_install_base_sold_product] table.

    Data type: String
    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: Question

    Data type: Number (Integer)

    Default: 0
    cases.support_manager Sys_id of the CSM manager assigned to the case. Located in the User [sys_user] table.

    Data type: String
    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. Located in the Task [task] table.

    Data type: String
    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. Located in the User [sys_user] table.

    Data type: Array
    cases.wf_activity Sys_id of the workflow activity record associated with the case. Located in the Workflow Activity [wf_activity] table.

    Data type: String
    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. Located in the User [sys_user] table.

    Data type: Array
    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.

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

    Return results:

    {
  "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 update​CS0001034",
        "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 Alert​CS0001008",
        "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 down​CS0001033",
        "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 account​CS0001048",
        "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

    Supported request parameters

    Table 25. Path parameters
    Name Description
    api_version Optional. Version of the endpoint to access. For example, v1 or v2. Only specify this value to use an endpoint version other than the latest.

    Data type: String
    id Sys_id of the install base item record. Located in the Install Base Item [sn_install_base_item] table.

    Data type: String
    Table 26. Query parameters
    Name Description
    field name-value pairs Field-value pairs to use to filter the child install base item records. Located in the Install Base Item [sn_install_base_item] 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 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
    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
    Table 27. Request body parameters (XML or JSON)
    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.

    Table 28. Request headers
    Header Description
    Accept Data format of the response body. Supported types: application/json or application/xml.

    Default: application/json
    Table 29. Response headers
    Header Description
    None

    Status codes

    The following status codes apply to this HTTP action. For a list of possible status codes used in the REST API, see REST API HTTP response codes.

    Table 30. Status 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

    "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

    "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

    "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

    "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

    "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

    "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

    "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

    "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

    "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 Service Household (com.snc.household) plugin is installed.

    Data type: Object

    "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

    "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

    "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

    "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

    "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

    "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

    "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

    "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

    "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

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

    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:

    {
  "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

    Supported request parameters

    Table 31. Path parameters
    Name Description
    api_version Optional. Version of the endpoint to access. For example, v1 or v2. Only specify this value to use an endpoint version other than the latest.

    Data type: String
    id Sys_id of the install base item record. Located in the Install Base Item [sn_install_base_item] table.

    Data type: String
    Table 32. Query parameters
    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
    Table 33. Request body parameters (XML or JSON)
    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.

    Table 34. Request headers
    Header Description
    Accept Data format of the response body. Supported types: application/json or application/xml.

    Default: application/json
    Table 35. Response headers
    Header Description
    None

    Status codes

    The following status codes apply to this HTTP action. For a list of possible status codes used in the REST API, see REST API HTTP response codes.

    Table 36. Status 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

    "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

    "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

    "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

    "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

    "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. Located in the Rate Care [fm_contract_rate_card] table.
    Possible values:
    • true: Rate card.
    • false: No rate card.

    Data type: Boolean string
    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

    "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

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

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

    Return results:

    {
  "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\t​CNTR0000701",
        "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

    Supported request parameters

    Table 37. Path parameters
    Name Description
    api_version Optional. Version of the endpoint to access. For example, v1 or v2. Only specify this value to use an endpoint version other than the latest.

    Data type: String
    id Sys_id of the install base item record. Located in the Install Base Item [sn_install_base_item] table.

    Data type: String
    Table 38. Query parameters
    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
    Table 39. Request body parameters (XML or JSON)
    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.

    Table 40. Request headers
    Header Description
    Accept Data format of the response body. Supported types: application/json or application/xml.

    Default: application/json
    Table 41. Response headers
    Header Description
    None

    Status codes

    The following status codes apply to this HTTP action. For a list of possible status codes used in the REST API, see REST API HTTP response codes.

    Table 42. Status 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

    "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

    "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

    "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

    "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

    "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

    "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

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

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

    Return results:

    {
  "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

    Supported request parameters

    Table 43. Path parameters
    Name Description
    api_version Optional. Version of the endpoint to access. For example, v1 or v2. Only specify this value to use an endpoint version other than the latest.

    Data type: String
    id Sys_id of the install base item record. Located in the Install Base Item [sn_install_base_item] table.

    Data type: String
    Table 44. Query parameters
    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
    Table 45. Request body parameters (XML or JSON)
    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.

    Table 46. Request headers
    Header Description
    Accept Data format of the response body. Supported types: application/json or application/xml.

    Default: application/json
    Table 47. Response headers
    Header Description
    None

    Status codes

    The following status codes apply to this HTTP action. For a list of possible status codes used in the REST API, see REST API HTTP response codes.

    Table 48. Status 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

    "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

    "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

    "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

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

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

    Return results:

    {
  "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

    Supported request parameters

    Table 49. Path parameters
    Name Description
    api_version Optional. Version of the endpoint to access. For example, v1 or v2. Only specify this value to use an endpoint version other than the latest.

    Data type: String
    id Sys_id of the install base item record. Located in the Install Base Item [sn_install_base_item] table.

    Data type: String
    Table 50. Query parameters
    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
    Table 51. Request body parameters (XML or JSON)
    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.

    Table 52. Request headers
    Header Description
    Accept Data format of the response body. Supported types: application/json or application/xml.

    Default: application/json
    Table 53. Response headers
    Header Description
    None

    Status codes

    The following status codes apply to this HTTP action. For a list of possible status codes used in the REST API, see REST API HTTP response codes.

    Table 54. Status 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

    "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

    "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

    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

    "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

    "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. Located in the Contact [customer_contact] table.

    Data type: String
    relatedparties.install_base_item Details about the install base item associated with the related parties record.

    Data type: Object

    "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

    "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. Located in the Responsibility Definition [sn_customerservice_responsibility_def] table.

    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
    relatedparties.service_organization Details about the service organization associated with the related parties record.

    Data type: Object

    "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. Located in the Service Organization [sn_customer_service_organization] table.

    Data type: String
    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

    "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 Add related party configurations to cases, sold products, install bases, or service organizations.
    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

    "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. Located in the User [sys_user] table.

    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.

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

    Return results:

    
  "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

    Supported request parameters

    Table 55. Path parameters
    Name Description
    api_version Optional. Version of the endpoint to access. For example, v1 or v2. Only specify this value to use an endpoint version other than the latest.

    Data type: String
    id Sys_id of the install base item record. Located in the Install Base Item [sn_install_base_item] table.

    Data type: String
    Table 56. Query parameters
    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
    Table 57. Request body parameters (XML or JSON)
    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.

    Table 58. Request headers
    Header Description
    Accept Data format of the response body. Supported types: application/json or application/xml.

    Default: application/json
    Table 59. Response headers
    Header Description
    None

    Status codes

    The following status codes apply to this HTTP action. For a list of possible status codes used in the REST API, see REST API HTTP response codes.

    Table 60. Status 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

    "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

    "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

    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

    "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

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

    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:

    {
  "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

    Supported request parameters

    Table 61. Path parameters
    Name Description
    api_version Optional. Version of the endpoint to access. For example, v1 or v2. Only specify this value to use an endpoint version other than the latest.

    Data type: String
    id Sys_id of the install base item record. Located in the Install Base Item [sn_install_base_item] table.

    Data type: String
    Table 62. Query parameters
    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
    Table 63. Request body parameters (XML or JSON)
    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.

    Table 64. Request headers
    Header Description
    Accept Data format of the response body. Supported types: application/json or application/xml.

    Default: application/json
    Table 65. Response headers
    Header Description
    None

    Status codes

    The following status codes apply to this HTTP action. For a list of possible status codes used in the REST API, see REST API HTTP response codes.

    Table 66. Status 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

    "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

    "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

    "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

    "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

    "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

    "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

    "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

    "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

    "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

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

    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:

    {
  "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}

    Supported request parameters

    Table 67. Path parameters
    Name Description
    api_version Optional. Version of the endpoint to access. For example, v1 or v2. Only specify this value to use an endpoint version other than the latest.

    Data type: String
    Table 68. Query parameters
    Name Description
    None
    Table 69. Request body parameters (XML or JSON)
    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. Located in the Account [customer_account] table.

    Note:
    If you pass the account parameter, you can't also pass the consumer parameter.

    Data type: String
    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. Located in the Asset [alm_asset] table.

    Data type: String
    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

    "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. Located in the Install Base Item [sn_install_base_item] table.

    Data type: String
    configuration_item Sys_id of the configuration item associated with the install base item record. Located in the Configuration Item [cmdb_ci] table.

    Data type: String
    consumer Required when creating an install base item for a consumer.
    Sys_id of the consumer associated with the install base item record. Located in the Consumer [csm_consumer] table.
    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
    consumer_profile Sys_id of the consumer profile associated with the install base item record. Located in the Consumer Profile [sn_csm_consumer_profile] table.

    Data type: String
    contact
    Sys_id of the account contact record that is primarily responsible for the install base item. Located in the Contact [customer_contact] table.
    Note:
    Contacts can only be specified for account install base items.

    Data type: String
    household Sys_id of the household associated with the install base item record. Located in the Household [csm_household] table.
    Note:
    This field is only valid when the Customer Service Household (com.snc.household) plugin is installed.

    Data type: String
    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. Located in the Location [cmn_location] table.

    Data type: String
    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. Located in the Install Base Item [sn_install_base_item] table.

    Data type: String
    product_model Sys_id of the product model associated with the install base item record. Located in the Product Model [cmdb_model] table.

    Data type: String
    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. Located in the Service Organization [sn_customer_service_organization] table.

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

    The following request and response headers apply to this HTTP action only, or apply to this action in a distinct way. For a list of general headers used in the REST API, see Supported REST API headers.

    Table 70. Request 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
    Table 71. Response headers
    Header Description
    None

    Status codes

    The following status codes apply to this HTTP action. For a list of possible status codes used in the REST API, see REST API HTTP response codes.

    Table 72. Status 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

    "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

    "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

    "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

    "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

    "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 item

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

    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:

    {
  "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"
      }
    }
  }
}
      
}

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

    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}

    Supported request parameters

    Table 73. Path parameters
    Name Description
    api_version Optional. Version of the endpoint to access. For example, v1 or v2. Only specify this value to use an endpoint version other than the latest.

    Data type: String
    id Sys_id of the install base item record. Located in the Install Base Item [sn_install_base_item] table.

    Data type: String
    related_party_sys_id Sys_id of the related party record. By default, this is located in the Install Base Related Party [sn_install_base_related_party] table.

    Data type: String
    Table 74. Query parameters
    Name Description
    None
    Table 75. Request body parameters (XML or JSON)
    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. Located in the Account [customer_account] table.

    Note:
    If you pass the account parameter, you can't also pass the consumer parameter.

    Data type: String
    consumer Required if the type parameter is Authorized Consumer or Listed Consumer.
    Sys_id of the consumer associated with the install base item record. Located in the Consumer [csm_consumer] table.
    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
    contact Sys_id of the contact record associated with the related parties record. Located in the Contact [customer_contact] table.

    Data type: String
    responsibility Sys_id of the associated responsibility record. This record defines the access level for the install base information. Located in the Responsibility Definition [sn_customerservice_responsibility_def] table.

    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
    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. Located in the Service Organization [sn_customer_service_organization] table.

    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
    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. Located in the Related Party Configuration [sn_customerservice_related_party_configuration] table.
    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
    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. Located in the User [sys_user] table.

    Data type: String

    For Authorized Member and Listed Member, this user must be associated with the specified service_organization record.

    Headers

    The following request and response headers apply to this HTTP action only, or apply to this action in a distinct way. For a list of general headers used in the REST API, see Supported REST API headers.

    Table 76. Request 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
    Table 77. Response headers
    Header Description
    None

    Status codes

    The following status codes apply to this HTTP action. For a list of possible status codes used in the REST API, see REST API HTTP response codes.

    Table 78. Status 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

    "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

    "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

    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

    "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

    "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. Located in the Contact [customer_contact] table.

    Data type: String
    item.install_base_item Details about the install base item associated with the related parties record.

    Data type: Object

    "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

    "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. Located in the Responsibility Definition [sn_customerservice_responsibility_def] table.

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

    "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 Add related party configurations to cases, sold products, install bases, or service organizations.
    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

    "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. Located in the User [sys_user] table.

    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 to update the contact record associated with the related party.

    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:

    {
"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

    Supported request parameters

    Table 79. Path parameters
    Name Description
    api_version Optional. Version of the endpoint to access. For example, v1 or v2. Only specify this value to use an endpoint version other than the latest.

    Data type: String
    id Sys_id of the install base item record. Located in the Install Base Item [sn_install_base_item] table.

    Data type: String
    Table 80. Query parameters
    Name Description
    None
    Table 81. Request body parameters (XML or JSON)
    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

    The following request and response headers apply to this HTTP action only, or apply to this action in a distinct way. For a list of general headers used in the REST API, see Supported REST API headers.

    Table 82. Request 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
    Table 83. Response headers
    Header Description
    None

    Status codes

    The following status codes apply to this HTTP action. For a list of possible status codes used in the REST API, see REST API HTTP response codes.

    Table 84. Status 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

    "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

    "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

    "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

    "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

    "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. Located in the Install Base Item [sn_install_base_item] table.

    Data type: String
    item.configuration_item Details about the configuration item associated with the install base item record.

    Data type: Object

    "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

    "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

    "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

    "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

    "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 Service Household (com.snc.household) plugin is installed.

    Data type: Object

    "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

    "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

    "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

    "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

    "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

    "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

    "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

    "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

    "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

    "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

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

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

    Return results:

    {
  "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

    Supported request parameters

    Table 85. Path parameters
    Name Description
    api_version Optional. Version of the endpoint to access. For example, v1 or v2. Only specify this value to use an endpoint version other than the latest.

    Data type: String
    Table 86. Query parameters
    Name Description
    None
    Table 87. Request body parameters (XML or JSON)
    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. Located in the Account [customer_account] table.

    Note:
    If you pass the account parameter, you can't also pass the consumer parameter.

    Data type: String
    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. Located in the Asset [alm_asset] table.

    Data type: String
    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

    "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. Located in the Install Base Item [sn_install_base_item] table.

    Data type: String
    configuration_item Sys_id of the configuration item associated with the install base item record. Located in the Configuration Item [cmdb_ci] table.

    Data type: String
    consumer Required when creating an install base item for a consumer.
    Sys_id of the consumer associated with the install base item record. Located in the Consumer [csm_consumer] table.
    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
    consumer_profile Sys_id of the consumer profile associated with the install base item record. Located in the Consumer Profile [sn_csm_consumer_profile] table.

    Data type: String
    contact
    Sys_id of the account contact record that is primarily responsible for the install base item. Located in the Contact [customer_contact] table.
    Note:
    Contacts can only be specified for account install base items.

    Data type: String
    household Sys_id of the household associated with the install base item record. Located in the Household [csm_household] table.
    Note:
    This field is only valid when the Customer Service Household (com.snc.household) plugin is installed.

    Data type: String
    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. Located in the Location [cmn_location] table.

    Data type: String
    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. Located in the Install Base Item [sn_install_base_item] table.

    Data type: String
    product_model Sys_id of the product model associated with the install base item record. Located in the Product Model [cmdb_model] table.

    Data type: String
    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. Located in the Service Organization [sn_customer_service_organization] table.

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

    The following request and response headers apply to this HTTP action only, or apply to this action in a distinct way. For a list of general headers used in the REST API, see Supported REST API headers.

    Table 88. Request 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
    Table 89. Response headers
    Header Description
    None

    Status codes

    The following status codes apply to this HTTP action. For a list of possible status codes used in the REST API, see REST API HTTP response codes.

    Table 90. Status 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

    "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

    "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

    "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

    "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

    "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. Located in the Install Base Item [sn_install_base_item] table.

    Data type: String
    item.configuration_item Details about the configuration item associated with the install base item record.

    Data type: Object

    "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

    "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

    "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

    "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

    "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 Service Household (com.snc.household) plugin is installed.

    Data type: Object

    "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

    "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

    "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

    "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

    "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

    "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

    "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

    "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

    "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

    "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

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

    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.

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

    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.

    {
  "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

    Supported request parameters

    Table 91. Path parameters
    Name Description
    api_version Optional. Version of the endpoint to access. For example, v1 or v2. Only specify this value to use an endpoint version other than the latest.

    Data type: String
    id Sys_id of the install base item record. Located in the Install Base Item [sn_install_base_item] table.

    Data type: String
    Table 92. Query parameters
    Name Description
    None
    Table 93. Request body parameters (XML or JSON)
    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. Located in the Account [customer_account] table.

    Note:
    If you pass the account parameter, you can't also pass the consumer parameter.

    Data type: String
    consumer Required if the type parameter is Authorized Consumer or Listed Consumer.
    Sys_id of the consumer associated with the install base item record. Located in the Consumer [csm_consumer] table.
    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
    contact Sys_id of the contact record associated with the related parties record. Located in the Contact [customer_contact] table.

    Data type: String
    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. Located in the Responsibility Definition [sn_customerservice_responsibility_def] table.

    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
    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. Located in the Service Organization [sn_customer_service_organization] table.

    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
    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. Located in the Related Party Configuration [sn_customerservice_related_party_configuration] table.
    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
    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. Located in the User [sys_user] table.

    Data type: String

    Headers

    The following request and response headers apply to this HTTP action only, or apply to this action in a distinct way. For a list of general headers used in the REST API, see Supported REST API headers.

    Table 94. Request 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
    Table 95. Response headers
    Header Description
    None

    Status codes

    The following status codes apply to this HTTP action. For a list of possible status codes used in the REST API, see REST API HTTP response codes.

    Table 96. Status 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

    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

    "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

    "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. Located in the Contact [customer_contact] table.

    Data type: String
    error Details about the error that occurred when trying to process the request.

    Data type: Object

    "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

    "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

    "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. Located in the Responsibility Definition [sn_customerservice_responsibility_def] table.

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

    "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 Add related party configurations to cases, sold products, install bases, or service organizations.
    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

    "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. Located in the User [sys_user] table.

    Data type: String

    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.

    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:

    {
"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",
  }
}