# List purchase invoices

Find received purchase invoices in a date range with cursor pagination.

## Endpoint

```http
GET https://prod.gets.complyance.io/api/v3/documents?type=purchases
```

## Authentication

`Authorization: Bearer YOUR_API_KEY`. The API key selects the workspace and environment.

## Parameters

| Query | Required | Description |
| - | - | - |
| `type` | Yes | `purchases` |
| `companyId` | No | Connect company ID for a UAE company. Restricts results to that company. Use the `companyId` returned by [List companies](https://docs.complyance.io/api-reference/connect/companies/#list-companies). |
| `from` | Yes | Start date, `YYYY-MM-DD` |
| `to` | No | End date, `YYYY-MM-DD`; defaults to `from` |
| `limit` | No | Page size, 1–100; default 100 |
| `cursor` | No | Opaque `nextCursor` from the previous response |
| `peppolId` | No | Buyer’s Peppol participant ID, including its scheme, such as `0235:100000000000003` |
| `source` | No | Exact source name, such as `acme-erp` |
| `version` | No | Exact source version, such as `1.0.0`; can be used with or without `source` |

```bash title="List one day's received purchases"
curl --get 'https://prod.gets.complyance.io/api/v3/documents' \
  --header "Authorization: Bearer ${COMPLYANCE_API_KEY}" \
  --header 'Accept: application/json' \
  --data-urlencode 'type=purchases' \
  --data-urlencode 'from=2026-09-22' \
  --data-urlencode 'limit=100'
```

The range includes both dates, using UTC day boundaries for receipt/storage. It does not filter by the supplier’s invoice issue date.

All supplied filters must match. You can use `companyId` alone or combine it with `peppolId`, `source` and `version`. Source names and versions are case-sensitive. A source name without a version includes all its versions; a version without a source name includes all sources with that version. An unmatched source or version returns an empty page.

```bash title="Filter purchases by company, buyer and source"
curl --get 'https://prod.gets.complyance.io/api/v3/documents' \
  --header "Authorization: Bearer ${COMPLYANCE_API_KEY}" \
  --data-urlencode 'type=purchases' \
  --data-urlencode 'from=2026-09-22' \
  --data-urlencode 'companyId=66b9f0a1c2d3e4f567890123' \
  --data-urlencode 'peppolId=0235:100000000000003' \
  --data-urlencode 'source=acme-erp' \
  --data-urlencode 'version=1.0.0'
```

## Response

```json title="Example response"
{
  "success": true,
  "data": {
    "items": [
      {
        "documentId": "01JEXAMPLE0000000000000142",
        "receivedAt": "2026-09-22T08:15:00.000Z",
        "storedAt": "2026-09-22T08:15:02.000Z",
        "status": "purchase.invoice.stored",
        "country": "AE",
        "environment": "sandbox",
        "invoiceNumber": "INV-2026-0142",
        "supplierName": "Acme Trading LLC",
        "issueDate": "2026-09-22"
      }
    ],
    "hasMore": false,
    "nextCursor": null
  }
}
```

`invoiceNumber`, `supplierName` and `issueDate` can be `null`. `receivedAt` and `storedAt` describe receipt and storage; they are distinct from the supplier’s issue date.

When `hasMore` is `true`, request the next page with `cursor=nextCursor`. URL-encode the cursor and retain the same date range, filters and limit. Stop when `hasMore` is `false`. Do not construct or modify a cursor.

## Errors

| HTTP / code | Meaning |
| - | - |
| `400 VALIDATION_ERROR` | A date is not `YYYY-MM-DD`, `from` is after `to`, or the `cursor` is not valid |
| `400 NOT_SUPPORTED` | Sales listing was requested; use `type=purchases` |
| `401` | Missing or invalid authentication; see [authentication failures](https://docs.complyance.io/api-reference/authentication/#authentication-failures) |
| `422` | `from` or `type` is missing, `type` is not recognised, or `limit` is above 100, `peppolId` has no scheme and identifier, or `companyId`, `source` or `version` is blank |
| `500 INTERNAL_ERROR` | Retrieval failed; retry with backoff |

A `422` lists the checks that failed in its own format, without `success`, `code` and `message`. Check the HTTP status before reading the body.

Next, [get a purchase invoice](https://docs.complyance.io/api-reference/purchases/get/) using a returned `documentId`.

Last updated 23 October 2026

Source: https://docs.complyance.io/api-reference/purchases/list/