> ## Documentation Index > Fetch the complete documentation index at: https://www.vobiz.ai/docs/llms.txt > Use this file to discover all available pages before exploring further. # List recipients > Returns the broadcast's recipients in upload order, each with its template `variables` and per-recipient send state. Filter by `status` to find failures, opted-out numbers or rows still waiting to send. ## OpenAPI ````yaml openapi-sms.yaml GET /broadcasts/{id}/recipients openapi: 3.0.3 info: title: Vobiz Messaging API description: > Send and receive SMS, MMS and RCS messages, buy messaging numbers, register for US 10DLC and toll-free, run broadcasts, manage conversations, opt-outs and webhooks. **Base URL:** `https://api.vobiz.ai/api/v1/sms` **Authentication:** every request needs the `X-Auth-ID` and `X-Auth-Token` headers. The account is taken from your credentials; you never put an account ID in a path or body. Field names in this API are camelCase. version: '1.0' contact: email: support@vobiz.ai url: https://vobiz.ai servers: - url: https://api.vobiz.ai/api/v1/sms description: Production security: - AuthID: [] AuthToken: [] tags: - name: Messages description: Send messages and inspect their delivery state. - name: Numbers description: >- Messaging-capable numbers on your account, inventory search, purchase and release. - name: Coverage description: Where you can send, per country. - name: Conversations description: Two-way threads between one of your numbers and a contact. - name: Opt-outs description: Numbers that must not receive messages on a channel. - name: Webhooks description: Subscriptions that deliver message and broadcast events to your server. - name: Broadcasts description: Bulk sends from an uploaded recipient list. - name: RCS Senders description: RCS sender (agent) identities and their message templates. - name: 10DLC Brands description: US 10DLC brand registration. - name: 10DLC Campaigns description: US 10DLC campaigns, toll-free verification and supporting documents. paths: /broadcasts/{id}/recipients: parameters: - name: id in: path required: true description: >- The broadcast's `id` (UUID), as returned by `POST /broadcasts` or `GET /broadcasts`. An id that is not a UUID, or that belongs to another account, returns `404` with `broadcast not found`. schema: type: string format: uuid example: 3f8d2a6e-5b1c-4e7f-a9d0-2c4b6e8f1a35 get: tags: - Broadcasts summary: List recipients description: >- Returns the broadcast's recipients in upload order, each with its template `variables` and per-recipient send state. Filter by `status` to find failures, opted-out numbers or rows still waiting to send. The response gives the page in `recipients` and the count matching your filter in `total`. For a downloadable file of the same data, use `GET /broadcasts/{id}/export`. operationId: list-recipients parameters: - name: status in: query description: >- Return only recipients in this state, matched case-insensitively. `pending` waits to send, `sending` is in progress, `sent` and `delivered` track the message, `failed` has an `errorCode`, `opted_out` was excluded because the number opted out, and `skipped` was still pending when the broadcast was cancelled. Omit it to return every recipient; any other value returns `400`. schema: type: string enum: - pending - sending - sent - delivered - failed - opted_out - skipped - name: limit in: query description: >- Maximum number of recipients to return, from 1 to 500. Defaults to 50 when you omit it or pass `0`. A value above 500 returns `400` with `limit must be between 1 and 500`, and a non-integer returns `400` with `limit must be an integer`. schema: type: integer minimum: 1 maximum: 500 default: 50 - name: offset in: query description: >- Number of recipients to skip before the page starts, for paging through results with `limit`. Defaults to `0`. A negative value returns `400` with `offset must be >= 0`, and a non-integer returns `400` with `offset must be an integer`. schema: type: integer minimum: 0 default: 0 responses: '200': description: A page of recipients. content: application/json: schema: $ref: '#/components/schemas/BroadcastRecipientList' example: recipients: - id: 1042 row: 2 to: '+14155550123' variables: name: Priya amount: $42.00 status: sent messageId: 9b2e1c40-8a3d-4f5e-9c1a-7d6b2e8f4a01 errorCode: '' errorMessage: '' sentAt: '2026-10-12T11:05:10Z' - id: 1043 row: 3 to: '+14155550124' variables: name: Sam amount: $18.50 status: pending messageId: '' errorCode: '' errorMessage: '' sentAt: null total: 2 '400': description: '`status`, `limit` or `offset` is invalid.' content: application/json: schema: $ref: '#/components/schemas/Error' examples: status: value: error: >- status must be one of pending, sending, sent, delivered, failed, opted_out, skipped limit: value: error: limit must be between 1 and 500 '401': $ref: '#/components/responses/Unauthorized' '404': description: The broadcast does not exist on your account. content: application/json: schema: $ref: '#/components/schemas/Error' example: error: broadcast not found x-codeSamples: - lang: typescript label: Node SDK source: > import { VobizClient } from "@vobiz/sdk"; const client = new VobizClient({ apiKey: "MA_XXXXXXXX", authToken: "YOUR_AUTH_TOKEN" }); await client.sms.broadcasts.listRecipients({ id: "3f8d2a6e-5b1c-4e7f-a9d0-2c4b6e8f1a35" }) - lang: python label: Python SDK source: | from vobiz import Vobiz client = Vobiz(api_key="MA_XXXXXXXX", auth_token="YOUR_AUTH_TOKEN") client.sms.broadcasts.list_recipients( id="3f8d2a6e-5b1c-4e7f-a9d0-2c4b6e8f1a35", ) - lang: go label: Go SDK source: | import ( "context" vobiz "github.com/vobiz-ai/Vobiz-Go-SDK" "github.com/vobiz-ai/Vobiz-Go-SDK/client" "github.com/vobiz-ai/Vobiz-Go-SDK/option" "github.com/vobiz-ai/Vobiz-Go-SDK/sms" ) c := client.NewClient( option.WithAPIKey("MA_XXXXXXXX"), option.WithAuthToken("YOUR_AUTH_TOKEN"), ) request := &sms.ListRecipientsRequest{ ID: "3f8d2a6e-5b1c-4e7f-a9d0-2c4b6e8f1a35", } c.Sms.Broadcasts.ListRecipients( context.TODO(), request, ) - lang: java label: Java SDK source: | import com.vobiz.api.VobizApiClient; VobizApiClient client = VobizApiClient .builder() .apiKey("MA_XXXXXXXX") .authToken("YOUR_AUTH_TOKEN") .build(); client.sms().broadcasts().listRecipients( "3f8d2a6e-5b1c-4e7f-a9d0-2c4b6e8f1a35", ListRecipientsRequest .builder() .build() ); - lang: ruby label: Ruby SDK source: > require 'vobiz' client = Vobiz::Client.new(api_key: 'MA_XXXXXXXX', auth_token: 'YOUR_AUTH_TOKEN') client.sms.broadcasts.list_recipients(id: "3f8d2a6e-5b1c-4e7f-a9d0-2c4b6e8f1a35") - lang: csharp label: C# SDK source: | using Vobiz; using Vobiz.Sms; var client = new VobizApiClient("YOUR_AUTH_TOKEN", "MA_XXXXXXXX"); await client.Sms.Broadcasts.ListRecipientsAsync( new ListRecipientsRequest { Id = "3f8d2a6e-5b1c-4e7f-a9d0-2c4b6e8f1a35" } ); - lang: php label: PHP SDK source: > sms->broadcasts->listRecipients( '3f8d2a6e-5b1c-4e7f-a9d0-2c4b6e8f1a35', new ListRecipientsRequest([]), ); components: schemas: BroadcastRecipientList: type: object properties: recipients: type: array items: $ref: '#/components/schemas/BroadcastRecipient' description: The recipients on this page, in upload order. total: type: integer description: >- Number of recipients that match the `status` filter across all pages, or all recipients when you pass no filter. example: 3 description: >- One page of a broadcast's recipients, in upload order, with the count that matches your filter. Error: type: object description: >- The body of every error response: a flat object with one `error` string that explains what went wrong. Use the HTTP status code to decide how to handle the error, and log `error` for diagnosis. required: - error properties: error: type: string example: 'recipient has opted out: +14155550123' description: >- Human-readable explanation of the error, for example `phoneNumber is required` or `recipient has opted out: +14155550123`. Branch on the HTTP status code rather than on this text. BroadcastRecipient: type: object description: >- One recipient of a broadcast: the normalised number, the variables from its upload row and the state of its message. properties: id: type: integer format: int64 example: 1042 description: >- Numeric identifier of the recipient within Vobiz. Used in the broadcast's per-recipient idempotency key. row: type: integer description: >- Where the recipient came from in the upload. For a file it is the line number in the file, so with a header line the first data row is `2`; for a JSON `numbers` array it is the 1-based position. example: 2 to: type: string description: The recipient's number, normalised to E.164. example: '+14155550123' variables: type: object description: >- Every column value from the recipient's upload row, keyed by the column name as written in your header, including the phone column. Used to fill the template. Only the phone column is present for JSON uploads. additionalProperties: type: string example: name: Priya amount: $42.00 status: type: string enum: - pending - sending - sent - delivered - failed - opted_out - skipped example: sent description: >- The recipient's send state: `pending`, `sending`, `sent`, `delivered`, `failed`, `opted_out` (excluded because the number opted out of SMS from you) or `skipped` (still pending when the broadcast was cancelled). messageId: type: string description: >- The `id` of the message sent to this recipient; look it up with `GET /messages/{id}`. Empty string until the message is sent. example: 9b2e1c40-8a3d-4f5e-9c1a-7d6b2e8f4a01 errorCode: type: string description: >- Why the send failed: the message's `errorCode`, or `send_failed` / `routing_failed`. Empty string unless `status` is `failed`. example: '' errorMessage: type: string example: '' description: >- Human-readable detail for a failed send. Empty string unless `status` is `failed`. sentAt: type: string format: date-time nullable: true example: '2026-10-12T10:30:02Z' description: >- When the message to this recipient was sent (ISO 8601, UTC). `null` until then. responses: Unauthorized: description: Missing or invalid `X-Auth-ID` / `X-Auth-Token`. content: application/json: schema: $ref: '#/components/schemas/Error' example: error: missing or invalid credentials securitySchemes: AuthID: type: apiKey in: header name: X-Auth-ID description: Your Vobiz account Auth ID (`MA_XXXXXXXX`). AuthToken: type: apiKey in: header name: X-Auth-Token description: Your Vobiz account Auth Token. ```` This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.