This endpoint performs an upsert operation for document files: it uploads a new document or replaces
an existing document's file based on the identifier you provide.

Document Identification

You must provide exactly one of the following identifiers (providing both will result in an error):

1. document_id (integer):

• Use the internal Customerly document ID to replace an existing document's file
• If the document doesn't exist or is currently processing, an error will be returned

2. custom_document_id (string):

• Use your custom identifier for upsert operations
• If a document with this custom_document_id exists, its file will be replaced
• If it doesn't exist, a new document will be created with this identifier
• Must be unique within your app

Important: You cannot specify both document_id and custom_document_id in the same request.
If neither is provided, the upload will fail.

File Requirements

• Supported formats: PDF, Word (doc/docx), TXT
• Maximum size: 100MB
• Required: You must include a file in the request

Processing

The document content will be extracted asynchronously:

1. Initial status will be processing
2. Once extraction completes successfully, status changes to active
3. If extraction fails, status will be set to failed

You can poll the GET /documents/{id} endpoint to check the current processing status.

Title

• If title is not provided, the filename (without extension) will be used as the document title

AI Training

If is_ai_enabled is set to true, the document will be trained for AI-powered features after text extraction.
Note: AI training can take a few minutes to complete after the document status becomes active.

Document Folders

To organize documents in folders, use the polymorphic_folder_id parameter:

1. Create folders in the Customerly UI or use GET /documents/folders to list existing folders
2. Get the folder ID from the response
3. Pass the folder ID in the polymorphic_folder_id parameter when uploading the document