Skip to main content

Submit for Processing

Upload a document to POST /v1/process against a named processing configuration and receive results via webhook. Idempotent per (config, batch, file).

The Submit for Processing endpoint, POST /v1/process, is the named-operations front door of the Talonic API: upload a document, name the processing configuration to run it through, and get results delivered asynchronously via the process.completed webhook. It always returns immediately (202 Accepted) with a run_id and a poll_url, so you never block on the pipeline.

Idempotency is automatic. The same (config_id, batch_id, file) combination returns the existing run instead of re-processing, so a retried upload is safe. If batch_id is absent, dedup applies within a 24-hour window. This makes the endpoint robust for at-least-once delivery from upstream systems.

This surface uses the operations scope. Configure the processing configurations (and discover their IDs) with GET /v1/configs.
Building a new integration? Start with POST /v1/pipelines instead: it runs the same engine with full per-stage configuration and the governed review flow, and it is where new capabilities land. /v1/process remains fully supported for existing named-configuration integrations, but a deprecation marker for it is planned.
POST/v1/process

Multipart form fields

config_id*stringProcessing configuration ID (from GET /v1/configs).
file*fileDocument to process. Max 500 MB.
batch_idstringOptional batch identifier. Enables permanent dedup for this (config, batch, file) triple.
metadatastringOptional JSON string with additional metadata.

curl

curl -s -X POST https://api.talonic.com/v1/process \
  -H "Authorization: Bearer tlnc_your_api_key" \
  -F "config_id=cfg_bridgeway_invoice_v1" \
  -F "batch_id=BW-2026-0512-001" \
  -F "file=@invoice-0847.pdf"

Response

Response fields (202)

request_idstringIdentifier for this submission.
run_idstringThe run UUID to poll.
config_idstringThe configuration used.
batch_idstringThe batch identifier, when one was provided.
statusstringAlways processing on acceptance.
poll_urlstringURL to poll for the run result.

Response (202)

{
  "request_id": "req_9f8e7d6c",
  "run_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "config_id": "cfg_bridgeway_invoice_v1",
  "batch_id": "BW-2026-0512-001",
  "status": "processing",
  "poll_url": "/v1/runs/a1b2c3d4-e5f6-7890-abcd-ef1234567890"
}
A 200 (instead of 202) means an idempotency hit: the existing run result is returned without re-processing.

Errors

Error responses

400validation_errorMissing required field (config_id or file).
401unauthorizedMissing or invalid API key.
402insufficient_creditsYour credit balance is too low to run this configuration.
404not_foundConfig ID not found or inactive.

Frequently asked questions

How is idempotency handled?+
The same (config_id, batch_id, file) combination returns the existing run rather than re-processing, so retried uploads are safe. Without batch_id, deduplication applies within a 24-hour window.
How do I get processing results?+
Results are delivered via the process.completed webhook, or poll the run via the poll_url returned on submission (GET /v1/runs/:id). The run response carries the markdown, structured data, and reconciliation output once complete.
What is the maximum file size for /v1/process?+
A single document upload can be up to 500 MB. The file is sent as multipart form data under the field name file, together with the required config_id.
What happens if I run out of credits?+
The submission is rejected with a 402 insufficient credits error and no run is created. Top up your balance or enable auto top-up in billing settings, then resubmit.
Should a new integration use /v1/process or /v1/pipelines?+
Prefer POST /v1/pipelines for new integrations: it runs the same engine with full per-stage configuration and the governed review flow. /v1/process stays supported for existing named-configuration integrations, but a deprecation marker for it is planned.

Related

Get Run
List Configs
Credits & Usage
Run a Pipeline (preferred for new integrations)