# List contacts

`GET /contacts`

Returns customer contacts for one shop (`shop_id`) or all your shops,
sorted by creation date descending, with visit, order, opt-in and
loyalty information.

Requires the `contacts:read` scope.

**Returns** a `data` array of up to `limit` contacts and a
`pagination` object. Fetch the next page by passing
`pagination.next_cursor` back as `cursor`, until `has_more` is
`false`. `data` is empty when nothing matches the filters.

Contacts are unique per shop and phone number; `sources` lists every
channel that collected the contact, and `has_loyalty` flags loyalty
program members. For a full export, paginate until `has_more` is
`false`: cursor pagination guarantees every contact is returned exactly
once even while new ones are being created.

## Example request

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

## Query parameters

- `shop_id` (string) – Restrict to a single shop (omit to query all your shops)
- `source` (string) (one of: apitic, zenchef, genlog, zelty, unknown, game, loyalty, fork, imported, manual, campaign, yavin, deliverect, audience) – Filter by the source that collected the contact
- `sms_optin` (boolean) – Filter by SMS opt-in status
- `from` (string) (format: date) – Only contacts created on or after this date
- `to` (string) (format: date) – Only contacts created on or before this date
- `cursor` (string) – Opaque cursor from the previous response's `pagination.next_cursor`
- `limit` (integer) (default: 25; min: 1; max: 100) – Number of items per page

## Responses

### 200 – Paginated list of contacts

```json
{
  "data": [
    {
      "id": "66c3d4e5f6a7b8c9d0e1f2a3",
      "shop_id": "64f1a2b3c4d5e6f7a8b9c0d1",
      "phone": "+33612345678",
      "firstname": "Marie",
      "lastname": "Dupont",
      "gender": "female",
      "emails": [
        "marie.dupont@example.com"
      ],
      "birthdate": "1990-04-12T00:00:00.000Z",
      "sources": [
        "loyalty",
        "campaign"
      ],
      "total_visits": 14,
      "last_visit_date": "2026-07-20T19:42:00Z",
      "total_order_amount": 412.5,
      "last_order_date": "2026-07-20T19:42:00Z",
      "sms_optin": true,
      "sms_blacklisted": false,
      "has_loyalty": true,
      "created_at": "2025-11-03T12:00:00Z"
    }
  ],
  "pagination": {
    "next_cursor": null,
    "has_more": false
  }
}
```

### 401 – Missing, invalid, or revoked API key

### 403 – The API key does not grant access to this resource

### 422 – Invalid request parameters

Errors are `application/problem+json` (RFC 9457) with `type`, `title`, `status` and `detail` fields.