Upload Document

Endpoint

POST /core/upload

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

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	Email address of the user on whose behalf this document is being uploaded. If not provided, the document will be attributed to the API key creator
`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 /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/core/upload \
  -H "X-API-Key: ca_your_api_key_here" \
  -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/core/upload"
headers = {
    "X-API-Key": "ca_your_api_key_here",
    "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/core/upload', {
  method: 'POST',
  headers: {
    'X-API-Key': 'ca_your_api_key_here',
    '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

401 Unauthorized

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

{
  "detail": "Invalid API key"
}

400 Bad Request

Returned when document_type_id is not a valid document type for your organization. Use GET /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"
    }
  ]
}

500 Internal Server Error

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

{
  "detail": "Failed to upload document: Internal processing error"
}

Notes

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

401 Unauthorized

400 Bad Request

422 Validation Error

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

​401 Unauthorized

​400 Bad Request

​422 Validation Error

​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

401 Unauthorized

400 Bad Request

422 Validation Error

500 Internal Server Error

Notes

Use Cases