GET/io/contacts/contacts

Returns a paginated list of the acting user's contacts.

Query parameters

user_idstringquery

Required when using service-key auth. Must be a valid UUID.

pageintegerquery

Page number (default 1).

limitintegerquery

Contacts per page, 1–100 (default 20).

statusstringquery

Filter by status: subscribed | unsubscribed | bounced | complained.

searchstringquery

Partial match on email, first_name, or last_name.

sortBystringquery

created_at (default) | email | last_engagement_at | lead_score.

sortOrderstringquery

desc (default) | asc.

workspace_idstringquery

Filter to a specific workspace UUID.

{
  "data": [
    {
      "id": "cnt_abc123",
      "user_id": "usr_xyz",
      "email": "[email protected]",
      "first_name": "Alice",
      "last_name": "Smith",
      "status": "subscribed",
      "engagement_tier": "high",
      "lead_score": 72,
      "created_at": "2026-01-15T10:00:00Z",
      "updated_at": "2026-05-20T08:30:00Z"
    }
  ],
  "pagination": {
    "total": 1240,
    "page": 1,
    "limit": 20,
    "totalPages": 62
  }
}

List Contacts