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
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
Expense, Cost Center and Project
fields are not supported by the
/api/sam/v2/contracts.json
API. You can use
contracts CSV import (which supports the new fields) for integration.
Column name | Description | Importance |
---|---|---|
contract_id | Identifier of contract.
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 |
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"
]
}
}