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

# Upload Document

> Upload a document to Chamelio's Core for processing. Documents are processed asynchronously and will be available in your organization's document repository.

## Endpoint

```
POST /v2/core/upload
```

## 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:write`

## Request Body

The request body must be a JSON object with the following fields:

### Required Fields

| Field                 | Type   | Description                                                                                                              |
| --------------------- | ------ | ------------------------------------------------------------------------------------------------------------------------ |
| `file_name`           | string | Name of the file being uploaded (e.g., "contract.pdf")                                                                   |
| `file_extension`      | string | File extension indicating the document type. Supported values: `pdf`, `docx`, `doc`, `txt`, `xlsx`, `xls`, `pptx`, `ppt` |
| `file_content_base64` | string | Base64-encoded content of the file                                                                                       |

### Optional Fields

| Field                   | Type    | Description                                                                                                                                                                                                                                                           |
| ----------------------- | ------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `user_email`            | string  | **Ignored on this endpoint.** The document is always attributed to the access token's user. Accepted for compatibility with the API-key surface                                                                                                                       |
| `attributes`            | array   | List of metadata attributes to attach to the document. Each attribute contains `name`, `data_type`, and `value`                                                                                                                                                       |
| `field_overrides`       | array   | List of pre-filled org field values that override the values Chamelio's AI would otherwise extract. Each entry is a [Document Field Override Object](#document-field-override-object)                                                                                 |
| `business_id`           | integer | Identifier of the business to associate the document with                                                                                                                                                                                                             |
| `document_type_id`      | integer | Identifier of the document type to assign to the document. Must be a valid document type for your organization - retrieve available types via [`GET /v2/core/document-types`](/api-reference/endpoint/v2/core/document-types). An invalid value returns a `400` error |
| `override_on_duplicate` | boolean | Whether to override an existing document if a duplicate is detected. Defaults to `false`                                                                                                                                                                              |

### Attribute Object

Each object in the `attributes` array contains:

| Field       | Type   | Description                                                                    |
| ----------- | ------ | ------------------------------------------------------------------------------ |
| `name`      | string | Name of the metadata field (e.g., "contract\_type", "effective\_date")         |
| `data_type` | string | Type of the field. Allowed values: `text`, `date`, `number`, `boolean`, `link` |
| `value`     | string | Value of the metadata field (formatted as a string regardless of data\_type)   |

### Document Field Override Object

Each object in the `field_overrides` array sets a pre-filled value for a specific org field, overriding the value Chamelio's AI extraction would produce:

| Field              | Type           | Required | Description                                                                                       |
| ------------------ | -------------- | -------- | ------------------------------------------------------------------------------------------------- |
| `org_field_id`     | integer        | Yes      | Identifier of the org field to set                                                                |
| `field_value_type` | string         | Yes      | Type of the field value. Allowed values: `text`, `enum`, `number`, `boolean`, `date`, `clause`    |
| `value`            | string or null | No       | The value to set. May be a string, number, boolean, or date; omit or set to `null` to leave empty |
| `is_verified`      | boolean        | No       | Whether the provided value should be marked as verified. Defaults to `false`                      |

## Request Example

<CodeGroup>
  ```bash cURL theme={null}
  curl -X POST https://platform.chamelio.ai/v2/core/upload \
    -H "Authorization: Bearer your_access_token" \
    -H "Content-Type: application/json" \
    -d '{
      "file_name": "master_services_agreement.pdf",
      "file_extension": "pdf",
      "file_content_base64": "JVBERi0xLjQKJeLjz9MKMyAwIG9iago8PC9...",
      "user_email": "john.doe@example.com",
      "attributes": [
        {
          "name": "contract_type",
          "data_type": "text",
          "value": "Master Services Agreement"
        },
        {
          "name": "effective_date",
          "data_type": "date",
          "value": "2025-01-01"
        },
        {
          "name": "contract_value",
          "data_type": "number",
          "value": "250000"
        },
        {
          "name": "auto_renew",
          "data_type": "boolean",
          "value": "true"
        },
        {
          "name": "vendor_website",
          "data_type": "link",
          "value": "https://vendor.example.com"
        }
      ]
    }'
  ```

  ```python Python theme={null}
  import requests
  import base64

  # Read and encode file
  with open("contract.pdf", "rb") as f:
      file_content = base64.b64encode(f.read()).decode('utf-8')

  url = "https://platform.chamelio.ai/v2/core/upload"
  headers = {
      "Authorization": "Bearer your_access_token",
      "Content-Type": "application/json"
  }

  payload = {
      "file_name": "master_services_agreement.pdf",
      "file_extension": "pdf",
      "file_content_base64": file_content,
      "user_email": "john.doe@example.com",
      "attributes": [
          {
              "name": "contract_type",
              "data_type": "text",
              "value": "Master Services Agreement"
          },
          {
              "name": "effective_date",
              "data_type": "date",
              "value": "2025-01-01"
          }
      ]
  }

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

  ```javascript JavaScript theme={null}
  import fs from 'fs';

  // Read and encode file
  const fileBuffer = fs.readFileSync('contract.pdf');
  const fileContent = fileBuffer.toString('base64');

  const response = await fetch('https://platform.chamelio.ai/v2/core/upload', {
    method: 'POST',
    headers: {
      'Authorization': 'Bearer your_access_token',
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({
      file_name: 'master_services_agreement.pdf',
      file_extension: 'pdf',
      file_content_base64: fileContent,
      user_email: 'john.doe@example.com',
      attributes: [
        {
          name: 'contract_type',
          data_type: 'text',
          value: 'Master Services Agreement'
        },
        {
          name: 'effective_date',
          data_type: 'date',
          value: '2025-01-01'
        }
      ]
    })
  });

  const data = await response.json();
  console.log(data);
  ```
</CodeGroup>

## Response

### Success Response

**Status Code:** `200 OK`

```json theme={null}
{
  "document_processing_id": 12345,
  "file_name": "master_services_agreement.pdf",
  "status": "success"
}
```

### Response Fields

| Field                    | Type    | Description                                                                                              |
| ------------------------ | ------- | -------------------------------------------------------------------------------------------------------- |
| `document_processing_id` | integer | Unique identifier for the document processing job. Use this ID to track the document's processing status |
| `file_name`              | string  | Name of the uploaded file                                                                                |
| `status`                 | string  | Upload status (always "success" for successful uploads)                                                  |

## 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:write"
}
```

### 400 Bad Request

Returned when `document_type_id` is not a valid document type for your organization. Use [`GET /v2/core/document-types`](/api-reference/endpoint/v2/core/document-types) to retrieve valid values.

```json theme={null}
{
  "detail": "document_type_id 42 is not valid for this org. See GET /core/document-types for available document types."
}
```

### 422 Validation Error

Returned when the request body is invalid or missing required fields.

```json theme={null}
{
  "detail": [
    {
      "loc": ["body", "file_name"],
      "msg": "field required",
      "type": "value_error.missing"
    }
  ]
}
```

### 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 document upload fails due to a server error.

```json theme={null}
{
  "detail": "Failed to upload document"
}
```

## Notes

<Info>
  The document is attributed to the access token's user. `/v2` has no impersonation, so `user_email`
  in the request body is ignored - use the API-key surface if you need to upload as another user.
</Info>

<Info>
  Documents are processed asynchronously. After a successful upload, the document will be queued for processing. Processing time varies depending on document size and complexity.
</Info>

<Warning>
  File content must be properly base64-encoded. Ensure you encode the binary file content, not the file path or text representation.
</Warning>

## Use Cases

This endpoint is useful for:

* **Automated document ingestion** - Integrate document uploads into your existing workflows
* **Bulk document processing** - Upload multiple documents programmatically
* **System integration** - Connect your document management system with Chamelio
* **Custom metadata** - Attach structured metadata to documents during upload for better organization and searchability