# List contacts

`GET /v1/contacts`

Returns the company's contacts, including archived ones, ordered by name. 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 `contacts:read`, `read:ledger`

## Request

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

## Query parameters

- `search` (string, optional): Part of the name, or the exact CVR number
- `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 contacts

```json
{
  "contacts": [
    {
      "id": "550e8400-e29b-41d4-a716-446655440000",
      "name": "Acme ApS",
      "cvr": 12345678,
      "vat_number": "DK12345678",
      "country_code": "DK",
      "address_street": "Vestergade 1",
      "address_zip": "1456",
      "address_city": "Copenhagen",
      "country": "Denmark",
      "email": "billing@acme.dk",
      "phone": "+45 12 34 56 78",
      "attn_person": "Jane Doe",
      "e_invoice_number": "12345678",
      "e_invoice_scheme": "DK:CVR",
      "archived": false
    }
  ],
  "has_more": false,
  "next_offset": 0
}
```

## Errors

- `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.