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:

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 Contract
  • maintenance_contract: Maintenance Contract
  • support_contract: Support Contract
  • support_and_maintenance_contract: Support & Maintenance Contract
  • other_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 Prepared
  • scheduled_for_activation: Scheduled for Activation
  • active: Active
  • expired: 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.