← Developers
API REFERENCE · VERSION 1

Build your connection.

Retrieve contract records and saved documents with predictable JSON responses and workspace-scoped authentication. Start here, then try the calls in the interactive console.

Base URL: https://app.contraxaware.com/api/integration/v1

Make your first call.

1

Create a key. Sign in to ContraxAware as the workspace owner. Open Settings → API access. Give the integration a name, choose its expiry, and allow document downloads if needed.

2

Save the key securely. It is shown once. Configure it as the CONTRAXAWARE_API_KEY environment variable in your server or development environment.

3

List contracts, then use an ID. The list response includes contract IDs you can use to retrieve a record or its saved document.

Want to see the flow first? The test console includes clearly labeled fictional example data and a live mode for your own workspace.

Examples: Node.js 18+, Python with the requests package, modern .NET, or cURL. Replace contract-id in individual-record examples with an ID from the list response.

Authentication & access.

Authorization: Bearer YOUR_API_KEY

Send the key in the Authorization header over HTTPS. API calls authenticate independently of your browser login. Each key belongs to one workspace; do not send a workspace parameter.

ScopeAccess
contracts:readIncluded with every key. Reads contract records and custom-field values.
documents:readOptional. Includes document metadata and enables downloading the linked saved agreement.
Keys grant access to all contracts in their workspace, including confidential contracts. Treat them as server secrets. Never put a live key in public frontend code, a URL, or a shared example. Revoke unused keys in Settings → API access.

Keys expire after 30, 90, or 365 days, and can be revoked immediately. A workspace can have up to 10 active keys. API credentials cannot be created in the isolated testing workspace.

List contracts.

GET/contracts

Returns contract records in ascending ID order. Use search for a case-insensitive text match across saved field values.

ParameterMeaning
limitOptional page size, 1–100. Default: 25.
qOptional text search, up to 200 characters.
afterOptional cursor. Use pagination.nextCursor from the previous response.
curl --fail-with-body "https://app.contraxaware.com/api/integration/v1/contracts?limit=10" \
  -H "Authorization: Bearer $CONTRAXAWARE_API_KEY"
EXAMPLE RESPONSE
{
  "data": [
    {
      "id": "contract-id",
      "name": "Northstar Software Agreement",
      "contractType": {
        "id": "type-id",
        "name": "SaaS contracts"
      },
      "status": "Active",
      "company": "Northstar",
      "effectiveDate": "2026-01-01",
      "expirationDate": "2026-12-31",
      "revision": 1,
      "createdAt": "2026-01-01T12:00:00.000Z",
      "updatedAt": "2026-01-02T12:00:00.000Z",
      "fields": [
        {
          "id": "f_name",
          "name": "Contract name",
          "type": "text",
          "commonKey": "name",
          "value": "Northstar Software Agreement"
        }
      ],
      "document": {
        "id": "document-id",
        "title": "Software Agreement",
        "filename": "Agreement.pdf",
        "contentType": "application/pdf",
        "size": 18432,
        "version": 1,
        "isSigned": false,
        "downloadPath": "/api/integration/v1/contracts/contract-id/document"
      }
    }
  ],
  "pagination": {
    "limit": 10,
    "nextCursor": null
  }
}

To fetch the next page, keep the same search and limit and add after=NEXT_CURSOR, URL-encoding the cursor. A null nextCursor means there are no more results. An empty list is a successful response.

Get a contract.

GET/contracts/{id}

Retrieve one contract using its ID from the list response. The fields array provides your configured field names, types, shared keys, and saved values.

curl --fail-with-body "https://app.contraxaware.com/api/integration/v1/contracts/contract-id" \
  -H "Authorization: Bearer $CONTRAXAWARE_API_KEY"
EXAMPLE RESPONSE
{
  "data": {
    "id": "contract-id",
    "name": "Northstar Software Agreement",
    "contractType": {
      "id": "type-id",
      "name": "SaaS contracts"
    },
    "status": "Active",
    "company": "Northstar",
    "effectiveDate": "2026-01-01",
    "expirationDate": "2026-12-31",
    "revision": 1,
    "createdAt": "2026-01-01T12:00:00.000Z",
    "updatedAt": "2026-01-02T12:00:00.000Z",
    "fields": [
      {
        "id": "f_name",
        "name": "Contract name",
        "type": "text",
        "commonKey": "name",
        "value": "Northstar Software Agreement"
      }
    ],
    "document": {
      "id": "document-id",
      "title": "Software Agreement",
      "filename": "Agreement.pdf",
      "contentType": "application/pdf",
      "size": 18432,
      "version": 1,
      "isSigned": false,
      "downloadPath": "/api/integration/v1/contracts/contract-id/document"
    }
  }
}

Download a contract document.

GET/contracts/{id}/document

Requires documents:read. Returns the binary PDF or Word file currently linked to this contract, with Content-Type and Content-Disposition headers. Save the response as a file; it is not JSON.

curl --fail-with-body "https://app.contraxaware.com/api/integration/v1/contracts/contract-id/document" \
  -H "Authorization: Bearer $CONTRAXAWARE_API_KEY" \
  --output agreement.download

This call retrieves the current linked saved agreement, not attachments, version history, signature evidence, or every document associated with the contract. The metadata’s isSigned value describes that document. A contract may have no document yet.

Understand the response.

FieldMeaning
idStable contract ID.
name / company / statusSaved shared-field values. Status is the saved contract status, not a full approval or signing progress feed.
contractTypeContract type ID and name.
effectiveDate / expirationDateSaved dates when populated; otherwise null.
revision / createdAt / updatedAtRecord revision and ISO 8601 timestamps.
fieldsArray of field IDs, labels, types, commonKey values, and saved values. Stable field IDs allow custom mappings.
documentLinked saved-document metadata, or null when no file is available or the key lacks documents:read. downloadPath is relative to https://app.contraxaware.com and still requires the key.

Fields and values vary by contract type. Unknown or empty shared values return null. Document metadata includes filename, contentType, size in bytes, version, and isSigned. Clients should tolerate additional response fields as the API expands.

Errors, limits & troubleshooting.

The limit is 60 authenticated requests per minute per key. A 429 response includes Retry-After: 60. Use pagination, reuse retrieved data when appropriate, and retry after the indicated delay.

HTTP statusWhat to do
400Check parameter names, lengths, and limit (1–100). Individual contract endpoints accept no query parameters.
401Provide a valid key. Check whether it expired or was revoked. Sign-in cookies do not authorize API calls.
403The key lacks the document permission. Create a replacement with documents:read if appropriate.
404The contract does not exist in this key’s workspace, or no linked document is available.
405Use GET. Contract writes are not provided by these endpoints.
429Wait 60 seconds, then retry.
500 / 503Retry later. If the error continues, contact support with the request ID.
EXAMPLE RESPONSE
{
  "error": {
    "code": "invalid_api_key",
    "message": "This API key is invalid, expired, or revoked."
  },
  "requestId": "example-request-id"
}

Responses include X-Request-Id. Errors include the same requestId in JSON. Contract and document responses use Cache-Control: private, no-store. Browser testing supports cross-origin requests with an Authorization header; cookies are not required.

Need help connecting your system?

Tell us what you want to build. We can discuss the integration and which contract information you need.

Contact us about the API ↗

Conversion measurement

With your permission, Google can receive basic visit and conversion data to help us understand which ads are useful. We do not include contract content, filenames, email addresses or account details in these events.