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 PUT actions 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 occurrs 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"
    ]
  }
}