API Reference

Integrate document extraction into your applications with the Veontra REST API v1.

Base URL: https://api.veontra.com/api/v1

Introduction

The Veontra API lets you upload documents, track processing status, export extracted data, and receive real-time webhook notifications.

All endpoints are JSON over HTTPS unless noted otherwise. Create an API key on the Developer page before making requests.

API version: v1
Content type: application/json (multipart/form-data for uploads)
Organization-scoped: each key belongs to one organization

Authentication

Include your API key as a Bearer token in the Authorization header on every request.

Authorization

Authorization: Bearer YOUR_API_KEY

Keys are created in Developer → API keys. Revoked keys return 401 Unauthorized.

GEThttps://api.veontra.com/api/v1/usage

Get usage

Returns billing usage and quota for the organization tied to the API key.

-cmd">curl -X GET "https://api.veontra.com/api/v1/usage" \
  -H "Authorization: Bearer YOUR_API_KEY"

Returns the same usage object as the in-app billing page (pages processed, limits, plan status).

POSThttps://api.veontra.com/api/v1/documents

Upload documents

Upload one or more files for extraction. Processing runs asynchronously; use webhooks or poll document status.

Field	Type	Description
files	file[]	Required. Up to 10 files per request (PDF, PNG, JPG).
document_type	string	Optional. Document type slug (e.g. invoice, receipt).
field_schema	string	Optional. JSON string with custom field definitions. Overrides the template schema when both are sent.
document_language	auto \| en \| ru \| hy \| es \| de \| fr	Optional. Language hint for OCR and extraction: auto, en, ru, hy, es, de, fr. If omitted, defaults to auto (automatic detection).
field_template_id	integer	Optional. ID of a saved field template. When set without field_schema, the template schema, highlighting, and quality are applied.
field_highlighting	boolean	Optional. true/false. Enables field source highlighting. Defaults from the template when field_template_id is set, otherwise false.
extraction_quality	standard \| high	Optional. standard or high. Defaults from the template when field_template_id is set, otherwise standard.

Example: upload one invoice

Send multipart/form-data. Only files is required; Veontra starts processing asynchronously and returns 202 Accepted.

POST https://api.veontra.com/api/v1/documents

Authorization: Bearer YOUR_API_KEY
Content-Type: multipart/form-data

files — required — your PDF or image (field name must be files)
document_type — receipt
document_language — en

Example — minimal request

-comment"># Minimal example — one invoice PDF, language auto-detected
-cmd">curl -X POST "https://api.veontra.com/api/v1/documents" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -F "files=@/path/to/invoice.pdf" \
  -F "document_type=invoice"

Example — with explicit language

-comment"># Same request with an explicit document language
-cmd">curl -X POST "https://api.veontra.com/api/v1/documents" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -F "files=@/path/to/invoice.pdf" \
  -F "document_type=invoice" \
  -F "document_language=ru"

Example response

response.http

HTTP/1.1 202 Accepted
Content-Type: application/json

{
  "accepted": 1,
  "billing_units": 2,
  "documents": [
    {
      "id": 42,
      "file_name": "invoice.pdf",
      "mime_type": "application/pdf",
      "page_count": 2,
      "field_highlighting": false,
      "extraction_quality": "standard",
      "credit_cost": 2,
      "document_type": "invoice",
      "document_language": "auto",
      "field_schema": { "fields": [] },
      "field_template_id": null,
      "status": "pending",
      "error_message": null,
      "created_at": "2026-06-12T12:00:00.000Z",
      "updated_at": "2026-06-12T12:00:00.000Z"
    }
  ]
}

document_language is optional. Omit it or pass auto for automatic language detection.

Returns 202 Accepted with an array of created document objects.

Next: wait for webhook document.completed or poll GET /documents/. When status is needs_review, approve with POST /documents//approve, then export.

GEThttps://api.veontra.com/api/v1/documents

List documents

Paginated list of documents for your organization.

processing

-cmd">curl -X GET "https://api.veontra.com/api/v1/documents?page=1&limit=20&status=approved" \
  -H "Authorization: Bearer YOUR_API_KEY"

GEThttps://api.veontra.com/api/v1/documents/{id}

Get document

Returns a single document with extracted fields and processing status.

-cmd">curl -X GET "https://api.veontra.com/api/v1/documents/123" \
  -H "Authorization: Bearer YOUR_API_KEY"

POSThttps://api.veontra.com/api/v1/documents/{id}/approve

Approve document

Marks a document in needs_review as approved so it can be exported.

-cmd">curl -X POST "https://api.veontra.com/api/v1/documents/123/approve" \
  -H "Authorization: Bearer YOUR_API_KEY"

Returns the updated document detail. Only documents with status needs_review can be approved.

GEThttps://api.veontra.com/api/v1/documents/{id}/export

Export document

Download extracted data for an approved document as a file attachment.

Query param format: csv, json, or xlsx.

-cmd">curl -X GET "https://api.veontra.com/api/v1/documents/123/export?format=csv" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  --output document.csv

DELETEhttps://api.veontra.com/api/v1/documents/{id}

Delete document

Permanently deletes a document and its extracted data.

-cmd">curl -X DELETE "https://api.veontra.com/api/v1/documents/123" \
  -H "Authorization: Bearer YOUR_API_KEY"

Returns 204 No Content on success.

Webhooks

Configure webhook endpoints on the Developer page to receive HTTP POST callbacks when document status changes.

document.completed — extraction finished, ready for review (status needs_review)
document.approved — document approved
document.failed — processing failed

Each request includes an X-Veontra-Signature header with an HMAC-SHA256 hex digest of the raw JSON body, prefixed with sha256=.

Webhook header

X-Veontra-Signature: sha256=<hex_hmac_sha256_of_raw_body>

Example payload:

payload.json

{
  "event": "document.completed",
  "document_id": 123,
  "status": "needs_review",
  "error_message": null,
  "occurred_at": "2026-06-11T12: 00: 00.000Z"
}

Create and manage webhooks on the Developer page.

Errors

Errors return a JSON body with statusCode and message. Common HTTP status codes:

Code	Meaning
401	Missing or invalid API key.
402	Quota exceeded or paid plan required.
404	Resource not found.
422	Invalid request parameters or body.