> ## 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 opt-outs > Returns the numbers on your opt-out list, newest first, including entries created from STOP, START and HELP keyword replies and the ones you added. ## OpenAPI ````yaml openapi-sms.yaml GET /opt-outs 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: /opt-outs: get: tags: - Opt-outs summary: List opt-outs description: >- Returns the numbers on your opt-out list, newest first, including entries created from STOP, START and HELP keyword replies and the ones you added. Pass both `limit` and `offset` on every call: the response is a bare JSON array, and it is `null` when the page has no records (including when `limit` is missing). Page by increasing `offset` until a page returns fewer items than `limit` or `null`. To check a single number, use `GET /opt-outs/{phoneNumber}` instead. operationId: list-opt-outs parameters: - name: limit in: query required: true description: >- Required. Maximum number of opt-outs to return, `1` or greater. Without it the response is `null`. schema: type: integer minimum: 1 example: 50 - name: offset in: query required: true description: >- Required. Number of records to skip before the page starts. Pass `0` for the first page, then add `limit` for each following page. schema: type: integer minimum: 0 example: 0 responses: '200': description: A page of opt-outs, or `null` when there are none. content: application/json: schema: type: array nullable: true items: $ref: '#/components/schemas/OptOut' example: - id: 4e8b2d61-7c3a-4f9e-a1d5-9b6c0e2f8a37 accountId: MA_XXXXXXXX phoneNumber: '+14155550123' channel: sms reason: manual source: manual syncedToProvider: true createdAt: '2026-10-18T07:23:03Z' - id: 7b1d9f3e-2a6c-4e5b-8d0f-3c9a1e7b5d26 accountId: MA_XXXXXXXX phoneNumber: '+14155550124' channel: sms reason: stop source: inbound syncedToProvider: false createdAt: '2026-10-17T19:04:40Z' '401': $ref: '#/components/responses/Unauthorized' '500': $ref: '#/components/responses/ServerError' 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.optOuts.listOptOuts({ limit: 1, offset: 1 }) - lang: python label: Python SDK source: | from vobiz import Vobiz client = Vobiz(api_key="MA_XXXXXXXX", auth_token="YOUR_AUTH_TOKEN") client.sms.opt_outs.list_opt_outs( limit=1, offset=1, ) - 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.ListOptOutsRequest{ Limit: 1, Offset: 1, } c.Sms.OptOuts.ListOptOuts( 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().optOuts().listOptOuts( ListOptOutsRequest .builder() .limit(1) .offset(1) .build() ); - lang: ruby label: Ruby SDK source: > require 'vobiz' client = Vobiz::Client.new(api_key: 'MA_XXXXXXXX', auth_token: 'YOUR_AUTH_TOKEN') client.sms.opt_outs.list_opt_outs( limit: 1, offset: 1 ) - lang: csharp label: C# SDK source: > using Vobiz; using Vobiz.Sms; var client = new VobizApiClient("YOUR_AUTH_TOKEN", "MA_XXXXXXXX"); await client.Sms.OptOuts.ListOptOutsAsync(new ListOptOutsRequest { Limit = 1, Offset = 1 }); - lang: php label: PHP SDK source: > sms->optOuts->listOptOuts( new ListOptOutsRequest([ 'limit' => 1, 'offset' => 1, ]), ); components: schemas: OptOut: type: object description: >- A phone number on your opt-out list for one channel. Vobiz blocks sends and broadcast deliveries to it on that channel until you delete the entry. properties: id: type: string format: uuid example: 4e8b2d61-7c3a-4f9e-a1d5-9b6c0e2f8a37 description: Unique identifier of the opt-out record (UUID). accountId: type: string description: Your Vobiz account ID (Auth ID), for example `MA_XXXXXXXX`. example: MA_XXXXXXXX phoneNumber: type: string example: '+14155550123' description: The blocked phone number in E.164 format. channel: type: string example: sms description: >- Channel the number is blocked on: `sms`, `mms` or `rcs`. An `sms` entry also blocks `mms`. reason: type: string description: >- Why the entry exists. `stop`, `start` or `help` when the contact replied with a keyword; `manual` or your own text when you created it through the API or console. example: manual source: type: string enum: - inbound - manual description: >- `inbound` when the entry came from a keyword reply, `manual` when you created it through the API or console. syncedToProvider: type: boolean description: '`true` when the block has also been applied on the upstream network.' createdAt: type: string format: date-time example: '2026-10-18T07:23:03Z' description: When the number was added to the list (ISO 8601, UTC). 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. 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 ServerError: description: Unexpected error. Retry with the same idempotency key where one applies. content: application/json: schema: $ref: '#/components/schemas/Error' example: error: internal error 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.