Contracts API
List contracts
List all contracts for an account:
GET /contracts
Response
Status: 200 OK
[
{
"id": 84,
"sourceID": null,
"name": "0012PQ-MSAS-000605491 - Microsoft Software Assurance Support & Maintenance Agreement",
"status": "active",
"category": "support_and_maintenance_contract",
"created_at": "2016-03-13T02:10:15-05:00",
"supplier": {
"id": 27,
"name": "Microsoft Corporation"
},
"updated_at": "2016-03-13T02:10:15-05:00"
},
{
"id": 87,
"sourceID": null,
"name": "0106-SAPUS-00046608 - SAP Enterprise Support for SAP ERP Central Component",
"status": "active",
"category": "support_and_maintenance_contract",
"created_at": "2016-03-13T02:10:15-05:00",
"supplier": {
"id": 29,
"name": "SAP AG"
},
"updated_at": "2016-03-13T02:10:15-05:00"
},
"..."
]
The response contains these fields by default. Filtering and pagination are available to reduce/limit the collection of contracts.
Predefined Filters
The following predefined filters are available:
/contracts/active
: List all active contracts/contracts/inactive
: List all inactive contracts
Collection Fields
By default the following fields will appear in collections of contracts:
id
sourceID
name
category
status
supplier
created_at
updated_at
Obtain a different set of fields using the ?fields=parameter.
Filtering
Filtering is available for the following fields:
id
source
sourceID
name
category
status
supplier
created_at
updated_at
Sorting
By default a collection of contracts is sorted ascending by name
.
The following fields are accepted by the ?sort=parameter:
id
sourceID
name
category
status
supplier
created_at
updated_at
Get a single contract
GET /contracts/:id
Response
Status: 200 OK
{
"category": "support_and_maintenance_contract",
"created_at": "2016-03-13T02:10:15-05:00",
"customer": {
"id": 5,
"name": "Widget Data Center"
},
"customer_rep": {
"id": 63,
"name": "Jo-Ann Stock"
},
"expiry_date": "2014-11-03",
"id": 84,
"name": "0012PQ-MSAS-000605491 - Microsoft Software Assurance Support & Maintenance Agreement",
"notice_date": "2014-10-04",
"remarks": "24x7 Problem Resolution Support=>\n- Support 24 hours a day, 7 days a week. You get around-the-clock phone support for business-critical issues. The number of phone incidents available depends on your Software Assurance investment.\n- Extended product support coverage. You get phone support for all Microsoft servers, Microsoft Windows operating systems, and Microsoft Office system products and editions, even if the specific license requiring support does not have Software Assurance coverage.\n- Unlimited online support. You get Web support during business hours for all Standard and Enterprise edition server products that are covered by Software Assurance.\n\nNew Version Rights=>\n- Access to new software versions that are released during the term of the Software Assurance coverage at no additional charge.\n- If a new version of a Microsoft product (e.g. any program within the Microsoft Office system) is released during the term of coverage, the licenses will automatically be upgraded to the new version. There is no need to go through the traditional procurement process.\n\nCharges=> For desktop software=> 29% of the license cost per annum.\nFor server software=> 25% of the license cost per annum.\nNo notice required.\nIf the annual support & maintenance charge is not paid, the support contract is not renewed.",
"source": null,
"sourceID": null,
"start_date": "2008-11-04",
"status": "active",
"supplier": {
"id": 27,
"name": "Microsoft Corporation"
},
"supplier_contact": {
"id": 51,
"name": "Barney Turban"
},
"time_zone": "Pacific Time (US & Canada)",
"updated_at": "2016-03-18T07:44:09-05:00",
"custom_fields": null,
"ui_extension": null
}
The response contains these fields.
Create a contract
POST /contract
When creating a new contract these fields are available.
Response
Status: 201 Created
{
"category": "...",
"...": "..."
}
The response contains all fields of the created contract and is similar to the response in Get a single contract
Update a contract
PATCH /contracts/:id
When updating a contract these fields are available.
Response
Status: 200 OK
{
"category": "...",
"...": "..."
}
The response contains all fields of the updated contract and is similar to the response in Get a single contract
Fields
- attachments
- Readonly aggregated Attachments
- category
- Required enum, default:
lease_contract
— The Category field is used to select the appropriate category for the contract. Valid values are: -
lease_contract
: Lease Contractmaintenance_contract
: Maintenance Contractsupport_contract
: Support Contractsupport_and_maintenance_contract
: Support & Maintenance Contractother_type_of_contract
: Other Type of Contract
- created_at
- Readonly datetime — The date and time at which the contract was created.
- custom_fields
- Optional custom fields — Custom fields provided in JSON format by the UI Extension that is linked to the contract.
- custom_fields_attachments
- Writeonly attachments The attachments used in Custom fields.
- customer
- Required reference to Organization — The Customer field is used to select the organization that pays for the contract.
- customer_rep
- Optional reference to Person — The Customer representative field is used to select the person who represents the customer of the contract.
- expiry_date
- Optional date — The Expiry date field is used to specify the date through which the contract will be active. The contract expires at the end of this day if it is not renewed before then. When the contract has expired, its status will automatically be set to “Expired”.
-
As long as notice still needs to be given to terminate the contract, the Expiry date field is to remain empty.
- id
- Readonly integer — The unique ID of the contract.
- name
- Required string (max 128) — The Name field is used to enter the name of the contract.
-
If a unique ID is given to each contract, then this ID can be added at the start of the name. Example:
-
- 2EGXQ2W – Dell 3-Year ProSupport and Next Business Day Onsite Repair for CMP00035
- notice_date
- Optional date — The Notice date field is used to specify the last day on which the supplier organization can still be contacted to terminate the contract to ensure that it expires on the intended expiry date.
-
The Notice date field is left empty, and the Expiry date field is filled out, when the contract is to expire on a specific date and no notice needs to be given to terminate it.
-
As long as notice still needs to be given to terminate the contract, the Expiry date field is to remain empty.
- remarks
- Optional text (max 64KB) — The Remarks field is used to add any additional information about the contract that might prove useful.
- remarks_attachments
- Writeonly attachments The attachments used in the Remarks field.
- source
- Optional string (max 30) - See source
- sourceID
- Optional string (max 128) - See source
- start_date
- Optional date — The Start date field is used to specify the first day during which the contract is active.
- status
- Required enum, default:
scheduled_for_activation
— The Status field displays the current status of the contract. The available options are: -
being_prepared
: Being Preparedscheduled_for_activation
: Scheduled for Activationactive
: Activeexpired
: Expired
- supplier
- Optional reference to Organization — The Supplier field is used to select the organization that has provided the contract to the customer.
- supplier_contact
- Optional reference to Person — The Supplier contact field is used to select the person who represents the supplier of the contract.
- time_zone
- Optional time_zone — The Time zone field is used to select the time zone that applies to the start date, notice date and expiry date of the contract.
- ui_extension
- Readonly reference to UI Extension — The UI extension field indicates the UI extension that is applied to the contract.
- updated_at
- Readonly datetime — The date and time of the last update of the contract. If the contract has no updates it contains the
created_at
value.