# List contacts

`GET /v1/contacts`

Returns a page of your workspace's contacts, newest first.

Needs `contacts:read`.

## Query parameters

- `limit` (integer): How many items to return. From 1 to 100. Default `25`.
- `cursor` (string): The `next_cursor` of the previous page, unchanged. A cursor that was changed, or made for a different `sort`, is `400 invalid_request`.
- `sort` (string): `created_at` lists newest first. `updated_at` lists oldest change first. Default `created_at`.
- `phone` (string): Only the contact with this number. Any spelling of the number works (spaces and dashes are ignored, and `00` counts as `+`). A number that isn't valid is `422 invalid_phone`.
- `tag` (array of strings): Only contacts that have this tag. Repeat it to get contacts that have any of the tags (at most 50).
- `created_after` (string, date-time): Only contacts created after this time (RFC 3339).
- `updated_after` (string, date-time): Only contacts changed after this time (RFC 3339). A change shows up about 30 seconds after it's saved.

## Syncing changes

Use `sort=updated_at` to copy changes into your own system. A contact moves to the end of the list each time it changes. Resume a minute early and skip contacts you already have. See [Pagination](/reference/api/#pagination).

## Phone numbers

A key with `contacts:read` sees full phone numbers. The app's masking settings don't apply to keys.

## Example

```sh
curl "https://app.soosh.io/v1/contacts?sort=updated_at&updated_after=2026-10-13T09%3A30%3A00Z&limit=50" \
  -H "Authorization: Bearer $SOOSH_API_KEY"
```

Response 200:

```json
{
  "data": [
    {
      "id": "4ea0d485-435d-407f-837a-c7d67095f23a",
      "phone": "+919876543210",
      "whatsapp_user_id": null,
      "name": "Priya Sharma",
      "whatsapp_name": "Priya S",
      "attributes": {
        "customer_id": "8812",
        "city": "Pune",
        "orders": 3
      },
      "tags": [
        "VIP"
      ],
      "marketing_opt_out": false,
      "number_id": "0f6d3c1e-5b7a-4c52-9a55-3f6a2d5c8b10",
      "chat": {
        "status": "open",
        "assigned_agent_id": "5b1d7d0e-3c2a-4f61-9a0e-6f8f3b2c1d40",
        "last_message_at": "2026-10-14T09:30:12.481Z",
        "last_inbound_at": "2026-10-14T09:12:40.117Z"
      },
      "created_at": "2026-10-14T09:05:11.420Z",
      "updated_at": "2026-10-14T09:30:12.481Z"
    }
  ],
  "next_cursor": null
}
```

## Returns

200. A page of contacts.

## Errors

Besides the ones every request can get (https://docs.soosh.io/reference/api/errors/):

- 422 `invalid_phone`: The `phone` filter isn't a valid number.