Run Extractor

curl -X POST https://api.doctly.ai/api/v1/e/invoice-extractor \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -F "file=@invoice.pdf"

{
  "id": "123e4567-e89b-12d3-a456-426614174000",
  "file_name": "invoice.pdf",
  "file_size": 524288,
  "page_count": 2,
  "status": "PENDING",
  "extractor_id": "987fcdeb-a654-3210-9876-543210987654",
  "extractor": {
    "id": "987fcdeb-a654-3210-9876-543210987654",
    "name": "Invoice Extractor",
    "slug": "invoice-extractor",
    "cost_type": "PER_PAGE",
    "cost_credits": 5
  },
  "created_at": "2024-03-21T13:45:00Z"
}

{
  "detail": "Provide only one of 'file' or 'url'."
}

{
  "detail": "One of 'file' or 'url' must be provided."
}

{
  "detail": "Extractor with path 'unknown-extractor' not found for your account."
}

{
  "detail": [
    {
      "loc": ["body", "file"],
      "msg": "field required",
      "type": "value_error.missing"
    }
  ]
}

curl -X POST https://api.doctly.ai/api/v1/e/invoice-extractor \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -F "file=@invoice.pdf"

POST /api/v1/e/{slug} Run a custom extractor on a document file. Extractors are pre-configured pipelines that extract specific data from documents and return structured output (JSON, CSV, XML, or Markdown).

Request

Headers

string

required

Bearer token authentication. Example: Bearer YOUR_API_KEY

Path Parameters

string

required

The unique slug identifier of the extractor (e.g., invoice-extractor)

Body Parameters

file

The document file to process. Supported formats: PDF, DOCX, PNG, JPG, JPEG, WEBP, GIF.

Provide either file or url, not both.

string

URL to download the document from. The file will be fetched and processed.

Provide either file or url, not both.

string

Webhook URL to receive a POST request when extraction completes.

Example Request

curl -X POST https://api.doctly.ai/api/v1/e/invoice-extractor \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -F "file=@invoice.pdf"

import requests

slug = "invoice-extractor"
url = f"https://api.doctly.ai/api/v1/e/{slug}"
headers = {"Authorization": "Bearer YOUR_API_KEY"}

with open("invoice.pdf", "rb") as f:
    files = {"file": ("invoice.pdf", f, "application/pdf")}
    data = {"callback_url": "https://your-domain.com/webhook"}  # optional
    response = requests.post(url, headers=headers, files=files, data=data)

print(response.json())

const formData = new FormData();
formData.append('file', fileInput.files[0]);
formData.append('callback_url', 'https://your-domain.com/webhook');

const response = await fetch('https://api.doctly.ai/api/v1/e/invoice-extractor', {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer YOUR_API_KEY'
  },
  body: formData
});

const data = await response.json();

From URL

curl -X POST https://api.doctly.ai/api/v1/e/invoice-extractor \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -F "url=https://example.com/invoice.pdf"

import requests

slug = "invoice-extractor"
url = f"https://api.doctly.ai/api/v1/e/{slug}"
headers = {"Authorization": "Bearer YOUR_API_KEY"}

data = {"url": "https://example.com/invoice.pdf"}
response = requests.post(url, headers=headers, data=data)

print(response.json())

Response

Show Extraction Response

string

Unique identifier (UUID) for the document/extraction job

string

Original filename

integer

Size of the file in bytes

integer

Number of pages in the document

string

Processing status: PENDING, PROCESSING, COMPLETED, or FAILED

string

UUID of the extractor used

object

Details of the extractor used

Show Extractor Object

string

Extractor UUID

string

Display name of the extractor

string

URL-friendly identifier

string

Pricing model: PER_PAGE or PER_DOCUMENT

integer

Credits charged per page or per document

string

ISO 8601 timestamp

Example Responses

{
  "id": "123e4567-e89b-12d3-a456-426614174000",
  "file_name": "invoice.pdf",
  "file_size": 524288,
  "page_count": 2,
  "status": "PENDING",
  "extractor_id": "987fcdeb-a654-3210-9876-543210987654",
  "extractor": {
    "id": "987fcdeb-a654-3210-9876-543210987654",
    "name": "Invoice Extractor",
    "slug": "invoice-extractor",
    "cost_type": "PER_PAGE",
    "cost_credits": 5
  },
  "created_at": "2024-03-21T13:45:00Z"
}

{
  "detail": "Provide only one of 'file' or 'url'."
}

{
  "detail": "One of 'file' or 'url' must be provided."
}

{
  "detail": "Extractor with path 'unknown-extractor' not found for your account."
}

{
  "detail": [
    {
      "loc": ["body", "file"],
      "msg": "field required",
      "type": "value_error.missing"
    }
  ]
}

Webhooks

If callback_url is provided, you’ll receive a POST request when extraction completes:

{
  "document_id": "123e4567-e89b-12d3-a456-426614174000",
  "status": "COMPLETED",
  "file_name": "invoice.pdf",
  "extractor": {
    "id": "987fcdeb-a654-3210-9876-543210987654",
    "name": "Invoice Extractor",
    "slug": "invoice-extractor"
  }
}

Polling for Results

After running an extractor, poll Get Document until status is COMPLETED:

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

import time
import requests

doc_id = "123e4567-e89b-12d3-a456-426614174000"
headers = {"Authorization": "Bearer YOUR_API_KEY"}

while True:
    resp = requests.get(
        f"https://api.doctly.ai/api/v1/documents/{doc_id}",
        headers=headers
    ).json()
    
    print(f"Status: {resp['status']}")
    
    if resp["status"] in ("COMPLETED", "FAILED"):
        if resp["status"] == "COMPLETED":
            # Download extraction result
            result = requests.get(resp["output_file_url"])
            data = result.json()  # JSON extraction result
            print(data)
        break
    
    time.sleep(5)

const docId = '123e4567-e89b-12d3-a456-426614174000';
const headers = { 'Authorization': 'Bearer YOUR_API_KEY' };

while (true) {
  const response = await fetch(
    `https://api.doctly.ai/api/v1/documents/${docId}`,
    { headers }
  );
  const doc = await response.json();
  
  console.log(`Status: ${doc.status}`);
  
  if (doc.status === 'COMPLETED' || doc.status === 'FAILED') {
    if (doc.status === 'COMPLETED') {
      // Download extraction result
      const result = await fetch(doc.output_file_url);
      const data = await result.json();
      console.log(data);
    }
    break;
  }
  
  await new Promise(r => setTimeout(r, 5000));
}

Extractor Output Formats

Extractors can output data in different formats:

Format	Content-Type	Description
JSON	`application/json`	Structured data as JSON object
CSV	`text/csv`	Tabular data as CSV
XML	`application/xml`	Structured data as XML
Markdown	`text/markdown`	Formatted text as Markdown

The output format is determined by the extractor configuration.

Each extractor is designed for specific document types. Using an invoice extractor on a resume may produce incomplete or incorrect results.

API Overview

Documents

Extractors

Collections

Collection Files

Chat

Request

Headers

Path Parameters

Body Parameters

Example Request

From URL

Response

Example Responses

Webhooks

Polling for Results

Extractor Output Formats

​Request

​Headers

​Path Parameters

​Body Parameters

​Example Request

​From URL

​Response

​Example Responses

​Webhooks

​Polling for Results

​Extractor Output Formats

Request

Headers

Path Parameters

Body Parameters

Example Request

From URL

Response

Example Responses

Webhooks

Polling for Results

Extractor Output Formats