# Tabscanner API v2

> Receipt and invoice OCR REST API. Upload a photo of a receipt (JPEG or PNG) to `POST https://api3.tabscanner.com/v2/receipts` as multipart/form-data (part `file`, optional `region`, `documentType`, `model`) with `Authorization: Bearer <key>` and an `Idempotency-Key` header. The response is `202 Accepted` with a `token`. Poll `GET https://api3.tabscanner.com/v2/receipts/{token}`, waiting `Retry-After` seconds between calls, until `status` is `done` (data in `result`) or `failed`. The result contains establishment, date, total, subTotal, tax, taxes, tip, serviceCharges, discount, currency, paymentMethod, address, lineItems, summaryItems and a confidence score for each value. `GET /v2/account` returns the remaining credit.

Important: standard HTTP status codes. Errors are `application/problem+json` with a stable `code` (for example `API_KEY_INVALID` 401, `INSUFFICIENT_CREDIT` 402, `TOKEN_NOT_FOUND` 404, `RATE_LIMITED` 429). A pending result is `200` with `"status": "pending"`, not an error. Retry `5xx`, `409` and `429` with backoff, reusing the same `Idempotency-Key` for uploads; do not retry other `4xx`. One credit per accepted upload; everything else is free. Optional `model` values: `harajuku`, and `harajuku-pro`, a more thorough, slower version; omit for standard OCR. Models are available on subscription and contract plans (`features.models` on `GET /v2/account`), and the `-pro` models also need the Pro package (`features.proModels`); otherwise `403 MODEL_NOT_PERMITTED`. Call the API from a server only.

## Documentation

- [Full documentation as Markdown](https://docs3.tabscanner.com/llms-full.txt): the complete API reference in one file.
- [For AI agents](https://docs3.tabscanner.com/agents.html): tool definitions, reference implementation, rules and which fields to trust.
- [OpenAPI 3.1 specification](https://docs3.tabscanner.com/openapi.yaml): every endpoint, parameter, field and error code, generated from the API.
- [Result JSON Schema](https://docs3.tabscanner.com/schemas/result.schema.json): JSON Schema 2020-12 for the result object.
- [Changelog](https://docs3.tabscanner.com/changelog.html)

## Reference sections

- [Introduction](https://docs3.tabscanner.com/#introduction)
- [Quickstart](https://docs3.tabscanner.com/#quickstart): full upload-and-poll program in curl, Node.js, Python, PHP, Ruby, Java, Go and C#/.NET.
- [Authentication](https://docs3.tabscanner.com/#authentication)
- [Requests and responses](https://docs3.tabscanner.com/#conventions): status codes, problem details, request IDs.
- [POST /v2/receipts](https://docs3.tabscanner.com/#upload)
- [GET /v2/receipts/{token}](https://docs3.tabscanner.com/#result)
- [GET /v2/account](https://docs3.tabscanner.com/#account)
- [Result object](https://docs3.tabscanner.com/#result-object)
- [LineItem object](https://docs3.tabscanner.com/#line-item)
- [Models](https://docs3.tabscanner.com/#models)
- [Polling and timeouts](https://docs3.tabscanner.com/#polling)
- [Retries and idempotency](https://docs3.tabscanner.com/#retries)
- [Errors](https://docs3.tabscanner.com/#errors): every error code with what to do.
- [Regions and locales](https://docs3.tabscanner.com/#regions)
- [Limits and rate limits](https://docs3.tabscanner.com/#limits)

## Optional

- [Tabscanner website](https://tabscanner.com): product, plans and pricing.
- [Dashboard](https://dashboard.tabscanner.com): sign up and API keys.
- [v1 documentation](https://docs.tabscanner.com): the original API.