Upload Document

Endpoint

POST /v2/core/upload

Authentication

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

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

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"
      }
    ]
  }'

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())

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);

Response

Success Response

Status Code: 200 OK

{
  "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.

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

400 Bad Request

Returned when document_type_id is not a valid document type for your organization. Use GET /v2/core/document-types to retrieve valid values.

{
  "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.

{
  "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.

{
  "detail": "Rate limit exceeded"
}

500 Internal Server Error

Returned when the document upload fails due to a server error.

{
  "detail": "Failed to upload document"
}

Notes

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.

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

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

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

Overview

API Key Access

OAuth App Access

Webhooks

Endpoint

Authentication

Request Body

Required Fields

Optional Fields

Attribute Object

Document Field Override Object

Request Example

Response

Success Response

Response Fields

Error Responses

400 Bad Request

401 Unauthorized

403 Forbidden

400 Bad Request

422 Validation Error

429 Too Many Requests

500 Internal Server Error

Notes

Use Cases

​Endpoint

​Authentication

​Request Body

​Required Fields

​Optional Fields

​Attribute Object

​Document Field Override Object

​Request Example

​Response

​Success Response

​Response Fields

​Error Responses

​400 Bad Request

​401 Unauthorized

​403 Forbidden

​400 Bad Request

​422 Validation Error

​429 Too Many Requests

​500 Internal Server Error

​Notes

​Use Cases

Endpoint

Authentication

Request Body

Required Fields

Optional Fields

Attribute Object

Document Field Override Object

Request Example

Response

Success Response

Response Fields

Error Responses

400 Bad Request

401 Unauthorized

403 Forbidden

400 Bad Request

422 Validation Error

429 Too Many Requests

500 Internal Server Error

Notes

Use Cases