> ## 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.

# Upload recipients

> Sets the recipient list of a `draft` broadcast; each upload replaces the previous list.



## OpenAPI

````yaml openapi-sms.yaml POST /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
    post:
      tags:
        - Broadcasts
      summary: Upload recipients
      description: >-
        Sets the recipient list of a `draft` broadcast; each upload replaces the
        previous list. Send `multipart/form-data` with a `.csv` or `.xlsx`
        `file` (10 MB maximum) to use template variables from extra columns, or
        JSON with a `numbers` array for a plain list. Numbers without a country
        code are normalised to E.164 with `defaultCountry` (default `US`).
        Duplicates are dropped, invalid rows are reported in `invalid`, and
        numbers that opted out of SMS from you are kept with status `opted_out`
        and never sent. A broadcast can hold up to 10,000 recipients; a larger
        list returns `422`.
      operationId: upload-recipients
      requestBody:
        required: true
        content:
          multipart/form-data:
            schema:
              $ref: '#/components/schemas/UploadRecipientsFile'
            encoding:
              file:
                contentType: >-
                  text/csv,
                  application/vnd.openxmlformats-officedocument.spreadsheetml.sheet
          application/json:
            schema:
              $ref: '#/components/schemas/UploadRecipientsJSON'
            example:
              numbers:
                - '+14155550123'
                - '+14155550124'
                - 415 555 0125
              defaultCountry: US
      responses:
        '200':
          description: Upload summary. The broadcast's `columns` and `stats` are updated.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UploadResult'
              example:
                total: 5
                valid: 3
                invalid:
                  - row: 4
                    value: abc
                    reason: contains letters or symbols
                invalidCount: 1
                duplicates: 1
                optedOut: 0
                columns:
                  - phone
                  - name
                  - amount
        '400':
          description: The body or file is not usable.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
              examples:
                noFile:
                  value:
                    error: multipart field "file" is required
                noNumbers:
                  value:
                    error: numbers is required
                body:
                  value:
                    error: >-
                      body must be multipart with a "file" field, or JSON
                      {"numbers": [...]}
                extension:
                  value:
                    error: file must be .csv or .xlsx
                unreadable:
                  value:
                    error: 'could not read the file: check it is a valid CSV or XLSX'
                country:
                  value:
                    error: defaultCountry must be a supported ISO 3166-1 alpha-2 code
        '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
        '409':
          description: The broadcast is no longer a draft.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
              example:
                error: cannot change the recipients of a broadcast that is running
        '413':
          description: The file is larger than 10 MB.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
              example:
                error: file is larger than 10MB
        '422':
          description: The upload has more recipients than a broadcast can hold.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
              example:
                error: 'too many recipients: the limit is 10000 per broadcast'
      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.uploadRecipients({
                id: "3f8d2a6e-5b1c-4e7f-a9d0-2c4b6e8f1a35",
                numbers: ["+14155550123", "+14155550124", "415 555 0125"],
                defaultCountry: "US"
            })
        - lang: python
          label: Python SDK
          source: |
            from vobiz import Vobiz

            client = Vobiz(api_key="MA_XXXXXXXX", auth_token="YOUR_AUTH_TOKEN")

            client.sms.broadcasts.upload_recipients(
                id="3f8d2a6e-5b1c-4e7f-a9d0-2c4b6e8f1a35",
                numbers=[
                    "+14155550123",
                    "+14155550124",
                    "415 555 0125"
                ],
                default_country="US",
            )
        - 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.UploadRecipientsJSON{
                    ID: "3f8d2a6e-5b1c-4e7f-a9d0-2c4b6e8f1a35",
                    Numbers: []string{
                        "+14155550123",
                        "+14155550124",
                        "415 555 0125",
                    },
                    DefaultCountry: sms.UploadRecipientsJSONDefaultCountryUs.Ptr(),
                }
            c.Sms.Broadcasts.UploadRecipients(
                    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().uploadRecipients(
                "3f8d2a6e-5b1c-4e7f-a9d0-2c4b6e8f1a35",
                UploadRecipientsJson
                    .builder()
                    .numbers(
                        Arrays.asList("+14155550123", "+14155550124", "415 555 0125")
                    )
                    .defaultCountry(UploadRecipientsJsonDefaultCountry.US)
                    .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.upload_recipients(
              id: "3f8d2a6e-5b1c-4e7f-a9d0-2c4b6e8f1a35",
              numbers: ["+14155550123", "+14155550124", "415 555 0125"],
              default_country: "US"
            )
        - lang: csharp
          label: C# SDK
          source: |
            using Vobiz;
            using Vobiz.Sms;

            var client = new VobizApiClient("YOUR_AUTH_TOKEN", "MA_XXXXXXXX");

            await client.Sms.Broadcasts.UploadRecipientsAsync(
                new UploadRecipientsJson
                {
                    Id = "3f8d2a6e-5b1c-4e7f-a9d0-2c4b6e8f1a35",
                    Numbers = new List<string>() { "+14155550123", "+14155550124", "415 555 0125" },
                    DefaultCountry = UploadRecipientsJsonDefaultCountry.Us,
                }
            );
        - lang: php
          label: PHP SDK
          source: >
            <?php


            require 'vendor/autoload.php';


            use Vobiz\VobizClient;


            $client = new VobizClient(apiKey: 'MA_XXXXXXXX', authToken:
            'YOUR_AUTH_TOKEN');


            $client->sms->broadcasts->uploadRecipients(
                '3f8d2a6e-5b1c-4e7f-a9d0-2c4b6e8f1a35',
                new UploadRecipientsJson([
                    'numbers' => [
                        '+14155550123',
                        '+14155550124',
                        '415 555 0125',
                    ],
                    'defaultCountry' => UploadRecipientsJsonDefaultCountry::Us->value,
                ]),
            );
components:
  schemas:
    UploadRecipientsFile:
      type: object
      required:
        - file
      properties:
        file:
          type: string
          format: binary
          description: >-
            A `.csv` or `.xlsx` file of at most 10 MB and 10,000 recipients. The
            phone column is detected from its header (`phone`, `mobile`,
            `msisdn`, `number`, `to`, `phonenumber` and similar), otherwise the
            first column is used. Files without a header get the columns
            `phone`, `column2`, `column3` and so on; CSV delimiters `,`, `;` and
            tab are detected, and for XLSX the first sheet is read.
        defaultCountry:
          type: string
          default: US
          description: >-
            ISO 3166-1 alpha-2 country code, matched case-insensitively, used to
            normalise numbers that have no country code. Defaults to `US`.
          enum:
            - US
            - CA
            - GB
            - IN
            - AU
            - NZ
            - IE
            - DE
            - FR
            - ES
            - IT
            - NL
            - BE
            - CH
            - AT
            - SE
            - 'NO'
            - DK
            - FI
            - PL
            - PT
            - BR
            - MX
            - AR
            - CO
            - CL
            - SG
            - MY
            - ID
            - PH
            - TH
            - VN
            - JP
            - KR
            - CN
            - HK
            - AE
            - SA
            - QA
            - IL
            - TR
            - ZA
            - NG
            - KE
            - EG
            - PK
            - BD
            - LK
            - NP
          example: US
      description: >-
        A recipient file upload. Every column other than the phone column
        becomes a template variable named after its header.
    UploadRecipientsJSON:
      type: object
      required:
        - numbers
      properties:
        numbers:
          type: array
          description: >-
            Phone numbers, one per recipient, up to 10,000. Numbers without a
            country code are normalised with `defaultCountry`. An empty array
            clears the list.
          items:
            type: string
          example:
            - '+14155550123'
            - '+14155550124'
        defaultCountry:
          type: string
          default: US
          description: >-
            ISO 3166-1 alpha-2 country code, matched case-insensitively, used to
            normalise numbers that have no country code. Defaults to `US`.
          enum:
            - US
            - CA
            - GB
            - IN
            - AU
            - NZ
            - IE
            - DE
            - FR
            - ES
            - IT
            - NL
            - BE
            - CH
            - AT
            - SE
            - 'NO'
            - DK
            - FI
            - PL
            - PT
            - BR
            - MX
            - AR
            - CO
            - CL
            - SG
            - MY
            - ID
            - PH
            - TH
            - VN
            - JP
            - KR
            - CN
            - HK
            - AE
            - SA
            - QA
            - IL
            - TR
            - ZA
            - NG
            - KE
            - EG
            - PK
            - BD
            - LK
            - NP
          example: US
      description: >-
        A plain recipient list sent as JSON. Use the file form instead when the
        template needs per-recipient variables.
    UploadResult:
      type: object
      description: >-
        Summary of a recipient upload. The upload replaces the broadcast's
        previous recipient list.
      properties:
        total:
          type: integer
          description: Rows read from the file or array, excluding the header line.
          example: 5
        valid:
          type: integer
          description: >-
            Rows with a valid, unique number that were stored as recipients,
            including opted-out numbers.
          example: 3
        invalid:
          type: array
          description: >-
            Rejected rows with the reason for each, at most the first 100. Fix
            them in your file and upload again.
          items:
            $ref: '#/components/schemas/InvalidRecipient'
        invalidCount:
          type: integer
          description: >-
            Total rejected rows, including any beyond the 100 listed in
            `invalid`.
          example: 1
        duplicates:
          type: integer
          description: Rows dropped because the same number appeared earlier in the upload.
          example: 1
        optedOut:
          type: integer
          description: >-
            Stored rows marked `opted_out` because the number opted out of SMS
            from you. They count towards `valid` and are never sent.
          example: 0
        columns:
          type: array
          description: >-
            Column names detected in the upload, as written in your header. The
            first is the phone column; the rest are template variables.
          items:
            type: string
          example:
            - phone
            - name
            - amount
    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.
    InvalidRecipient:
      type: object
      description: A row that was rejected during a recipient upload and not stored.
      properties:
        row:
          type: integer
          description: >-
            Where the row came from: the line number in the file (the header is
            line 1), or the 1-based position in a JSON `numbers` array.
          example: 7
        value:
          type: string
          description: >-
            The phone value exactly as it appeared in the row. Empty when the
            phone cell was blank.
          example: abc
        reason:
          type: string
          enum:
            - missing phone number
            - contains letters or symbols
            - too short
            - too long
            - not a valid US/Canada number
            - not a valid Indian mobile number
            - unsupported defaultCountry
          example: contains letters or symbols
          description: >-
            Why the number was rejected: `missing phone number` (blank cell),
            `contains letters or symbols`, `too short`, `too long`, `not a valid
            US/Canada number`, `not a valid Indian mobile number` or
            `unsupported defaultCountry`.
  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.