API Documentation

How the DocServant API works

DocServant uses a template-first approach to document extraction:

• Templates define the structure of extracted data
• Templates are created once in DocServant Studio
• The API processes documents against a template
• All processing is asynchronous
• Results are delivered via webhooks

Templates

Templates are the foundation of DocServant's extraction model. Every API request references a template ID.

What templates define

• The fields to extract from documents
• Data types and formats for each field
• How fields map to spreadsheet columns
• Validation rules and transformations

Creating templates

Templates are created and managed in DocServant Studio. Upload a sample document, define your columns, and the template is ready to use via the API.

Quick Start

The typical workflow for integrating DocServant:

Authentication

All API requests must include your API key in the Authorization header using the Bearer scheme.

Authorization: Bearer sk_live_your_api_key_here

Rate Limits

Rate limits are applied per API key and vary by plan. Exceeding your rate limit will result in a 429 Too Many Requests response. Check the X-RateLimit-Remaining header to monitor your usage.

Jobs

Jobs represent document processing requests. When you submit a document, a job is created and enters the processing queue. Jobs progress through these statuses:

• queued — Job is waiting to be processed
• processing — Document is being analyzed and data extracted
• completed — Extraction finished successfully
• failed — An error occurred during processing

Outputs

Completed jobs produce two output formats:

• JSON output — Structured data ideal for programmatic use
• XLSX output — Ready-to-use spreadsheet file

Both outputs are accessible via signed URLs that expire after 24 hours.

Endpoints

All endpoints are relative to the base URL:

https://api.docservant.com/v1

Submit a Job

{
  "jobId": "job_abc123def456",
  "status": "queued",
  "templateId": "tpl_xyz789",
  "createdAt": "2026-01-15T10:30:00Z"
}

cURL Example

curl -X POST https://api.docservant.com/v1/jobs \
  -H "Authorization: Bearer sk_live_your_api_key" \
  -F "templateId=tpl_xyz789" \
  -F "file=@invoice.pdf"

Get Job Status

{
  "jobId": "job_abc123def456",
  "status": "completed",
  "templateId": "tpl_xyz789",
  "createdAt": "2026-01-15T10:30:00Z",
  "completedAt": "2026-01-15T10:30:45Z",
  "outputs": {
    "jsonUrl": "https://storage.docservant.com/outputs/job_abc123.json?token=...",
    "xlsxUrl": "https://storage.docservant.com/outputs/job_abc123.xlsx?token=..."
  }
}

For failed jobs, the response includes an error field with details:

{
  "jobId": "job_abc123def456",
  "status": "failed",
  "error": {
    "code": "EXTRACTION_FAILED",
    "message": "Unable to extract data from document. The file may be corrupted or in an unsupported format."
  }
}

Webhooks

Why webhooks?

Document processing is asynchronous — extraction may take seconds to minutes depending on document complexity. Rather than polling the API, webhooks notify your server when jobs complete.

• Results may take time to generate
• Webhooks are the primary delivery mechanism
• Webhooks are sent for both success and failure states

Configure your webhook endpoint in the Developers section after signing in.

Events

• job.completed — Fired when a job finishes successfully
• job.failed — Fired when a job fails

Payload Example

{
  "event": "job.completed",
  "jobId": "job_abc123def456",
  "templateId": "tpl_xyz789",
  "status": "completed",
  "completedAt": "2026-01-15T10:30:45Z",
  "outputs": {
    "jsonUrl": "https://storage.docservant.com/outputs/job_abc123.json?token=...",
    "xlsxUrl": "https://storage.docservant.com/outputs/job_abc123.xlsx?token=..."
  }
}

For failed jobs:

{
  "event": "job.failed",
  "jobId": "job_abc123def456",
  "templateId": "tpl_xyz789",
  "status": "failed",
  "error": {
    "code": "EXTRACTION_FAILED",
    "message": "Unable to extract data from document."
  }
}

Webhook Security

All webhook requests are signed so you can verify they're from DocServant. Each request includes these headers:

X-DocServant-Signature: sha256=a1b2c3d4e5f6...
X-DocServant-Timestamp: 1705312245

To verify the signature, compute an HMAC-SHA256 of the timestamp and request body using your webhook secret, then compare it to the signature header. Reject requests with timestamps older than 5 minutes to prevent replay attacks.

Error Handling

Jobs may fail due to unreadable documents, invalid templates, or processing errors. Failed jobs return a webhook event with error details. Clients should handle retries where appropriate.

HTTP Status Codes

Rate Limits by Plan

Examples

Extract Invoices into JSON

Submit an invoice for extraction and fetch the structured JSON output:

# Submit the invoice
curl -X POST https://api.docservant.com/v1/jobs \
  -H "Authorization: Bearer sk_live_your_api_key" \
  -F "templateId=tpl_invoices" \
  -F "file=@invoice.pdf"

# Response: { "jobId": "job_abc123", "status": "queued" }

# Poll for completion (or use webhooks)
curl https://api.docservant.com/v1/jobs/job_abc123 \
  -H "Authorization: Bearer sk_live_your_api_key"

# When status is "completed", fetch the JSON output
curl "https://storage.docservant.com/outputs/job_abc123.json?token=..."

Bulk Upload and Append to Workbook

When you submit multiple documents with the same template, each job produces its own output files. To consolidate results, fetch individual JSON outputs and merge them in your application, or download each XLSX and combine sheets programmatically.

# Submit multiple documents
for file in invoices/*.pdf; do
  curl -X POST https://api.docservant.com/v1/jobs \
    -H "Authorization: Bearer sk_live_your_api_key" \
    -F "templateId=tpl_invoices" \
    -F "file=@$file"
done

Handle Webhook Callback (Node.js)

const express = require('express');
const crypto = require('crypto');

const app = express();
app.use(express.json());

app.post('/webhooks/docservant', (req, res) => {
  const signature = req.headers['x-docservant-signature'];
  const timestamp = req.headers['x-docservant-timestamp'];

  // Verify signature
  const payload = timestamp + '.' + JSON.stringify(req.body);
  const expected = 'sha256=' + crypto
    .createHmac('sha256', process.env.WEBHOOK_SECRET)
    .update(payload)
    .digest('hex');

  if (signature !== expected) {
    return res.status(401).send('Invalid signature');
  }

  // Process the event
  const { event, jobId, outputs } = req.body;

  if (event === 'job.completed') {
    console.log(`Job ${jobId} completed!`);
    // Fetch outputs.jsonUrl and process the data
  }

  res.status(200).send('OK');
});

Changelog