List purchase scans

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.

Authorization

AuthorizationBearer <token>

In: header

Query Parameters

limit?integer

Range1 <= value <= 100

starting_after?|

Formatuuid

ending_before?|

Formatuuid

search?string

Lengthlength <= 200

sort?string

Value in"received_at" | "-received_at" | "issue_date" | "-issue_date" | "total" | "-total" | "status" | "-status"

filter[status]?string

Value in"received" | "queued" | "processing" | "needs_review" | "duplicate" | "failed" | "auto_created" | "created" | "archived"

filter[source][]?array<>

Value in"upload" | "email" | "api"

filter[supplier_id][]?array<>

Formatuuid

filter[document_kind][]?array<>

Value in"invoice" | "simplified_qualified" | "ticket" | "delivery_note" | "other" | "undetermined"

filter[file_kind][]?array<>

Value in"pdf" | "image"

filter[supplier_link_state][]?array<>

Value in"linked" | "pending_link" | "unidentified"

filter[has_issues]?boolean

filter[sender]?string

Lengthlength <= 254

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

Comma-separated list of supplier ids (up to 20).

Formatuuid

filter[created][eq]?string

Formatdate

filter[created][gt]?string

Formatdate

filter[created][gte]?string

Formatdate

filter[created][lt]?string

Formatdate

filter[created][lte]?string

Formatdate

filter[issued_on][eq]?string

Formatdate

filter[issued_on][gt]?string

Formatdate

filter[issued_on][gte]?string

Formatdate

filter[issued_on][lt]?string

Formatdate

filter[issued_on][lte]?string

Formatdate

filter[total][eq]?string

Match^-?(?:0|[1-9]\d*)(?:\.\d{1,4})?$

filter[total][gt]?string

Match^-?(?:0|[1-9]\d*)(?:\.\d{1,4})?$

filter[total][gte]?string

Match^-?(?:0|[1-9]\d*)(?:\.\d{1,4})?$

filter[total][lt]?string

Match^-?(?:0|[1-9]\d*)(?:\.\d{1,4})?$

filter[total][lte]?string

Match^-?(?:0|[1-9]\d*)(?:\.\d{1,4})?$

Headers

Factuarea-Version?string

Pin the API version (YYYY-MM-DD, Stripe-style date versioning) for this request; omit to use the key's pinned version, or the latest if none. Unsupported version → 400 unsupported_api_version; malformed → 400 parameter_invalid_format. The effective version is echoed in the Factuarea-Version response header. See the Versioning guide.

Formatdate

X-Active-Profile?string

Operate on behalf of a child company (gestoría master key): pass its public id (UUID v7) and the request runs against that child's data without changing the key's scope, tier or environment (omit to use the key's own company). Invalid UUID → 400 parameter_invalid_uuid; unknown or non-owned id → 404 profile_not_found. See the Acting on behalf guide.

Formatuuid

Response Body

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

Request example

const apiKey = process.env.FACTUAREA_API_KEY;if (!apiKey) throw new Error("Set FACTUAREA_API_KEY");const response = await fetch("https://api.factuarea.com/v1/purchase_scans?limit=25", {  method: "GET",  headers: { Authorization: `Bearer ${apiKey}`, ...{"Accept":"application/json"} },});if (!response.ok) throw new Error(await response.text());if (response.status !== 204) console.log(await response.json());

Response example

{
  "data": [
    {
      "id": "019e0000-0000-7000-8000-000000000042",
      "version": 3,
      "source": "api",
      "status": "needs_review",
      "original_filename": "factura-proveedor.pdf",
      "mime_type": "application/pdf",
      "page_count": 1,
      "received_at": "2026-09-12T10:30:00Z",
      "uploaded_by": {
        "name": "Administración"
      },
      "supplier_id": "019e0000-0000-7000-8000-000000000010",
      "supplier_name": "Suministros Ejemplo SL",
      "document_number": "PROV-2026-0042",
      "issue_date": "2026-09-12",
      "currency": "EUR",
      "total": "121",
      "issue_count": 0,
      "available_actions": [
        "save_review",
        "convert",
        "archive",
        "download_source"
      ],
      "purchase_invoice_id": null,
      "last_error": null,
      "deferred_until": null,
      "deferred_reason": null,
      "document_kind": "invoice",
      "file_kind": "pdf",
      "supplier_link_state": "linked"
    }
  ],
  "has_more": false,
  "next_cursor": null
}

{
  "error": {
    "type": "invalid_request_error",
    "code": "parameter_unknown",
    "message": "La consulta incluye un parámetro no admitido.",
    "doc_url": "https://docs.factuarea.com/errors/parameter_unknown",
    "request_id": "req_scanner_example",
    "param": "filter[unknown]"
  }
}

Missing API key

{
  "error": {
    "type": "authentication_error",
    "code": "missing_api_key",
    "message": "No se ha proporcionado una API key válida en el header Authorization.",
    "param": null,
    "doc_url": "https://docs.factuarea.com/guides/errors#missing_api_key",
    "request_id": "req_01HKQS5N8VR7QXJ9K3T6BWPMZA"
  }
}

Invalid API key format

{
  "error": {
    "type": "authentication_error",
    "code": "invalid_api_key",
    "message": "La API key no tiene el formato esperado (debe empezar por fact_live_ o fact_test_).",
    "param": null,
    "doc_url": "https://docs.factuarea.com/guides/errors#invalid_api_key",
    "request_id": "req_01HKQS5N9JTQM7HVTQP3FBN5XB"
  }
}

Revoked API key

{
  "error": {
    "type": "authentication_error",
    "code": "api_key_revoked",
    "message": "Esta API key ha sido revocada y ya no es válida.",
    "param": null,
    "doc_url": "https://docs.factuarea.com/guides/errors#api_key_revoked",
    "request_id": "req_01HKQS5NA8K7E2V9YDZWMT6RJC"
  }
}

API key lacks required scope

{
  "error": {
    "type": "authorization_error",
    "code": "insufficient_scope",
    "message": "Esta API key no tiene el scope requerido para esta operación.",
    "param": null,
    "doc_url": "https://docs.factuarea.com/guides/errors#insufficient_scope",
    "request_id": "req_01HKQS5NBC3P8M1KX4V7SLNHQD"
  }
}

Plan upgrade required

{
  "error": {
    "type": "authorization_error",
    "code": "feature_not_available_in_plan",
    "message": "Esta funcionalidad requiere el plan empresario o superior. Actualiza tu suscripción para acceder.",
    "param": null,
    "doc_url": "https://docs.factuarea.com/guides/errors#feature_not_available_in_plan",
    "request_id": "req_01HKQS5NCK4V9N2L7Y8X3WPMRE"
  }
}

Plan without public API access

{
  "error": {
    "type": "authorization_error",
    "code": "addon_not_active",
    "message": "Tu plan actual no incluye acceso a la API pública. Contrata o renueva un plan de Factuarea para usar la API.",
    "param": null,
    "doc_url": "https://docs.factuarea.com/guides/errors#addon_not_active",
    "request_id": "req_01HKQS5NDP5W0Q3M8Z9A4BVSNF"
  }
}

{
  "error": {
    "type": "invalid_request_error",
    "code": "invalid_param_value",
    "message": "El valor del parámetro de consulta no es válido.",
    "doc_url": "https://docs.factuarea.com/errors/invalid_param_value",
    "request_id": "req_scanner_example",
    "param": "filter[status]"
  }
}

Rate limit exceeded

{
  "error": {
    "type": "rate_limit_error",
    "code": "rate_limit_exceeded",
    "message": "Has excedido el rate limit de 60 peticiones por minuto. Reintenta tras 30 segundos.",
    "param": null,
    "doc_url": "https://docs.factuarea.com/guides/errors#rate_limit_exceeded",
    "request_id": "req_01HKQS5NKW1C6W9T4G5H0JBZVL"
  }
}

Too many authentication failures (temporary lockout)

{
  "error": {
    "type": "authentication_error",
    "code": "too_many_auth_failures",
    "message": "Has alcanzado el número máximo de intentos de autenticación fallidos. La API key queda bloqueada temporalmente. Reintenta tras el tiempo indicado en `Retry-After`.",
    "param": null,
    "doc_url": "https://docs.factuarea.com/guides/errors#too_many_auth_failures",
    "request_id": "req_01HKQS5NKW1C6W9T4G5H0JBZVM"
  }
}

Too many concurrent uploads in flight

{
  "error": {
    "type": "rate_limit_error",
    "code": "upload_in_flight_budget_exceeded",
    "message": "Tu empresa tiene demasiadas subidas en curso a la vez: este archivo ocupa 10 MB y el margen simultáneo es de 120 MB. Espera a que terminen las subidas en marcha y vuelve a intentarlo dentro de 45 segundos.",
    "param": null,
    "doc_url": "https://docs.factuarea.com/guides/errors#upload_in_flight_budget_exceeded",
    "request_id": "req_01HKQS5NUPLOADINFLIGHT005"
  }
}

Company-wide rate limit exceeded (all keys combined)

{
  "error": {
    "type": "rate_limit_error",
    "code": "company_rate_limit_exceeded",
    "message": "Tu empresa ha superado su límite conjunto de 900 peticiones por minuto, contando a la vez todas sus credenciales. Es un techo de la empresa, así que repartir el tráfico no lo eleva. Reintenta en 12 segundos, o solicita una ampliación de plan si necesitas más capacidad.",
    "param": null,
    "doc_url": "https://docs.factuarea.com/guides/errors#company_rate_limit_exceeded",
    "request_id": "req_01HKQS5NCOMPANYRATELIMIT06"
  }
}

Company-wide monthly quota exhausted (all keys combined)

{
  "error": {
    "type": "rate_limit_error",
    "code": "company_monthly_quota_exceeded",
    "message": "Tu empresa ha agotado su cuota conjunta de 150000 peticiones de este mes, contando a la vez todas sus credenciales. Es un techo de la empresa, así que repartir el tráfico no lo eleva. El contador se reinicia el día 1 del mes siguiente; solicita una ampliación de plan si necesitas más volumen antes.",
    "param": null,
    "doc_url": "https://docs.factuarea.com/guides/errors#company_monthly_quota_exceeded",
    "request_id": "req_01HKQS5NCOMPANYMONTHLY0007"
  }
}

{
  "error": {
    "type": "api_error",
    "code": "internal_error",
    "message": "Ha ocurrido un error inesperado. Si persiste, contacta con soporte adjuntando el request_id.",
    "param": null,
    "doc_url": "https://docs.factuarea.com/guides/errors#internal_error",
    "request_id": "req_01HKQS5NLX2D7X0U5H6J1KCAWM"
  }
}