---
title: "Add recipients to a text broadcast"
method: POST
path: "/texts/broadcasts/{id}/recipients"
tags: ["texts"]
---

# Add recipients to a text broadcast

`POST /texts/broadcasts/{id}/recipients`

Use this API to add recipients to a text broadcast which is already created. Post a list of Recipient objects to be immediately added to the text broadcast campaign. These contacts will not go through validation process, and will be acted upon as they are added. Recipients may be added as a list of contact ids, or list of numbers

## Path parameters

- `id` integer, required

## Query parameters

- `fields` string
- `strictValidation` boolean
- `sendImmediately` boolean

## Request body

- TextRecipient[]
  - `phoneNumber` string — Phone number in E.164 format (11-digit) or short code. Example: 12132000384, 67076
  - `fromNumber` string — ~
  - `contactId` integer — An id of existing contact in account
  - `attributes` object — A map of string attributes associated with a recipient
  - `message` string — A text message
  - `media` Media[] — A list of media objects' ids associated with a text message
    - `id` integer — An id of a media file
    - `accountId` integer — ~
    - `name` string — A name of a media file
    - `created` integer — The time when the given resource was created, formatted in unix time milliseconds (read only). Example: 1473781817000
    - `lengthInBytes` integer — A size of a media file in bytes
    - `mediaType` string — A MIME type of media file, ex: image/jpeg, image/png, video/mp4, audio/mp3, etc
    - `publicUrl` string — A public URL of a media file
  - `extractedSingleRecipient` boolean — ~
  - `meta` object — ~

## Response `200`

successful operation

- TextList — ~
  - `items` object[] — ~
    - `id` integer — An id of an action
    - `fromNumber` string — Sender's phone number in E.164 format (11-digit) or short code. Example: 12132000384, 67076
    - `toNumber` string — Recipient's phone number in E.164 format (11-digit) or short code. Example: 12132000384, 67076
    - `attributes` object — Map of user-defined string attributes associated with an action
    - `state` 'READY' | 'SELECTED' | 'CALLBACK' | 'FINISHED' | 'DISABLED' | 'SKIPPED' | 'DNC' | 'DUP' | 'INVALID' | 'TIMEOUT' | 'PERIOD_LIMIT' | 'RESTRICTED_NUMBER' — Current state of an action (READY, SELECTED, CALLBACK, DISABLED, FINISHED, DNC, DUP, INVALID, TIMEOUT, PERIOD_LIMIT). See [call states and results](https://developers.callfire.com/results-responses-errors.html)
    - `campaignId` integer — An id of broadcast if given text was sent as a part of text broadcast
    - `batchId` integer — An id of contact batch associated with an action
    - `contact` Contact — Represents a contact in CallFire platform. Contains info about the people you want to contact. It allows you to store a user-defined properties for each contact
      - `id` integer — An id of a contact
      - `firstName` string — A first name of a contact
      - `lastName` string — A last name of a contact
      - `zipcode` string — A Zip code of a contact
      - `homePhone` string — Phone number in E.164 format (11-digit). Example: 12132000384
      - `workPhone` string — Phone number in E.164 format (11-digit). Example: 12132000384
      - `mobilePhone` string — Phone number in E.164 format (11-digit). Example: 12132000384
      - `extraPhone1` string — Phone number in E.164 format (11-digit). Example: 12132000384
      - `extraPhone2` string — Phone number in E.164 format (11-digit). Example: 12132000384
      - `extraPhone3` string — Phone number in E.164 format (11-digit). Example: 12132000384
      - `externalId` string — An external id of a contact for syncing with external sources
      - `externalSystem` string — External system that external id refers to
      - `properties` object — Map of user-defined string properties for contact
      - `deleted` boolean — A deleted contact, deleted contacts are hidden from search results
    - `inbound` boolean — An action inbound
    - `created` integer — The time when the given resource was created, formatted in unix time milliseconds (read only). Example: 1473781817000 for Sat, 05 Jan 1985 14:03:37 GMT
    - `modified` integer — The time when the given resource was modified, formatted in unix time milliseconds (read only). Example: 1473781817000 for Sat, 05 Jan 1985 14:03:37 GMT
    - `labels` string[] — Labels associated with an action
    - `message` string — A text message
    - `finalTextResult` 'SENT' | 'RECEIVED' | 'DNT' | 'TOO_BIG' | 'INTERNAL_ERROR' | 'CARRIER_ERROR' | 'CARRIER_TEMP_ERROR' | 'UNDIALED' | 'INVALID_NUMBER' — Result of text (SENT, RECEIVED, DNT, TOO_BIG, INTERNAL_ERROR, CARRIER_ERROR, CARRIER_TEMP_ERROR, UNDIALED). See [call states and results](https://developers.callfire.com/results-responses-errors.html)
    - `records` TextRecord[] — List of text records, each record contains additional details: time of sending, cost, current state. A single contact may have multiple numbers. If given text was sent as part of broadcast with configured retry logic then each text record will contain details about attempted number
      - `id` integer — An id of a text record
      - `toNumber` string — An attempted phone number
      - `billedAmount` number, float — A cost of a sent text
      - `finishTime` integer — A time when the given resource was updated, formatted in unix time milliseconds (read only). Example: 1473781817000
      - `switchId` string — ~
      - `callerName` string — ~
      - `labels` string[] — Labels associated with a text action
      - `message` string — A text message
      - `textResult` 'SENT' | 'RECEIVED' | 'DNT' | 'TOO_BIG' | 'INTERNAL_ERROR' | 'CARRIER_ERROR' | 'CARRIER_TEMP_ERROR' | 'UNDIALED' | 'INVALID_NUMBER' — Result of a text (SENT, RECEIVED, DNT, TOO_BIG, INTERNAL_ERROR, CARRIER_ERROR, CARRIER_TEMP_ERROR, UNDIALED). See [call states and results](https://developers.callfire.com/results-responses-errors.html)
    - `media` Media[] — ~
      - `id` integer — An id of a media file
      - `accountId` integer — ~
      - `name` string — A name of a media file
      - `created` integer — The time when the given resource was created, formatted in unix time milliseconds (read only). Example: 1473781817000
      - `lengthInBytes` integer — A size of a media file in bytes
      - `mediaType` string — A MIME type of media file, ex: image/jpeg, image/png, video/mp4, audio/mp3, etc
      - `publicUrl` string — A public URL of a media file

## Other responses

- `400` — Bad request
- `401` — Unauthorized
- `403` — Forbidden
- `404` — Not found
- `500` — Internal Server Error

---

[API](https://skmtc.net/callfire/apis/callfire-api-documentation.md) · [All operations](https://skmtc.net/callfire/apis/callfire-api-documentation/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/callfire/callfire-api-documentation/versions/9f6fb501bc03/schema)