{"revision":"c10276e953456835cdbb1f3a60d58ae1980be353","document":{"id":544,"path":"api-reference/rest-apis/sam_soft_us_int-api.md","title":"SAM-Software Usage Data Integration API","bundle":null,"doc_type":null,"release":"australia","body":"\n# SAM-Software Usage Data Integration API\n\nThe SAM-Software Usage Data Integration API provides endpoints to create and update records in the Software Usage \\[samp\\_sw\\_usage\\] table.\n\nThis 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.\n\n**Parent Topic:**[REST API reference](https://raw.githubusercontent.com/ServiceNow/ServiceNowDocs/australia/markdown/australia/api-reference/rest-apis/api-rest.md)\n\n## SAM-Software Usage Data Integration - POST /sam\\_software\\_usage\\_integration/createOrUpdate\n\nCreates or updates a specified record in the Software Usage \\[samp\\_sw\\_usage\\] table.\n\nYou can create/update one or more software usage records in a single call.\n\n### URL format\n\nVersioned URL: `/api/now/{api_version}/sam_software_usage_integration/createOrUpdate`\n\nDefault URL: `/api/now/sam_software_usage_integration/createOrUpdate`\n\n**Note:** Available versions are specified in the [REST API Explorer](https://raw.githubusercontent.com/ServiceNow/ServiceNowDocs/australia/markdown/australia/api-reference/rest-api-explorer/use-REST-API-Explorer.md). For scripted REST APIs there is additional version information on the [Scripted REST Service form](https://raw.githubusercontent.com/ServiceNow/ServiceNowDocs/australia/markdown/australia/api-reference/rest-api-explorer/c_CustomWebServices.md).\n\n### Supported request parameters\n\n<table class=\"rest_api_path_parameters\"><thead><tr><th>\n\nName\n\n</th><th>\n\nDescription\n\n</th></tr></thead><tbody><tr><td>\n\napi\\_version\n\n</td><td id=\"version-entry-RESTAPI\">\n\nOptional. 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\n\n</td></tr></tbody>\n</table>|Name|Description|\n|----|-----------|\n|None| |\n\n<table class=\"rest_api_request_body\"><thead><tr><th>\n\nName\n\n</th><th>\n\nDescription\n\n</th></tr></thead><tbody><tr><td>\n\nitems\n\n</td><td>\n\nList 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\\):\n\n Possible **reclamation\\_type** values and the column information that must be passed:\n\n-   total\\_usage:\n    -   configuration\\_item\n    -   last\\_used\\_time\n    -   month\\_used\n    -   norm\\_product\n    -   year\n-   last\\_used\\_date:\n    -   configuration\\_item\n    -   norm\\_product\n\n 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.\n\n Data type: Array\n\n</td></tr></tbody>\n</table>### Headers\n\nThe 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://raw.githubusercontent.com/ServiceNow/ServiceNowDocs/australia/markdown/australia/api-reference/rest-api-explorer/c_RESTAPI.md).\n\n<table class=\"rest_api_request_headers\"><thead><tr><th>\n\nHeader\n\n</th><th>\n\nDescription\n\n</th></tr></thead><tbody><tr><td>\n\nAccept\n\n</td><td id=\"accept-entry-RESTAPI\">\n\nData format of the response body. Supported types: **application/json** or **application/xml**. Default: **application/json**\n\n</td></tr><tr><td>\n\nContent-Type\n\n</td><td id=\"content_type-entry-RESTAPI\">\n\nData format of the request body. Supported types: **application/json** or **application/xml**. Default: **application/json**\n\n</td></tr></tbody>\n</table>|Header|Description|\n|------|-----------|\n|None| |\n\n### Status codes\n\nThe 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://raw.githubusercontent.com/ServiceNow/ServiceNowDocs/australia/markdown/australia/api-reference/rest-api-explorer/c_RESTAPI.md).\n\n|Status code|Description|\n|-----------|-----------|\n|200|Successful. The request was successfully processed.|\n|401|Unauthorized. The user credentials are incorrect or have not been passed.|\n|404|Not found. The requested item wasn't found.|\n|405|Invalid method. The functionality is disabled.|\n|500|Internal server error. An unexpected error occurred while processing the request. The response contains additional information about the error.|\n\n### Response body parameters \\(JSON or XML\\)\n\n<table><thead><tr><th>\n\nName\n\n</th><th>\n\nDescription\n\n</th></tr></thead><tbody><tr><td>\n\nitems\n\n</td><td>\n\nName-value pair list of all fields in the software usage record.Data type: Array \\(content varies\\)\n\n</td></tr></tbody>\n</table>### cURL request\n\nThe following example illustrates how to create a new software usage record.\n\n```\ncurl -X POST \"https://instance.servicenow/api/now/sam_software_usage_integration/createOrUpdate\" \\\n-H \"Accept: application/json\" \\\n-H \"Content-Type: application/json\" \\\n-d \"{'items': [\\\n  {\n    'configuration_item':'eaa9604d3790200044e0bfc8bcbe5dc1',\\\n    'month_used':2,\\\n    'norm_product':'40209c060b3022002d6c650d37673a89',\\\n    'norm_publisher':'24dcccc20b3022002d6c650d37673ab3',\\\n    'reclamation_type':'total_usage',\\\n    'usage_count': 13,\\\n    'total_usage_time':13,\\\n    'year':2020\n  }\\\n]}\"\n```\n\n```\n{\n  \"result\": {\n    \"reply\": {\n      \"items\": [\n        {\n          \"configuration_item\": \"eaa9604d3790200044e0bfc8bcbe5dc1\",\n          \"month_used\": 2,\n          \"norm_product\": \"40209c060b3022002d6c650d37673a89\",\n          \"norm_publisher\": \"24dcccc20b3022002d6c650d37673ab3\",\n          \"reclamation_type\": \"total_usage\",\n          \"usage_count\": 13,\n          \"total_usage_time\": 13,\n          \"year\": 2020,\n          \"sysId\": \"13d15fe59d511010f8772c637e39afe5\",\n          \"status\": \"INSERT\"\n        }\n      ]\n    },\n    \"message\": \"Ok\"\n  }\n}\n```\n\nThe following example illustrates how to update multiple software usage records in a single call.\n\n```\ncurl -X POST \"https://instance.servicenow/api/now/sam_software_usage_integration/createOrUpdate\" \\\n-H \"Accept: application/json\" \\\n-H \"Content-Type: application/json\" \\\n-d \"{'items': [\\\n  {\\\n    'configuration_item': 'eaa9604d3790200044e0bfc8bcbe5dc1',\\\n    'month_used': 2,\\\n    'norm_product': '40209c060b3022002d6c650d37673a89',\\\n    'norm_publisher': '24dcccc20b3022002d6c650d37673ab3',\\\n    'reclamation_type': 'total_usage',\\\n    'usage_count': 13,\\\n    'total_usage_time': 13,\\\n    'year': 2020\n  },\n  {\\\n    'configuration_item': '0aa9e80d3790200044e0bfc8bcbe5da0',\\\n    'month_used': 2,\\\n    'norm_product': '40209c060b3022002d6c650d37673a89',\\\n    'norm_publisher': '24dcccc20b3022002d6c650d37673ab3',\\\n    'reclamation_type': 'total_usage',\\\n    'usage_count': 19,\\\n    'total_usage_time': 19,\\\n    'year': 2020\n  },\n  {\\\n    'configuration_item': 'a0a9a80d3790200044e0bfc8bcbe5d3c',\\\n    'month_used': 2,\\\n    'norm_product': '40209c060b3022002d6c650d37673a89',\\\n    'norm_publisher': '24dcccc20b3022002d6c650d37673ab3',\\\n    'reclamation_type': 'total_usage',\\\n    'usage_count': 7,\\\n    'total_usage_time': 7,\\\n    'year': 2020},\n  {\\\n    'configuration_item': '48a9280d3790200044e0bfc8bcbe5d55',\\\n    'month_used': 2,\\\n    'norm_product': '40209c060b3022002d6c650d37673a89',\\\n    'norm_publisher': '24dcccc20b3022002d6c650d37673ab3',\\\n    'reclamation_type': 'total_usage',\\\n    'usage_count': 1,\\\n    'total_usage_time': 1,\\\n    'year': 2020},\n  {\\\n    'configuration_item': '61a9680d3790200044e0bfc8bcbe5d11',\\\n    'month_used': 2,\\\n    'norm_product': '40209c060b3022002d6c650d37673a89',\\\n    'norm_publisher': '24dcccc20b3022002d6c650d37673ab3',\\\n    'reclamation_type': 'total_usage',\\\n    'usage_count': 18,\\\n    'total_usage_time': 18,\\\n    'year': 2020}\n]}\"\n```\n\n```\n{\n  \"result\": {\n    \"reply\": {\n      \"items\": [\n        {\n          \"configuration_item\": \"eaa9604d3790200044e0bfc8bcbe5dc1\",\n          \"month_used\": 2,\n          \"norm_product\": \"40209c060b3022002d6c650d37673a89\",\n          \"norm_publisher\": \"24dcccc20b3022002d6c650d37673ab3\",\n          \"reclamation_type\": \"total_usage\",\n          \"usage_count\": 13,\n          \"total_usage_time\": 13,\n          \"year\": 2020,\n          \"sysId\": \"13d15fe59d511010f8772c637e39afe5\",\n          \"status\": \"INSERT\"\n        },\n        {\n          \"configuration_item\": \"0aa9e80d3790200044e0bfc8bcbe5da0\",\n          \"month_used\": 2,\n          \"norm_product\": \"40209c060b3022002d6c650d37673a89\",\n          \"norm_publisher\": \"24dcccc20b3022002d6c650d37673ab3\",\n          \"reclamation_type\": \"total_usage\",\n          \"usage_count\": 19,\n          \"total_usage_time\": 19,\n          \"year\": 2020,\n          \"sysId\": \"2cd15fe59d521010f9772c637e39aff4\",\n          \"status\": \"UPDATE\"\n        },\n        {\n          ...\n        },\n      ]\n    },\n    \"message\": \"Ok\"\n  }\n}\n```\n\n"}}