10.0.6 REST API for managing contracts

With the /api/sam/v2/contracts.json API, you can import and export contract data with purchase information. This operation is used to automate integration with external purchase systems. You can also manage contracts using: contracts CSV import, user interface - All Contracts panel and deprecated contracts migration.

Check the limitations of Adding and updating contracts before using the API.


User You must have Manage Contracts permission along with access to the computer group of the contract.

Resource URL



GET /api/sam/v2/contracts.json

Schema description



Available columns

Column name Description Importance
contract_id Identifier of contract.
  • A contract is updated only when a contract ID is available.
  • Contract ID must be unique among all contracts.
  • On UI, it is generated automatically.

Type: String

name​ Name of the contract.

Type: String

type Type of the contract: 1 - License, 2 - Support, 3 - Service, 4 - Hardware, 5 - Other.

Type: Integer

threshold Threshold for the contract measured value. It is optional.

Type: Integer

computer_group Contract's computer group object. To check the list of computer group columns, see, computer_group. Optional
metric Contract's metric group object. To check the list of metric columns, see, metric. Optional
purchase_order Array of purchase orders assigned to the contract. To check the list of purchase order columns, see, purchase_orders. Optional
software_products Array of software products assigned to the contract. To check the list of software product columns, see, software_product. Optional
Note: All associations, computer_group, metric, purchase_order, and software_product are optional. If computer_group association is not provided and contract is being created, All Computers group is used.

Available metrics

For a list of available metric, refer to Metric IDs and code names and 10.0.4 REST API for managing license metrics. Metrics not applicable to contracts are: INTERNAL_PVU, INTERNAL_RVU_MAPC.

  • If a column is not provided in the request for a contract, related contract's data is not changed.
  • To clear a field, use null value, such as "contract_custom_field_1": null, "threshold" null.
  • If a request is invalid or an error occurs in processing, no contracts or related data is updated, and in the response, detailed explanation is provided for each invalid contract under "rowErrors". The entries numbering starts from 1.
   "message":{"code":"CODUI4099E","text":"Contract processing failed. The contracts have not been imported."},
   "rowErrors":{"1":["|CODUI4047E|Required field contract_id is empty",
   "|CODUI4057E|Custom field with ID 2 is required"],"2":
     "|CODUI4057E|Custom field with ID 2 is required"],
      "|CODUI4042E|A contract with the specified contract ID already exists",
      "|CODUI4057E|Custom field with ID 2 is required"],"4":["|CODUI4057E|Custom field with ID 2 is required"],
      "5":["|CODUI4057E|Custom field with ID 2 is required"],"6":["|CODUI4057E|Custom field with ID 2 is required"],
      "7":["|CODUI4040E|A contract with the specified name and type already exists"