Skip to main content
Process Document
curl --request POST \
  --url https://api.example.com/api/v1/documents/ \
  --header 'Authorization: <authorization>' \
  --header 'Content-Type: <content-type>' \
  --data '
{
  "accuracy": "<string>",
  "extractor_id": "<string>",
  "page_separator": true,
  "skip_images": true,
  "callback_url": "<string>"
}
'
{
  "id": "123e4567-e89b-12d3-a456-426614174000",
  "file_name": "document.pdf",
  "file_size": 1048576,
  "created_at": "2024-03-21T13:45:00Z",
  "status": "PENDING",
  "accuracy": "ultra",
  "page_count": null
}

​
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

​
file
file
required
A document file to process. The file must be a PDF, Docx, or Image file.
​
accuracy
string
default:"lite"
Markdown conversion with processing accuracy level. Options: lite or ultra.
  • lite: Faster processing with great accuracy
  • ultra: Highest accuracy, but slower processing
​
extractor_id
string
default:"lite"
The ID of the custom extractor to use with your document.
​
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.
​
callback_url
string
Optional webhook URL to receive processing status updates.

​
Example Request of Document to Markdown

curl -X POST https://api.doctly.ai/api/v1/documents/ \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -F "[email protected]" \
  -F "accuracy=ultra" \
  -F "callback_url=https://your-domain.com/webhook"

​
Response

​
object
object
Created document object.

​
Example Responses

{
  "id": "123e4567-e89b-12d3-a456-426614174000",
  "file_name": "document.pdf",
  "file_size": 1048576,
  "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": "document.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