Quickstart

Upload your first invoice and receive a webhook notification in under 10 minutes.

1. Get an API key

Go to Settings → API Keys in the Parseo dashboard and create a new key. Choose the scopes you need:

Scope	Grants
`invoice:read`	Read invoice data
`invoice:write`	Upload invoices
`invoice:export`	Export invoices in an accounting-system format
`webhook:read`	List and inspect webhook endpoints
`webhook:manage`	Create, update, delete, and test webhook endpoints

Store your key securely — it is shown only once.

2. Upload an invoice

curl -X POST https://app.parseo.app/external/v1/invoices \
  -H "Authorization: Bearer parseo_live_..." \
  -H "X-Client-Id: <your-client-id>" \
  -H "Idempotency-Key: $(uuidgen)" \
  -F "file=@invoice.pdf"

The API returns 202 Accepted immediately with a processing job — the invoice itself is created only after OCR succeeds.

{
  "jobId": "job_abc123",
  "status": "processing"
}

Uploading several files at once? Use POST /invoices/batch — up to 10 files per request. Each result item carries its own jobId.

3. Poll the job

curl https://app.parseo.app/external/v1/jobs/job_abc123 \
  -H "Authorization: Bearer parseo_live_..."

The status field transitions: processing → completed (with invoiceId populated) or failed (with an error object). On completed, the invoiceId is the inv_... you pass to the invoice endpoints.

{
  "id": "job_abc123",
  "status": "completed",
  "sourceFile": "invoice.pdf",
  "clientId": "cl_xyz",
  "invoiceId": "inv_abc123",
  "error": null,
  "createdAt": "2026-04-24T10:15:30.000Z",
  "updatedAt": "2026-04-24T10:15:34.000Z"
}

4. Retrieve structured data

Once the job reports completed, fetch the invoice by the invoiceId returned above:

curl https://app.parseo.app/external/v1/invoices/inv_abc123 \
  -H "Authorization: Bearer parseo_live_..."

Or pull an export:

curl https://app.parseo.app/external/v1/invoices/inv_abc123/export?format=json \
  -H "Authorization: Bearer parseo_live_..."

5. Set up a webhook (recommended)

Instead of polling, subscribe to invoice.processed events to be notified the moment processing finishes:

curl -X POST https://app.parseo.app/external/v1/webhooks \
  -H "Authorization: Bearer parseo_live_..." \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://your-server.example.com/webhooks/parseo",
    "events": ["invoice.processed"]
  }'

Save the secret from the response — you will need it to verify webhook signatures.

See Webhooks Overview for the full event catalogue and payload schema.