← 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. Enables document downloads, completed evidence packages, and viewer sessions.
requests:writeOptional. Creates intake requests and adds external deal associations.
integrations:manageOptional. Creates, lists, and stops webhook subscriptions.
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.

Requests, deal links & lifecycle.

The integration lab offers a guided example for every call. Choose a deal or contract by name. Its IDs are filled in automatically, including the saved request behind an agreement. Request details shows the resulting path and IDs. Example responses are labeled until you run a call.

Start with the TotalDeal integration test to select a saved deal and create a real request. Owner access is required to select TotalDeal records.

Open integration lab →

Read contract progress

GET /contracts/{id}/progress

Uses the Contract Map lifecycle and actions. Returns stage, phase, responsible people, next actions, signatureRequestId, and waiting timestamps when an active approval or signing request supplies them.

Required scope contracts:read

Inspect and copy cURL, JavaScript, Python, and C# examples for this call in the integration lab.

Discover contract types

GET /contract-types

Returns data as an array of id, name, and description. The catalog supports up to 100 types.

Required scope contracts:read

Inspect and copy cURL, JavaScript, Python, and C# examples for this call in the integration lab.

Load a request form

GET /contract-types/{id}/request-form

Returns fields with stable IDs, labels, types, options, help, and required flags. Conditions and readOnly rules use those IDs. Evaluate conditions against the current answers. The initial API supports the company agreement request path.

Required scope contracts:read

Inspect and copy cURL, JavaScript, Python, and C# examples for this call in the integration lab.

Request an agreement

POST /contract-requests

Uses the normal intake process and its configured routing and template handling. Supply an Idempotency-Key header of 8–100 letters, numbers, underscores, or hyphens. Repeat the same key and payload to recover the same request. Different details with the same key return 409. Requests create real records. The externalRecord connects the resulting agreement to its source deal.

Required scope requests:write

Inspect and copy cURL, JavaScript, Python, and C# examples for this call in the integration lab.

EXAMPLE REQUEST BODY
{
  "contractTypeId": "type-id",
  "values": {
    "field-id": "Value from the request form"
  },
  "reason": "Please prepare an agreement for this deal.",
  "desiredDate": "",
  "externalRecord": {
    "connectionId": "totaldeal:company-id",
    "objectType": "deal",
    "recordId": "deal-id"
  }
}

Track intake

GET /contract-requests/{id}

Returns state, contractId, assignedTo, submittedAt, targetDate, requester-visible messages, and any generation warning. Submitted requests appear in the normal intake workspace.

Required scope contracts:read

Inspect and copy cURL, JavaScript, Python, and C# examples for this call in the integration lab.

Find agreements for a deal

GET /external-records/{connectionId}/{objectType}/{recordId}/contracts

Returns contract records linked to one external object. URL-encode every identifier. Include the external system or organization in connectionId. Supports up to 100 linked agreements per external record.

Required scope contracts:read

Inspect and copy cURL, JavaScript, Python, and C# examples for this call in the integration lab.

Link an existing agreement

PUT /contracts/{id}/external-links/{connectionId}/{objectType}/{recordId}

Adds the association without altering the contract. Repeating the call keeps one association. No JSON body is required.

Required scope requests:write

Inspect and copy cURL, JavaScript, Python, and C# examples for this call in the integration lab.

Download signing evidence

GET /signature-requests/{id}/completed-package

Returns a ZIP containing the preserved original, signing and completed PDFs, signature images, evidence manifest, and verification files. Available only after completion. A 409 identifies an incomplete request or an older agreement without a preserved package. Obtain the signature request ID from contract progress.

Required scope documents:read

Inspect and copy cURL, JavaScript, Python, and C# examples for this call in the integration lab.

Open the saved agreement

POST /contracts/{id}/viewer-sessions

Returns a URL valid for five minutes. Each viewer must sign in to ContraxAware and have permission to the document. PDF files display in the browser. Word documents download. Revoking the issuing API key invalidates its viewing links. No request body is required.

Required scope documents:read

Inspect and copy cURL, JavaScript, Python, and C# examples for this call in the integration lab.

Subscribe to changes

POST /webhook-subscriptions

Returns id, URL, event types, and a signing secret shown in the creation response. Supported events are contract.updated, request.updated, approval.updated, and signature.updated. Delivery carries resource IDs, revision, contractId when present, and state. It sends the event after application activity, with increasing retry delays and an hourly background check. Receivers must tolerate duplicate event IDs. HTTPS destinations on app.totaldealcrm.com are enabled. Additional receiver origins require deployment configuration. A workspace supports 10 active subscriptions.

Required scope integrations:manage

Inspect and copy cURL, JavaScript, Python, and C# examples for this call in the integration lab.

EXAMPLE REQUEST BODY
{
  "url": "https://app.totaldealcrm.com/api/contraxaware-events/receiver-id",
  "events": [
    "contract.updated",
    "request.updated",
    "approval.updated",
    "signature.updated"
  ]
}

Check webhook health

GET /webhook-subscriptions

Returns active status, last HTTP status, last attempt, next attempt, and consecutive failures. Signing secrets are excluded.

Required scope integrations:manage

Inspect and copy cURL, JavaScript, Python, and C# examples for this call in the integration lab.

Stop a subscription

DELETE /webhook-subscriptions/{id}

Stops future deliveries and removes the stored signing secret. A delivery already in flight can finish.

Required scope integrations:manage

Inspect and copy cURL, JavaScript, Python, and C# examples for this call in the integration lab.

Verify webhook notifications

Verify X-ContraxAware-Signature using HMAC-SHA256 with the subscription secret over the timestamp, a dot, and the exact raw request body. The signature header is v1= followed by the lowercase hex digest. Reject timestamps older than five minutes. Store event IDs to deduplicate successful deliveries. Return a 2xx response after durable acceptance. Failed deliveries retry with increasing delays up to one hour. Events contain resource references and state. Use an authenticated API call to retrieve details.

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.
requestIdThe linked intake request ID, or null for agreements without a saved request. Use it to check request status.
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 a required permission. Create a replacement with the scope documented for that endpoint.
404The contract does not exist in this key’s workspace, or no linked document is available.
405Check the HTTP method documented for this endpoint.
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.