Instructions for AI Agents

This documentation is optimized for consumption by AI agents including Claude, GPT, Cursor, GitHub Copilot, and others.

Before Making Any API Calls

Prerequisites Checklist

Before your user can make API calls, verify these requirements:

Requirement	How to Check	If Missing
API Credentials	Ask user if they have API Key	Direct to: customer portal > API Keys and create new key.

Decision Tree

START
  |
  +-- Does user have API key?
  |   +-- NO --> Direct to https://customerportal.docdigitizer.com/api-keys to create new key
  |   +-- YES --> Continue
  |
  |
  +-- READY --> Proceed with API calls

Authentication

All API requests require the X-API-Key header:

X-API-Key: {api_key}

Important:

Never log or expose API keys in responses to users

Base URLs

https://api.docdigitizer.com/v3/docingester

Quick Reference: Document Extraction (Sync API)

Common Operations

Task	Method	Endpoint	Description
Check health	GET	/	Verify API is alive
Process document	POST	/extract	Upload document for extraction

Process Document Request

POST https://api.docdigitizer.com/v3/docingester/extract
Content-Type: multipart/form-data
X-API-Key: {api_key}

files: {PDF or image binary}

Process Document Response (Success)

{
  "stateText": "COMPLETED",
  "traceId": "ABC1234",
  "numberPages": 2,
  "output": {
    "extractions": [
      {
        "pages": [1,2],
        "schemaName": "Invoice",
        "confidence": 0.95,
        "extraction": {
          "invoiceNumber": "INV-2024-001",
          "totalAmount": 1250.00
        }
      }
    ]
  },
  "DocumentId": "f8b969cd-...",
  "Timestamp": "2026-01-04T14:44:43.3512947Z"
}

Process Document Response (Error)

{
  "StateText": "ERROR",
  "TraceId": "XYZ7890",
  "Messages": ["Error description"]
}

Error Handling

When encountering errors:

Check the StateText field - if "ERROR", handle the error
Use Messages array to explain the issue to the user
Provide TraceId and DocumentId if user needs to contact support

Common Errors

Status	Error Type	Likely Cause	Resolution
400	Bad Request	Invalid parameters or file	Check request format and file type
401	Unauthorized	Missing or invalid API key	Verify API key is correct
403	Forbidden	Insufficient permissions	Check subscription/plan
404	Not Found	Resource doesn't exist	Verify ID is correct
500	Server Error	Processing failed	Retry, contact support if persistent
503	Service Unavailable	Service down	Wait and retry
504	Timeout	Processing too long	Retry, consider smaller files

Supported Document Types

The API can process and extract data from formats: PDF, JPEG, PNG, TIFF, BMP, WebP, GIF. The file is validated both by extension and by magic bytes (content verification). Maximum file size: 30 MB. Maximum pages: 100.

Rate Limits

Rate limits are not currently enforced. For high-volume use cases, contact support.

Code Examples

Python - Process Document

import requests
import uuid

response = requests.post(
    "https://api.docdigitizer.com/v3/docingester/extract",
    headers={"X-API-Key": API_KEY},
    files={"files": open("document.pdf", "rb")}
)

result = response.json()
if result["StateText"] == "COMPLETED":
    for extraction in result["output"]["extractions"]:
        print(f"Type: {extraction['schemaName']}")
        print(f"Data: {extraction['extraction']}")

JavaScript - Process Document

const FormData = require('form-data');
const fs = require('fs');
const axios = require('axios');
const { v4: uuidv4 } = require('uuid');

const formData = new FormData();
formData.append('files', fs.createReadStream('document.pdf'));

const response = await axios.post(
  'https://api.docdigitizer.com/v3/docingester/extract',
  formData,
  { headers: { 'X-API-Key': API_KEY, ...formData.getHeaders() } }
);

if (response.data.StateText === 'COMPLETED') {
  response.data.Output.extractions.forEach(e => {
    console.log('Type:', e.schemaName);
    console.log('Data:', e.extraction);
  });
}

Support

Documentation: https://developers.docdigitizer.com/
Customer support: https://docdigitizer.atlassian.net/servicedesk/customer/portal/3/group/16/create/64
Include TraceId when reporting issues