---
title: "Add roster members"
method: POST
path: "/api/v1/discovery/roster-members/add"
tags: ["discovery"]
---

# Add roster members

`POST /api/v1/discovery/roster-members/add`

## Request

- Base URL: `https://point11.ai`
- URL: `https://point11.ai/api/v1/discovery/roster-members/add`
- 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`)

Add customers to a Discovery campaign's roster. They join this month's calendar, so its next run interviews them, and their conversations accrue against the organization's plan. Refused on a campaign that is not active or paused or is a one-time campaign whose run has finished, while its first run is still choosing its customers, when any customer cannot join (each named with its reason), or when Billing would not admit the work; read discovery_roster_quotes_get first. Returns how many joined and when they start.

## Headers

- `Point11-Organization` string, uuid
- `Idempotency-Key` string, uuid, required

## Request body

- DiscoveryRosterMembersAddRequest
  - `campaignId` string, required: The Discovery campaign's id, or its campaign key.
  - `customerIds` string[], required: The customers' ids (1–1000)

## Response `200`

Success.

- DiscoveryRosterMembersAddResponse
  - `changed` integer, required: Customers who joined.
  - `start` object, nullable, required: When they start; null when none joined.
    - `cycle` string, required: The UTC month (YYYY-MM) they are placed in.
    - `thisCycle` boolean, required: Whether that is the month they joined in, not the next one.
    - `firstConversationAt` string, date-time, nullable, required: The earliest their first conversation can start; null while no run is coming.

## Other responses

- `400`: The input, query, or Idempotency-Key is invalid.
- `401`: The bearer is missing, expired, or not accepted.
- `402`: Billing refused the write: the code names the reason and `details.reason` carries it.
- `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/36a84c7aca11?raw)