Get Contract Data - Chamelio Documentation

Endpoint

POST /core/contracts/{document_id}

Authentication

This endpoint requires authentication via API key. Include your API key in the X-API-Key header:

X-API-Key: ca_your_api_key_here

Path Parameters

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

Request Body

Field	Type	Required	Default	Description
`include_summary`	boolean	No	`false`	Include the AI-generated document summary in the response
`include_attributes`	boolean	No	`false`	Include document attributes (category, visibility, active status, exhibits, etc.)
`include_extracted_fields`	boolean	No	`true`	Include the extracted document fields in the response

Request Example

curl -X POST "https://platform.chamelio.ai/core/contracts/42" \
  -H "X-API-Key: ca_your_api_key_here" \
  -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/core/contracts/{document_id}"
headers = {
    "X-API-Key": "ca_your_api_key_here",
    "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/core/contracts/${documentId}`,
  {
    method: 'POST',
    headers: {
      'X-API-Key': 'ca_your_api_key_here',
      '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

{
  "document_id": 42,
  "org_id": 1,
  "version": 3,
  "file_name": "Acme_MSA_2025.pdf",
  "document_title": "Master Service Agreement - Acme Corp",
  "document_type": "MSA",
  "category": "contract",
  "visibility": "visible",
  "active": {
    "value": "active",
    "is_verified": true
  },
  "summary": "Master service agreement between Acme Corp and our organization, covering SaaS platform licensing and support services.",
  "exhibits": ["Exhibit A - Pricing", "Exhibit B - SLA"],
  "attachments_ids": [101, 102],
  "previous_versions": [38, 35],
  "fields": [
    {
      "field_name": "Counterparty",
      "field_value_type": "text",
      "org_field_id": 1,
      "is_verified": true,
      "is_unclear": false,
      "reasoning": "Extracted from the first page header",
      "source_text": ["This agreement is entered into by Acme Corporation"],
      "chunk_ids": [1],
      "text_value": "Acme Corporation"
    },
    {
      "field_name": "Contract Value",
      "field_value_type": "number",
      "org_field_id": 2,
      "is_verified": false,
      "is_unclear": false,
      "reasoning": "Found in Section 4 - Pricing",
      "source_text": ["The total contract value shall not exceed $150,000"],
      "chunk_ids": [4],
      "number_value": 150000.0
    },
    {
      "field_name": "Auto-Renewal",
      "field_value_type": "boolean",
      "org_field_id": 3,
      "is_verified": false,
      "is_unclear": false,
      "reasoning": "Found in Section 8 - Term",
      "source_text": ["This agreement shall automatically renew"],
      "chunk_ids": [8],
      "boolean_value": true
    },
    {
      "field_name": "Effective Date",
      "field_value_type": "date",
      "org_field_id": 4,
      "is_verified": true,
      "is_unclear": false,
      "reasoning": "Found on the signature page",
      "source_text": ["Effective as of January 15, 2025"],
      "chunk_ids": [12],
      "date_value": "2025-01-15"
    },
    {
      "field_name": "Contract Type",
      "field_value_type": "enum",
      "org_field_id": 5,
      "is_verified": false,
      "is_unclear": false,
      "reasoning": "Determined from the document title and content",
      "source_text": null,
      "chunk_ids": null,
      "enum_value": "Master Service Agreement"
    },
    {
      "field_name": "Unclear Field Example",
      "field_value_type": "text",
      "org_field_id": 6,
      "is_verified": false,
      "is_unclear": true,
      "reasoning": "Multiple conflicting values found in the document",
      "source_text": ["Amount: $50,000", "Total: $75,000"],
      "chunk_ids": [3, 7],
      "text_value": null
    }
  ],
  "mapped_fields": {
    "text": {
      "vendor_name": "Acme Corporation"
    },
    "number": {
      "total_value": 150000.0
    },
    "boolean": {
      "auto_renew": true
    },
    "date": {
      "effective_date": "2025-01-15T00:00:00Z"
    },
    "link": {}
  },
  "workflow_metadata": {
    "workflow_state_id": "ws_abc123",
    "workflow_id": "vendor_contract_review",
    "org_id": 1,
    "user_id": 10,
    "workflow_version": 2,
    "task_id": 5001
  },
  "related_template": {
    "template_id": 7,
    "template_version": 1
  },
  "document_created_at": "2025-01-15T10:30:00Z",
  "source": "external_api",
  "uploaded_by_user_id": 10
}

Response Fields

Field	Type	Description
`document_id`	integer	Unique identifier for the document
`org_id`	integer	Organization identifier
`version`	integer	Document schema version
`file_name`	string	Original file name
`document_title`	string or null	Human-readable document title
`document_type`	string	Type of document (e.g., “MSA”, “NDA”, “SOW”)
`category`	string	Document category: `contract`, `policy`, `template`, `archive`
`visibility`	string	Visibility level: `none`, `visible`, `admin_only`, `archive`
`active`	object	Active status with verification flag (see below)
`summary`	string or null	AI-generated summary of the document
`exhibits`	array of strings	List of exhibit names found in the document
`attachments_ids`	array of integers	IDs of attached documents
`previous_versions`	array of integers	Document IDs of previous versions
`fields`	array	Extracted document fields (see below)
`mapped_fields`	object	Key-value pairs grouped by type (see below)
`workflow_metadata`	object or null	Workflow context if the document is part of a workflow
`related_template`	object or null	Associated template information
`document_created_at`	string or null	ISO 8601 timestamp of the original document date
`source`	string or null	How the document was ingested: `drive`, `sharepoint`, `local`, `email`, `workflow`, `integration`, `external_api`, `docusign`, `salesforce`
`uploaded_by_user_id`	integer or null	ID of the user who uploaded the document

Active Object

Field	Type	Description
`value`	string	Active status: `active`, `inactive`, `unknown`
`is_verified`	boolean	Whether the active status has been verified by a user

Field Object

Each field in the fields array represents an extracted data point from the document. The value field varies by type.

Common Fields

Field	Type	Description
`field_name`	string	Display name of the field
`field_value_type`	string	Type discriminator: `text`, `clause`, `enum`, `number`, `boolean`, `date`, `bullet_list`, `business`, `user_party`
`org_field_id`	integer	Organization-level field definition ID
`is_verified`	boolean	Whether the value has been verified by a user
`is_unclear`	boolean	Whether the AI could not determine a clear value
`reasoning`	string or null	AI reasoning for the extracted value
`source_text`	array of strings or null	Relevant text excerpts from the document
`chunk_ids`	array of integers or null	Document chunk IDs where the value was found

Value Fields by Type

`field_value_type`	Value Field	Type	Description
`text`	`text_value`	string or null	Plain text value
`clause`	`text_value`	string or null	Contract clause text
`enum`	`enum_value`	string or null	Selected option from a predefined list
`business`	`enum_value`	string or null	Business entity name
`business`	`business_id`	integer or null	Business entity ID
`user_party`	`enum_value`	string or null	User party value
`number`	`number_value`	number or null	Numeric value
`boolean`	`boolean_value`	boolean or null	True/false value
`date`	`date_value`	string or null	ISO 8601 date
`bullet_list`	`json_value`	object/array or null	Structured list data

When is_unclear is true, the value field will be null — this means the AI found conflicting or ambiguous information in the document.

Mapped Fields Object

Pre-mapped key-value pairs organized by data type. These are populated from workflow metadata.

Field	Type	Description
`text`	object	String key-value pairs
`number`	object	Numeric key-value pairs
`boolean`	object	Boolean key-value pairs
`date`	object	Date key-value pairs (ISO 8601 values)
`link`	object	URL key-value pairs

Workflow Metadata Object

Present when the document is associated with a workflow.

Field	Type	Description
`workflow_state_id`	string	Workflow state identifier
`workflow_id`	string	Workflow definition identifier
`org_id`	integer	Organization ID
`user_id`	integer	User who initiated the workflow
`workflow_version`	integer or null	Workflow version number
`task_id`	integer or null	Associated task ID

Present when the document was created from a template.

Field	Type	Description
`template_id`	integer	Template identifier
`template_version`	integer	Template version number

Error Responses

401 Unauthorized

Returned when authentication fails. See the authentication errors section for details.

{
  "detail": "Invalid API key"
}

404 Not Found

Returned when the document doesn’t exist or you don’t have access to it.

{
  "detail": "Document not found"
}

500 Internal Server Error

Returned when the request fails due to a server error.

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

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

​Endpoint

​Authentication

​Path Parameters

​Request Body

​Request Example

​Response

​Success Response

​Response Fields

​Active Object

​Field Object

​Common Fields

​Value Fields by Type

​Mapped Fields Object

​Workflow Metadata Object

​Related Template Object

​Error Responses

​401 Unauthorized

​404 Not Found

​500 Internal Server Error

​Use Cases

Endpoint

Authentication

Path Parameters

Request Body

Request Example

Response

Success Response

Response Fields

Active Object

Field Object

Common Fields

Value Fields by Type

Mapped Fields Object

Workflow Metadata Object

Related Template Object

Error Responses

401 Unauthorized

404 Not Found

500 Internal Server Error

Use Cases