---
title: "Send calls"
method: POST
path: "/calls"
tags: ["calls"]
---

# Send calls

`POST /calls`

Use the /calls API to send individual calls quickly. A verified Caller ID and sufficient credits are required to make a call. CallRecipient represents a single recipient identified by phone number or contact id in CallFire system. You can attach user-defined attributes to a Call action via CallRecipient.attributes property, attributes are available in Call action response

## Query parameters

- `fields` string
- `campaignId` integer
- `defaultLiveMessage` string
- `defaultMachineMessage` string
- `defaultLiveMessageSoundId` integer
- `defaultMachineMessageSoundId` integer
- `defaultVoice` 'MALE1' | 'FEMALE1' | 'FEMALE2' | 'SPANISH1' | 'FRENCHCANADIAN1'
- `strictValidation` boolean

## Request body

- CallRecipient[]
  - `phoneNumber` string — Recipient's phone number in E.164 format (11-digit) or short code. Example: 12132000384
  - `fromNumber` string — ~
  - `contactId` integer — An id of existing contact used as recipient
  - `attributes` object — Map of user-defined string attributes associated with recipient
  - `dialplanXml` string — An IVR xml document describing dialplan to setup an IVR broadcast. If dialplan is set there is no need to set live, machine and transfer sounds (or vice versa)
  - `liveMessage` string — Text to be turned into a sound, this text will be played when the phone is answered
  - `liveMessageSoundId` integer — An id of a sound file to play if phone is answered
  - `machineMessage` string — Text to be used to turn into sound, this text will be played when answering machine is detected
  - `machineMessageSoundId` integer — An id of a sound file to play if answering machine is detected
  - `transferMessage` string — Text to be turned into sound, this text will be played when the transfer digit is played
  - `transferMessageSoundId` integer — An id of a sound file to play if call is transferred
  - `transferDigit` string — A digit pressed to initiate the transfer
  - `transferNumber` string — Phone number in E.164 format (11-digit) to transfer the call to. Example: 12132000384
  - `voice` 'MALE1' | 'FEMALE1' | 'FEMALE2' | 'SPANISH1' | 'FRENCHCANADIAN1' — The voice to be used (MALE1, FEMALE1, FEMALE2, SPANISH1, FRENCHCANADIAN1)

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