# List invoices

`GET /v1/invoices`

Returns the company's invoices, credit notes and offers, newest issue date first; check `type`. A malformed `contact_id`, `from_date` or `to_date` returns 400. An unknown `status` returns an empty list. An out-of-range `limit` or `offset` is clamped rather than refused: `limit` to 1-500, and 0 or a value that is not a number falls back to the default.

**Scopes:** any of `invoices:read`, `read:ledger`

## Request

```bash
curl https://api.numina.app/v1/invoices \
  -H "Authorization: Bearer numi_YOUR_API_KEY"
```

## Query parameters

- `status` (string, optional): Filter by status. A value that does not exist returns an empty list. One of: `draft`, `sent`, `closed`, `paid`, `cancelled`, `accepted`, `declined`.
- `contact_id` (string (uuid), optional): Filter by contact ID
- `from_date` (string, optional): Filter invoices issued on or after this date (YYYY-MM-DD) (YYYY-MM-DD)
- `to_date` (string, optional): Filter invoices issued on or before this date (YYYY-MM-DD) (YYYY-MM-DD)
- `limit` (integer, optional): Maximum number of results (default 100). Clamped to 1-500. Default: `100`. (1–500)
- `offset` (integer, optional, nullable): Number of results to skip for pagination Default: `0`. (≥ 0)

## Response `200`

List of invoices

```json
{
  "invoices": [
    {
      "id": "550e8400-e29b-41d4-a716-446655440000",
      "invoice_number": 1001,
      "type": "invoice",
      "credited_invoice_id": "550e8400-e29b-41d4-a716-446655440000",
      "status": "sent",
      "issue_date": "2026-01-15",
      "due_date": "2026-02-15",
      "contact_id": "550e8400-e29b-41d4-a716-446655440001",
      "contact_name": "Acme ApS",
      "currency": "DKK",
      "subtotal": 10000,
      "vat": 2500,
      "vat_rate": 25,
      "total": 12500,
      "has_mixed_vat": false,
      "outstanding_balance": 12500,
      "outstanding_balance_currency": "DKK",
      "currency_rate": 0,
      "delivery_status": "sent",
      "email_delivery_status": "string",
      "email_sent_at": "string",
      "e_invoice_sent_at": "string",
      "is_overdue": false,
      "payment_state": "open",
      "unmatched_payments_note": "string",
      "items": [
        {
          "unit": "string",
          "vat_account_id": "string",
          "vat_code": "string",
          "sales_account_number": 0,
          "vat_rate": 0,
          "id": "550e8400-e29b-41d4-a716-446655440002",
          "description": "Consulting services",
          "quantity": 10,
          "unit_price": 1000
        }
      ],
      "memo": "Project Q1 delivery",
      "payment_details": {
        "bank_name": "Danske Bank",
        "scheme": "dk-registration-number",
        "clearing_code": "3409",
        "account_number": "0012345678",
        "iban": "DK5030000012345678",
        "swift_bic": "DABADKKK"
      },
      "created_at": "2026-01-15T10:30:00Z"
    }
  ],
  "has_more": false,
  "next_offset": 0
}
```

## Errors

- `400` Bad Request - Invalid input or validation failed
- `401` Unauthorized - Invalid or missing authentication
- `403` Forbidden - Missing scope, or the company is archived
- `429` Too Many Requests - Rate limit exceeded
- `500` Internal Server Error

See https://developers.numina.app/errors.md for the error format.