# List contacts

> List contacts on the connected account, newest first.

Source: https://sndr.sh/docs/cranl/contacts/list-contacts

`GET https://api.sndr.sh/api/cranl/v1/contacts`

List contacts on the connected account, newest first. Cursor-paginated; counts holds account-wide totals per status.

Scope: `read`

**Query parameters**

- `limit` (integer): Page size. Default 50, max 200.
- `cursor` (string): The next_cursor value from the previous page. Omit for the first page.
- `status` (string): Only contacts with this status: subscribed | unsubscribed | bounced | complained.
- `group_id` (string): Only contacts in this group (grp_...).
- `q` (string): Case-insensitive search in email, first name and last name.

**Request**

```bash
curl 'https://api.sndr.sh/api/cranl/v1/contacts?status=subscribed&limit=20' \
  -H 'Authorization: Bearer sndr_your_access_token'
```

**Response** (200)

```json
{
  "data": [
    {
      "id":              "con_0e6b7f21-c58",
      "organization_id": "org_8d41c7a2-3f6",
      "email":           "jane@example.com",
      "first_name":      "Jane",
      "last_name":       "Doe",
      "attributes":      { "plan": "pro", "city": "Berlin" },
      "status":          "subscribed",
      "source":          "checkout",
      "created_at":      "2026-03-01T10:00:00Z",
      "updated_at":      "2026-03-01T10:00:00Z"
    }
  ],
  "has_more": false,
  "count":    1,
  "limit":    20,
  "counts":   { "subscribed": 1, "unsubscribed": 0, "bounced": 0, "complained": 0 }
}
```

**Errors**

- `unauthenticated` (401): Missing or invalid Bearer token.
- `token_expired` (401): Access token expired — exchange the refresh token for a new pair.
- `token_revoked` (401): Token was explicitly revoked.
- `insufficient_scope` (403): Token is missing the read scope.
- `validation_failed` (422): limit is above 200, or cursor is not a value returned as next_cursor.