---
title: "List roster members (v4)"
method: GET
path: "/api/v1/discovery/roster-members-v4"
tags: ["discovery"]
---

# List roster members (v4)

`GET /api/v1/discovery/roster-members-v4`

## Request

- Base URL: `https://point11.ai`
- URL: `https://point11.ai/api/v1/discovery/roster-members-v4`
- Auth: one of:
  - HTTP bearer
  - OAuth 2 (authorization code, authorization URL `https://auth.point11.ai/oauth2/authorize`, token URL `https://auth.point11.ai/oauth2/token`)

List a Discovery campaign's customers (its roster): the current ones by default, or the removed ones, or all; searched by name, narrowed to audiences, and sorted. Each row is the customer with when it joined, whether and when it was removed, and its conversations, brand share and win rate in this campaign. Also answers the roster's counts, whether it can be changed now (and why not), and the audiences to narrow by.

## Query parameters

- `limit` integer: Number of customers to return (1–100)
- `cursor` string: Opaque cursor returned as nextCursor by the previous page
- `campaignId` string, required: The Discovery campaign's id, or its campaign key.
- `search` string: Words a customer's name contains.
- `audiences` string[]: Source and label names: a customer in any named source and in any named label (system audiences are labels) is listed; a kind none names narrows nothing.
- `sortColumn` 'customerId' | 'name' | 'profile' | 'performance' | 'employer' | 'location' | 'audiences' | 'sources' | 'status' | 'membershipStatus' | 'conversations' | 'brandShare' | 'brandWinRate' | 'age' | 'householdIncome' | 'headcount' | 'annualRevenue' | 'trigger' | 'intentStage' | 'language' | 'createdAt': Default createdAt.
- `sortDirection` 'asc' | 'desc': Default desc.
- `status` 'current' | 'removed' | 'all': Which memberships to list.

## Headers

- `Point11-Organization` string, uuid

## Response `200`

Success.

- DiscoveryRosterMembersListV4Response
  - `data` object[], required
    - `id` string, uuid, required
    - `customerKey` string, nullable, required
    - `label` string, required
    - `businessProfileId` string, uuid, required
    - `businessProfileKey` string, nullable, required
    - `profileName` string, nullable, required
    - `profileUrl` string, required
    - `profileBusinessSummary` string, nullable, required
    - `source` 'generated' | 'manual' | 'connected', required
    - `poolStatus` 'active' | 'retired', required
    - `retiredAt` string, date-time, nullable, required
    - `forecastSeeded` boolean, required
    - `audiences` string[], required
    - `systemAudiences` string[], required
    - `userAudiences` string[], required
    - `userAudienceIds` string[], required
    - `sources` string[], required
    - `jobTitle` string, nullable, required
    - `gender` object, nullable, required: Gender
      - `id` string, nullable, required
      - `label` string, nullable, required
    - `age` number, nullable, required: Age
    - `age.band` object, nullable, required: Age band
      - `id` string, nullable, required
      - `label` string, nullable, required
    - `language` object, nullable, required: Language
      - `id` string, nullable, required
      - `label` string, nullable, required
    - `location` string, nullable, required: Location
    - `market` object, nullable, required: Market
      - `id` string, nullable, required
      - `label` string, nullable, required
    - `areaType` object, nullable, required: Area type
      - `id` string, nullable, required
      - `label` string, nullable, required
    - `education` object, nullable, required: Education
      - `id` string, nullable, required
      - `label` string, nullable, required
    - `lifeStage` object, nullable, required: Life stage
      - `id` string, nullable, required
      - `label` string, nullable, required
    - `householdIncome` number, nullable, required: Household income
    - `householdIncome.band` object, nullable, required: Income band
      - `id` string, nullable, required
      - `label` string, nullable, required
    - `occupation` object, nullable, required: Occupation
      - `id` string, nullable, required
      - `label` string, nullable, required
    - `seniority` object, nullable, required: Seniority
      - `id` string, nullable, required
      - `label` string, nullable, required
    - `employer` string, nullable, required: Employer
    - `companySize` number, nullable, required: Company size
    - `companySize.band` object, nullable, required: Size band
      - `id` string, nullable, required
      - `label` string, nullable, required
    - `annualRevenue` number, nullable, required: Annual revenue
    - `buyerType` object, nullable, required: Buyer type
      - `id` string, nullable, required
      - `label` string, nullable, required
    - `audience` object, nullable, required: Audience
      - `id` string, nullable, required
      - `label` string, nullable, required
    - `product` object, nullable, required: Product
      - `id` string, nullable, required
      - `label` string, nullable, required
    - `channel` object, nullable, required: Channel
      - `id` string, nullable, required
      - `label` string, nullable, required
    - `buyerRole` object, nullable, required: Buyer role
      - `id` string, nullable, required
      - `label` string, nullable, required
    - `intentStage` object, nullable, required: Intent stage
      - `id` string, nullable, required
      - `label` string, nullable, required
    - `job` object, nullable, required: Job to be done
      - `id` string, nullable, required
      - `label` string, nullable, required
    - `triggerType` object, nullable, required: Trigger type
      - `id` string, nullable, required
      - `label` string, nullable, required
    - `trigger` string, nullable, required: Trigger
    - `createdAt` string, date-time, required
    - `generationRunId` string, uuid, nullable, required
    - `latestDiscoveryOutcome` DiscoveryItemLatestDiscoveryOutcome, nullable, required
      - `result` 'won' | 'lost', required
      - `brand` string, required
      - `color` string, nullable
      - `source` object, nullable
        - `url` string, nullable, required
        - `label` string, required
        - `faviconUrl` string, nullable, required
        - `faviconTone` 'dark' | 'light' | 'mixed' | 'unknown', nullable
        - `faviconTransparent` boolean, nullable
        - `faviconNeedsLightBackplate` boolean, nullable
        - `faviconNeedsDarkBackplate` boolean, nullable
        - `color` string, nullable
    - `rosterMembershipId` string, uuid, required
    - `sampledAt` string, date-time, required: When the customer joined the roster.
    - `removedAt` string, date-time, nullable, required
    - `removedByUserId` string, uuid, nullable, required
    - `membershipStatus` 'current' | 'removed' | 'archived_in_pool', required: `archived_in_pool` is on the roster but archived in Business.
    - `performance` object, required: This campaign's conversations with the customer.
      - `totalConversations` integer, required
      - `brandShareCount` integer, required
      - `brandWinCount` integer, required
      - `brandSharePct` number, required
      - `brandWinRatePct` number, required
      - `latestOutcome` DiscoveryItemLatestDiscoveryOutcome, nullable, required
        - `result` 'won' | 'lost', required
        - `brand` string, required
        - `color` string, nullable
        - `source` object, nullable
          - `url` string, nullable, required
          - `label` string, required
          - `faviconUrl` string, nullable, required
          - `faviconTone` 'dark' | 'light' | 'mixed' | 'unknown', nullable
          - `faviconTransparent` boolean, nullable
          - `faviconNeedsLightBackplate` boolean, nullable
          - `faviconNeedsDarkBackplate` boolean, nullable
          - `color` string, nullable
  - `nextCursor` string, nullable, required
  - `totalCount` integer, required: Customers the search and audiences keep.
  - `pageIndex` integer, required: How many whole pages of this limit sort before the page answered.
  - `facetOptions` object[], required: The audiences to narrow by.
    - `id` string, required
    - `value` string, required
    - `label` string, required
    - `count` integer, required
    - `kind` 'source' | 'system-audience' | 'user-audience', required
  - `facetTotalCount` integer, required
  - `query` string, required: The search as the roster read it.
  - `editable` boolean, required: Whether the roster can change now.
  - `editBlockedReason` string, nullable, required: Why it cannot, when it cannot.
  - `audienceTypes` string[], required: The audience types of the customers this list draws from, each read as a Buyer type (b2c is B2C; b2b, prosumer and mixed are B2B); a column only another Buyer type carries is not a column.
  - `campaignId` string, uuid, required
  - `businessProfileId` string, uuid, required
  - `included` integer, required: Customers on the roster now.
  - `currentCount` integer, required
  - `removedCount` integer, required
  - `archivedInPoolCount` integer, required
  - `status` 'current' | 'removed' | 'all', required
  - `campaign` object, required
    - `id` string, uuid, required
    - `campaignKey` string, nullable, required
    - `name` string, nullable, required
    - `status` 'active' | 'paused' | 'archived' | 'deleted', required
    - `changeable` boolean, required: Whether its status admits roster changes: active or paused.

## Other responses

- `400`: The input, query, or Idempotency-Key is invalid.
- `401`: The bearer is missing, expired, or not accepted.
- `403`: The credential lacks the operation's scope or role, or the operation needs a different door.
- `404`: The resource or organization does not exist for this caller.
- `405`: This path takes another HTTP method, named in `Allow`.
- `409`: The request conflicts with current state or with prior use of its Idempotency-Key.
- `413`: The request, or the answer it asks for, is too large; narrow it.
- `429`: The credential's rate budget is spent; retry after `Retry-After` seconds.
- `500`: An unexpected server failure; retry later. Only `request_id` identifies it.
- `503`: A dependency is temporarily unavailable; retry after `Retry-After` seconds.
- `default`: Another status a product answers for its own refusal (for example `415` for an unsupported attachment); branch on `code`.

---

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