---
sourceDocument: Yokohama API Reference
sourceDocumentLink: https://www.servicenow.com/docs/r/yokohama/api-reference

 Release :

    - yokohama

ft:locale :

    - en-US

ft:publication_title :

    - Yokohama API Reference

ft:clusterId :

    - crapiref

bundleId :

    - crapiref

workflow :

    - Creator


---

# SAM-Software Usage Data Integration API

# SAM-Software Usage Data Integration API {#ariaid-title1}

* Release version: Yokohama
* 
* Updated January 30, 2025
* 
* ![](https://www.servicenow.com/docs/portal-asset/ico-clock) 3 minutes to read

The SAM-Software Usage Data Integration API provides endpoints to
create and update records in the Software Usage \[samp_sw_usage\] table.

This API requires activation of the Software Asset Management Professional (com.snc.samp)
plugin. It also requires that you have either the sam_admin or sam_developer role to access the
endpoint.

## SAM-Software Usage Data Integration - POST
/sam_software_usage_integration/createOrUpdate {#ariaid-title2}

Creates or updates a specified record in the Software Usage \[samp_sw_usage\]
table.
You can create/update one or more software usage records in a single call.

### URL format

Versioned URL:
/api/now/{api_version}/sam_software_usage_integration/createOrUpdate

Default URL:
/api/now/sam_software_usage_integration/createOrUpdate  
Note:  
Available versions are specified in the [REST API Explorer](https://www.servicenow.com/docs/VV5d3pcHRv4pFxM~yEJQZA "In this tutorial you will use the REST API Explorer to test the ServiceNow REST APIs."). For scripted REST APIs there is additional version information on the [Scripted REST Service form](https://www.servicenow.com/docs/cpRBis~pwSIJPZVsP8Hkxw "The scripted REST API feature allows application developers to build custom web service APIs.").

### Supported request parameters

{#sam_soft_us_int-POST-createOrUpdate__entry__2}{#sam_soft_us_int-POST-createOrUpdate__version-not_optional-RESTAPI}

| Name | Description |
|-|-|
| api_version | Optional. Version of the endpoint to access. For example, <kbd class="ph userinput">v1</kbd> or <kbd class="ph userinput">v2</kbd>. Only specify this value to use an endpoint version other than the latest. Data type: String |
[Table 1. Path parameters]

{#sam_soft_us_int-POST-createOrUpdate__entry__6}

| Name | Description |
|-|-|
| None |   |
[Table 2. Query parameters]

{#sam_soft_us_int-POST-createOrUpdate__entry__10}

| Name | Description |
|-|-|
| items | List of column names and values for each field to store in the software usage record. The column information that you must pass depends on the value you specify for reclamation_type (which is a required field): Possible reclamation_type values and the column information that must be passed: * total_usage: * configuration_item * last_used_time * month_used * norm_product * year {#sam_soft_us_int-POST-createOrUpdate__ul_cvy_2qh_zlb} * last_used_date: * configuration_item * norm_product {#sam_soft_us_int-POST-createOrUpdate__ul_pxb_jqh_zlb} {#sam_soft_us_int-POST-createOrUpdate__ul_rk3_zrc_zlb} The combination of these fields uniquely identify a record. If the record is not found in the table, a new record with the specified fields is created; otherwise the existing record is updated. Data type: Array |
[Table 3. Request body parameters (XML or JSON)]

### 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](https://www.servicenow.com/docs/aXidvjgEVmS~V~ZL0h85lQ "REST (REpresentational State Transfer) is a simple stateless architecture that provides standards between computer systems on the web, making it easier for them to communicate with each other.").
{#sam_soft_us_int-POST-createOrUpdate__entry__14}{#sam_soft_us_int-POST-createOrUpdate__accept-RESTAPI}{#sam_soft_us_int-POST-createOrUpdate__content_type-RESTAPI}

| 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 4. Request headers]

{#sam_soft_us_int-POST-createOrUpdate__entry__20}

| Header | Description |
|-|-|
| None |   |
[Table 5. Response headers]

### 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](https://www.servicenow.com/docs/aXidvjgEVmS~V~ZL0h85lQ "REST (REpresentational State Transfer) is a simple stateless architecture that provides standards between computer systems on the web, making it easier for them to communicate with each other.").
{#sam_soft_us_int-POST-createOrUpdate__entry__24}{#sam_soft_us_int-POST-createOrUpdate__entry-200-status-code}{#sam_soft_us_int-POST-createOrUpdate__entry-401-status-code}{#sam_soft_us_int-POST-createOrUpdate__entry-404-status-code}{#sam_soft_us_int-POST-createOrUpdate__entry-405-status-code}{#sam_soft_us_int-POST-createOrUpdate__entry-500-status-code}

| Status code | Description |
|-|-|
| 200 | Successful. The request was successfully processed. |
| 401 | Unauthorized. The user credentials are incorrect or have not been passed. |
| 404 | Not found. The requested item wasn't found. |
| 405 | Invalid method. The functionality is disabled. |
| 500 | Internal server error. An unexpected error occurred while processing the request. The response contains additional information about the error. |
[Table 6. Status codes]

### Response body parameters (JSON or XML)

{#sam_soft_us_int-POST-createOrUpdate__entry__36}

| Name | Description |
|-|-|
| items | Name-value pair list of all fields in the software usage record. Data type: Array (content varies) |
[ ]

### cURL request

The following example illustrates how to create a new software usage record.

    curl -X POST "https://instance.servicenow/api/now/sam_software_usage_integration/createOrUpdate" \
    -H "Accept: application/json" \
    -H "Content-Type: application/json" \
    -d "{'items': [\
      {
        'configuration_item':'eaa9604d3790200044e0bfc8bcbe5dc1',\
        'month_used':2,\
        'norm_product':'40209c060b3022002d6c650d37673a89',\
        'norm_publisher':'24dcccc20b3022002d6c650d37673ab3',\
        'reclamation_type':'total_usage',\
        'usage_count': 13,\
        'total_usage_time':13,\
        'year':2020
      }\
    ]}"

<br />

    {
      "result": {
        "reply": {
          "items": [
            {
              "configuration_item": "eaa9604d3790200044e0bfc8bcbe5dc1",
              "month_used": 2,
              "norm_product": "40209c060b3022002d6c650d37673a89",
              "norm_publisher": "24dcccc20b3022002d6c650d37673ab3",
              "reclamation_type": "total_usage",
              "usage_count": 13,
              "total_usage_time": 13,
              "year": 2020,
              "sysId": "13d15fe59d511010f8772c637e39afe5",
              "status": "INSERT"
            }
          ]
        },
        "message": "Ok"
      }
    }

The following example illustrates how to update multiple software usage records in a single
call.

    curl -X POST "https://instance.servicenow/api/now/sam_software_usage_integration/createOrUpdate" \
    -H "Accept: application/json" \
    -H "Content-Type: application/json" \
    -d "{'items': [\
      {\
        'configuration_item': 'eaa9604d3790200044e0bfc8bcbe5dc1',\
        'month_used': 2,\
        'norm_product': '40209c060b3022002d6c650d37673a89',\
        'norm_publisher': '24dcccc20b3022002d6c650d37673ab3',\
        'reclamation_type': 'total_usage',\
        'usage_count': 13,\
        'total_usage_time': 13,\
        'year': 2020
      },
      {\
        'configuration_item': '0aa9e80d3790200044e0bfc8bcbe5da0',\
        'month_used': 2,\
        'norm_product': '40209c060b3022002d6c650d37673a89',\
        'norm_publisher': '24dcccc20b3022002d6c650d37673ab3',\
        'reclamation_type': 'total_usage',\
        'usage_count': 19,\
        'total_usage_time': 19,\
        'year': 2020
      },
      {\
        'configuration_item': 'a0a9a80d3790200044e0bfc8bcbe5d3c',\
        'month_used': 2,\
        'norm_product': '40209c060b3022002d6c650d37673a89',\
        'norm_publisher': '24dcccc20b3022002d6c650d37673ab3',\
        'reclamation_type': 'total_usage',\
        'usage_count': 7,\
        'total_usage_time': 7,\
        'year': 2020},
      {\
        'configuration_item': '48a9280d3790200044e0bfc8bcbe5d55',\
        'month_used': 2,\
        'norm_product': '40209c060b3022002d6c650d37673a89',\
        'norm_publisher': '24dcccc20b3022002d6c650d37673ab3',\
        'reclamation_type': 'total_usage',\
        'usage_count': 1,\
        'total_usage_time': 1,\
        'year': 2020},
      {\
        'configuration_item': '61a9680d3790200044e0bfc8bcbe5d11',\
        'month_used': 2,\
        'norm_product': '40209c060b3022002d6c650d37673a89',\
        'norm_publisher': '24dcccc20b3022002d6c650d37673ab3',\
        'reclamation_type': 'total_usage',\
        'usage_count': 18,\
        'total_usage_time': 18,\
        'year': 2020}
    ]}"

<br />

    {
      "result": {
        "reply": {
          "items": [
            {
              "configuration_item": "eaa9604d3790200044e0bfc8bcbe5dc1",
              "month_used": 2,
              "norm_product": "40209c060b3022002d6c650d37673a89",
              "norm_publisher": "24dcccc20b3022002d6c650d37673ab3",
              "reclamation_type": "total_usage",
              "usage_count": 13,
              "total_usage_time": 13,
              "year": 2020,
              "sysId": "13d15fe59d511010f8772c637e39afe5",
              "status": "INSERT"
            },
            {
              "configuration_item": "0aa9e80d3790200044e0bfc8bcbe5da0",
              "month_used": 2,
              "norm_product": "40209c060b3022002d6c650d37673a89",
              "norm_publisher": "24dcccc20b3022002d6c650d37673ab3",
              "reclamation_type": "total_usage",
              "usage_count": 19,
              "total_usage_time": 19,
              "year": 2020,
              "sysId": "2cd15fe59d521010f9772c637e39aff4",
              "status": "UPDATE"
            },
            {
              ...
            },
          ]
        },
        "message": "Ok"
      }
    }