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

# Add recipients to a call broadcast

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

Use this API to add the recipients to an existing voice broadcast. Post a list of Recipient objects to be added to the voice 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

## Request body

- Recipient[]
  - `phoneNumber` string — A recipient's phone number in E.164 format (11-digit) or short code. Example: 12132000384, 67076
  - `fromNumber` string — ~
  - `contactId` integer — An id of existing contact used as recipient
  - `attributes` object — Map of user-defined string attributes associated with recipient

## Response `200`

successful operation

- CallList — ~
  - `items` object[] — ~
    - `id` integer — An id of an action
    - `fromNumber` string — A sender's phone number in E.164 (11-digit) format
    - `toNumber` string — A recipient's phone number in E.164 (11-digit) format
    - `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' — 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 associated with an action if call is sent as part of call 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 — Is 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 action or broadcast for this action
    - `finalCallResult` 'LA' | 'AM' | 'BUSY' | 'DNC' | 'XFER' | 'NO_ANS' | 'XFER_LEG' | 'INTERNAL_ERROR' | 'CARRIER_ERROR' | 'CARRIER_TEMP_ERROR' | 'UNDIALED' | 'SD' | 'POSTPONED' | 'ABANDONED' | 'SKIPPED' — Result of a call (LA, AM, BUSY, DNC, XFER, NO_ANS, XFER_LEG, INTERNAL_ERROR, CARRIER_ERROR, CARRIER_TEMP_ERROR, UNDIALED, SD, POSTPONED, ABANDONED, SKIPPED). See [call states and results](https://developers.callfire.com/results-responses-errors.html)
    - `records` CallRecord[] — List of call records, each record contains call details like originate time, duration, cost, notes made by agents. A single contact may have a multiple phone numbers. In this case if given call was sent as a part of broadcast with configured retry logic then each call record will contain details about attempted phone number
      - `id` integer — An id of a call record
      - `toNumber` string — A phone number to which a call was addressed. Phone number in E.164 format (11-digit). Example: 12132000384
      - `billedAmount` number, float — A cost of the call
      - `finishTime` integer — Timestamp when call was finished, formatted in unix time milliseconds (read only). Example: 1473781817000 for Sat, 05 Jan 1985 14:03:37 GMT
      - `switchId` string — ~
      - `callerName` string — ~
      - `labels` string[] — Labels associated with a call action
      - `result` 'LA' | 'AM' | 'BUSY' | 'DNC' | 'XFER' | 'NO_ANS' | 'XFER_LEG' | 'INTERNAL_ERROR' | 'CARRIER_ERROR' | 'CARRIER_TEMP_ERROR' | 'UNDIALED' | 'SD' | 'POSTPONED' | 'ABANDONED' | 'SKIPPED' — ~
      - `originateTime` integer — A date and time (timestamp) when call was originated by CallFire platform and went to downstream provider, formatted in unix time milliseconds (read only). Example: 1473781817000
      - `answerTime` integer — Timestamp when call was answered, formatted in unix time milliseconds (read only). Example: 1473781817000 for Sat, 05 Jan 1985 14:03:37 GMT
      - `duration` integer — Duration of the call in seconds
      - `notes` Note[] — Notes of call added by agent
        - `text` string — A text of a note
        - `created` integer — The time when the given resource was created, formatted in unix time milliseconds (read only). Example: 1473781817000
      - `recordings` CallRecording[] — A list of voice recordings of the call
        - `id` integer — An id of a call recording
        - `callId` integer — An id of a call action
        - `campaignId` integer — Contains broadcast id if call was sent as a part of voice broadcast
        - `name` string — A name of a recording
        - `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
        - `lengthInBytes` integer — A size of a recording file in bytes
        - `lengthInSeconds` integer — Duration of a recording in seconds
        - `hash` string — A unique string hash identifier of a recording
        - `mp3Url` string — A public URL of a call recording
        - `state` 'RECORDING' | 'READY' | 'ERROR' — Current state of a recording, available values: RECORDING - recording is in progress, READY - recording is ready, ERROR - error has occurred and recording can be broken
      - `questionResponses` QuestionResponse[] — Notes of call added by an agent
        - `question` string — A text of a question
        - `response` string — Client's answer
    - `agentCall` boolean — An internal call to an agent
    - `notes` Note[] — Notes of call added by an agent
      - `text` string — A text of a note
      - `created` integer — The time when the given resource was created, formatted in unix time milliseconds (read only). Example: 1473781817000

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