REST API

The DocView Capture REST API lets other systems send documents for capture. A client uploads one or more files, DocView Capture creates a batch, and the batch goes through the Batch Setup's workflow like any scanned or imported batch. The client can then ask for the batch's status.

All endpoints are under /api/v1 on your DocView Capture site, for example https://capture.contoso.com/api/v1. Always use HTTPS.

Endpoints

"Batch classes" is the technical name of Batch Setups, so the API uses it in paths and field names.

Authentication with an API key

Every request needs the header X-Api-Key with a valid key:

X-Api-Key: dvc_AbCdEfGh_...

Create a key

1. Sign in as a user with the permission Admin.ImportSources.
2. Go to Administration › Batch Settings › Import sources.
3. In the REST API keys card, type a name for the key, for example the name of the calling system.
4. Optionally, select the Batch Setups the key may use. Leave the selection empty to allow all Batch Setups.
5. Optionally, set an expiry date.
6. Click Create key and copy the key. It is shown only once.

Keys start with dvc_. DocView Capture stores only a salted hash of each key, so a lost key cannot be recovered. Create a new one and revoke the old one.

Click Revoke to stop a key at once. The list shows when each key was last used. Creating and revoking keys is recorded in the audit log.

Important: Treat an API key like a password. Keep it in your integration's secret store, never in source code, and use one key per calling system so you can revoke them separately.

Authentication errors

A request without the header, or with an unknown, revoked or expired key, receives 401 Unauthorized with the header WWW-Authenticate: ApiKey header="X-Api-Key".

List Batch Setups

GET /api/v1/batch-classes returns the Batch Setups that have a released version and that the key may use.

curl -H "X-Api-Key: $DOCVIEW_KEY" https://capture.contoso.com/api/v1/batch-classes

[
  {
    "id": "0f8fad5b-d9cb-469f-a165-70867728950e",
    "name": "Sample Invoices",
    "description": "Supplier invoices and credit notes"
  }
]

Create a batch

POST /api/v1/batches takes a multipart/form-data body:

Supported files are PDF, TIFF (single and multipage), JPEG and PNG. Files are recognised by their content. PDFs and multipage TIFFs are split into pages. Each file can be up to the Maximum upload size (MB) set on the Settings page (200 MB by default).

The batch is placed after the Scan step straight away, so automatic processing starts without an operator.

Example with curl

curl -X POST https://capture.contoso.com/api/v1/batches \
  -H "X-Api-Key: $DOCVIEW_KEY" \
  -F batchClass="Sample Invoices" \
  -F files=@invoice-1001.pdf \
  -F files=@invoice-1002.pdf \
  -F priority=3 \
  -F "metadata[sourceSystem]=ERP" \
  -F "fields[Reference]=PO-48213"

Response

On success the API answers 201 Created. The Location header and statusUrl point to the status endpoint.

{
  "id": "3b1f6c2e-8a4d-4f0e-9c61-2d7a5b9e0f14",
  "name": "Sample Invoices 2026-09-30 0007",
  "pages": 4,
  "documents": 2,
  "queue": "recognition",
  "statusUrl": "/api/v1/batches/3b1f6c2e-8a4d-4f0e-9c61-2d7a5b9e0f14"
}

queue is the workflow module the batch waits in (see the status values below). The example values are illustrative.

Example in C#

using System.Net.Http.Headers;

using var http = new HttpClient { BaseAddress = new Uri("https://capture.contoso.com/") };
http.DefaultRequestHeaders.Add("X-Api-Key", Environment.GetEnvironmentVariable("DOCVIEW_KEY"));

using var form = new MultipartFormDataContent();
form.Add(new StringContent("Sample Invoices"), "batchClass");

var file = new ByteArrayContent(await File.ReadAllBytesAsync("invoice-1001.pdf"));
file.Headers.ContentType = new MediaTypeHeaderValue("application/pdf");
form.Add(file, "files", "invoice-1001.pdf");

using var response = await http.PostAsync("api/v1/batches", form);
response.EnsureSuccessStatusCode();
Console.WriteLine(await response.Content.ReadAsStringAsync());

Example in JavaScript (Node.js 18 or later)

import { readFile } from 'node:fs/promises';

const form = new FormData();
form.append('batchClass', 'Sample Invoices');
form.append('files', new Blob([await readFile('invoice-1001.pdf')], { type: 'application/pdf' }), 'invoice-1001.pdf');

const response = await fetch('https://capture.contoso.com/api/v1/batches', {
  method: 'POST',
  headers: { 'X-Api-Key': process.env.DOCVIEW_KEY },
  body: form,
});
if (!response.ok) throw new Error(`${response.status}: ${await response.text()}`);
console.log(await response.json());

Get a batch's status

GET /api/v1/batches/{id} returns the batch, or 404 Not Found when it does not exist or the key may not use its Batch Setup.

curl -H "X-Api-Key: $DOCVIEW_KEY" \
  https://capture.contoso.com/api/v1/batches/3b1f6c2e-8a4d-4f0e-9c61-2d7a5b9e0f14

{
  "id": "3b1f6c2e-8a4d-4f0e-9c61-2d7a5b9e0f14",
  "name": "Sample Invoices 2026-09-30 0007",
  "batchClass": "Sample Invoices",
  "queue": "export",
  "state": "Completed",
  "priority": 3,
  "pages": 4,
  "documents": 2,
  "error": null,
  "createdAt": "2026-09-30T09:12:44.512+00:00",
  "completedAt": "2026-09-30T09:13:21.087+00:00"
}

Status values

state is one of:

queue is the module key: scan, qc, recognition, classification-review, extraction, correction, index, verify or export.

Tip: Poll the status no more than every few seconds, and stop when state is Completed or Error. Store the batch id in your system so you can find the batch later in the Batch Manager.

Errors

Errors use the standard problem details format (application/problem+json). The detail property holds the message. A shortened example:

{
  "status": 422,
  "detail": "'scan.docx' is not a supported file. Use PDF, TIFF, JPEG or PNG."
}

Limits

• Rate limit: 600 requests per minute per client IP address by default. Administrators change it with RateLimits:ApiPerMinute. See the configuration reference.
• File size: the Maximum upload size (MB) setting applies to each file. A whole request can be up to 1 GB.
• A proxy or firewall in front of the server may have lower limits.

Health endpoints

For monitoring, two endpoints need no key:

Note: The path /api/v1/scan-sessions is used by the Scan Agent to upload scanned pages. It is not meant for integrations.

Related pages

• Import sources
• Importing documents
• Output and export
• Configuration reference