AustraliaREFERENCE GUIDE

Entitlement API

ServiceNow documentation·14 min readView source ↗

On this page

Entitlement API

The Entitlement API provides endpoints to create and retrieve entitlement records from an instance.

Entitlement checks occur as part of post-sales support services for customers that purchase a product, such as an appliance or computer. Entitlement checks are made by agents to determine what services customers are eligible to receive for the products they’ve purchased. Use the Entitlement API to define and retrieve entitlements.

This API accesses and stores data in the following tables:

Account [customer_account]
Consumer [csm_consumer]
Household [csm_household]
Install Base [sn_install_base_item]
Product Model [cmdb_model]
Product Offering [sn_prd_pm_product_offering]
Sold Product [sn_install_base_sold_product]

To access this API, the following plugins must be activated on the associated instance:

Customer Contracts and Entitlements (com.sn_pss_core)
Customer Service Install Base Management (com.snc.install_base)
Product Catalog Management Core (com.sn_prd_pm)

In addition, to successfully call this API you must have the sn_pss_core.pss_integrator role. This API runs in the sn_pss_core namespace.

Parent Topic:REST API reference

Entitlement - GET /sn_pss_core/entitlement/{id}

Returns the specified entitlement record, its associated coverage, and its latest usage details.

The following is the list of tables in which the entitlement data is stored:

Characteristics [sn_pss_core_entitlement_characteristic]
Entitlement [service_entitlement]
Entitlement Usage [sn_pss_core_entitlement_usage]
Sold Product Covered [sn_install_base_m2m_contract_sold_product] - This table contains information for both sold products covered and install base items covered.

URL format

Versioned URL: /api/sn_pss_core/{api_version}/entitlement/{id}

Default URL: /api/sn_pss_core/entitlement/{id}

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

Supported request parameters

Name

</th><th>

Description

</th></tr></thead><tbody><tr><td>

api_version

</td><td id=“version-entry-RESTAPI”>

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

</td></tr><tr><td>

</td><td>

Sys_id of the entitlement record to retrieve.Data type: String

Table: Entitlement [service_entitlement]

</td></tr></tbody> </table><table class=“rest_api_query_parameters”><thead><tr><th>

Name

</th><th>

Description

</th></tr></thead><tbody><tr><td>

display_value

</td><td>

Type of data to return.Valid values:

false: Return the value for all fields. For example, "state":"draft".
true: Return the display_value for all fields. For example, "state":"Draft"
all: Return all information for all fields.

Data type: String

Default: false

Headers

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

Header

</th><th>

Description

</th></tr></thead><tbody><tr><td>

</td><td id=“accept-entry-RESTAPI”>

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

Status codes

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

Status code Description 200 Successful. The request was successfully processed. 400 Bad Request. A bad request type or malformed request was detected. 403 Forbidden. The user doesn’t have access rights to the specified record. 404 Not found. The requested item wasn’t found. 500 Internal server error. An unexpected error occurred while processing the request. The response contains additional information about the error.

Response body parameters

Name

</th><th>

Description

</th></tr></thead><tbody><tr><td>

account

</td><td>

Sys_id of the account record to which the entitlement belongs.

Data type: String

Table: Account [customer_account]

</td></tr><tr><td>

consumer

</td><td>

Sys_id of the consumer record to which the entitlement belongs.

Data type: String

Table: Consumer [csm_consumer]

</td></tr><tr><td>

contract

</td><td>

Sys_id of the contract record to which the entitlement belongs.Data type: String

Table: Service Contract [sn_pss_core_service_contract]

</td></tr><tr><td>

end_date

</td><td>

End date of the entitlement.Data type: String

Format: yyyy-mm-dd

Default: Never ends until manually removed.

</td></tr><tr><td>

entitlement_characteristics

</td><td>

List of characteristics associated with the entitlement.Data type: Array of Objects

"entitlement_characteristics" [
  {
    "characteristic": "String",
    "characteristic_option": "String",
    "entitlement": "String",
    "entitlement_usage": [Array],
    "service_contract_line": "String",
    "sys_created_by": "String",
    "sys_created_on": "String",
    "sys_id": "String",
    "sys_updated_by": "String",
    "sys_updated_on": "String",
    "type": "String",
    "value": "String"
  }
]

Stored in: Characteristic [sn_pss_core_entitlement_characteristic]

</td></tr><tr><td>

entitlement_characteristics.characteristic

</td><td>

Sys_id of the characteristic record associated with the entitlement.

Data type: String

Table: Characteristic [sn_prd_pm_characteristic]

</td></tr><tr><td>

entitlement_characteristics.characteristic_option

</td><td>

Sys_id of the characteristic option record associated with the entitlement.Data type: String

Table: Characteristic Option [sn_prd_pm_characteristic_option]

</td></tr><tr><td>

entitlement_characteristics.entitlement

</td><td>

Sys_id of the associated entitlement record.Data type: String

Table: Entitlement [service_entitlement]

</td></tr><tr><td>

entitlement_characteristics.entitlement_usage

</td><td>

List of entitlement usages associated with the entitlement characteristic.Data type: Array of Objects

"entitlement_usage": [
  {
    "entitlement": "String",
    "entitlement_characteristic": "String",
    "period_end": "String",
    "period_start": "String",
    "service_contract_line": "String",
    "sys_created_by": "String",
    "sys_created_on": "String",
    "sys_id": "String",
    "sys_updated_by": "String",
    "sys_updated_on": "String",
    "total_units": "String",
    "used_units": "String"
  }
]

</td></tr><tr><td>

entitlement_characteristics.entitlement_usage.entitlement

</td><td>

Sys_id of the entitlement record associated with the entitlement usage.Data type: String

Table: Entitlement [service_entitlement]

</td></tr><tr><td>

entitlement_characteristics.entitlement_usage.entitlement_characteristic

</td><td>

Sys_id of the entitlement characteristic record associated with the entitlement usage.Data type: String

Table: Characteristic [sn_pss_core_entitlement_characteristic]

</td></tr><tr><td>

entitlement_characteristics.entitlement_usage.period_end

</td><td>

End date when the entitlement usage is no longer tracked.Data type: String

Format: yyyy-mm-dd

</td></tr><tr><td>

entitlement_characteristics.entitlement_usage.period_start

</td><td>

Starting date of when the entitlement usage is tracked.Data type: String

Format: yyyy-mm-dd

</td></tr><tr><td>

entitlement_characteristics.entitlement_usage.service_contract_line

</td><td>

Sys_id of the service contract line to which the current entitlement usage belongs. Data type: String

</td></tr><tr><td>

entitlement_characteristics.entitlement_usage.sys_created_by

</td><td>

Name of the user that created the entitlement usage record.Data type: String

</td></tr><tr><td>

entitlement_characteristics.entitlement_usage.sys_created_on

</td><td>

Date and time that the entitlement usage record was created.Data type: String

</td></tr><tr><td>

entitlement_characteristics.entitlement_usage.sys_id

</td><td>

Sys_id of the entitlement usage record.Data type: String

Table: Entitlement Usage [sn_pss_core_entitlement_usage]

</td></tr><tr><td>

entitlement_characteristics.entitlement_usage.sys_updated_by

</td><td>

Name of the user that last updated the entitlement usage record.Data type: String

</td></tr><tr><td>

entitlement_characteristics.entitlement_usage.sys_updated_on

</td><td>

Date and time that the entitlement usage record was last updated.Data type: String

</td></tr><tr><td>

entitlement_characteristics.entitlement_usage.total_units

</td><td>

Total coverage value of the associated entitlement characteristic.Data type: String

</td></tr><tr><td>

entitlement_characteristics.entitlement_usage.used_units

</td><td>

Number of units used by the account or consumer between the period_start and the period_end.Data type: String

</td></tr><tr><td>

entitlement_characteristics.type

</td><td>

Type of entitlement characteristic. Valid values:

coverage
coverage_and_usage

Data type: String

</td></tr><tr><td>

entitlement_characteristics.value

</td><td>

Value of the characteristic.

Data type: String

</td></tr><tr><td>

entitlement_name

</td><td>

Name of the entitlement.

Data type: String

</td></tr><tr><td>

household

</td><td>

Sys_id of the household record associated with the entitlement.

Data type: String

Table: Household [csm_household]

</td></tr><tr><td>

install_base_items_covered

</td><td>

List of install base items covered under the entitlement.Data type: Array of Objects

 "install_base_items_covered": [ 
  {
    "added": "String",
    "contract": "String",
    "entitlement": "String",
    "install_base": "String",
    "removed": "String",
    "service_contract_line": "String",
    "sys_created_by": "String",
    "sys_created_on": "String",
    "sys_id": "String",
    "sys_updated_by": "String",
    "sys_updated_on": "String"
  }
]

Table: Sold Product Covered [sn_install_base_m2m_contract_sold_product]

</td></tr><tr><td>

install_base_items_covered.added

</td><td>

Date that the associated install base item was added to the entitlement.Data type: String

</td></tr><tr><td>

install_base_items_covered.contract

</td><td>

Sys_id of the service contract record associated with the install base item.Data type: String

Table: Service Contract [sn_pss_core_service_contract]

</td></tr><tr><td>

install_base_items_covered.install_base

</td><td>

Sys_id of the install base item covered by the service contract line.Data type: String

Table: Install Base Item [sn_install_base_item]

</td></tr><tr><td>

install_base_items_covered.removed

</td><td>

Date that the associated install base item was removed from the entitlement.Data type: String

</td></tr><tr><td>

install_base_items_covered.entitlement

</td><td>

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

Table: Entitlement [service_entitlement]

</td></tr><tr><td>

install_base_items_covered.service_contract_line

</td><td>

Sys_id of the associated service contract line record.Data type: String

Table: Service Contract Line [sn_pss_core_service_contract_line]

</td></tr><tr><td>

install_base_items_covered.sys_created_by

</td><td>

Name of the user that created the install base item record.Data type: String

</td></tr><tr><td>

install_base_items_covered.sys_created_on

</td><td>

Date and time that the install base item record was created.Data type: String

</td></tr><tr><td>

install_base_items_covered.sys_id

</td><td>

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

Table: Sold Product Covered [sn_install_base_m2m_contract_sold_product]

</td></tr><tr><td>

install_base_items_covered.sys_updated_by

</td><td>

Name of the user that last updated the install base item record.Data type: String

</td></tr><tr><td>

install_base_items_covered.sys_updated_on

</td><td>

Date and time that the install base item record was last updated.Data type: String

</td></tr><tr><td>

product

</td><td>

Sys_id of the product model record associated with the entitlement.Data type: String

Table: Product Model [cmdb_model]

</td></tr><tr><td>

product_offering

</td><td>

Sys_id of the product offering record associated with the entitlement.Data type: String

Table: Product Offering [sn_prd_pm_product_offering]

</td></tr><tr><td>

sold_entitlement

</td><td>

Sys_id of the sold product record associated with the entitlement.Data type: String

Table: Sold Product [sn_install_base_sold_product]

</td></tr><tr><td>

sold_products_covered

</td><td>

List of products covered.Data type: Array of Objects

"sold_products_covered": [ 
  {
    "added": "String",
    "contract": "String",
    "entitlement": "String",
    "removed": "String",
    "service_contract_line": "String",
    "sold_product": "String",
    "sys_created_by": "String",
    "sys_created_on": "String",
    "sys_id": "String",
    "sys_updated_by": "String",
    "sys_updated_on": "String"
  }
]

Table: Sold Product Covered [sn_install_base_m2m_contract_sold_product]

</td></tr><tr><td>

sold_products_covered.added

</td><td>

Date that the associated sold product was added to the entitlement.Data type: String

Format: yyyy-mm-dd

Default: Current date

</td></tr><tr><td>

sold_products_covered.contract

</td><td>

Sys_id of the service contract record associated with the sold product covered.Data type: String

Table: Service Contract [sn_pss_core_service_contract]

</td></tr><tr><td>

sold_products_covered.entitlement

</td><td>

Sys_id of the entitlement record associated with the sold product covered.Data type: String

Table: Entitlement [service_entitlement]

</td></tr><tr><td>

sold_products_covered.removed

</td><td>

Date that the associated sold product was removed from the entitlement.Data type: String

Format: yyyy-mm-dd

Default: No end date

</td></tr><tr><td>

sold_products_covered.service_contract_line

</td><td>

Sys_id of the service contract line record associated with the sold product covered.Data type: String

Table: Service Contract Line [sn_pss_core_service_contract_line]

</td></tr><tr><td>

sold_products_covered.sold_product

</td><td>

Sys_id of the product covered by the entitlement.Data type: String

Table: Sold Product [sn_install_base_sold_product]

</td></tr><tr><td>

sold_products_covered.sys_created_by

</td><td>

Name of the user that created the sold product covered record.Data type: String

</td></tr><tr><td>

sold_products_covered.sys_created_on

</td><td>

Date and time that the sold product covered record was created.Data type: String

</td></tr><tr><td>

sold_products_covered.sys_id

</td><td>

Sys_id of the product covered by this service contract.Data type: String

Table: Sold Product Covered [sn_install_base_m2m_contract_sold_product]

</td></tr><tr><td>

sold_products_covered.sys_updated_by

</td><td>

Name of the user that last updated the sold product covered record.Data type: String

</td></tr><tr><td>

sold_products_covered.sys_updated_on

</td><td>

Date and time that the sold product covered record was last updated.Data type: String

</td></tr><tr><td>

start_date

</td><td>

Start date of the entitlement.

Data type: String

Format: yyyy-mm-dd

</td></tr><tr><td>

state

</td><td>

Current state of the entitlement.

Valid values: (case-sensitive)

active
cancelled
draft
expired
suspended

Data type: String

</td></tr><tr><td>

sys_created_by

</td><td>

Name of the user that created the entitlement record.Data type: String

</td></tr><tr><td>

sys_created_on

</td><td>

Date and time that the entitlement record was created.Data type: String

</td></tr><tr><td>

sys_id

</td><td>

Sys_id of the associated entitlement record.Data type: String

Table: Entitlement [service_entitlement]

</td></tr><tr><td>

sys_updated_by

</td><td>

Name of the user that last updated the entitlement record.Data type: String

</td></tr><tr><td>

sys_updated_on

</td><td>

Date and time that the entitlement record was created.Data type: String

</td></tr></tbody> </table>### cURL request

The following example shows how to call this endpoint to retrieve an entitlement template.

curl "https://instance.servicenow.com/api/sn_pss_core/entitlement/fc73d2de89226110f877430a4e008" \
--request GET \
--header "Accept:application/json" \
--user "username":"password"

Response:

{
  "result": {
    "sys_id": "5a651515d1f53110f8776589fa411f7b",
    "sys_created_by": "admin",
    "sys_updated_by": "admin",
    "sys_created_on": "2023-10-09 11:31:59",
    "sys_updated_on": "2023-10-09 11:31:59",
    "entitlement_name": "indep entl",
    "account": "4c325111d1f53110f8776589fa411f3d",
    "consumer": null,
    "household": null,
    "contract": null,
    "service_contract_line": null,
    "state": "active",
    "product_offering": null,
    "sold_entitlement": null,
    "product": null,
    "start_date": "2023-10-03",
    "end_date": "2024-12-03",
    "sold_products_covered": [
      {
        "sys_id": "d6651515d1f53110f8776589fa411f7c",
        "sys_created_by": "admin",
        "sys_updated_by": "admin",
        "sys_created_on": "2023-10-09 11:31:59",
        "sys_updated_on": "2023-10-09 11:31:59",
        "contract": null,
        "service_contract_line": null,
        "entitlement": "5a651515d1f53110f8776589fa411f7b",
        "sold_product": "0df21151d1f53110f8776589fa411f1b",
        "added": "",
        "removed": ""
      }
    ],
    "install_base_items_covered": [
      {
        "sys_id": "12651515d1f53110f8776589fa411f7d",
        "sys_created_by": "admin",
        "sys_updated_by": "admin",
        "sys_created_on": "2023-10-09 11:31:59",
        "sys_updated_on": "2023-10-09 11:31:59",
        "contract": null,
        "service_contract_line": null,
        "entitlement": "5a651515d1f53110f8776589fa411f7b",
        "install_base": "e2639951d1f53110f8776589fa411f2b",
        "added": "",
        "removed": ""
      }
    ],
    "entitlement_characteristics": [
      {
        "sys_id": "12651515d1f53110f8776589fa411f7e",
        "sys_created_by": "admin",
        "sys_updated_by": "admin",
        "sys_created_on": "2023-10-09 11:31:59",
        "sys_updated_on": "2023-10-09 11:31:59",
        "service_contract_line": null,
        "entitlement": "5a651515d1f53110f8776589fa411f7b",
        "characteristic_option": "495149b7539e61106bfcddeeff7b1262",
        "value": "5",
        "characteristic": "63418db7539e61106bfcddeeff7b1238",
        "type": "coverage_and_usage",
        "entitlement_usage": [
          {
            "sys_id": "de651515d1f53110f8776589fa411f7e",
            "sys_created_by": "admin",
            "sys_updated_by": "admin",
            "sys_created_on": "2023-10-09 11:31:59",
            "sys_updated_on": "2023-10-09 11:31:59",
            "entitlement": "5a651515d1f53110f8776589fa411f7b",
            "service_contract_line": null,
            "entitlement_characteristic": "12651515d1f53110f8776589fa411f7e",
            "period_start": "2023-10-03",
            "period_end": "2024-12-03",
            "total_units": "5",
            "used_units": "25"
          }
        ]
      }
    ]
  }
}

Entitlement - POST /sn_pss_core/entitlement

Creates an entitlement record and all its related detail records.

The following is the list of tables in which the entitlement data is stored:

Characteristic [sn_pss_core_entitlement_characteristic]
Entitlement [service_entitlement]
Entitlement Usage [sn_pss_core_entitlement_usage]
Sold Products Covered [sn_install_base_m2m_contract_sold_product] - This table contains information for both sold products covered and install base items covered.

URL format

Versioned URL: /api/sn_pss_core/{api_version}/entitlement

Default URL: /api/sn_pss_core/entitlement

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

Supported request parameters

Name

</th><th>

Description

</th></tr></thead><tbody><tr><td>

api_version

</td><td id=“version-entry-RESTAPI”>

Optional. Version of the endpoint to access. For example, v1 or v2. Only specify this value to use an endpoint version other than the latest. Data type: String

Name

</th><th>

Description

</th></tr></thead><tbody><tr><td>

account

</td><td>

Required if the consumer parameter is not passed.Sys_id of the account record to which the entitlement belongs.

Data type: String

Table: Account [customer_account]

</td></tr><tr><td>

consumer

</td><td>

Required if the account parameter is not passed. Sys_id of the consumer record to which the entitlement belongs.

Data type: String

Table: Consumer [csm_consumer]

</td></tr><tr><td>

end_date

</td><td>

End date of the entitlement.Data type: String

Format: yyyy-mm-dd

Default: Never ends until manually removed.

</td></tr><tr><td>

entitlement_characteristics

</td><td>

List of characteristics associated with the entitlement.Data type: Array of Objects

"entitlement_characteristics": [
  {
    "characteristic": "String",
    "characteristic_option": "String",
    "entitlement_usage": {Object},
    "type": "String",
    "value": "String"
  }
]

Stored in: Characteristic [sn_pss_core_entitlement_characteristic]

</td></tr><tr><td>

entitlement_characteristics.characteristic

</td><td>

Required. Sys_id of the characteristic record associated with the entitlement.

Data type: String

Table: Characteristic [sn_prd_pm_characteristic]

</td></tr><tr><td>

entitlement_characteristics.characteristic_option

</td><td>

Sys_id of the characteristic option record associated with the entitlement.Data type: String

Table: Characteristic Option [sn_prd_pm_characteristic_option]

</td></tr><tr><td>

entitlement_characteristics.entitlement_usage

</td><td>

Used unit value for the associated entitlement characteristic.Only pass this parameter if the entitlement_characteristics are under the entitlement.

Data type: Object

"entitlement_usage": {
    "used_units": "String"
}

Stored in: Entitlement Usage [sn_pss_core_entitlement_usage]

</td></tr><tr><td>

entitlement_characteristics.entitlement_usage.usage_units

</td><td>

Usage of the associated entitlement characteristic.Data type: String

</td></tr><tr><td>

entitlement_characteristics.type

</td><td>

Type of entitlement characteristic. Valid values:

coverage
coverage_and_usage

Data type: String

</td></tr><tr><td>

entitlement_characteristics.value

</td><td>

Required if the input_type parameter contained in the record specified in the entitlement_characteristics.characteristic parameter, is not choice.Value of the characteristic.

Data type: String

</td></tr><tr><td>

entitlement_name

</td><td>

Required. Name of the entitlement.

Data type: String

</td></tr><tr><td>

household

</td><td>

Only passed when the household plugins are active and the consumer parameter is passed. Sys_id of the household record associated with the entitlement.

Data type: String

Table: Household [csm_household]

</td></tr><tr><td>

install_base_items_covered

</td><td>

List of install base items covered under the entitlement. The information in this array is inserted in the Sold Product Covered [sn_install_base_m2m_contract_sold_product] table.

Data type: Array of Objects

"install_base_items_covered": [ { "added": "String", "install_base": "String", "removed": "String" } ]

For more information on Install Base Items Configure install base.

</td></tr><tr><td>

install_base_items_covered.added

</td><td>

Date that the associated install base item was added to the entitlement.Data type: String

Format: yyyy-mm-dd

Default: Current date

</td></tr><tr><td>

install_base_items_covered.install_base

</td><td>

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

Table: Install Base Item [sn_install_base_item]

</td></tr><tr><td>

install_base_items_covered.removed

</td><td>

Date that the associated install base item was removed from the entitlement.Data type: String

Format: yyyy-mm-dd

Default: No end date

</td></tr><tr><td>

product

</td><td>

Sys_id of the product model record associated with the entitlement.Data type: String

Table: Product Model [cmdb_model]

</td></tr><tr><td>

product_offering

</td><td>

Sys_id of the product offering record associated with the entitlement.Data type: String

Table: Product Offering [sn_prd_pm_product_offering]

</td></tr><tr><td>

sold_entitlement

</td><td>

Sys_id of the sold product record associated with the entitlement.Data type: String

Table: Sold Product [sn_install_base_sold_product]

</td></tr><tr><td>

sold_products_covered

</td><td>

List of products covered under the entitlement.Data type: Array of Objects

"sold_products_covered": [ 
  {
    "added": "String",
    "removed": "String",
    "sold_product": "String"
  }
]

Stored in: Sold Product Covered [sn_install_base_m2m_contract_sold_product]

</td></tr><tr><td>

sold_products_covered.added

</td><td>

Date that the associated sold product was added to the entitlement.Data type: String

Format: yyyy-mm-dd

Default: Current date

</td></tr><tr><td>

sold_products_covered.removed

</td><td>

Date that the associated sold product was removed from the entitlement.Data type: String

Format: yyyy-mm-dd

Default: No end date

</td></tr><tr><td>

sold_products_covered.sold_product

</td><td>

Sys_id of the product covered by the entitlement.Data type: String

Table: Sold Product [sn_install_base_sold_product]

</td></tr><tr><td>

start_date

</td><td>

Required. Start date of the entitlement.

Data type: String

Format: yyyy-mm-dd

</td></tr><tr><td>

state

</td><td>

Required.Current state of the entitlement.

Valid values: (case-sensitive)

active
cancelled
draft
expired
suspended

Data type: String

</td></tr></tbody> </table>### Headers

Header

</th><th>

Description

</th></tr></thead><tbody><tr><td>

</td><td id=“accept-entry-RESTAPI”>

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

</td></tr><tr><td>

Content-Type

</td><td id=“content_type-entry-RESTAPI”>

Data format of the request body. Supported types: application/json or application/xml. Default: application/json

Status codes

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

Status code Description 201 Successful. The request was successfully processed and the records were created. 400 Bad Request. A bad request type or malformed request was detected. 403 Forbidden. The user doesn’t have permission to access the API. 500 Internal server error. An unexpected error occurred while processing the request. The response contains additional information about the error.

Response body parameters (JSON)

Name

</th><th>

Description

</th></tr></thead><tbody><tr><td>

entitlement_characteristics

</td><td>

List of the entitlement characteristic objects created under the entitlement. Data type: Array of Objects

"entitlement_characteristics" [
  {
    "entitlement_usage": {Object},
    "sys_id": "String"
  }
]

</td></tr><tr><td>

entitlement_characteristics.entitlement_usage

</td><td>

Entitlement usage object inserted under the entitlement_characteristic.Data type: Object

"entitlement_usage": {
    "sys_id": "String"
}

</td></tr><tr><td>

entitlement_characteristics.entitlement_usage.sys_id

</td><td>

Sys_id of the entitlement usage record.Data type: String

Table: Entitlement Usage [sn_pss_core_entitlement_usage]

</td></tr><tr><td>

entitlement_characteristics.sys_id

</td><td>

Sys_id of a entitlement characteristics record associated with the entitlement.Data type: String

Table: Characteristic [sn_pss_core_entitlement_characteristic]

</td></tr><tr><td>

entitlement_name

</td><td>

Name of the entitlement.

Data type: String

</td></tr><tr><td>

install_base_items_covered

</td><td>

List of sys_ids of the install base items covered under the entitlement. Data type: Array of Objects

"install_base_items_covered": [ 
  {
    "sys_id": "String"
  }
]

</td></tr><tr><td>

install_base_items_covered.sys_id

</td><td>

Sys_id of a install base items covered by the entitlement.Data type: String

Table: Sold Product Covered [sn_install_base_m2m_contract_sold_product]

</td></tr><tr><td>

sold_prodocts_covered

</td><td>

List of sys_ids of the products covered under the entitlement. Data type: Array of Objects

"sold_products_covered": [ 
  {
    "sys_id": "String"
  }
]

</td></tr><tr><td>

sold_products_covered.sys_id

</td><td>

Sys_id of a product associated with the entitlement.Data type: String

Table: Sold Product Covered [sn_install_base_m2m_contract_sold_product]

</td></tr><tr><td>

sys_id

</td><td>

Sys_id of the associated entitlement record.Data type: String

Table: Entitlement [service_entitlement]

</td></tr></tbody> </table>### cURL request

The following example shows how to create an entitlement template.

curl "https://instance.servicenow.com/api/sn_pss_core/entitlement" \
--request POST \
--header "Accept:application/json" \
--data
{
  "state": "active",
  "entitlement_name": "indep entl",
  "account": "4c325111d1f53110f8776589fa411f3d",
  "start_date": "2023-10-03",
  "end_date": "2024-12-03",
  "sold_products_covered": [
    {
      "sold_product": "0df21151d1f53110f8776589fa411f1b"
    }
  ], 
  "install_base_items_covered": [
    {
      "install_base": "e2639951d1f53110f8776589fa411f2b"
    }
  ],
  "entitlement_characteristics": [
    {
      "characteristic": "63418db7539e61106bfcddeeff7b1238",
      "characteristic_option": "495149b7539e61106bfcddeeff7b1262",
      "value": "20",
      "type": "coverage_and_usage",
      "entitlement_usage": {
        "used_units": "25"
      } 
    }
  ]
}

Response:

{
  "result": {
    "sys_id": "5a651515d1f53110f8776589fa411f7b",
    "entitlement_name": "indep entl",
    "sold_products_covered": [
      {
        "sys_id": "d6651515d1f53110f8776589fa411f7c"
      }
    ],
    "install_base_items_covered": [
      {
        "sys_id": "12651515d1f53110f8776589fa411f7d"
      }
    ],
    "entitlement_characteristics": [
      {
        "sys_id": "12651515d1f53110f8776589fa411f7e",
        "entitlement_usage": {
          "sys_id": "de651515d1f53110f8776589fa411f7e"
        }
      }
    ]
  }
}

Keep exploring.

Find another answer, or bring this documentation into your own tools.

Search the library →Read via the REST API ↗