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

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.

Related

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