API Reference

InvoiceParser Pro API

REST API for invoice data extraction. Upload a document, receive structured vendor/total/line-item data, download Excel or CSV, or push results to your systems via webhooks.

v1 · StableBase URL: api.invoiceparserpro.com/api/v1

Introduction

The InvoiceParser Pro API lets you extract structured data from PDF and image invoices at scale. Upload a file, receive a job ID, and poll for the completed result — or register a webhook and let us push the result to you.

All endpoints are under https://api.invoiceparserpro.com/api/v1. Responses are JSON. Errors always include a machine-readable code field.

Authentication

Pass your API key as a Bearer token in every request. Keys are created and managed from the API Access page. The raw key value is shown once at creation — store it securely.

Header

Authorization: Bearer ipp_live_xxxx_xxxxxxxxxxxxxxxxxxxxxxxx

Keys scoped to a single account. All requests are logged against the key that issued them.

Quick start

Upload an invoice and retrieve the structured result in two requests.

1 · Upload

cURL

curl -X POST "https://api.invoiceparserpro.com/api/v1/invoices" \
  -H "Authorization: Bearer ipp_live_xxxx_xxxxxxxxxxxxxxxx" \
  -F "file=@invoice.pdf"

2 · Poll until completed

cURL

curl "https://api.invoiceparserpro.com/api/v1/invoices/{job_id}" \
  -H "Authorization: Bearer ipp_live_xxxx_xxxxxxxxxxxxxxxx"

Python example

Python

import time, requests

KEY = "ipp_live_xxxx_xxxxxxxxxxxxxxxx"
BASE = "https://api.invoiceparserpro.com/api/v1"
HEADERS = {"Authorization": f"Bearer {KEY}"}

# Upload
with open("invoice.pdf", "rb") as f:
    job = requests.post(f"{BASE}/invoices", headers=HEADERS,
                        files={"file": f}).json()

# Poll
while True:
    result = requests.get(f"{BASE}/invoices/{job['job_id']}",
                          headers=HEADERS).json()
    if result["status"] == "completed":
        print(result["result"])
        break
    time.sleep(2)

Rate limits

Limits are applied per API key. Exceeding a limit returns 429 Too Many Requests.

EndpointLimit

POST /api/v1/invoices60 req / min / key

POST /api/v1/batches10 req / min / key

GET /api/v1/*120 req / min / key

POST /api/v1/webhooks20 req / min / key

Errors

Every error response includes a machine-readable code field and a human-readable message.

CodeHTTPDescription

INVALID_API_KEY401Invalid, revoked, or missing API key.

TIER_REQUIRED403Business-tier subscription required.

INSUFFICIENT_CREDITS402Not enough credits on the account.

INVALID_FILE400Unsupported format, too large, or corrupt.

JOB_NOT_FOUND404Job not found or belongs to another account.

EXTRACTION_FAILED422Document could not be parsed.

RATE_LIMITED429Too many requests — back off and retry.

Error shape

{
  "success": false,
  "error": {
    "code": "INSUFFICIENT_CREDITS",
    "message": "You have 0 credits remaining. Add credits to continue.",
    "http_status": 402
  }
}

Invoices

Upload invoices for extraction, poll job status, list jobs, and download structured Excel or CSV output.

POST/api/v1/invoices

API key

Upload and process an invoice

Upload a PDF or image, extract vendor, totals, line items, and validation metadata. Returns a job_id that can be polled with the job retrieval endpoint. Runs synchronously when the background queue is disabled; otherwise returns 202 Accepted and processes asynchronously.

Rate limit: 60 requests / minute / API key

Parameters

ParameterTypeDescription

fileformrequired
file (pdf, png, jpg, jpeg, webp)
The invoice document. Single file per request. Max size enforced by server-side validation (typical limit: 10 MB).
export_modeformoptional
string
Default: standard
Column set used for the generated Excel and CSV. Accepts `standard` (core AP fields) or `full` (every extracted field, including raw line item metadata).
include_bounding_boxesformoptional
boolean
Default: false
When `true`, includes a `field_locations` object in the result containing Azure Document Intelligence polygon coordinates for each extracted field. Useful for building UI overlays or verifying extraction position on the source document.
external_idformoptional
string
Caller-supplied idempotency key. If a job already exists with the same `external_id` for your account, the existing job is returned and no credit is charged. Scoped to your account — different API key holders may reuse the same string. Recommended for safe 5xx retries in production pipelines.
Authorizationheaderrequired
string
Bearer token in the form `Bearer ipp_live_...`.

Request

cURL

curl -X POST "https://api.invoiceparserpro.com/api/v1/invoices" \
  -H "Authorization: Bearer ipp_live_xxxx_xxxxxxxxxxxxxxxx" \
  -F "file=@invoice.pdf" \
  -F "export_mode=standard" \
  -F "external_id=my-pipeline-run-1234" \
  -F "include_bounding_boxes=false"

Response

202 Accepted

{
  "success": true,
  "job_id": "550e8400-e29b-41d4-a716-446655440000",
  "status": "processing",
  "message": "Invoice queued for processing. Use GET /api/v1/invoices/{job_id} to check status and retrieve results."
}

GET/api/v1/invoices/{job_id}

API key

Retrieve an invoice job

Returns the current status of a job and, once complete, the full extracted payload including line items, totals, tax breakdown, confidence level, `automation_ready` boolean, and download URLs for Excel and CSV. `automation_ready` is `true` when confidence is HIGH and math validation passed — safe to use as a no-human-review gate in automated pipelines.

Parameters

ParameterTypeDescription

job_idpathrequired
string (uuid)
The job identifier returned by POST /api/v1/invoices.
Authorizationheaderrequired
string
Bearer token in the form `Bearer ipp_live_...`.

Request

cURL

curl -X GET "https://api.invoiceparserpro.com/api/v1/invoices/550e8400-e29b-41d4-a716-446655440000" \
  -H "Authorization: Bearer ipp_live_xxxx_xxxxxxxxxxxxxxxx"

Response

200 OK

{
  "success": true,
  "job_id": "550e8400-e29b-41d4-a716-446655440000",
  "status": "completed",
  "filename": "acme-2026-01.pdf",
  "created_at": "2026-04-11T14:02:19.314Z",
  "completed_at": "2026-04-11T14:02:31.802Z",
  "credits_charged": 1,
  "result": {
    "vendor": "Acme Corp",
    "invoice_number": "INV-2026-001",
    "invoice_date": "2026-01-15",
    "due_date": "2026-02-14",
    "subtotal": 1000.00,
    "tax": 100.00,
    "total": 1100.00,
    "currency": "USD",
    "confidence": "HIGH",
    "automation_ready": true,
    "validation_status": "valid",
    "line_items": [
      {
        "description": "Consulting services",
        "quantity": 10,
        "unit_price": 100.00,
        "tax_amount": 10.00,
        "amount": 1000.00
      }
    ]
  },
  "downloads": {
    "excel": "/api/v1/invoices/550e8400-.../download/excel",
    "csv":   "/api/v1/invoices/550e8400-.../download/csv"
  }
}

GET/api/v1/invoices/{job_id}/download/{format}

API key

Download invoice output

Streams the generated Excel or CSV file for a completed job. Returns a 400 error when called before the job has reached the `completed` state.

Parameters

ParameterTypeDescription

job_idpathrequired
string (uuid)
The job identifier returned by POST /api/v1/invoices.
formatpathrequired
string
Either `excel` (returns an .xlsx file) or `csv`.
Authorizationheaderrequired
string
Bearer token in the form `Bearer ipp_live_...`.

Request

cURL

curl -X GET "https://api.invoiceparserpro.com/api/v1/invoices/550e8400-.../download/excel" \
  -H "Authorization: Bearer ipp_live_xxxx_xxxxxxxxxxxxxxxx" \
  -o invoice.xlsx

Response

200 OK · binary

HTTP/1.1 200 OK
Content-Type: application/vnd.openxmlformats-officedocument.spreadsheetml.sheet
Content-Disposition: attachment; filename="invoice_550e8400.xlsx"

<binary spreadsheet body>

GET/api/v1/jobs

API key

List invoice jobs

Returns recent jobs for the authenticated API key owner, ordered newest first. Each entry includes the extraction confidence so you can filter for low-confidence results without fetching each job individually.

Parameters

ParameterTypeDescription

limitqueryoptional
integer (1–100)
Default: 50
Maximum number of jobs to return in a single page.
offsetqueryoptional
integer (>= 0)
Default: 0
Pagination offset. Combine with `limit` for simple offset pagination.
Authorizationheaderrequired
string
Bearer token in the form `Bearer ipp_live_...`.

Request

cURL

curl -X GET "https://api.invoiceparserpro.com/api/v1/jobs?limit=20&offset=0" \
  -H "Authorization: Bearer ipp_live_xxxx_xxxxxxxxxxxxxxxx"

Response

200 OK

{
  "success": true,
  "data": {
    "jobs": [
      {
        "job_id": "550e8400-e29b-41d4-a716-446655440000",
        "status": "completed",
        "filename": "acme-2026-01.pdf",
        "confidence": "HIGH",
        "credits_charged": 1,
        "created_at": "2026-04-11T14:02:19.314Z",
        "completed_at": "2026-04-11T14:02:31.802Z"
      }
    ],
    "limit": 20,
    "offset": 0
  }
}

Batches

Submit multiple invoices in a single request. The batch is queued and processed asynchronously — poll the retrieve endpoint until status reaches `done`.

POST/api/v1/batches

API key

Create a batch

Upload up to 25 invoices in a single multipart request. Each file counts as one credit. Returns a batch_id for polling. Processing is always asynchronous.

Rate limit: 10 requests / minute / API key

Parameters

ParameterTypeDescription

filesformrequired
file[] (pdf, png, jpg, jpeg)
Invoice files. Up to 25 per request. Each file consumes one credit.
export_modeformoptional
string
Default: standard
Column set for generated Excel/CSV: `standard` or `full`.
Authorizationheaderrequired
string
Bearer token in the form `Bearer ipp_live_...`.

Request

cURL

curl -X POST "https://api.invoiceparserpro.com/api/v1/batches" \
  -H "Authorization: Bearer ipp_live_xxxx_xxxxxxxxxxxxxxxx" \
  -F "files=@invoice-jan.pdf" \
  -F "files=@invoice-feb.pdf" \
  -F "files=@invoice-mar.pdf"

Response

202 Accepted

{
  "success": true,
  "batch_id": "7c9e6679-7425-40de-944b-e07fc1f90ae7",
  "status": "processing",
  "file_count": 3,
  "message": "Batch of 3 invoice(s) queued. Poll GET /api/v1/batches/{batch_id} for status."
}

GET/api/v1/batches/{batch_id}

API key

Retrieve a batch

Returns the status of a batch job. When status is `done`, the response includes per-file extraction results and download URLs for the combined Excel and CSV outputs.

Parameters

ParameterTypeDescription

batch_idpathrequired
string (uuid)
The batch identifier returned by POST /api/v1/batches.
Authorizationheaderrequired
string
Bearer token in the form `Bearer ipp_live_...`.

Request

cURL

curl -X GET "https://api.invoiceparserpro.com/api/v1/batches/7c9e6679-7425-40de-944b-e07fc1f90ae7" \
  -H "Authorization: Bearer ipp_live_xxxx_xxxxxxxxxxxxxxxx"

Response

200 OK

{
  "success": true,
  "batch_id": "7c9e6679-7425-40de-944b-e07fc1f90ae7",
  "status": "done",
  "file_count": 3,
  "successful": 3,
  "failed": 0,
  "created_at": "2026-04-11T14:10:00.000Z",
  "completed_at": "2026-04-11T14:10:47.312Z",
  "results": [
    {
      "filename": "invoice-jan.pdf",
      "status": "success",
      "vendor": "Acme Corp",
      "invoice_number": "INV-2026-001",
      "total": 1100.00,
      "currency": "USD",
      "confidence": "HIGH"
    },
    {
      "filename": "invoice-feb.pdf",
      "status": "success",
      "vendor": "Globex LLC",
      "invoice_number": "GBX-0042",
      "total": 540.00,
      "currency": "USD",
      "confidence": "HIGH"
    }
  ],
  "downloads": {
    "excel": "/download/7c9e6679-.../excel",
    "csv":   "/download/7c9e6679-.../csv",
    "qb":    "/download/7c9e6679-.../qb",
    "zoho":  "/download/7c9e6679-.../zoho"
  }
}

Webhooks

Register HTTPS endpoints to receive push notifications when jobs complete or fail. Eliminates the need to poll. Each delivery is signed with HMAC-SHA256 — verify the X-IPP-Signature header to confirm authenticity.

POST/api/v1/webhooks

API key

Register a webhook

Register an HTTPS endpoint to receive signed event payloads. The signing secret is returned once — store it securely. Maximum 5 active webhooks per account.

Parameters

ParameterTypeDescription

urlbodyrequired
string (HTTPS URL)
The HTTPS endpoint that will receive POST requests. Must start with https://.
eventsbodyoptional
string[]
Default: all events
Event types to subscribe to. Omit to subscribe to all. Valid values: `job.completed`, `job.failed`, `batch.completed`, `batch.failed`.

Request

cURL

curl -X POST "https://api.invoiceparserpro.com/api/v1/webhooks" \
  -H "Authorization: Bearer ipp_live_xxxx_xxxxxxxxxxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://your-app.com/webhooks/ipp",
    "events": ["job.completed", "job.failed"]
  }'

Response

200 OK

{
  "success": true,
  "data": {
    "webhook_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
    "url": "https://your-app.com/webhooks/ipp",
    "events": ["job.completed", "job.failed"],
    "secret": "whsec_a3f2c1...",
    "warning": "Store this secret securely. It will not be shown again.",
    "created_at": "2026-04-11T14:00:00.000Z"
  }
}

GET/api/v1/webhooks

API key

List webhooks

Returns all active webhook endpoints for the account. Signing secrets are never included in listings.

Parameters

ParameterTypeDescription

Authorizationheaderrequired
string
Bearer token in the form `Bearer ipp_live_...`.

Request

cURL

curl -X GET "https://api.invoiceparserpro.com/api/v1/webhooks" \
  -H "Authorization: Bearer ipp_live_xxxx_xxxxxxxxxxxxxxxx"

Response

200 OK

{
  "success": true,
  "data": {
    "webhooks": [
      {
        "webhook_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
        "url": "https://your-app.com/webhooks/ipp",
        "events": ["job.completed", "job.failed"],
        "created_at": "2026-04-11T14:00:00.000Z",
        "last_used_at": "2026-04-11T15:30:12.000Z",
        "failure_count": 0
      }
    ]
  }
}

DELETE/api/v1/webhooks/{webhook_id}

API key

Delete a webhook

Permanently deactivates a webhook endpoint. In-flight deliveries are not cancelled. Deletion is immediate and cannot be undone.

Parameters

ParameterTypeDescription

webhook_idpathrequired
string (uuid)
The webhook identifier returned by the create or list endpoints.
Authorizationheaderrequired
string
Bearer token in the form `Bearer ipp_live_...`.

Request

cURL

curl -X DELETE "https://api.invoiceparserpro.com/api/v1/webhooks/3fa85f64-5717-4562-b3fc-2c963f66afa6" \
  -H "Authorization: Bearer ipp_live_xxxx_xxxxxxxxxxxxxxxx"

Response

200 OK

{
  "success": true,
  "message": "Webhook 3fa85f64-5717-4562-b3fc-2c963f66afa6 deleted"
}

Account

Read account metadata — tier, credit balance, and the email associated with the API key.

GET/api/v1/account

API key

Retrieve account info

Returns the tier and remaining credit balance for the account that owns the API key. Use this before kicking off a batch to avoid mid-run credit exhaustion.

Parameters

ParameterTypeDescription

Authorizationheaderrequired
string
Bearer token in the form `Bearer ipp_live_...`.

Request

cURL

curl -X GET "https://api.invoiceparserpro.com/api/v1/account" \
  -H "Authorization: Bearer ipp_live_xxxx_xxxxxxxxxxxxxxxx"

Response

200 OK

{
  "success": true,
  "data": {
    "email": "you@example.com",
    "tier": "starter_business",
    "credits": 450
  }
}

API keys

Manage API keys from the web UI via session authentication. Keys created here are the credentials used by every /api/v1 endpoint below.

POST/api/v1/keys

Session

Create an API key

Creates a new API key bound to the authenticated Business-tier user. The full key value is returned once — store it securely, it will not be shown again. Requires session cookie or bearer session token.

Parameters

ParameterTypeDescription

namebodyoptional
string
Human-readable label for the key, e.g. "production-worker" or "ci-pipeline".

Request

cURL

curl -X POST "https://api.invoiceparserpro.com/api/v1/keys" \
  -H "Content-Type: application/json" \
  -b "session=<your_session_cookie>" \
  -d '{"name": "production-worker"}'

Response

200 OK

{
  "success": true,
  "data": {
    "key_id": "key_7f3a9c",
    "key": "ipp_live_xxxxxx_xxxxxxxxxxxxxxxxxxxxxxxx",
    "name": "production-worker",
    "created_at": "2026-04-11T14:02:19.314Z",
    "warning": "Store this key securely. It will not be shown again."
  }
}

GET/api/v1/keys

Session

List API keys

Returns every API key issued for the authenticated user, including created and last-used timestamps. The raw key value is never returned — only metadata.

Request

cURL

curl -X GET "https://api.invoiceparserpro.com/api/v1/keys" \
  -b "session=<your_session_cookie>"

Response

200 OK

{
  "success": true,
  "data": {
    "keys": [
      {
        "key_id": "key_7f3a9c",
        "name": "production-worker",
        "created_at": "2026-04-11T14:02:19.314Z",
        "last_used_at": "2026-04-11T15:44:02.119Z",
        "is_active": true
      }
    ]
  }
}

DELETE/api/v1/keys/{key_id}

Session

Revoke an API key

Permanently revokes a key. Subsequent requests using the revoked key will return 401 INVALID_API_KEY. Revocation is immediate and cannot be undone.

Parameters

ParameterTypeDescription

key_idpathrequired
string
The id of the key to revoke, as returned by the create/list endpoints.

Request

cURL

curl -X DELETE "https://api.invoiceparserpro.com/api/v1/keys/key_7f3a9c" \
  -b "session=<your_session_cookie>"

Response

200 OK

{
  "success": true,
  "message": "API key key_7f3a9c revoked"
}

Upcoming

Features on the active roadmap. Documenting them here sets developer expectations before GA and signals product velocity to integration teams evaluating IPP.

Multi-language SDK packages

Official Python and Node.js SDKs wrapping the REST API.

Why it matters · Removes auth boilerplate, handles retries, and provides typed response models — cutting integration time from hours to minutes.

Structured JSON output mode

A `response_format=json` parameter on POST /api/v1/invoices that skips Excel/CSV generation and returns the full extracted payload synchronously.

Why it matters · Ideal for pipelines that transform extracted data downstream — no download step, no file parsing, lower latency.

Rate limit response headers

X-RateLimit-Limit, X-RateLimit-Remaining, and Retry-After headers on every API response.

Why it matters · Lets clients implement adaptive throttling instead of guessing. Standard practice across Stripe, GitHub, and Linear.

Webhook retry and delivery log

Automatic retry with exponential backoff on webhook delivery failures, plus a GET /api/v1/webhooks/{id}/deliveries endpoint exposing the last 50 delivery attempts.

Why it matters · Reduces operational burden for integrators debugging missed events in production.

Vendor normalization endpoint

GET /api/v1/vendors returning the canonical vendor list learned from prior extractions, with merge and alias management.

Why it matters · Enables downstream deduplication when the same vendor appears under multiple name variants across invoices.

Changelog

A history of additions, improvements, and fixes to the InvoiceParser Pro API. Breaking changes are flagged explicitly — all other changes are backwards-compatible.

April 2026Latest

Newautomation_ready boolean added to extraction result — true when confidence is HIGH and math validation passes. Use as a no-human-review gate in automated AP pipelines.
Newinclude_bounding_boxes param on POST /invoices — opt-in field_locations object containing Azure Document Intelligence polygon coordinates per extracted field.
Newexternal_id idempotency key on POST /invoices — supply a caller-owned ID to safely retry on network errors or 5xx responses without double-charging credits.
NewDeveloper webhooks: POST / GET / DELETE /api/v1/webhooks. HMAC-SHA256 signed push delivery for job.completed, job.failed, batch.completed, and batch.failed events.
NewBatch API: POST /api/v1/batches accepts up to 25 invoices per request. GET /api/v1/batches/{batch_id} returns per-file results and combined Excel/CSV/QB/Zoho downloads.
ImprovedGET /api/v1/jobs now includes confidence (HIGH / MEDIUM / LOW) on each job row — filter low-confidence results without fetching individual jobs.
NewAzure pipeline: VendorTaxId, CustomerTaxId, PaymentTerm, ServiceStartDate, ServiceEndDate, and PaymentDetails (IBAN / SWIFT / BPay) now extracted and returned in the result.
ImprovedPer-field confidence scores added to field_locations — granular extraction quality signals for document review UIs.

March 2026

NewAPI v1 general availability. POST /api/v1/invoices, GET /api/v1/invoices/{job_id}, download endpoints, GET /api/v1/jobs, GET /api/v1/account, and API key management now stable.
NewSolo, Firm, and Firm Pro plans launched with dedicated monthly document allowances and API key access.
NewEnterprise proof-of-concept programme: time-boxed free trial with invoice cap for teams evaluating the API at volume before committing.
ImprovedExtraction pipeline upgraded to GPT-4o for enrichment. Accuracy improvement on complex multi-page and non-standard invoice layouts.
Newexport_mode=full param on POST /invoices — returns all extracted fields in Excel/CSV, including raw line item metadata and auxiliary fields.

February 2026

NewAzure Document Intelligence integration for primary extraction. Bounding box polygon data now captured at the field level for every processed invoice.
NewMulti-tax support: taxes[] array returned alongside the scalar tax field — breakdown by tax type and rate where the source document provides it.
NewCurrency detection field added to result — confidence-weighted, automatically falls back to document-stated currency when detected.
Newpo_number added to result — purchase order number extracted directly from the invoice header where present.
Newvendor_address and vendor_country (ISO 3166-1 alpha-2) added to result — enables vendor geo-routing and country-specific tax rule application downstream.
Newcustomer_name added to result — bill-to party name as printed on the invoice. Useful for multi-entity AP workflows routing invoices by recipient.
Newvalidation_explanation added to result — human-readable description of any validation flag (e.g. "Subtotal + tax does not equal total"). Surfaces the exact reason a job requires review.
Newtotal_source added to result — indicates how the total was obtained: explicit_total, derived_from_gst, derived_from_net_amount, or unknown. Useful for audit trails.
Newwarning_severity added to result — set to "risk" when the validation engine flags a job as requiring human review. Use as a filter gate before posting to your ERP.
ImprovedLine item extraction upgraded: quantity, unit_price, tax_amount, and amount now consistently populated; partial rows no longer dropped.
ImprovedValidation engine now distinguishes derived_total_confirmed (subtotal + tax = total matches within tolerance) from strict valid — improves automation_ready precision.

January 2026

NewImage invoice support: JPEG and PNG accepted on all upload endpoints alongside PDF. Images are pre-processed and normalised before extraction.
NewZoho Books CSV export available on batch downloads alongside existing Excel and QuickBooks formats.
ImprovedCredit deduction is now atomic — a failed extraction no longer consumes a credit if the error is on the extraction side.
FixedDue date parsing corrected for invoices using DD/MM/YYYY locale — previously swapped month and day on ambiguous dates.
Fixedvalidation_status was missing from GET /invoices/{job_id} response on async (queued) jobs. Now included in all completion states.

December 2025

NewPOST /api/v1/invoices beta released to early access users. Synchronous processing with job_id polling via GET /api/v1/invoices/{job_id}.
NewGET /api/v1/account endpoint — returns tier and live credit balance. Recommended check before large batch operations.
NewAPI key management via web UI: create, label, and revoke keys from the API Access page. Keys scoped to account.
NewExcel (.xlsx) download for processed invoices — single-file and batch results.
ImprovedExtraction confidence classification (HIGH / MEDIUM / LOW) now returned on every completed job. Based on field completeness and cross-field validation.

October 2025

NewInvoiceParser Pro API private alpha. Core extraction: vendor, invoice_number, invoice_date, due_date, subtotal, tax, total, currency, and line items.
NewPDF invoice support. Single-file upload, synchronous extraction, JSON result.
NewCSV export for extracted invoice data.