> ## Documentation Index > Fetch the complete documentation index at: https://docs.pazy.io/llms.txt > Use this file to discover all available pages before exploring further. # Invoice List API > Retrieve a paginated list of invoices with filters by date, state, vendor, amount, and tags ## Authentication All requests require an API key in the request headers. **Headers:** ``` Authorization: Api-Key YOUR_API_KEY ``` ## Request **Content-Type:** `application/json` ### Query Parameters | Parameter | Type | Required | Description | | --------------- | ------- | -------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------- | | `sortBy` | string | No | Field to sort results by. Allowed values: `total_amount`, `invoice_no`, `sequence_no`, `due_date`, `issued_date`, `date_created`. | | `sortOrder` | string | No | Sort direction. Allowed values: `asc` (ascending), `desc` (descending). | | `sortNullOrder` | string | No | Where to place results with null values in the sorted field. Allowed values: `first`, `last`. | | `limit` | integer | No | Number of records to return. Min 1, Max 100, Default 30. | | `cursor` | string | No | Cursor for pagination. Default 0. | | `dateType` | string | No | Type of date to filter by. Default `issued_date`. Possible values: `issued_date`, `due_date`, `payment_date`, `date_created`, `approved_date`. | | `startDate` | string | No | Start date for filtering (ISO 8601 UTC format: `YYYY-MM-DDTHH:mm:ssZ`). | | `endDate` | string | No | End date for filtering (ISO 8601 UTC format: `YYYY-MM-DDTHH:mm:ssZ`). | | `state` | array | No | Array of invoice states to filter by. Allowed values: `DRAFTED`, `APPROVAL_PENDING`, `APPROVED`, `PAID`, `ARCHIVED`. Currently supports exactly one state. | | `invoiceNumber` | string | No | Invoice number to filter by. | | `invoiceDate` | string | No | Invoice date to filter by (`YYYY-MM-DD` format). | | `vendorName` | string | No | Vendor name to filter by (partial match). | | `vendorId` | string | No | Vendor ID to filter by. | | `userId` | string | No | ID of the user associated with the invoice vendor. | | `tagId` | integer | No | Filter invoices containing this organization tag id. | | `amount` | number | No | Filter invoices with amount greater than or equal to this value. | ## Code Examples ```bash cURL theme={null} curl -X GET "https://api.pazy.io/v1.0/invoices?limit=30&state=APPROVED" \ -H "Authorization: Api-Key YOUR_API_KEY" ``` ```javascript JavaScript (Fetch API) theme={null} const params = new URLSearchParams({ limit: '30', state: 'APPROVED' }); const response = await fetch(`https://api.pazy.io/v1.0/invoices?${params}`, { method: 'GET', headers: { 'Authorization': 'Api-Key YOUR_API_KEY' } }); const result = await response.json(); ``` ```python Python (requests) theme={null} import requests url = "https://api.pazy.io/v1.0/invoices" headers = { "Authorization": "Api-Key YOUR_API_KEY" } params = { "limit": 30, "state": "APPROVED" } response = requests.get(url, headers=headers, params=params) result = response.json() ``` ## Success Response **HTTP Status:** `200 OK` **Response Fields:** | Field | Type | Description | | -------------------------------- | ------- | ------------------------------------------------------------------------------------------------------------------------- | | `ok` | boolean | Indicates whether the request was successful | | `data` | object | Contains the invoice list response data | | `data.invoices` | array | List of invoices | | `data.invoices[].id` | string | Unique identifier for the invoice | | `data.invoices[].vendorId` | string | Unique identifier for the vendor on the invoice | | `data.invoices[].vendorName` | string | Vendor display name (falls back to legal name) | | `data.invoices[].invoiceNumber` | string | Invoice number as specified on the invoice document | | `data.invoices[].sequenceNumber` | string | System-generated sequence number with organization prefix | | `data.invoices[].description` | string | Description or notes about the invoice | | `data.invoices[].invoiceDate` | string | Date when the invoice was issued (ISO 8601 format) | | `data.invoices[].dueDate` | string | Due date for invoice payment (ISO 8601 format) | | `data.invoices[].dateCreated` | string | Date when the invoice was created in the system (ISO 8601 format) | | `data.invoices[].amount` | number | Total invoice amount | | `data.invoices[].currency` | string | Currency code (e.g., `INR`, `USD`) | | `data.invoices[].remarks` | string | Additional remarks or notes associated with the invoice | | `data.invoices[].state` | string | Current state of the invoice. Possible values: `DRAFTED`, `APPROVAL_PENDING`, `APPROVED`, `PAID`, `DECLINED`, `ARCHIVED`. | | `data.invoices[].syncState` | string | Synchronization state with accounting system. Possible values: `SYNCED`, `NOT_SYNCED`, `SYNCED_WITH_ERRORS`, etc. | | `data.invoices[].source` | string | Source of invoice creation. Possible values: `API`, `WEB`, `EMAIL`, `SLACK`, `WHATSAPP`, `APP`, etc. | | `data.invoices[].selfUrl` | string | Shareable URL for viewing the invoice in the web interface | | `data.context` | object | Pagination metadata | | `data.context.count` | number | Number of invoices returned in this page | | `data.context.hasMore` | boolean | Indicates whether there are more invoices to fetch | | `data.context.nextCursor` | string | Cursor to fetch the next page | ### Response Example ```json theme={null} { "ok": true, "data": { "invoices": [ { "id": "invoice_identifier", "vendorId": "vendor_identifier", "vendorName": "ABC Suppliers", "invoiceNumber": "INV-2026-001", "sequenceNumber": "PZY/2026-27/INV/0001", "description": "Monthly services invoice", "invoiceDate": "2026-01-15", "dueDate": "2026-02-15", "dateCreated": "2026-01-15T10:30:00Z", "amount": 50000.00, "currency": "INR", "remarks": "Payment due in 30 days", "state": "APPROVED", "syncState": "SYNCED", "source": "API", "selfUrl": "https://app.pazy.io/invoice/invoice_identifier" } ], "context": { "count": 100, "hasMore": true, "nextCursor": "30" } } } ``` ## Error Responses ### Validation Error **HTTP Status:** `400 Bad Request` ```json theme={null} { "ok": false, "error": { "code": "VALIDATION_ERROR", "message": "Validation failed: /query/state: must be equal to one of the allowed values" } } ``` ### Access Denied **HTTP Status:** `403 Forbidden` ```json theme={null} { "ok": false, "error": { "code": "ACCESS_DENIED", "message": "Access denied: You can only view vendors you own" } } ``` ### Authentication Errors **HTTP Status:** `401 Unauthorized` ```json theme={null} { "ok": false, "error": { "code": "MISSING_CREDENTIALS", "message": "Missing Credentials" } } ``` ```json theme={null} { "ok": false, "error": { "code": "INVALID_API_KEY", "message": "Invalid API Key" } } ``` ### Permission Errors **HTTP Status:** `403 Forbidden` ```json theme={null} { "ok": false, "error": { "code": "INSUFFICIENT_PERMISSIONS", "message": "Permission check failed - PERMISSION_CHECK_FAILED" } } ``` ### Internal Error **HTTP Status:** `500 Internal Server Error` ```json theme={null} { "ok": false, "error": { "code": "INTERNAL_ERROR", "message": "Internal error" } } ``` ## Best Practices * Use `cursor` and `limit` together to paginate; `nextCursor` in the response can be used as the `cursor` value for the next call * `startDate` and `endDate` are interpreted against the column specified by `dateType` — change `dateType` to filter by due, payment, created, or approval date instead of the issued date * Use the `id` from the response as the input to the [Invoice Details API](/apis/invoice-details) for full invoice information * The API returns at most 100 invoices per call regardless of the `limit` value