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.

Permissions

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

Resource URL

https://hostname:port/api/sam/v2/contracts?token=<token>

Syntax

GET /api/sam/v2/contracts.json

Schema description

/api/sam/v2/schemas/contract.json

Association

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	Required
name	Name of the contract. Type: String	Optional
type	Type of the contract: 1 - License, 2 - Support, 3 - Service, 4 - Hardware, 5 - Other. Type: Integer	Optional
threshold	Threshold for the contract measured value. It is optional. Type: Integer	Optional
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.

{
   "incorrectRows":7,
   "allRows":7,
   "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"],
    "3":
     [
      "|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"
    ]
  }
}