Get Contract Data

Endpoint

POST /v2/core/contracts/{document_id}

Authentication

This endpoint requires an OAuth access token. Send it as a bearer token:

Authorization: Bearer your_access_token

Required scope: sor:read

Path Parameters

Parameter	Type	Required	Description
`document_id`	integer	Yes	Unique identifier for the document

Request Body

The body is optional. Send {} (or no body) to use the defaults, which return only the extracted fields.

Field	Type	Required	Default	Description
`include_summary`	boolean	No	`false`	Include the generated document `summary` in the response. When `false`, `summary` is returned as `null`
`include_attributes`	boolean	No	`false`	Include the mapped attribute values (`mapped_fields`) in the response. When `false`, `mapped_fields` is returned as `[]`
`include_extracted_fields`	boolean	No	`true`	Include the extracted org field values (`fields`) in the response. When `false`, `fields` is returned as `[]`

Request Example

curl -X POST "https://platform.chamelio.ai/v2/core/contracts/42" \
  -H "Authorization: Bearer your_access_token" \
  -H "Content-Type: application/json" \
  -d '{
    "include_summary": true,
    "include_attributes": true,
    "include_extracted_fields": true
  }'

import requests

document_id = 42

url = f"https://platform.chamelio.ai/v2/core/contracts/{document_id}"
headers = {
    "Authorization": "Bearer your_access_token",
    "Content-Type": "application/json"
}
body = {
    "include_summary": True,
    "include_attributes": True,
    "include_extracted_fields": True
}

response = requests.post(url, headers=headers, json=body)
print(response.json())

const documentId = 42;

const response = await fetch(
  `https://platform.chamelio.ai/v2/core/contracts/${documentId}`,
  {
    method: 'POST',
    headers: {
      'Authorization': 'Bearer your_access_token',
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({
      include_summary: true,
      include_attributes: true,
      include_extracted_fields: true
    })
  }
);

const data = await response.json();
console.log(data);

Response

Success Response

Status Code: 200 OK The response is a single document object. This is the same shape returned for each entry in the Search Documents documents array.

{
  "document_id": 42,
  "org_id": 1,
  "file_name": "Acme_MSA_2025.pdf",
  "document_title": "Master Service Agreement - Acme Corp",
  "document_type": "MSA",
  "summary": "Master service agreement between Acme Corp and our organization, covering SaaS platform licensing and support services.",
  "fields": [
    {
      "field_name": "Counterparty",
      "field_value_type": "text",
      "org_field_id": 1,
      "value": "Acme Corporation",
      "is_unclear": false,
      "is_null": false
    },
    {
      "field_name": "Contract Value",
      "field_value_type": "number",
      "org_field_id": 2,
      "value": 150000.0,
      "is_unclear": false,
      "is_null": false
    },
    {
      "field_name": "Effective Date",
      "field_value_type": "date",
      "org_field_id": 4,
      "value": "2025-01-15T00:00:00Z",
      "is_unclear": false,
      "is_null": false
    }
  ],
  "workflow_metadata": {
    "workflow_state_id": "ws_abc123",
    "workflow_id": "vendor_contract_review",
    "org_id": 1,
    "user_id": 10,
    "workflow_version": 2,
    "task_id": 5001
  },
  "document_created_at": "2025-01-15T10:30:00Z",
  "mapped_fields": [
    {
      "name": "vendor_name",
      "field_type": "text",
      "value": "Acme Corporation"
    },
    {
      "name": "total_value",
      "field_type": "number",
      "value": 150000.0
    }
  ]
}

Response Fields

Field	Type	Description
`document_id`	integer	Unique identifier of the document
`org_id`	integer	Identifier of the organization that owns the document
`file_name`	string or null	Original file name
`document_title`	string or null	Human-readable document title
`document_type`	string	Document type name
`summary`	string or null	Generated summary of the document. `null` unless `include_summary` was `true`
`fields`	array	Extracted org field values. Each entry is a Field Value Object. Empty when `include_extracted_fields` was `false`
`workflow_metadata`	object or null	Workflow context if the document originated from a workflow. See Workflow Metadata Object
`document_created_at`	string or null	Timestamp the document was created
`mapped_fields`	array	Mapped attribute values. Each entry is a Mapped Field Object. Empty unless `include_attributes` was `true`

Field Value Object

Field	Type	Description
`field_name`	string	Name of the org field
`field_value_type`	string	Value type of the field (e.g. `text`, `enum`, `number`, `boolean`, `date`, `clause`)
`org_field_id`	integer	Identifier of the org field
`value`	string, number, boolean, or null	Extracted value; `null` when unavailable
`is_unclear`	boolean	Whether the extracted value is uncertain
`is_null`	boolean	Whether the field was explicitly resolved as empty

Workflow Metadata Object

Field	Type	Description
`workflow_state_id`	string	Internal workflow state identifier
`workflow_id`	string	Workflow identifier
`org_id`	integer	Organization identifier
`user_id`	integer	Identifier of the user who ran the workflow
`workflow_version`	integer or null	Workflow version number
`task_id`	integer or null	Task identifier associated with the document

Mapped Field Object

Field	Type	Description
`name`	string	Name of the mapped attribute
`field_type`	string	Type of the attribute. One of `text`, `number`, `boolean`, `date`, `link`
`value`	string or number	Value of the mapped attribute

Error Responses

400 Bad Request

Returned when the access token has no user behind it. client_credentials tokens act as the admin who created the application, so this applies only to tokens issued before application creators were recorded.

{
  "detail": "client_credentials tokens are not associated with a user"
}

401 Unauthorized

Returned when the access token is missing, unknown, revoked, or expired, or when an X-API-Key was sent instead of a bearer token. See OAuth error responses.

{
  "detail": "Invalid access token"
}

403 Forbidden

Returned when the token does not carry the required scope.

{
  "detail": "Insufficient scope; this endpoint requires: sor:read"
}

404 Not Found

Returned when no document with that ID exists in your organization.

{
  "detail": "Not found"
}

429 Too Many Requests

Returned when your organization exceeds its per-minute request limit.

{
  "detail": "Rate limit exceeded"
}

500 Internal Server Error

Returned when the request fails due to a server error.

{
  "detail": "Failed to get contract data"
}

Notes

This endpoint is scoped to the organization, not to the access token’s user. Any document ID in your organization resolves, regardless of which document types that user may reach. A user must still be behind the token, so that per-document enforcement can be added later without breaking callers.

The include_* flags only add or remove sections from the response; they never change the document that is returned. With the default body ({}), summary is null and mapped_fields is [] - only the extracted fields are populated. Set include_summary and include_attributes to true to include those sections.

This endpoint returns the same document object as each entry in the Search Documents response. Use Search to find documents by field or attribute, then fetch a single document’s full data here by document_id.

Use Cases

Contract review - Retrieve all extracted fields and metadata for a contract
Data synchronization - Pull contract data into external systems (CRM, ERP)
Reporting - Build dashboards from extracted contract fields
Compliance checks - Verify key contract terms like renewal dates and values
Workflow integration - Access document data as part of automated workflows

Overview

API Key Access

OAuth App Access

Webhooks

Endpoint

Authentication

Path Parameters

Request Body

Request Example

Response

Success Response

Response Fields

Field Value Object

Workflow Metadata Object

Mapped Field Object

Error Responses

400 Bad Request

401 Unauthorized

403 Forbidden

404 Not Found

429 Too Many Requests

500 Internal Server Error

Notes

Use Cases

​Endpoint

​Authentication

​Path Parameters

​Request Body

​Request Example

​Response

​Success Response

​Response Fields

​Field Value Object

​Workflow Metadata Object

​Mapped Field Object

​Error Responses

​400 Bad Request

​401 Unauthorized

​403 Forbidden

​404 Not Found

​429 Too Many Requests

​500 Internal Server Error

​Notes

​Use Cases

Endpoint

Authentication

Path Parameters

Request Body

Request Example

Response

Success Response

Response Fields

Field Value Object

Workflow Metadata Object

Mapped Field Object

Error Responses

400 Bad Request

401 Unauthorized

403 Forbidden

404 Not Found

429 Too Many Requests

500 Internal Server Error

Notes

Use Cases