---
title: "List purchase scans"
method: GET
path: "/companies/{company}/purchase-scans"
tags: ["Purchase Scans"]
---

# List purchase scans

`GET /companies/{company}/purchase-scans`

## Request

- Base URL: `https://api.factuarea.com/v1`
- URL: `https://api.factuarea.com/v1/companies/{company}/purchase-scans`
- Auth: one of:
  - HTTP bearer
  - API key in header `X-API-Key`

List the documents received by the purchase scanner (upload, API or mailbox) with their lifecycle status, extraction issues and `available_actions`. Use `filter[status]`, `filter[source]` and the documented date/range filters; cursor-based pagination.

## Path parameters

- `company` string, uuid, required

## Query parameters

- `limit` integer
- `starting_after` string, uuid, nullable
- `ending_before` string, uuid, nullable
- `search` string
- `sort` 'received_at' | '-received_at' | 'issue_date' | '-issue_date' | 'total' | '-total' | 'status' | '-status'
- `filter[status]` 'received' | 'queued' | 'processing' | 'needs_review' | 'duplicate' | 'failed' | 'auto_created' | 'created' | 'archived'
- `filter[has_issues]` boolean
- `filter[sender]` string
- `filter[source]` string: Comma-separated list of scan sources. Allowed values: upload, email, api.
- `filter[document_kind]` string: Comma-separated list of document kinds. Allowed values: invoice, simplified_qualified, ticket, delivery_note, other, undetermined.
- `filter[file_kind]` string: Comma-separated list of file kinds. Allowed values: pdf, image.
- `filter[supplier_link_state]` string: Comma-separated list of supplier link states. Allowed values: linked, pending_link, unidentified.
- `filter[supplier_id]` string, uuid: Comma-separated list of supplier ids (up to 20).
- `filter[created][eq]` string, date
- `filter[created][gt]` string, date
- `filter[created][gte]` string, date
- `filter[created][lt]` string, date
- `filter[created][lte]` string, date
- `filter[issued_on][eq]` string, date
- `filter[issued_on][gt]` string, date
- `filter[issued_on][gte]` string, date
- `filter[issued_on][lt]` string, date
- `filter[issued_on][lte]` string, date
- `filter[total][eq]` string
- `filter[total][gt]` string
- `filter[total][gte]` string
- `filter[total][lt]` string
- `filter[total][lte]` string

## Headers

- `Factuarea-Version` string, date

## Response `200`

Successful scanner operation.

- object
  - `data` PurchaseScanListItem[], required
    - `id` string, uuid, required
    - `version` integer, required
    - `source` 'upload' | 'email' | 'api', required
    - `status` 'received' | 'queued' | 'processing' | 'needs_review' | 'duplicate' | 'failed' | 'auto_created' | 'created' | 'archived', required
    - `original_filename` string, required
    - `mime_type` string, required
    - `page_count` integer, required
    - `received_at` string, date-time, required
    - `uploaded_by` object, required
      - `name` string, nullable, required
    - `supplier_id` string, uuid, nullable, required
    - `supplier_name` string, nullable, required
    - `document_number` string, nullable, required
    - `issue_date` string, date, nullable, required
    - `currency` string, nullable, required
    - `total` string, nullable, required
    - `issue_count` integer, required: Number of issues still pending review: one per field, supplier identity counted once, 0 before the first extraction.
    - `available_actions` string[], required
    - `purchase_invoice_id` string, uuid, nullable, required
    - `last_error` object, nullable, required
      - `code` 'ocr_temporarily_unavailable' | 'scan_storage_unavailable' | 'file_safety_unavailable' | 'inbound_provider_unavailable' | 'resource_locked' | 'queue_delivery_failed' | 'purchase_scanner_disabled' | 'ocr_company_quota_exceeded' | 'module_upgrade_required' | 'unsupported_scan_format' | 'unsupported_purchase_document_type' | 'unsafe_scan_file' | 'scan_page_limit_exceeded' | 'purchase_scanner_internal_error', required
      - `recoverable` boolean, required
    - `deferred_until` string, date-time, nullable, required: When set, the scan is waiting for the company daily OCR quota to reset; it will be retried automatically.
    - `deferred_reason` 'ocr_daily_quota_reached' | 'null', nullable, required
    - `document_kind` 'invoice' | 'simplified_qualified' | 'ticket' | 'delivery_note' | 'other' | 'undetermined', required
    - `file_kind` 'pdf' | 'image', required
    - `supplier_link_state` 'linked' | 'pending_link' | 'unidentified', required
  - `has_more` boolean, required
  - `next_cursor` string, uuid, nullable, required

## Other responses

- `400`: The operation failed. Possible `error.code` values: `parameter_unknown` — the query contains a parameter this operation does not accept.
- `401`: Missing or invalid API key.
- `403`: The request is authenticated but not allowed: the API key lacks the required scope (`insufficient_scope`), the plan does not include the public API or this feature (`addon_not_active`, `feature_not_available_in_plan`), or the module is not available with a test key (`module_not_available_in_sandbox`). `company_inactive`: the company in the path is deactivated; reactivate it to operate.
- `404`: The requested resource does not exist or belongs to another company. `profile_not_found`: the company in the path does not exist, is not in the API key scope or belongs to the other environment (live or test).
- `422`: The request could not be validated. Possible `error.code` values: `invalid_param_value` — a recognized query parameter has an invalid value.
- `429`: Rate limit exceeded. Retry after the duration in `Retry-After`.
- `500`: Unexpected server error.

---

[API](https://skmtc.dev/factuarea/apis/factuarea-public-api.md) · [All operations](https://skmtc.dev/factuarea/apis/factuarea-public-api/llms.txt) · [OpenAPI document](https://skmtc.dev/factuarea/apis/factuarea-public-api/revisions/718e77934422?raw)