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.
Make your first call.
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.
Save the key securely. It is shown once. Configure it as the CONTRAXAWARE_API_KEY environment variable in your server or development environment.
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.
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. Includes document metadata and enables downloading the linked saved agreement. |
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.
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. |
curl --fail-with-body "https://app.contraxaware.com/api/integration/v1/contracts?limit=10" \
-H "Authorization: Bearer $CONTRAXAWARE_API_KEY"// Node.js 18+
const response = await fetch("https://app.contraxaware.com/api/integration/v1/contracts?limit=10", {
headers: { Authorization: `Bearer ${process.env.CONTRAXAWARE_API_KEY}` },
redirect: "error"
});
if (!response.ok) throw new Error(await response.text());
console.log(await response.json());import os
import requests
response = requests.get(
"https://app.contraxaware.com/api/integration/v1/contracts?limit=10",
headers={"Authorization": "Bearer " + os.environ["CONTRAXAWARE_API_KEY"]},
timeout=30, allow_redirects=False
)
response.raise_for_status()
print(response.json())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());{
"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.
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"// Node.js 18+
const response = await fetch("https://app.contraxaware.com/api/integration/v1/contracts/contract-id", {
headers: { Authorization: `Bearer ${process.env.CONTRAXAWARE_API_KEY}` },
redirect: "error"
});
if (!response.ok) throw new Error(await response.text());
console.log(await response.json());import os
import requests
response = requests.get(
"https://app.contraxaware.com/api/integration/v1/contracts/contract-id",
headers={"Authorization": "Bearer " + os.environ["CONTRAXAWARE_API_KEY"]},
timeout=30, allow_redirects=False
)
response.raise_for_status()
print(response.json())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());{
"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.
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// Node.js 18+
const response = await fetch("https://app.contraxaware.com/api/integration/v1/contracts/contract-id/document", {
headers: { Authorization: `Bearer ${process.env.CONTRAXAWARE_API_KEY}` },
redirect: "error"
});
if (!response.ok) throw new Error(await response.text());
const { writeFile } = await import("node:fs/promises");
await writeFile("agreement.download", Buffer.from(await response.arrayBuffer()));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.
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. |
| 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 the document permission. Create a replacement with documents:read if appropriate. |
| 404 | The contract does not exist in this key’s workspace, or no linked document is available. |
| 405 | Use GET. Contract writes are not provided by these endpoints. |
| 429 | Wait 60 seconds, then retry. |
| 500 / 503 | Retry later. If the error continues, contact support with the request ID. |
{
"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 ↗