Mahad OCR API reference

Create a key in the dashboard (app.mahadocr.com → API keys) after verifying your email address and phone number. Keys start with mk_live_, are shown once and stored only as a SHA-256 hash. Send the key in the X-MahadDoc-API-Key header on every request. Dashboard sessions use Authorization: Bearer <token> instead.

Keep keys on your server. Never put a key in browser JavaScript, a mobile app or a public repository; disable a key at once if it leaks.

curl https://api.mahadocr.com/v1/documents -H "X-MahadDoc-API-Key: mk_live_YOUR_KEY"

POST /v1/documents/upload — multipart/form-data. Returns 202 Accepted with the document; reading happens in the background. Uploading the exact same file again is recognised (cached: true).

curl -X POST https://api.mahadocr.com/v1/documents/upload \
  -H "X-MahadDoc-API-Key: mk_live_YOUR_KEY" \
  -F "[email protected]" -F "doc_type=passport"

HTTP/1.1 202 Accepted
{
  "id": "DOC_3f9a1c7e2b40", "name": "passport.jpg", "type": "Passport",
  "status": "processing", "cached": false, "uploaded_at": "2026-09-30T08:15:02",
  "outcome": { "status": "pending", "code": null, "message": "Processing.",
               "next_action": { "type": "WAIT", "message": "Check back shortly." }, "context": {} }
}

Batch

POST /v1/documents/batch — field files repeated, up to 20 files (more → 413 too_many_files). Your plan quota is checked for the whole batch first. Each item is either a document or { "filename", "error" } (unsupported_file, file_too_large); the response is { "items": [...], "queued": n }.

GET /v1/documents/{id} returns the document with a result object. Poll every few seconds until result.status is no longer processing.

Top-level keys: id, tenant_id, name, type, status, cached, uploaded_at, outcome, doc_type, fields, raw_json, engine, result, plus two legacy numeric keys (confidence, tamper_score) kept for older integrations. Build on result; raw_json is the engine’s internal record and may change.

List documents: GET /v1/documents?status=&type=&q=&page=1&page_size=25 (page_size at most 100) → { items, page, page_size, total }.

The document’s outcome is { status, code, message, next_action, context }. status is verified, action_required (→ document status review), rescan_required (→ review, decision rescan) or failed. Codes:

A person resolves a document with POST /v1/documents/{id}/approve (with corrected fields) or /reject; /rescan reads the stored original again without charging again.

JSON is always returned. Ask for more with outputs=xlsx (and pdf, docx) at upload. Available links appear in result.outputs:

pdf and docx exist for CVs today; for other document types they are listed under outputs.unavailable.

Signed webhook endpoints (v2 jobs)

Create an endpoint with POST /v2/webhooks { "url": "https://…", "events": [...] }. The response includes the endpoint’s own signing secret (whsec_…) — shown once. Events fire for documents uploaded to a job (POST /v2/jobs, then POST /v2/jobs/{id}/inputs).

POST https://your-server.example/hooks/mahad
Content-Type: application/json
X-Mahad-Event: job.finished
X-Mahad-Delivery: <delivery id>
X-Mahad-Signature: t=1790000000,v1=5f0c…

{"id":"evt_9c1e…","event":"job.finished","data":{"job_id":"…","entity_id":"…",
 "decision_id":"…","status":"verified","code":null,"state_version":1},"created":"2026-09-30T08:15:09+00:00"}

Reply with any 2xx. Failed deliveries are retried after 30 s, 2 min, 10 min, 30 min and 2 h (6 attempts), then marked dead. See every attempt with GET /v2/webhooks/{id}/deliveries. Destinations on internal networks are refused, and redirects are not followed.

Verify the signature — Python

import hashlib, hmac, time

def verify_mahad_webhook(secret: str, signature_header: str, raw_body: bytes,
                         tolerance_s: int = 300) -> bool:
    """X-Mahad-Signature: t=<unix>,v1=<hex HMAC-SHA256 of '<t>.<raw body>'>"""
    parts = dict(p.split("=", 1) for p in signature_header.split(","))
    t, received = parts.get("t", ""), parts.get("v1", "")
    if not t.isdigit() or abs(time.time() - int(t)) > tolerance_s:
        return False                                   # too old: possible replay
    expected = hmac.new(secret.encode(), f"{t}.".encode() + raw_body,
                        hashlib.sha256).hexdigest()
    return hmac.compare_digest(expected, received)

# Flask example — use the RAW body, not re-serialised JSON
# ok = verify_mahad_webhook(WHSEC, request.headers["X-Mahad-Signature"], request.get_data())

Verify the signature — Node

const crypto = require('crypto');

// X-Mahad-Signature: t=<unix>,v1=<hex HMAC-SHA256 of '<t>.<raw body>'>
function verifyMahadWebhook(secret, signatureHeader, rawBody, toleranceS = 300) {
  const parts = Object.fromEntries(signatureHeader.split(',').map((p) => p.split('=')));
  const t = Number(parts.t);
  if (!t || Math.abs(Date.now() / 1000 - t) > toleranceS) return false; // possible replay
  const expected = crypto.createHmac('sha256', secret)
    .update(`${parts.t}.`).update(rawBody).digest('hex');
  const a = Buffer.from(expected), b = Buffer.from(parts.v1 || '');
  return a.length === b.length && crypto.timingSafeEqual(a, b);
}

// Express: app.post('/hooks/mahad', express.raw({ type: 'application/json' }), (req, res) => {
//   if (!verifyMahadWebhook(process.env.MAHAD_WHSEC, req.get('X-Mahad-Signature'), req.body))
//     return res.sendStatus(400);
//   const event = JSON.parse(req.body); res.sendStatus(200);
// });

Dashboard webhook (v1 uploads)

A webhook URL set in the dashboard receives document.processed when a document uploaded with /v1/documents/upload finishes: { "event": "document.processed", "data": { "document_id", "status", "doc_type", … } } with headers X-MahadDoc-Event and X-MahadDoc-Signature: sha256=<hex>. It also carries X-Mahad-Signature: t=<unix>,v1=<hex>, signed exactly like the v2 webhooks above with your account's own secret — get it with GET /v2/webhooks/v1-secret and verify with the same code. The older X-MahadDoc-Signature header is still sent unchanged but is made with a service key you do not hold, so verify X-Mahad-Signature instead.

Every error has one shape, and every response carries an X-Request-ID header — quote it to support.

{
  "error": {
    "code": "file_too_large",
    "message": "File exceeds the 10 MB limit",
    "request_id": "8e1f…",
    "next_action": { "type": "SMALLER_FILE", "message": "Send a smaller file." }
  }
}

curl

curl -X POST https://api.mahadocr.com/v1/documents/upload -H "X-MahadDoc-API-Key: mk_live_YOUR_KEY" -F "[email protected]" -F "outputs=xlsx"
curl https://api.mahadocr.com/v1/documents/DOC_3f9a1c7e2b40 -H "X-MahadDoc-API-Key: mk_live_YOUR_KEY"
curl https://api.mahadocr.com/v1/documents/DOC_3f9a1c7e2b40/outputs/xlsx -H "X-MahadDoc-API-Key: mk_live_YOUR_KEY" -o invoice.xlsx

Python

import time, requests

API = "https://api.mahadocr.com/v1"
HEADERS = {"X-MahadDoc-API-Key": "mk_live_YOUR_KEY"}   # read from your server's secret store

with open("passport.jpg", "rb") as f:
    r = requests.post(f"{API}/documents/upload", headers=HEADERS,
                      files={"file": f}, data={"doc_type": "passport"})
r.raise_for_status()                          # 202
doc_id = r.json()["id"]

while True:
    doc = requests.get(f"{API}/documents/{doc_id}", headers=HEADERS).json()
    if doc["result"]["status"] != "processing":
        break
    time.sleep(2)

result = doc["result"]
print(result["decision"], result["values"])
for row in result["field_review"]["fields"]:
    if row["state"] != "ok":
        print("check:", row["label"], row["reason"])

Node

// Node 18+ (global fetch, FormData, Blob)
const fs = require('fs');
const API = 'https://api.mahadocr.com/v1';
const HEADERS = { 'X-MahadDoc-API-Key': process.env.MAHAD_API_KEY };

async function read(path) {
  const form = new FormData();
  form.append('file', new Blob([fs.readFileSync(path)]), 'passport.jpg');
  const up = await fetch(`${API}/documents/upload`, { method: 'POST', headers: HEADERS, body: form });
  if (up.status !== 202) throw new Error((await up.json()).error.code);
  const { id } = await up.json();
  for (;;) {
    const doc = await (await fetch(`${API}/documents/${id}`, { headers: HEADERS })).json();
    if (doc.result.status !== 'processing') return doc.result;
    await new Promise((r) => setTimeout(r, 2000));
  }
}

read('passport.jpg').then((r) => console.log(r.decision, r.values));

• Get an API key →
• Developer overview →
• OCR use cases →
• ID card OCR →
• PDF to structured data →
• Passport OCR →
• Invoice OCR →
• Interactive API docs →