PRprivy
Segments

List a segment's contacts

Changed on

Retrieve the segment's members as a paginated list of contacts, in the same shape as the Contacts API, most recently created first.

Membership is computed periodically, so the list may be up to an hour old (see counts.refreshed_at on the segment). If the segment's membership has never been computed, this endpoint returns 202 Accepted, starts the computation in the background, and you should retry shortly.

Every member is returned whatever their consent state, so pagination.total_count is the segment's total membership, as its total_count was at the last refresh. It is neither the segment's mailable_count nor its textable_count — those are consent-filtered counts taken at the last refresh.

Required scope: segments_read

get/segments/{id}/contacts

Request

  • Base URL
    https://api.privy.com/v1
  • Auth
    HTTP bearer

Path parameters

idstring required

The segment's unique identifier (returned as id in segment responses). Ids are opaque public strings — a numeric id from a Privy dashboard URL is not a valid API id and will 404; list segments and match by name instead.

Query parameters

pageinteger

Page number (starts at 1).

per_pageinteger

Number of results per page. Values outside 10–100 are clamped to the nearest bound.

Headers

Privy-Account-Idstring

Target a subaccount instead of the main connected account. Pass a subaccount id from get_account's subaccounts list. Only direct subaccounts of the connected account are reachable — omit this for the main account itself.

Response

A paginated list of the segment's member contacts.

Example response

{
  "data": [
    {
      "id": "cus_a1b2c3d4e5f6g7h8",
      "first_name": "Jane",
      "last_name": "Doe",
      "email": "jane@example.com",
      "email_consent": "subscribed",
      "email_consent_at": "2025-03-20T14:22:00Z",
      "phone_number": "+15551234567",
      "sms_consent": "subscribed",
      "sms_consent_at": "2025-03-20T14:22:00Z",
      "source": "csv",
      "source_type": "import",
      "imported": true,
      "import_ids": [
        "im_k2R5m8Q"
      ],
      "tags": [
        "vip",
        "repeat-buyer"
      ],
      "custom_fields": {
        "loyalty_tier": "gold",
        "referral_code": "JANE2024"
      },
      "created_at": "2025-01-15T10:30:00Z",
      "updated_at": "2025-03-20T14:22:00Z"
    }
  ],
  "pagination": {
    "page": 1,
    "per_page": 25,
    "total_count": 142,
    "total_pages": 6
  }
}

Changes

  • cf0885e90d5aRevision changes
    • warning

      added the new forbidden enum value to the / response property for the response status

    • warning

      added the new forbidden enum value to the / response property for the response status

    • warning

      added the new forbidden enum value to the / response property for the response status

    • warning

      added the new forbidden enum value to the / response property for the response status

    • warning

      added the new forbidden enum value to the / response property for the response status

    • warning

      added the new segment_builder_required enum value to the / response property for the response status

    • warning

      added the new segment_builder_required enum value to the / response property for the response status

    • warning

      added the new segment_builder_required enum value to the / response property for the response status

    • warning

      added the new segment_builder_required enum value to the / response property for the response status

    • warning

      added the new segment_builder_required enum value to the / response property for the response status

  • fe500ab59b3bRevision changes
    • info

      endpoint added