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.
Scope
Access
contracts:read
Included with every key. Reads contract records and custom-field values.
documents:read
Optional. Enables document downloads, completed evidence packages, and viewer sessions.
requests:write
Optional. Creates intake requests and adds external deal associations.
integrations:manage
Optional. 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.
Parameter
Meaning
limit
Optional page size, 1–100. Default: 25.
q
Optional text search, up to 200 characters.
after
Optional cursor. Use pagination.nextCursor from the previous response.
using System.Net.Http.Headers;
using var client = new HttpClient();
client.DefaultRequestHeaders.Authorization = new AuthenticationHeaderValue(
"Bearer", Environment.GetEnvironmentVariable("CONTRAXAWARE_API_KEY"));
using var response = await client.GetAsync("https://app.contraxaware.com/api/integration/v1/contracts?limit=10");
response.EnsureSuccessStatusCode();
Console.WriteLine(await response.Content.ReadAsStringAsync());
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.
using System.Net.Http.Headers;
using var client = new HttpClient();
client.DefaultRequestHeaders.Authorization = new AuthenticationHeaderValue(
"Bearer", Environment.GetEnvironmentVariable("CONTRAXAWARE_API_KEY"));
using var response = await client.GetAsync("https://app.contraxaware.com/api/integration/v1/contracts/contract-id");
response.EnsureSuccessStatusCode();
Console.WriteLine(await response.Content.ReadAsStringAsync());
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.
import os
import requests
response = requests.get(
"https://app.contraxaware.com/api/integration/v1/contracts/contract-id/document",
headers={"Authorization": "Bearer " + os.environ["CONTRAXAWARE_API_KEY"]},
timeout=30, allow_redirects=False
)
response.raise_for_status()
with open("agreement.download", "wb") as file:
file.write(response.content)
using System.Net.Http.Headers;
using var client = new HttpClient();
client.DefaultRequestHeaders.Authorization = new AuthenticationHeaderValue(
"Bearer", Environment.GetEnvironmentVariable("CONTRAXAWARE_API_KEY"));
using var response = await client.GetAsync("https://app.contraxaware.com/api/integration/v1/contracts/contract-id/document");
response.EnsureSuccessStatusCode();
await System.IO.File.WriteAllBytesAsync("agreement.download", await response.Content.ReadAsByteArrayAsync());
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.
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.
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.
Field
Meaning
id
Stable contract ID.
name / company / status
Saved shared-field values. Status is the saved contract status, not a full approval or signing progress feed.
contractType
Contract type ID and name.
requestId
The linked intake request ID, or null for agreements without a saved request. Use it to check request status.
effectiveDate / expirationDate
Saved dates when populated; otherwise null.
revision / createdAt / updatedAt
Record revision and ISO 8601 timestamps.
fields
Array of field IDs, labels, types, commonKey values, and saved values. Stable field IDs allow custom mappings.
document
Linked 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 status
What to do
400
Check parameter names, lengths, and limit (1–100). Individual contract endpoints accept no query parameters.
401
Provide a valid key. Check whether it expired or was revoked. Sign-in cookies do not authorize API calls.
403
The key lacks a required permission. Create a replacement with the scope documented for that endpoint.
404
The contract does not exist in this key’s workspace, or no linked document is available.
405
Check the HTTP method documented for this endpoint.
429
Wait 60 seconds, then retry.
500 / 503
Retry 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.