GET /contracts migration guide (v1.0 → v1.1)

Selecting the version

Send the version via the request header:

X-API-Version: 1.1

If the header is omitted, the default is:

• 1.0 for API keys created before Aug 1st 2026
• 1.1 for API keys created on or after Aug 1st 2026

We recommend always sending the header explicitly so your behavior doesn't depend on when the key was created.

What's new in v1.1

v1.1 adds capabilities that don't exist in v1.0:

Filtering by passing a field name as a query parameter (e.g. ?status=active&idApp=123) still works in v1.1, in addition to the new filters parameter.

New selectable fields in v1.1:

• creationTime — when the contract was created (ISO timestamp)
• source — how the contract was created (api, ui, …)

Response envelope

v1.0

{ "contracts": [ ... ] }

v1.1

{
  "contracts": [ ... ],
  "count": 3,
  "total": 355,
  "nextCursor": "WyIxMDE1MTkiXQ==",
  "aggregations": [ ... ]
}

• count — items in this page
• total — total matching the query
• nextCursor — pass back as cursor for the next page; null when exhausted
• aggregations — present only when aggs was requested

Pagination & default sort

Field value differences (breaking changes)

The same contract returns different value types under each version for several field types:

Field types that are unchanged: singleLine (text), multiLine (text), dropdown, email, cardNumber, fileUpload (documents), and the id field.

Removed: the calculated currency field

In v1.0 you could request currency in fields to get the contract's currency code as a string (e.g. "USD").

In v1.1 that field is no longer selectable — requesting it returns 400 "Invalid fields: currency". The currency code now lives inside every currency-typed field's object (amount.currency, yearlyCost.currency, …).

Other notes

• Whether an unset custom field appears as "<key>": null or is omitted from the response can differ between versions. Treat missing and null as equivalent.
• The order of JSON keys in the response is not stable across versions.

Example: same contract under each version

Single contract endpoint, requested with no fields parameter:

v1.0

{
  "contract": {
    "id": 100,
    "name": "Adobe 2026-2027",
    "idApp": 6960,
    "amount": "2699520",
    "currency": "USD",
    "owner": "1234"
  }
}

v1.1

{
  "contract": {
    "id": 100,
    "name": "Adobe 2024-2025",
    "idApp": 6960,
    "amount": { "value": 2699520, "currency": "USD", "convertedValue": 2699520 },
    "owner": 1234
  }
}

Migration checklist

1. Set the header explicitly: X-API-Version: 1.1.
2. Currency fields — replace contract.amount with contract.amount.value. Read the currency code from contract.amount.currency.
3. Remove currency from fields — read it from any currency field's .currency property instead.
4. Number, user, and contract-reference fields — treat as numbers.
5. Paginate — read nextCursor and loop until it is null. Don't assume one response contains the whole list.
6. Sort — pass an explicit sort if you depend on a deterministic order.