Verify Entitlements API

  • Release version: Yokohama
  • Updated January 30, 2025
  • 13 minutes to read

    • The Verify Entitlements API provides endpoints that enable you to obtain a list of valid entitlements, details about the characteristics of entitlements, and an entitlement's latest usage information.

    To access this API, the Entitlement Verification (com.sn_ent_verify) plugin must be activated.

    This API is provided within the sn_ent_verify namespace.

    The calling user must have the sn_pss_core.pss_integrator role.

    The REST endpoints of this API query data from the following tables:
    • Account [customer_account]
    • Consumer [csm_consumer]
    • Entitlement [service_entitlement]
    • Entitlement Characteristic [sn_pss_core_entitlement_characteristic]
    • Entitlement Usages [sn_pss_core_entitlement_usage]
    • Household [csm_household]
    • Install Base [sn_install_base_item]
    • Product Model [cmdb_model]
    • Product Offering [sn_prd_pm_product_offering]
    • Product Specification [sn_prd_pm_product_specification]
    • Service Contract [sn_pss_core_service_contract]
    • Service Contract Line [sn_pss_core_service_contract_line]
    • Sold Product [sn_install_base_sold_product]

    Verify Entitlements - GET /sn_ent_verify/verifyentitlements

    Returns the valid entitlement records based on the provided filter.

    You can filter entitlements based on:
    • Account
    • Consumer
    • Contract
    • Household
    • Install base
    • Product model
    • Product offering
    • Product specification
    • Service contract line
    • Sold entitlement
    • Sold product
    • State
    At a minimum, you must specify either the account or the consumer on which to filter the entitlements.

    When multiple filter parameters are passed, the endpoint applies the AND operator to the parameters. For example, if you pass filter parameters such as "account = boxeo" and “state = draft”, the endpoint returns all the entitlements with Account = boxeo AND state = draft.

    You can implement pagination for the return results by passing the system pagination parameters sysparm_offset and sysparm_limit. By default sysparm_offset is set to 0 and sysparm_limit is set to 10. So, if after applying the filter, 100 entitlements satisfy the criteria, the response will include the first 10 entitlements. You can modify these values by passing them in the endpoint call.

    URL format

    Versioned URL: /api/sn_ent_verify/{api_version}/verifyentitlements

    Default URL: /api/sn_ent_verify/verifyentitlements

    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

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

    Maximum: 100
    sysparm_offset Optional.
    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
    Table 2. Query parameters
    Name Description
    account Either the account or consumer parameter must be passed. They are mutually exclusive. Sys_id of the account record for which to return entitlement records.

    Data type: String

    Default: None

    Table: Account [customer_account]
    consumer Either the account or consumer parameter must be passed. They are mutually exclusive. Sys_id of the consumer record for which to return entitlement records.

    Data type: String

    Default: None

    Table: Consumer [csm_consumer]
    contract Sys_id of the contract record for which to return entitlement records.

    Data type: String

    Default: None

    Table: Contract [sn_pss_core_service_contract]
    display_value Flag that indicates whether to return the associated field value, display value, or both.
    Valid values:
    • true: Response contains only the display values of the fields. For example: "state": "Draft".
    • false: Response contains only the values of the fields. For example: "state": "draft".
    • all: Response contains all the information for the fields.

      For example:

      "state": {
  "name": "state",
  "label": "State",
  "value": "draft",
  "display_value": "true",
  "type": "string"
}

    Data type: String

    Default: false
    household Sys_id of the household record for which to return entitlement records.

    Data type: String

    Default: None

    Table: Household [csm_household]
    install_base Sys_id of the install base record for which to return entitlement records.

    The endpoint uses the sys_id of the install base record to search the Sold Product Covered [sn_install_base_m2m_contract_sold_product] table to return all entitlements covered by the associated install base.

    Data type: String

    Default: None

    Table: Install Base [sn_install_base_item]
    product Sys_id of the product record for which to return entitlement records.

    Data type: String

    Default: None

    Table: Product Model [cmdb_model]
    product_offering Sys_id of the product offering record for which to return entitlement records.

    Data type: String

    Default: None

    Table: Product Offering [sn_prd_pm_product_offering]
    product_specification Sys_id of product specification record for which to return entitlement records.

    Data type: String

    Default: None

    Table: Product Specification [sn_prd_pm_product_specification]
    service_contract_line Sys_id of the service contract line record for which to return entitlement records.

    Data type: String

    Default: None

    Table: Service Contract Line [sn_pss_core_service_contract_line]
    sold_entitlement Sys_id of the sold entitlement record for which to return entitlement records.

    Data type: String

    Default: None

    Table: Sold Product [sn_install_base_sold_product]
    sold_product Sys_id of the sold product record for which to return entitlement records.

    The endpoint uses the sys_id of the Sold Product record to search the Sold Product Covered [sn_install_base_m2m_contract_sold_product] table to return all entitlements covered by the associated sold product.

    Data type: String

    Default: None

    Table: Sold Product [sn_install_base_sold_product]
    state State of the entitlements to return.
    Valid values:
    • active
    • cancelled
    • draft
    • expired
    • suspended

    Data type: String

    Default: All
    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
    entitlements List of entitlements that match the passed filter criteria.

    Data type: Array of Objects

    "entitlements": [
  {
    "account": "String",
    "consumer": "String",
    "contract": "String",
    "end_date": "String",
    "entitlement_name": "String",
    "household": "String",
    "product": "String",
    "product_offering": "String",
    "product_specification": "String",
    "service_contract_line": "String",
    "sold_entitlement": "String",
    "start_date": "String",
    "state": "String",
    "sys_id": "String"
  }
]
    entitlements.account Sys_id of the account record associated with this entitlement.

    Data type: String

    Table: Account [customer_account]
    entitlements.consumer Sys_id of the consumer record associated with this entitlement.

    Data type: String

    Table: Consumer [csm_consumer]
    entitlements.contract Sys_id of the contract record associated with this entitlement.

    Data type: String

    Table: Contract [sn_pss_core_service_contract]
    entitlements.end_date Value of the End Date field on the associated entitlement record.

    Data type: String
    entitlements.entitlement_name Name of the entitlement.

    Data type: String
    entitlements.household Sys_id of the household record associated with this entitlement.

    Data type: String

    Table: Household [csm_household]
    entitlements.product Sys_id of the product record associated with this entitlement.

    Data type: String

    Table: Product Model [cmdb_model]
    entitlements.product_offering Sys_id of the product offer record associated with this entitlement.

    Data type: String

    Table: Product Offer [sn_prd_pm_product_offering]
    entitlements.product_specification Sys_id of the product specification record associated with this entitlement.

    Data type: String

    Table: Product Specification [sn_prd_pm_product_specification]
    entitlements.service_contract_line Sys_id of the service contract line record associated with this entitlement.

    Data type: String

    Table: Service Contract Line [sn_pss_core_service_contract_line]
    entitlements.sold_entitlement Sys_id of the sold entitlement record associated with this entitlement.

    Data type: String

    Table: Sold Product [sn_install_base_sold_product]
    entitlements.start_date Value of the Start Date field on the associated entitlement record.

    Data type: String
    entitlements.state State of the entitlements record.
    Possible values:
    • active
    • cancelled
    • draft
    • expired
    • suspended

    Data type: String
    entitlements.sys_id Sys_id of the entitlement record.

    Data type: String

    Table: Entitlement [service_entitlement]
    error Describes the error that occurred.

    Data type: Object

    "error": {
  "detail": "String",
  "message": "String"
}
    Examples of error responses:
    • Error message: Page size -20 is Invalid. Page size must be an integer between 1 and 100

      Error condition: Invalid sysparm_limit parameter passed. The sysparm_limit parameter must be between 1 and 100.

    • Error message: Page offset -23 is invalid. Offset must be an integer greater than or equal to 0

      Error condition: Invalid sysparm_offset parameter passed. The sysparm_offset parameter must be a whole number.

    • Error message: Invalid Query Parameter - accnt

      Error condition: Invalid query parameter, "accnt", was passed. Parameter should be "account".

    • Error message: Invalid choice value: state = drft

      Error condition: Invalid value, "drft", was passed. Parameter value should be "draft".
    error.detail Detailed information as to why the endpoint call failed.

    Data type: String
    error.message Message that describes the error at a high-level.

    Data type: String
    hasMore Flag that indicates whether there are more entitlement records to return.
    Possible values:
    • true: More entitlement records to return.
    • false: No more entitlement records.

    Data type: Boolean
    status Status of the endpoint call.
    Possible values:
    • failure: An error occurred when processing the request.
    • success: The call was processed successfully.

    Data type: String
    sysparm_limit If the sysparm_limit parameters was passed in the endpoint call, it contains the passed value, otherwise it contains the default value.

    Data type: Number
    sysparm_offset If the sysparm_offset parameters was passed in the endpoint call, it contains the passed value, otherwise it contains the default value.

    Data type: Number

    cURL request

    The following code example shows how to return entitlements for a specific account.

    curl "https://instance.service-now.com/api/sn_ent_verify/verifyentitlements?account=9e2fd2ee11b43110f877366201dea674" \
--request GET \
--header "Accept:application/json" \
--user "username":"password"

    Return results:

    {
  "result": {
    "sysparm_offset": "0",
    "sysparm_limit": "10",
    "has_more": "false",
    "entitlements": [
      {
        "sys_id": "38374bf251e27110f877bf82d3ddf30a",
        "entitlement_name": "test ent",
        "account": "9e2fd2ee11b43110f877366201dea674",
        "consumer": null,
        "household": null,
        "contract": "0e1747f251e27110f877bf82d3ddf31c",
        "service_contract_line": "da278fb251e27110f877bf82d3ddf3b7",
        "state": "active",
        "product_offering": null,
        "product_specification": null,
        "sold_entitlement": null,
        "product": null,
        "start_date": "2023-11-21",
        "end_date": ""
      },
      {
        "sys_id": "e6ad4e4151723d10f877bf82d3ddf3fb",
        "entitlement_name": "tets entitlement",
        "account": "9e2fd2ee11b43110f877366201dea674",
        "consumer": null,
        "household": null,
        "contract": "0e1747f251e27110f877bf82d3ddf31c",
        "service_contract_line": "e79dce4151723d10f877bf82d3ddf31d",
        "state": "active",
        "product_offering": null,
        "product_specification": null,
        "sold_entitlement": null,
        "product": null,
        "start_date": "2023-11-21",
        "end_date": ""
      }
    ],
    "status": "success"
  }
}

    cURL request

    The following code example shows how to return entitlements for a specific account and service contract line.

    curl "https://instance.service-now.com/api/sn_ent_verify/verifyentitlements?service_contract_line=e79dce4151723d10f877bf82d3ddf31d&account=9e2fd2ee11b43110f877366201dea674" \
--request GET \
--header "Accept:application/json" \
--user "username":"password"

    Return results:

    {
  "result": {
    "sysparm_offset": "0",
    "sysparm_limit": "10",
    "has_more": "false",
    "entitlements": [
      {
        "sys_id": "e6ad4e4151723d10f877bf82d3ddf3fb",
        "entitlement_name": "test entitlement",
        "account": "9e2fd2ee11b43110f877366201dea674",
        "consumer": null,
        "household": null,
        "contract": "0e1747f251e27110f877bf82d3ddf31c",
        "service_contract_line": "e79dce4151723d10f877bf82d3ddf31d",
        "state": "active",
        "product_offering": null,
        "product_specification": null,
        "sold_entitlement": null,
        "product": null,
        "start_date": "2023-11-21",
        "end_date": ""
      }
    ],
    "status": "success"
  }
}

    cURL request

    The following code example shows an error response.

    curl "https://instance.service-now.com/api/sn_ent_verify/verifyentitlements?service_contract_line=e79dce4151723d10f877bf82d3ddf31d" \
--request GET \
--header "Accept:application/json" \
--user "username":"password"

    Return results:

    {
  "error": {
    "detail": "At least one of Account or Consumer parameter is mandatory.",
    "message": "At least one of Account or Consumer parameter is mandatory."
  },
  "status": "failure"
}

    Verify Entitlements - GET /sn_ent_verify/verifyentitlements/getEntitlementCharacteristic/{id}

    Returns details of the specified entitlement characteristic record and its latest usage record.

    The latest usage record for a characteristic is defined as the record where the period start date is less than or equal to the current date and the period end date is greater than or equal to the current date.

    URL format

    Versioned URL: /api/sn_ent_verify/{api_version}/verifyentitlements/getEntitlementCharacteristic/{id}

    Default URL: /api/sn_ent_verify/verifyentitlements/getEntitlementCharacteristic/{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

    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
    id Sys_id of the entitlement characteristic record to return.

    Data type: String

    Table: Entitlement Characteristic [sn_pss_core_entitlement_characteristic]
    Table 8. Query parameters
    Name Description
    display_value Flag that indicates whether to return the associated field value, display value, or both.
    Valid values:
    • true: Response contains only the display values of the fields. For example: "state": "Draft".
    • false: Response contains only the values of the fields. For example: "state": "draft".
    • all: Response contains all the information for the fields.

      For example:

      "state": {
  "name": "state",
  "label": "State",
  "value": "draft",
  "display_value": "true",
  "type": "string"
}

    Data type: String

    Default: false
    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.
    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
    characteristic Sys_id of the associated entitlement characteristic record.

    Data type: String

    Table: Characteristic [sn_prd_pm_characteristic]
    characteristic_option Sys_id of the associated characteristic options record.

    Data type: String

    Table: Characteristic Option [sn_prd_pm_characteristic_option]
    entitlement_usage Details about the entitlement usage record associated with the specified entitlement characteristic record.

    Data type: Array of Objects

    "entitlement_usage": [
  {
    "entitlement_characteristic": "String",
    "period_end": "String",
    "period_start": "String",
    "sys_id": "String",
    "total_units": "String",
    "used_units": "String"
  }
]
    entitlement_usage.​entitlement_characteristic Sys_id of the associated entitlement characteristic record.

    Data type: String

    Table: Entitlement Characteristic [sn_pss_core_entitlement_characteristic]
    entitlement_usage.​period_end Value of the period end field in the entitlement usage record. This value is the date that the usage tracking ends for this entitlement.

    Data type: String
    entitlement_usage.​period_start Value of the period start field in the entitlement usage record. This value is the date that the usage tracking starts for this entitlement.

    Data type: String
    entitlement_usage.​sys_id Sys_id of the returned entitlement usage record.

    Data type: String

    Table: Entitlement Usages [sn_pss_core_entitlement_usage]
    entitlement_usage.​total_units Total number of units purchased.

    Data type: String

    Table: In the total_units field of the Entitlement Usages [sn_pss_core_entitlement_usage] table.
    entitlement_usage.​used_units Number of units that have been used.

    Data type: String

    Table: In the used_units field in the Entitlement Usages [sn_pss_core_entitlement_usage] table.
    sys_id Sys_id of the entitlement characteristic record.

    Data type: String

    Table: Entitlement Characteristic [sn_pss_core_entitlement_characteristic]
    type Value of the type field in the entitlement characteristic record.
    Possible values:
    • coverage
    • coverage_and_usage

    Data type: String
    value Coverage to give the characteristic.

    For some characteristics, coverages are defined in the Characteristic Option table. However, if there are no coverages defined in the Characteristic Option table, then you can pass the coverage information in the value parameter.

    Characteristic options are only defined for the characteristic types of:
    • check box
    • choice
    • yes/no
    For all other types of characteristics, the value parameter should contain the coverage value.

    For example, if the characteristic is “Number of Replacements” and its coverages are not defined in the Characteristic Option table, you can specify the coverages, such as "10", "20", in this parameter.

    Note:
    This parameter contains the final coverage value for the characteristic. If there is information in the Characteristic Option table, it is propagated to this parameter.

    Data type: String

    cURL request

    The following code example shows how to call this endpoint using all of its default values.

    curl "https://instance.servicenow.com/api/sn_ent_verify/verifyentitlements/getEntitlementCharacteristic/3c817faa43823110341605ed0bb8f23a" \
--request GET \
--header "Accept:application/json" \
--user "username":"password"

    Return results:

    {
  "result": {
    "sys_id": "3c817faa43823110341605ed0bb8f23a",
    "characteristic": "b73177aa43823110341605ed0bb8f246",
    "type": "coverage",
    "characteristic_option": "ff617baa43823110341605ed0bb8f266",
    "value": "Minor parts",
    "entitlement_usage": [
      {
        "sys_id": "03e3224d51b23d10f877bf82d3ddf310",
        "period_start": "2022-12-12",
        "period_end": "2025-12-12",
        "entitlement_characteristic": "3c817faa43823110341605ed0bb8f23a",
        "total_units": "10",
        "used_units": "5"
      }
    ]
  }
}

    cURL request

    The following code example shows how to call this endpoint and return all display values.

    curl "https://instance.servicenow.com/api/sn_ent_verify/verifyentitlements/getEntitlementCharacteristic/3c817faa43823110341605ed0bb8f23a?display_value=all" \
--request GET \
--header "Accept:application/json" \
--user "username":"password"

    Return results:

    {
  "result": {
    "sys_id": {
      "label": "Sys ID",
      "value": "3c817faa43823110341605ed0bb8f23a",
      "displayValue": "3c817faa43823110341605ed0bb8f23a",
      "type": "GUID"
    },
    "characteristic": {
      "name": "characteristic",
      "label": "Characteristic",
      "value": "b73177aa43823110341605ed0bb8f246",
      "display_value": "Repair parts covered",
      "type": "reference"
    },
    "type": {
      "name": "type",
      "label": "Type",
      "value": "coverage",
      "display_value": "Coverage",
      "type": "string"
    },
    "characteristic_option": {
      "name": "characteristic_option",
      "label": "Characteristic option",
      "value": "ff617baa43823110341605ed0bb8f266",
      "display_value": "Minor parts",
      "type": "reference"
    },
    "value": {
      "name": "value",
      "label": "Value",
      "value": "Minor parts",
      "display_value": "Minor parts",
      "type": "string"
    },
    "entitlement_usage": [
      {
        "sys_id": {
          "label": "Sys ID",
          "value": "03e3224d51b23d10f877bf82d3ddf310",
          "displayValue": "03e3224d51b23d10f877bf82d3ddf310",
          "type": "GUID"
        },
        "period_start": {
          "name": "period_start",
          "label": "Period start",
          "value": "2022-12-12",
          "display_value": "2022-12-12",
          "type": "glide_date"
        },
        "period_end": {
          "name": "period_end",
          "label": "Period end",
          "value": "2025-12-12",
          "display_value": "2025-12-12",
          "type": "glide_date"
        },
        "entitlement_characteristic": {
          "name": "entitlement_characteristic",
          "label": "Entitlement characteristic",
          "value": "3c817faa43823110341605ed0bb8f23a",
          "display_value": "Repair parts covered",
          "type": "reference"
        },
        "total_units": {
          "name": "total_units",
          "label": "Total units",
          "value": "10",
          "display_value": "10",
          "type": "string"
        },
        "used_units": {
          "name": "used_units",
          "label": "Used units",
          "value": "5",
          "display_value": "5",
          "type": "string"
        }
      }
    ]  
  }
}