Responses

How the Talonic extract endpoint responds: synchronous 200 with data and confidence scores for small documents, 202 Accepted with a poll URL for large ones.

The quick extract endpoint, POST /v1/extract, responds in one of two processing modes: documents of 5 pages or fewer return a synchronous 200 OK with the extracted data and confidence scores in the same response, while larger documents (or any request with options: {"async": true}) return 202 Accepted with a poll_url. Your client should branch on the HTTP status to handle both.

Synchronous (200 OK)

Returned for small documents when async is not forced. The response blocks until extraction is complete and carries the full extraction envelope: extraction_id, data, per-field confidence, and processing metadata.

{
  "extraction_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "request_id": "req_b2c3d4e5f6a78901",
  "status": "complete",
  "document": {
    "id": "c3d4e5f6-a7b8-9012-cdef-123456789012",
    "filename": "invoice-0847.pdf",
    "pages": 2,
    "type_detected": "invoice",
    "language_detected": "en"
  },
  "data": {
    "vendor_name": "Acme Corp",
    "invoice_number": "INV-2024-0847",
    "total_amount": 14250.00,
    "due_date": "2024-03-15"
  },
  "confidence": {
    "overall": 0.94,
    "fields": {
      "vendor_name": 0.99,
      "invoice_number": 0.98,
      "total_amount": 0.96,
      "due_date": 0.91
    }
  },
  "processing": {
    "duration_ms": 3420,
    "pages_processed": 2,
    "region": "eu-west"
  }
}

Asynchronous (202 Accepted)

Returned when the document exceeds 5 pages or options: {"async": true} is set. Poll GET /v1/documents/:id (the poll_url) until status transitions to completed, then fetch results from GET /v1/documents/:id/extractions.

{
  "request_id": "req_b2c3d4e5f6a78901",
  "status": "processing",
  "document": {
    "id": "c3d4e5f6-a7b8-9012-cdef-123456789012",
    "filename": "large-report.pdf",
    "pages": 42,
    "size_bytes": 8912640
  },
  "poll_url": "/v1/documents/c3d4e5f6-a7b8-9012-cdef-123456789012",
  "estimated_seconds": 63
}

Recommended polling: start at 2 seconds and back off exponentially (2s, 4s, 8s, 16s, capped at 30s), timing out after 5 minutes. To avoid polling entirely, configure a webhook destination and listen for extraction.complete events (see [Webhook Events](webhook-events)).