---
title: "List audience contacts"
method: GET
path: "/audience/contacts"
tags: ["Audience"]
---

# List audience contacts

`GET /audience/contacts`

## Request

- Base URL: `https://app.lettr.com/api`
- URL: `https://app.lettr.com/api/audience/contacts`
- Auth: HTTP bearer

List contacts with pagination and filtering. Requires the `audience:read` scope.

## Query parameters

- `page` integer
- `per_page` integer
- `search` string
- `status` 'subscribed' | 'unsubscribed' | 'bounced' | 'complained' | 'unverified'
- `list_id` string, uuid
- `segment_id` string, uuid

## Response `200`

Contacts retrieved successfully.

- ListAudienceContactsResponse
  - `message` string, required
  - `data` object, required
    - `contacts` AudienceContactView[], required
      - `id` string, uuid, required
      - `email` string, email, required
      - `status` 'subscribed' | 'unsubscribed' | 'bounced' | 'complained' | 'unverified', required: Contact subscription status
      - `properties` object, required: Custom properties for the contact (string values)
      - `created_at` string, date-time, required
      - `paused_until` string, date-time, nullable, required: End of the contact's send pause, set from the unsubscribe page. While this is in the future the contact keeps status subscribed but campaigns are not delivered to them.
      - `lists` AudienceContactListLink[], required
        - `id` string, uuid, required
        - `name` string, required
      - `topics` AudienceContactTopicLink[], required
        - `id` string, uuid, required
        - `name` string, required
    - `pagination` AudiencePagination, required: Pagination info for audience list responses
      - `total` integer, required: Total items
      - `per_page` integer, required: Items per page
      - `current_page` integer, required: Current page (1-indexed)
      - `last_page` integer, required: Last available page (= ceil(total / per_page), minimum 1)

## Other responses

- `401`: Unauthorized - Missing or invalid API key
- `403`: Forbidden - API key does not have the required scope
- `422`: Validation error
- `500`: Internal server error
- `503`: Service unavailable - the API key could not be verified, so the request was not processed. This does not mean the key is invalid; retry after the delay given in the Retry-After header.

---

[API](https://skmtc.dev/lettr/apis/lettr-api.md) · [All operations](https://skmtc.dev/lettr/apis/lettr-api/llms.txt) · [OpenAPI document](https://skmtc.dev/lettr/apis/lettr-api/revisions/48ef0dac1ebd?raw)