Retell AI Create Batch Call API
The Create Batch Call API from Retell AI — 1 operation(s) for create batch call.
OpenAPI Specification
openapi: 3.0.3
info:
title: Retell SDK Add Community Voice Create Batch Call API
version: 3.0.0
contact:
name: Retell Support
url: https://www.retellai.com/
email: support@retellai.com
license:
name: Apache 2.0
url: https://www.apache.org/licenses/LICENSE-2.0.html
servers:
- url: https://api.retellai.com
description: The production server.
security:
- api_key: []
tags:
- name: Create Batch Call
paths:
/create-batch-call:
post:
description: Create a batch call
operationId: createBatchCall
requestBody:
required: true
content:
application/json:
schema:
type: object
required:
- from_number
- tasks
properties:
name:
type: string
example: First batch call
description: The name of the batch call. Only used for your own reference.
trigger_timestamp:
type: number
example: 1735718400000
description: The scheduled time for sending the batch call, represented as a Unix timestamp in milliseconds. If omitted, the call will be sent immediately.
from_number:
type: string
minLength: 1
example: '+14157774444'
description: The number you own in E.164 format. Must be a number purchased from Retell or imported to Retell.
reserved_concurrency:
type: integer
minimum: 0
description: Number of concurrency reserved for all other calls that are not triggered by batch calls, such as inbound calls.
tasks:
type: array
description: A list of individual call tasks to be executed as part of the batch call. Each task represents a single outbound call and includes details such as the recipient's phone number and optional dynamic variables to personalize the call content.
items:
$ref: '#/components/schemas/BatchCallTask'
call_time_window:
$ref: '#/components/schemas/CallTimeWindow'
responses:
'201':
description: Successfully created a batch call.
content:
application/json:
schema:
$ref: '#/components/schemas/BatchCallResponse'
'400':
$ref: '#/components/responses/BadRequest'
'401':
$ref: '#/components/responses/Unauthorized'
'422':
$ref: '#/components/responses/UnprocessableContent'
'500':
$ref: '#/components/responses/InternalServerError'
tags:
- Create Batch Call
components:
schemas:
CallPresetAnalysisData:
type: object
required:
- type
- name
description: System preset for post-call analysis (voice agents). Use in post_call_analysis_data to override prompts or mark fields optional.
properties:
type:
type: string
enum:
- system-presets
description: Identifies this item as a system preset.
name:
type: string
enum:
- call_summary
- call_successful
- user_sentiment
description: Preset identifier for voice agent analysis.
example: call_summary
description:
type: string
minLength: 1
description: Prompt or description for this preset.
required:
type: boolean
description: If false, this field is optional in the analysis. If true or unset, the field is required.
conditional_prompt:
type: string
description: Optional instruction to help decide whether this field needs to be populated. If not set, the field is always included.
TimeWindow:
type: object
required:
- start
- end
properties:
start:
type: number
example: 540
description: Start time in minutes since local midnight.
end:
type: number
example: 1020
description: End time in minutes since local midnight.
VoicemailActionBridgeTransfer:
type: object
properties:
type:
type: string
enum:
- bridge_transfer
example: bridge_transfer
required:
- type
VoicemailActionPrompt:
type: object
properties:
type:
type: string
enum:
- prompt
example: prompt
text:
type: string
example: Summarize the call in 2 sentences.
description: The prompt used to generate the text to be spoken when the call is detected to be in voicemail.
required:
- type
- text
LanguageLegacy:
oneOf:
- $ref: '#/components/schemas/Language'
- type: string
enum:
- multi
example: en-US
description: Legacy single-string language format. Accepts any concrete locale from `Language`, plus the special scalar value `multi` for multilingual support. If unset, will use default value `en-US`.
Language:
type: string
example: en-US
enum:
- en-US
- en-IN
- en-GB
- en-AU
- en-NZ
- de-DE
- es-ES
- es-419
- hi-IN
- fr-FR
- fr-CA
- ja-JP
- pt-PT
- pt-BR
- zh-CN
- ru-RU
- it-IT
- ko-KR
- nl-NL
- nl-BE
- pl-PL
- tr-TR
- vi-VN
- ro-RO
- bg-BG
- ca-ES
- th-TH
- da-DK
- fi-FI
- el-GR
- hu-HU
- id-ID
- no-NO
- sk-SK
- sv-SE
- lt-LT
- lv-LV
- cs-CZ
- ms-MY
- af-ZA
- ar-SA
- az-AZ
- bs-BA
- cy-GB
- fa-IR
- fil-PH
- gl-ES
- he-IL
- hr-HR
- hy-AM
- is-IS
- kk-KZ
- kn-IN
- mk-MK
- mr-IN
- ne-NP
- sl-SI
- sr-RS
- sw-KE
- ta-IN
- ur-IN
- yue-CN
- uk-UA
description: Specifies what language (and dialect) the agent will operate in. For instance, selecting `en-GB` optimizes speech recognition for British English and indexes knowledge bases with English. If unset, will use default value `en-US`. This enum does not include the legacy scalar value `multi`.
ConversationFlowOverride:
type: object
description: Override properties for conversation flow configuration in agent override requests.
properties:
model_choice:
$ref: '#/components/schemas/ModelChoice'
description: The model choice for the conversation flow.
model_temperature:
type: number
minimum: 0
maximum: 1
example: 0.7
description: Controls the randomness of the model's responses. Lower values make responses more deterministic.
nullable: true
tool_call_strict_mode:
type: boolean
example: true
description: Whether to use strict mode for tool calls. Only applicable when using certain supported models.
nullable: true
knowledge_base_ids:
type: array
items:
type: string
example:
- kb_001
- kb_002
description: Knowledge base IDs for RAG (Retrieval-Augmented Generation).
nullable: true
kb_config:
type: object
$ref: '#/components/schemas/KBConfig'
description: Knowledge base configuration for RAG retrieval.
start_speaker:
type: string
enum:
- user
- agent
example: agent
description: Who starts the conversation - user or agent.
begin_after_user_silence_ms:
type: integer
example: 2000
description: If set, the AI will begin the conversation after waiting for the user for the duration (in milliseconds) specified by this attribute. This only applies if the agent is configured to wait for the user to speak first. If not set, the agent will wait indefinitely for the user to speak.
nullable: true
ModelChoice:
oneOf:
- $ref: '#/components/schemas/ModelChoiceCascading'
ModelChoiceCascading:
type: object
required:
- type
- model
properties:
type:
type: string
enum:
- cascading
description: Type of model choice
model:
$ref: '#/components/schemas/LLMModel'
description: The LLM model to use
high_priority:
type: boolean
description: Whether to use high priority pool with more dedicated resource, default false
LLMModel:
type: string
enum:
- gpt-4.1
- gpt-4.1-mini
- gpt-4.1-nano
- gpt-5
- gpt-5-mini
- gpt-5-nano
- gpt-5.1
- gpt-5.2
- gpt-5.4
- gpt-5.4-mini
- gpt-5.4-nano
- gpt-5.5
- claude-4.5-sonnet
- claude-4.6-sonnet
- claude-4.5-haiku
- gemini-2.5-flash-lite
- gemini-3.0-flash
- gemini-3.1-flash-lite
description: Available LLM models for agents.
PIIConfig:
type: object
required:
- mode
- categories
properties:
mode:
type: string
enum:
- post_call
default: post_call
description: The processing mode for PII scrubbing. Currently only post-call is supported.
categories:
type: array
items:
type: string
enum:
- person_name
- address
- email
- phone_number
- ssn
- passport
- driver_license
- credit_card
- bank_account
- password
- pin
- medical_id
- date_of_birth
- customer_account_number
uniqueItems: true
default: []
description: List of PII categories to scrub from transcripts and recordings.
ResponseEngineRetellLm:
type: object
required:
- type
- llm_id
properties:
type:
type: string
enum:
- retell-llm
description: type of the Response Engine.
llm_id:
type: string
description: id of the Retell LLM Response Engine.
version:
type: number
example: 0
description: Version of the Retell LLM Response Engine.
nullable: true
CallTimeWindow:
type: object
description: Allowed calling windows in a specific timezone. Each window is a half-open interval [startMin, endMin) in minutes since 00:00 local time. Cross-midnight windows are NOT allowed (must satisfy startMin < endMin). `endMin = 1440` (24:00) is valid.
properties:
windows:
type: array
minItems: 1
items:
$ref: '#/components/schemas/TimeWindow'
description: List of TimeWindow (start/end in minutes since local midnight).
timezone:
type: string
description: IANA timezone (e.g. America/Los_Angeles). Defaults to America/Los_Angeles if omitted.
day:
type: array
items:
$ref: '#/components/schemas/DayOfWeek'
description: Optional list of days to which the windows apply. If omitted or empty, windows apply to every day.
required:
- windows
ResponseEngineConversationFlow:
type: object
required:
- type
- conversation_flow_id
properties:
type:
type: string
enum:
- conversation-flow
description: type of the Response Engine.
conversation_flow_id:
type: string
description: ID of the Conversation Flow Response Engine.
version:
type: number
example: 0
description: Version of the Conversation Flow Response Engine.
nullable: true
ResponseEngine:
oneOf:
- $ref: '#/components/schemas/ResponseEngineRetellLm'
- $ref: '#/components/schemas/ResponseEngineCustomLm'
- $ref: '#/components/schemas/ResponseEngineConversationFlow'
VoicemailActionStaticText:
type: object
properties:
type:
type: string
enum:
- static_text
example: static_text
text:
type: string
example: Please give us a callback tomorrow at 10am.
description: The text to be spoken when the call is detected to be in voicemail.
required:
- type
- text
GuardrailConfig:
type: object
properties:
output_topics:
type: array
items:
type: string
enum:
- harassment
- self_harm
- sexual_exploitation
- violence
- defense_and_national_security
- illicit_and_harmful_activity
- gambling
- regulated_professional_advice
- child_safety_and_exploitation
uniqueItems: true
description: Selected prohibited agent topic categories to check. When agent messages contain these topics, they will be replaced with a placeholder message.
nullable: true
input_topics:
type: array
items:
type: string
enum:
- platform_integrity_jailbreaking
uniqueItems: true
description: Selected prohibited user topic categories to check. When user messages contain these topics, the agent will respond with a placeholder message instead of processing the request.
nullable: true
BatchCallResponse:
type: object
required:
- batch_call_id
- name
- from_number
- scheduled_timestamp
- total_task_count
properties:
batch_call_id:
type: string
example: batch_call_dbcc4412483ebfc348abb
description: Unique id of the batch call.
name:
type: string
example: First batch call
from_number:
type: string
example: '+14157774444'
scheduled_timestamp:
type: number
example: 1735718400
total_task_count:
type: number
description: Number of tasks within the batch call
call_time_window:
$ref: '#/components/schemas/CallTimeWindow'
description: Canonicalized minutes-based time windows. Present only if specified when the batch call was created or updated. See CallTimeWindow for format details ([startMin, endMin) in local minutes; no cross-midnight).
KBConfig:
type: object
properties:
top_k:
type: integer
minimum: 1
maximum: 10
example: 3
description: Max number of knowledge base chunks to retrieve
filter_score:
type: number
minimum: 0
maximum: 1
example: 0.6
description: Similarity threshold for filtering search results
ResponseEngineCustomLm:
type: object
required:
- type
- llm_websocket_url
properties:
type:
type: string
enum:
- custom-llm
description: type of the Response Engine.
llm_websocket_url:
type: string
description: LLM websocket url of the custom LLM.
VoicemailAction:
oneOf:
- $ref: '#/components/schemas/VoicemailActionPrompt'
- $ref: '#/components/schemas/VoicemailActionStaticText'
- $ref: '#/components/schemas/VoicemailActionHangup'
- $ref: '#/components/schemas/VoicemailActionBridgeTransfer'
PostCallAnalysisData:
oneOf:
- $ref: '#/components/schemas/AnalysisData'
- $ref: '#/components/schemas/CallPresetAnalysisData'
description: Post-call analysis item (custom data or voice preset). Use for voice agent post_call_analysis_data; validates only call presets (call_summary, call_successful, user_sentiment).
AsrProvider:
type: string
enum:
- azure
- deepgram
- soniox
description: ASR provider name.
VoiceHandbookConfig:
type: object
description: Behavior presets for voice agents. All presets are available.
properties:
default_personality:
type: boolean
description: Professional call center rep baseline.
natural_filler_words:
type: boolean
description: Sprinkle natural speech fillers like "um", "you know" for a more human, conversational tone.
high_empathy:
type: boolean
description: Warm acknowledgment of caller concerns.
echo_verification:
type: boolean
description: Repeat back and confirm important details (voice only).
nato_phonetic_alphabet:
type: boolean
description: Spell using NATO phonetic alphabet style (voice only).
speech_normalization:
type: boolean
description: Convert numbers/dates/currency to spoken forms (voice only).
smart_matching:
type: boolean
description: Treat near-match similar words as same entity to reduce impact of transcription error (voice only).
ai_disclosure:
type: boolean
description: When asked, acknowledge being a virtual assistant.
scope_boundaries:
type: boolean
description: Stay within prompt/context scope, don't invent details.
AgentVersionReference:
oneOf:
- type: integer
minimum: 0
example: 1
- type: string
minLength: 1
maxLength: 20
pattern: ^[a-z0-9_-]+$
example: prod
description: Agent version reference. Supports a numeric version (for example 3) or a tag/environment name (for example "prod"). When a tag is provided, resolution uses that exact tag assignment (including its dynamic variables). If the tag exists but is currently unassigned, it resolves to latest. When a numeric version (or latest) is provided, resolution applies dynamic variables from the preferred tag for that resolved version (most recently assigned), if any.
DayOfWeek:
type: string
enum:
- Monday
- Tuesday
- Wednesday
- Thursday
- Friday
- Saturday
- Sunday
description: Day of week. Matches server-side DayOfWeek enum.
BooleanAnalysisData:
type: object
required:
- type
- name
- description
properties:
type:
type: string
enum:
- boolean
description: Type of the variable to extract.
example: boolean
name:
type: string
description: Name of the variable.
example: is_converted
minLength: 1
description:
type: string
description: Description of the variable.
example: Whether the customer converted.
required:
type: boolean
description: Whether this data is required. If true and the data is not extracted, the call will be marked as unsuccessful.
conditional_prompt:
type: string
description: Optional instruction to help decide whether this field needs to be populated in the analysis. If not set, the field is always included. If required is true, this is ignored.
VoicemailActionHangup:
type: object
properties:
type:
type: string
enum:
- hangup
example: hangup
required:
- type
StringAnalysisData:
type: object
required:
- type
- name
- description
properties:
type:
type: string
enum:
- string
description: Type of the variable to extract.
example: string
name:
type: string
description: Name of the variable.
example: customer_name
minLength: 1
description:
type: string
description: Description of the variable.
example: The name of the customer.
examples:
type: array
items:
type: string
description: Examples of the variable value to teach model the style and syntax.
example:
- John Doe
- Jane Smith
required:
type: boolean
description: Whether this data is required. If true and the data is not extracted, the call will be marked as unsuccessful.
conditional_prompt:
type: string
description: Optional instruction to help decide whether this field needs to be populated in the analysis. If not set, the field is always included. If required is true, this is ignored.
RetellLlmOverride:
type: object
description: Override properties for Retell LLM configuration in agent override requests.
properties:
model:
$ref: '#/components/schemas/NullableLLMModel'
example: gpt-4.1
description: Select the underlying text LLM. If not set, would default to gpt-4.1.
s2s_model:
type: string
enum:
- gpt-realtime-1.5
- gpt-realtime
- gpt-realtime-mini
- null
example: gpt-realtime-1.5
description: Select the underlying speech to speech model. Can only set this or model, not both.
nullable: true
model_temperature:
type: number
example: 0
description: If set, will control the randomness of the response. Value ranging from [0,1]. Lower value means more deterministic, while higher value means more random. If unset, default value 0 will apply. Note that for tool calling, a lower value is recommended.
model_high_priority:
type: boolean
example: true
description: If set to true, will use high priority pool with more dedicated resource to ensure lower and more consistent latency, default to false. This feature usually comes with a higher cost.
nullable: true
tool_call_strict_mode:
type: boolean
example: true
description: Whether to use strict mode for tool calls. Only applicable when using certain supported models.
nullable: true
knowledge_base_ids:
type: array
items:
type: string
description: A list of knowledge base ids to use for this resource.
nullable: true
kb_config:
type: object
$ref: '#/components/schemas/KBConfig'
description: Knowledge base configuration for RAG retrieval.
nullable: true
start_speaker:
type: string
enum:
- user
- agent
description: The speaker who starts the conversation. Required. Must be either 'user' or 'agent'.
begin_after_user_silence_ms:
type: integer
example: 2000
description: If set, the AI will begin the conversation after waiting for the user for the duration (in milliseconds) specified by this attribute. This only applies if the agent is configured to wait for the user to speak first. If not set, the agent will wait indefinitely for the user to speak.
nullable: true
begin_message:
type: string
example: Hey I am a virtual assistant calling from Retell Hospital.
description: First utterance said by the agent in the call. If not set, LLM will dynamically generate a message. If set to "", agent will wait for user to speak first.
nullable: true
IvrAction:
oneOf:
- $ref: '#/components/schemas/IvrActionHangup'
AnalysisData:
oneOf:
- $ref: '#/components/schemas/StringAnalysisData'
- $ref: '#/components/schemas/EnumAnalysisData'
- $ref: '#/components/schemas/BooleanAnalysisData'
- $ref: '#/components/schemas/NumberAnalysisData'
NumberAnalysisData:
type: object
required:
- type
- name
- description
properties:
type:
type: string
enum:
- number
description: Type of the variable to extract.
example: number
name:
type: string
description: Name of the variable.
example: order_count
minLength: 1
description:
type: string
description: Description of the variable.
example: How many the customer intend to order.
required:
type: boolean
description: Whether this data is required. If true and the data is not extracted, the call will be marked as unsuccessful.
conditional_prompt:
type: string
description: Optional instruction to help decide whether this field needs to be populated in the analysis. If not set, the field is always included. If required is true, this is ignored.
NullableLLMModel:
type: string
enum:
- gpt-4.1
- gpt-4.1-mini
- gpt-4.1-nano
- gpt-5
- gpt-5-mini
- gpt-5-nano
- gpt-5.1
- gpt-5.2
- gpt-5.4
- gpt-5.4-mini
- gpt-5.4-nano
- gpt-5.5
- claude-4.5-sonnet
- claude-4.6-sonnet
- claude-4.5-haiku
- gemini-2.5-flash-lite
- gemini-3.0-flash
- gemini-3.1-flash-lite
- null
nullable: true
description: Available LLM models for agents.
AgentRequest:
type: object
properties:
response_engine:
$ref: '#/components/schemas/ResponseEngine'
description: The Response Engine to attach to the agent. It is used to generate responses for the agent. You need to create a Response Engine first before attaching it to an agent.
example:
type: retell-llm
llm_id: llm_234sdertfsdsfsdf
version: 0
agent_name:
type: string
example: Jarvis
description: The name of the agent. Only used for your own reference.
nullable: true
version_description:
type: string
example: Customer support agent for handling product inquiries
description: Optional description of the agent version. Used for your own reference and documentation.
nullable: true
voice_id:
type: string
example: retell-Cimo
description: Unique voice id used for the agent. Find list of available voices and their preview in Dashboard.
voice_model:
type: string
enum:
- eleven_turbo_v2
- eleven_flash_v2
- eleven_turbo_v2_5
- eleven_flash_v2_5
- eleven_multilingual_v2
- eleven_v3
- sonic-3
- sonic-3-latest
- tts-1
- gpt-4o-mini-tts
- speech-02-turbo
- speech-2.8-turbo
- s1
- s2-pro
- null
description: Select the voice model used for the selected voice. Each provider has a set of available voice models. Set to null to remove voice model selection, and default ones will apply. Check out dashboard for more details of each voice model.
nullable: true
fallback_voice_ids:
type: array
items:
type: string
example:
- cartesia-Cimo
- minimax-Cimo
description: When TTS provider for the selected voice is experiencing outages, we would use fallback voices listed here for the agent. Voice id and the fallback voice ids must be from different TTS providers. The system would go through the list in order, if the first one in the list is also having outage, it would use the next one. Set to null to remove voice fallback for the agent.
nullable: true
voice_temperature:
type: number
example: 1
description: Controls how stable the voice is. Value ranging from [0,2]. Lower value means more stable, and higher value means more variant speech generation. Check the dashboard to see what provider supports this feature. If unset, default value 1 will apply.
voice_speed:
type: number
minimum: 0.5
maximum: 2
example: 1
description: Controls speed of voice. Value ranging from [0.5,2]. Lower value means slower speech, while higher value means faster speech rate. If unset, default value 1 will apply.
enable_dynamic_voice_speed:
type: boolean
example: true
description: If set to true, will enable dynamic voice speed adjustment based on the user's speech rate and conversation context. If unset, default value false will apply.
enable_dynamic_responsiveness:
type: boolean
example: true
description: If set to true, the agent will dynamically adjust how quickly it responds based on the user's speech rate and past turn-taking behavior in the call. If unset, default value false will apply.
volume:
type: number
example: 1
description: If set, will control the volume of the agent. Value ranging from [0,2]. Lower value means quieter agent speech, while higher value means louder agent speech. If unset, default value 1 will apply.
voice_emotion:
type: string
nullable: true
enum:
- calm
- sympathetic
- happy
- sad
- angry
- fearful
- surprised
- null
example: calm
description: 'Controls the emotional tone of the agent''s voice. Currently supported for Cartesia and Minimax TTS providers. If unset, no emotion will be used.
'
responsiveness:
type: number
minimum: 0
maximum: 1
example: 1
description: Controls how responsive is the agent. Value ranging from [0,1]. Lower value means less responsive agent (wait more, respond slower), while higher value means faster exchanges (respond when it can). If unset, default value 1 will apply.
interruption_sensitivity:
type: number
minimum: 0
maximum: 1
example: 1
description: Controls how sensitive the agent is to user interruptions. Value ranging from [0,1]. Lower value means it will take longer / more words for user to interrupt agent, while higher value means it's easier for user to interrupt agent. If unset, default value 1 will apply. When this is set to 0, agent would never be interrupted.
enable_backchannel:
type: boolean
example: true
description: Controls whether the agent would backchannel (agent interjects the speaker with phrases like "yeah", "uh-huh" to signify interest and engagement). Backchannel when enabled tends to show up more in longer user utterances. If not set, agent will not backchannel.
backchannel_frequency:
type: number
example: 0.9
description: Only applicable when enable_backchannel is true. Controls how often the agent would backchannel when a backchannel is possible. Value ranging from [0,1]. Lower value means less frequent backchannel, while higher value means more frequent backchannel. If unset, default value 0.8 will apply.
backchannel_words:
type: array
items:
type: string
example:
- yeah
- uh-huh
description: Only applicable when enable_backchannel is true. A list of words that the agent would use as backchannel. If not set, default backchannel words will apply. Check out [backchannel default words](/agent/interaction-configuration#backchannel) for more details. Note that certain voices do not work too well with certain words, so it's recommended to experiment before adding any words.
nullable: true
reminder_trigger_ms:
type: number
example: 10000
description: If set (in milliseconds), will trigger a reminder to the agent to speak if the user has been silent for the specified duration after some agent speech. Must be a positive number. If unset, default value of 10000 ms (10 s) will apply.
reminder_max_count:
type: integer
# --- truncated at 32 KB (55 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/retell-ai/refs/heads/main/openapi/retell-ai-create-batch-call-api-openapi.yml