> ## Documentation Index
> Fetch the complete documentation index at: https://docs.chamelio.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Get Contract Data

> Retrieve the full document fields and metadata for a contract

## Endpoint

```
POST /v2/core/contracts/{document_id}
```

## Authentication

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

```bash theme={null}
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

<CodeGroup>
  ```bash cURL theme={null}
  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
    }'
  ```

  ```python Python theme={null}
  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())
  ```

  ```javascript JavaScript theme={null}
  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);
  ```
</CodeGroup>

## 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](/api-reference/endpoint/v2/core/search) `documents` array.

```json theme={null}
{
  "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](#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](#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](#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.

```json theme={null}
{
  "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](/api-reference/oauth-apps#error-responses).

```json theme={null}
{
  "detail": "Invalid access token"
}
```

### 403 Forbidden

Returned when the token does not carry the required scope.

```json theme={null}
{
  "detail": "Insufficient scope; this endpoint requires: sor:read"
}
```

### 404 Not Found

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

```json theme={null}
{
  "detail": "Not found"
}
```

### 429 Too Many Requests

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

```json theme={null}
{
  "detail": "Rate limit exceeded"
}
```

### 500 Internal Server Error

Returned when the request fails due to a server error.

```json theme={null}
{
  "detail": "Failed to get contract data"
}
```

## Notes

<Warning>
  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.
</Warning>

<Info>
  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.
</Info>

<Tip>
  This endpoint returns the same document object as each entry in the [Search Documents](/api-reference/endpoint/v2/core/search)
  response. Use Search to find documents by field or attribute, then fetch a single document's full data here by `document_id`.
</Tip>

## 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