[
  {
    "id": "123e4567-e89b-12d3-a456-426614174000",
    "file_name": "document1.pdf",
    "file_size": 1048576,
    "created_at": "2024-03-21T13:45:00Z",
    "status": "PENDING",
    "accuracy": "ultra",
    "page_count": null
  },
  {
    "id": "987fcdeb-a654-3210-9876-543210987654",
    "file_name": "document2.pdf",
    "file_size": 2097152,
    "created_at": "2024-03-21T13:45:00Z",
    "status": "PENDING",
    "accuracy": "ultra",
    "page_count": null
  }
]

​
Create Document

Upload a new document for processing. This endpoint supports asynchronous processing with status updates available through polling or webhooks.

​
Request

​
Headers

​
Authorization
string
required

Bearer token authentication. See our Authentication guide for more details. Example: Bearer YOUR_API_KEY

​
Content-Type
string
required

Must be multipart/form-data

​
Body Parameters

​
files
array
required

Array of files to process. Each file must be a PDF document.

​
callback_url
string

Optional webhook URL to receive processing status updates.

​
accuracy
string
default:"lite"

Processing accuracy level. Options: lite or ultra.

  • lite: Faster processing with great accuracy
  • ultra: Highest accuracy, but slower processing
​
page_separator
boolean
default:"true"

Whether to include page separators in the output.

​
skip_images
boolean
default:"false"

Whether to skip image extraction from the document.

​
Example Request

curl -X POST https://api.doctly.ai/api/v1/documents/ \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -F "files=@document1.pdf" \
  -F "files=@document2.pdf" \
  -F "accuracy=ultra" \
  -F "callback_url=https://your-domain.com/webhook"

​
Response

​
[]
array

Array of created document objects.

​
Example Responses

[
  {
    "id": "123e4567-e89b-12d3-a456-426614174000",
    "file_name": "document1.pdf",
    "file_size": 1048576,
    "created_at": "2024-03-21T13:45:00Z",
    "status": "PENDING",
    "accuracy": "ultra",
    "page_count": null
  },
  {
    "id": "987fcdeb-a654-3210-9876-543210987654",
    "file_name": "document2.pdf",
    "file_size": 2097152,
    "created_at": "2024-03-21T13:45:00Z",
    "status": "PENDING",
    "accuracy": "ultra",
    "page_count": null
  }
]

​
Webhook Notifications

If a callback_url is provided, you will receive a POST request when processing has completed:

{
  "id": "123e4567-e89b-12d3-a456-426614174000",
  "file_name": "document1.pdf"
}

Webhook URLs must be HTTPS and publicly accessible.

​
Webhook Failure Handling

If the webhook delivery fails:

  • The system will automatically retry up to 3 times
  • Each retry attempt waits 5 seconds before trying again

​
Next Step: Poll for Completion

After you create a document the status will be PENDING. Call Get Document periodically using the returned id until status changes to COMPLETED or FAILED. The output_file_url field will then be available for download.

# Poll every 5 s until status==COMPLETED or status==FAILED
DOC_ID="123e4567-e89b-12d3-a456-426614174000"
while true; do
  STATUS=$(curl -s https://api.doctly.ai/api/v1/documents/$DOC_ID \
    -H "Authorization: Bearer YOUR_API_KEY" | jq -r '.status')
  echo "Status: $STATUS"
  if [ "$STATUS" = "COMPLETED" ] || [ "$STATUS" = "FAILED" ]; then
    break
  fi
  sleep 5
done