DocuClipper logo

Getting started

Get structured data from bank statements, invoices, and tax forms in minutes. New integrations should use the Agent API (/agent/*): PAT auth, direct-to-S3 upload, clean JSON output.

Start free trialAuthentication →For AI agents →

60-second quickstart (free test key)

Try every read endpoint end to end before you spend a page. A test key (dcp_test_…) works without limits on our sample bank statements and returns each sample's finished result at once.

  1. Create an API account at docuclipper.com/signup/?product=api then create a test key in your DocuClipper developer console.
  2. List the samples with GET /agent/sandbox/samples.
  3. Create a job on a sample with POST /agent/jobs. It is finished when the call returns.
  4. Read the transactions and the verdict with GET /agent/documents/<id>/transactions.
bash
BASE=https://www.docuclipper.com/api/v1
AUTH="Authorization: Bearer dcp_test_..."   # your test key

# 1. List the sample bank statements (documentId, name, pages)
curl -s "$BASE/agent/sandbox/samples" -H "$AUTH" | jq
DOC_ID=$(curl -s "$BASE/agent/sandbox/samples" -H "$AUTH" \
  | jq -r '.samples[0].documentId')

# 2. Create a job on that sample: it comes back finished, no pages used
curl -s -X POST "$BASE/agent/jobs" -H "$AUTH" \
  -H "Content-Type: application/json" -d "{\"documents\":[$DOC_ID]}" | jq

# 3. Read the transactions and the verification verdict
curl -s "$BASE/agent/documents/$DOC_ID/transactions" -H "$AUTH" \
  | jq '{verdict: .verification.status, count, first: .transactions[0]}'

verification.status is verified, needs_review (with the periods, pages and difference to check) or unverifiable (with the reason). See Verification. /agent/documents/<id> and /agent/documents/<id>/data work on samples too. Uploads are refused with a test key.

Going live

Add a card in your developer console to get 50 free live pages, and create a live key (dcp_…). Swap the key, then upload your own statement instead of picking a sample:

bash
AUTH="Authorization: Bearer dcp_..."   # your live key
JSON="Content-Type: application/json"

# 1. Get an upload URL, then PUT the PDF to it
RESP=$(curl -s -X POST "$BASE/agent/documents/upload-url" \
  -H "$AUTH" -H "$JSON" -d '{"filename":"jan.pdf","mimetype":"application/pdf"}')
DOC_ID=$(echo "$RESP" | jq -r .document.id)
curl -s -X PUT "$(echo "$RESP" | jq -r .url)" \
  -H "Content-Type: application/pdf" --data-binary @jan.pdf

# 2. Create the job and wait for it (use a webhook in production)
JOB_ID=$(curl -s -X POST "$BASE/agent/jobs" -H "$AUTH" -H "$JSON" \
  -d "{\"documents\":[$DOC_ID]}" | jq -r .jobId)
while :; do
  S=$(curl -s "$BASE/agent/jobs/$JOB_ID?waitSeconds=40" -H "$AUTH" | jq -r .status)
  [ "$S" = "Succeeded" ] && break
  [ "$S" = "Failed" ] || [ "$S" = "OutOfCredits" ] && exit 1
done

# 3. Same read as the sandbox
curl -s "$BASE/agent/documents/$DOC_ID/transactions" -H "$AUTH" \
  | jq .verification.status

After the free pages, the API plan is $199/month with 2,000 pages included and $0.10 per page after that. Already on a DocuClipper web plan? Your plan includes API access: generate a key in Account → API and use the steps below.

Quick start (5 steps)

  1. Generate a PAT in Account → API. Tokens look like dcp_… and are shown once.
  2. Subscribe to job-completion events (one-time setup) – POST /api/v1/agent/webhooks with { url, events: ["bank_statement.extraction.completed"] }. Store the signing secret returned once; you'll use it to verify each event. Skip this in dev and use polling (step 5), but for production, webhooks are how you avoid hammering /jobs/<id>.
  3. Upload – get a presigned URL via POST /api/v1/agent/documents/upload-url with { filename, mimetype }, then PUT the file bytes directly to the returned URL. Keeps large uploads off our servers.
  4. Create the job – POST /api/v1/agent/jobs with { documents: [<docId>] } (bank-mode + v2 are defaults).
  5. Receive the result – your webhook fires when the job hits Succeeded; fetch GET /api/v1/agent/jobs/<id>/data to get the structured payload (or /transactions for the flat per-row view). Dev only: if you skipped step 2, poll GET /api/v1/agent/jobs/<id> until status === "Succeeded".

First request (cURL)

bash
curl -X POST "https://www.docuclipper.com/api/v1/agent/documents/upload-url" \
  -H "Authorization: Bearer dcp_..." \
  -H "Content-Type: application/json" \
  -d '{"filename":"statement.pdf","mimetype":"application/pdf"}'

Response: { url: "<presigned PUT URL>", document: { id, s3Key, s3Path } }. PUT the file to url with Content-Type: application/pdf, then use document.id when you POST /agent/jobs.

Already on the legacy /protected/* API?

It's fully supported, keep using POST /protected/document (multipart), POST /protected/job, and POST /protected/job/<id>/export. See Bank Statement OCR API for the legacy flow. The Agent API is the recommended path for new integrations.

Document type APIs

Format conversion APIs

Next steps

  • OCR API hub — overview of every document type and export format.
  • Authentication – PAT setup, where they work, and verifying your token.
  • For AI agents – end-to-end cURL example, MCP tool dispatch, OpenAPI spec.
  • MCP server – add DocuClipper to ChatGPT, Claude or any MCP client as a remote connector: statements with reconciliation, invoices and fraud reports.
  • Webhooks – avoid polling.