Algodocs API Reference

Quickstart

Three calls take you from zero to extracted data:

Find your extractor. Call GET /v1/extractors and copy the id of the extractor you configured in the dashboard.
Upload a document. Send a file to POST /v1/document/upload_local. You get back a documentId.
Poll for results. Call GET /v1/extracted_data/{documentId} until the data object is populated.

Tip: Processing is asynchronous. After upload, wait a moment and poll the extracted-data endpoint — most documents finish in a few seconds.

End-to-end · cURL

# 1. upload a file
curl -X POST \
  https://api.algodocs.com/v1/document/upload_local/EXTRACTOR_ID/FOLDER_ID \
  -H "x-api-key: YOUR_API_KEY" \
  -F "file=sample.pdf"

# 2. fetch results (use the returned id)
curl https://api.algodocs.com/v1/extracted_data/182609 \
  -H "x-api-key: YOUR_API_KEY"

Base URL & versioning

All endpoints are served over HTTPS from a single, versioned base URL:

https://api.algodocs.com/v1

Every path in this reference is relative to that base. Responses are JSON and all timestamps use ISO 8601 in UTC (for example 2026-06-27T10:45:52Z). You can change the reporting timezone from Settings in your account.

Client libraries

Prefer not to hand-roll HTTP requests? Algodocs maintains official client libraries that wrap every endpoint in this reference. You can always call the REST API directly too.

🐍

Python client

Python 3 bindings for the full API. Install from PyPI:

pip3 install algodocs

GitHub ↗ · PyPI ↗

🐘

PHP client

PHP bindings for the full API (requires PHP 5.5 or above).

GitHub ↗

Install

pip3 install algodocs

# clone the official PHP client
git clone https://github.com/algodocs/algodocs-php

Authentication

Every endpoint requires authentication. Register for a free account and generate your Secret API key at app.algodocs.com/restapi. The API accepts two interchangeable schemes — pick whichever fits your stack. You can verify your credentials any time with GET /v1/me.

Basic authentication

Base64-encode email_address:api_key — i.e. base64('you@example.com:YOUR_API_KEY') — and send it in the Authorization header (cURL's --user does this for you).

Header parameters

Field	Type	Description
`email_address`	String	The email you registered with.
`api_key`	String	Your Secret API key.

API key header

Or skip Basic auth entirely and pass the secret key in the x-api-key header. This is the simplest option for server-to-server calls.

Header parameters

Field	Type	Description
`api_key`	String	Your Secret API key.

Keep keys secret. Never embed your API key in client-side code or public repositories. Treat it like a password and rotate it from the dashboard if exposed.

Authenticated request

curl https://api.algodocs.com/v1/me \
  -H "x-api-key: YOUR_API_KEY"

# Authorization: Basic base64("email:api_key")
curl https://api.algodocs.com/v1/me \
  --user "you@example.com:YOUR_API_KEY"

How extraction works

The model is built around three objects:

🔧

Extractor

A trained configuration that knows which fields to pull from a document type — e.g. an Invoice Extractor returning invoice number, date and total.

🗂️

Folder

An organizational bucket. Each uploaded document lives in a folder so you can group and query results later.

📄

Document

A single uploaded file. Once processed, it exposes a data object plus links to the original, Excel, JSON and XML outputs.

Errors

When the classifier can't recognize an uploaded document, the request still succeeds — but the data object carries an error message instead of the extracted fields, as shown on the right.

Classifier failure


    [
        {
            "id": "43300b4e06454ef7bae10b03df622bsh",
            "documentId": 485976,
            "uploadedAt": "2022-05-09T09:31:20Z",
            "fileName": "Invoice.pdf",
            "folderId": "1a5e2f9c624b",
            "data":
            {
                "error": "Classifier could not recognize this document."
            }
        }
    ]

GET /v1/me

Current user

Returns the full name and email of the account tied to your credentials. Handy as a health-check that your authentication is wired up correctly.

Response fields

Field	Type	Description
`fullName`	string	Account holder's name.
`email`	string	Account email address.

Request

curl https://api.algodocs.com/v1/me \
  -H "x-api-key: YOUR_API_KEY"

200 — Response

{
    "fullName": "John Doe",
    "email": "john@example.com"
}

GET /v1/extractors

List extractors

Retrieves every extractor on your account. Use the returned id values when uploading documents so Algodocs knows which fields to pull.

Response fields

Field	Type	Description
`id`	string	Unique extractor identifier.
`name`	string	Display name set in the dashboard.

Request

curl https://api.algodocs.com/v1/extractors \
  -H "x-api-key: YOUR_API_KEY"

200 — Response

[
    {
        "id": "6d86215bf9cb4fc6ac1f6967",
        "name": "Invoice Extractor"
    },
    {
        "id": "6a0cdd3949444cf189e62416",
        "name": "Bank Statement Extractor"
    }
]

GET /v1/folders

List folders

Returns the folder tree used to organize documents. parentId is null for the root folder and references another folder's id otherwise.

Response fields

Field	Type	Description
`id`	string	Unique folder identifier.
`parentId`	string · null	Parent folder, or null at root.
`name`	string	Folder name.

Request

curl https://api.algodocs.com/v1/folders \
  -H "x-api-key: YOUR_API_KEY"

200 — Response

[
    {
        "id": "1a5e2f9c624b",
        "parentId": null,
        "name": "root"
    },
    {
        "id": "c40daa5550d9",
        "parentId": "1a5e2f9c624b",
        "name": "Invoices"
    }
]

POST /v1/document/upload_local/{extractor_id}/{folder_id}

Upload a local file

Uploads a document from your machine as multipart form data. The response confirms the upload and returns the new document's id, which you use to fetch results.

Path parameters

Param	Description
`extractor_id`	The extractor that should process the file.
`folder_id`	Destination folder for the document.

Body

Field	Type	Description
`file`	file	The PDF or image to extract from.

Request

curl -X POST \
https://api.algodocs.com/v1/document/\
upload_local/EXTRACTOR_ID/FOLDER_ID \
-H "x-api-key: YOUR_API_KEY" \
-F "file=sample.pdf"

200 — Response

{
    "id": 182609,
    "fileSize": 136925,
    "fileMD5CheckSum": "955C30272DC...787D5",
    "uploadedAt": "2026-06-27T14:03:24Z"
}

POST /v1/document/upload_url/{extractor_id}/{folder_id}

Upload from a URL

Tells Algodocs to fetch and process a document from a publicly accessible URL — no need to stream the file yourself.

Body

Field	Type	Description
`url`	string	Public URL of the document to fetch.

Request

curl -X POST \
https://api.algodocs.com/v1/document/\
upload_url/EXTRACTOR_ID/FOLDER_ID \
-H "x-api-key: YOUR_API_KEY" \
-F "url=https://api.algodocs.com/content/SampleInvoice.pdf"

200 — Response

{
    "id": 182610,
    "fileSize": 136925,
    "fileMD5CheckSum": "955C30272DC...787D5",
    "uploadedAt": "2026-06-27T14:44:11Z"
}

POST /v1/document/upload_base64/{extractor_id}/{folder_id}

Upload base64

Sends a base64-encoded file inline — useful when you already hold the bytes in memory and don't want to write a temp file.

Body

Field	Type	Description
`file_base64`	string	Base64-encoded file content.
`filename`	string	Name to store the document under.

Request

curl -X POST \
https://api.algodocs.com/v1/document/\
upload_base64/EXTRACTOR_ID/FOLDER_ID \
-H "x-api-key: YOUR_API_KEY" \
-F "file_base64=JVBERi0xLjcK..." \
-F "filename=invoice.pdf"

200 — Response

{
    "id": 182610,
    "fileSize": 136925,
    "fileMD5CheckSum": "955C30272DC...787D5",
    "uploadedAt": "2026-06-27T14:44:11Z"
}

GET /v1/extracted_data/{document_id}

Get extracted data — single document

Returns the extraction result for one document as an array. System fields are always present; the data object holds the fields defined by your extractor. If processing is still running, poll until data is populated.

Multi-page & split documents. When a document is split into multiple records (for example a multi-page PDF or line items), the response contains one object per record — each with its own pageNumber out of totalPages. That's why the result is always a list.

Key response fields

Field	Description
`documentId`	The document this result belongs to.
`processedAt`	When extraction finished (UTC).
`mediaOriginal` · `mediaExcel` · `mediaJson` · `mediaXml`	Download links for the original file and each output format.
`data`	Extractor-defined fields (e.g. invoice number, amount).

Request

curl https://api.algodocs.com/v1/\
extracted_data/182608 \
-H "x-api-key: YOUR_API_KEY"

200 — Response

[
    {
        "id": "5fe7608abd59783e98438b3e",
        "documentId": 182608,
        "uploadedAt": "2026-06-20T16:10:21Z",
        "processedAt": "2026-06-20T16:10:50Z",
        "fileName": "Invoice.pdf",
        "folderId": "a8woh6w32rt4",
        "mediaOriginal": "https://api.algodocs.com/v1/media/niGNFZgpj655iThANTDhIgE3lQoSagCbsBkw0PRhzAo7DeanCToefGYGdd1pbYOC4udg8l9xBWiHr70HgAQQsXwmceSnn2FammDJAtOQjqdSXROGMUIaIxKGxrDu2mJ8/1/original",
        "mediaExcel": "https://api.algodocs.com/v1/media/niGNFZgpj655iThANTDhIgE3lQoSagCbsBkw0PRhzAo7DeanCToefGYGdd1pbYOC4udg8l9xBWiHr70HgAQQsXwmceSnn2FammDJAtOQjqdSXROGMUIaIxKGxrDu2mJ8/1/excel",
        "mediaJson": "https://api.algodocs.com/v1/media/niGNFZgpj655iThANTDhIgE3lQoSagCbsBkw0PRhzAo7DeanCToefGYGdd1pbYOC4udg8l9xBWiHr70HgAQQsXwmceSnn2FammDJAtOQjqdSXROGMUIaIxKGxrDu2mJ8/1/json",
        "mediaXml": "https://api.algodocs.com/v1/media/niGNFZgpj655iThANTDhIgE3lQoSagCbsBkw0PRhzAo7DeanCToefGYGdd1pbYOC4udg8l9xBWiHr70HgAQQsXwmceSnn2FammDJAtOQjqdSXROGMUIaIxKGxrDu2mJ8/1/xml",
        "totalPages": 1,
        "pageNumber": 1,
        "data":
            {
                "InvoiceNumber": "11223344",
                "Date": "2026-04-15",
                "Amount": 1250.0,
                ...
            }
    }
]

GET /v1/extracted_data/{extractor_id}

Get extracted data — many documents

Returns results for every document processed by an extractor. Filter and paginate with the optional query parameters below.

Query parameters

Param	Type	Description
`folderId`	string	Only return documents in this folder.
`date`	string	Only documents uploaded after this date.
`limit`	integer	Max records to return. Default 10,000.

Request

curl "https://api.algodocs.com/v1/\
extracted_data/EXTRACTOR_ID\
?folderId=078f5vn8ocoy&limit=50" \
-H "x-api-key: YOUR_API_KEY"

200 — Response


[
    {
        "id": "5fe627aabd5978699892bd36",
        "documentId": 182584,
        "uploadedAt": "2026-06-20T17:55:46Z",
        "processedAt": "2026-06-20T17:55:54Z",
        "fileName": "Invoice-3.pdf",
        "folderId": "fi4w58ws7d6a",
        "mediaOriginal": "https://api.algodocs.com/v1/media/ZpRcE5Jit37OHUvbXCfkZ2SRYRwuf6JLKDgTwV4guKEnMB6Tvw7IJ3Tw6AOn8OCXUWDDdceB8zqOY5EWkczjyBChkkmwGhHfHh3qx2gTS5aKdE8BvrCvPTYSUWTtpivq/1/original",
        "mediaExcel": "https://api.algodocs.com/v1/media/ZpRcE5Jit37OHUvbXCfkZ2SRYRwuf6JLKDgTwV4guKEnMB6Tvw7IJ3Tw6AOn8OCXUWDDdceB8zqOY5EWkczjyBChkkmwGhHfHh3qx2gTS5aKdE8BvrCvPTYSUWTtpivq/1/excel",
        "mediaJson": "https://api.algodocs.com/v1/media/ZpRcE5Jit37OHUvbXCfkZ2SRYRwuf6JLKDgTwV4guKEnMB6Tvw7IJ3Tw6AOn8OCXUWDDdceB8zqOY5EWkczjyBChkkmwGhHfHh3qx2gTS5aKdE8BvrCvPTYSUWTtpivq/1/json",
        "mediaXml": "https://api.algodocs.com/v1/media/ZpRcE5Jit37OHUvbXCfkZ2SRYRwuf6JLKDgTwV4guKEnMB6Tvw7IJ3Tw6AOn8OCXUWDDdceB8zqOY5EWkczjyBChkkmwGhHfHh3qx2gTS5aKdE8BvrCvPTYSUWTtpivq/1/xml",
        "totalPages": 1,
        "pageNumber": 1,
        "data":
            {
                "InvoiceNumber": "45872154",
                "Date": "2026-03-11",
                "Amount": 4750.0,
                ...
            }
    },
    {
        "id": "5fe7608abd59783e98438b3e",
        "documentId": 182608,
        "uploadedAt": "2026-06-20T16:10:21Z",
        "processedAt": "2026-06-20T16:10:50Z",
        "fileName": "Invoice.pdf",
        "folderId": "a8woh6w32rt4",
        "mediaOriginal": "https://api.algodocs.com/v1/media/niGNFZgpj655iThANTDhIgE3lQoSagCbsBkw0PRhzAo7DeanCToefGYGdd1pbYOC4udg8l9xBWiHr70HgAQQsXwmceSnn2FammDJAtOQjqdSXROGMUIaIxKGxrDu2mJ8/1/original",
        "mediaExcel": "https://api.algodocs.com/v1/media/niGNFZgpj655iThANTDhIgE3lQoSagCbsBkw0PRhzAo7DeanCToefGYGdd1pbYOC4udg8l9xBWiHr70HgAQQsXwmceSnn2FammDJAtOQjqdSXROGMUIaIxKGxrDu2mJ8/1/excel",
        "mediaJson": "https://api.algodocs.com/v1/media/niGNFZgpj655iThANTDhIgE3lQoSagCbsBkw0PRhzAo7DeanCToefGYGdd1pbYOC4udg8l9xBWiHr70HgAQQsXwmceSnn2FammDJAtOQjqdSXROGMUIaIxKGxrDu2mJ8/1/json",
        "mediaXml": "https://api.algodocs.com/v1/media/niGNFZgpj655iThANTDhIgE3lQoSagCbsBkw0PRhzAo7DeanCToefGYGdd1pbYOC4udg8l9xBWiHr70HgAQQsXwmceSnn2FammDJAtOQjqdSXROGMUIaIxKGxrDu2mJ8/1/xml",
        "totalPages": 1,
        "pageNumber": 1,
        "data":
            {
                "InvoiceNumber": "11223344",
                "Date": "2026-04-15",
                "Amount": 1250.0,
                ...
            }
    },
    ...
]

Turn any document into structured data.

Quickstart

Base URL & versioning

Client libraries

Python client

PHP client

Authentication

Basic authentication

Header parameters

API key header

Header parameters

How extraction works

Extractor

Folder

Document

Errors

Current user

Response fields

List extractors

Response fields

List folders

Response fields

Upload a local file

Path parameters

Body

Upload from a URL

Body

Upload base64

Body

Get extracted data — single document

Key response fields

Get extracted data — many documents

Query parameters