POST /v2/create-phone-call – Retell AI Retell SDK

Create a new outbound phone call

post/v2/create-phone-call

Request body

from_numberstring required

The number you own in E.164 format. Must be a number purchased from Retell or imported to Retell.

to_numberstring required

The number you want to call, in E.164 format. If using a number purchased from Retell, only US numbers are supported as destination.

override_agent_idstring

For this particular call, override the agent used with this agent id. This does not bind the agent to this number, this is for one time override.

metadataobject

An arbitrary object for storage purpose only. You can put anything here like your internal customer id associated with the call. Not used for processing. You can later get this field from the call object.

retell_llm_dynamic_variablesobject

Add optional dynamic variables in key value pairs of string that injects into your Response Engine prompt and tool description. Only applicable for Response Engine.

custom_sip_headersobject

Add optional custom SIP headers to the call.

ignore_e164_validationboolean

If true, the e.164 validation will be ignored for the from_number. This can be useful when you want to dial to internal pseudo numbers. This only applies when you are using custom telephony and does not apply when you are using Retell Telephony. If omitted, the default value is false.

Example request

{
  "from_number": "+14157774444",
  "to_number": "+12137774445",
  "override_agent_id": "oBeDLoLOeuAbiuaMFXRtDOLriTJ5tSxD",
  "override_agent_version": 1,
  "agent_override": {
    "agent": {
      "agent_name": "Jarvis",
      "version_description": "Customer support agent for handling product inquiries",
      "voice_id": "retell-Cimo",
      "fallback_voice_ids": [
        "cartesia-Cimo",
        "minimax-Cimo"
      ],
      "voice_temperature": 1,
      "voice_speed": 1,
      "enable_dynamic_voice_speed": true,
      "enable_dynamic_responsiveness": true,
      "volume": 1,
      "voice_emotion": "calm",
      "responsiveness": 1,
      "interruption_sensitivity": 1,
      "enable_backchannel": true,
      "backchannel_frequency": 0.9,
      "backchannel_words": [
        "yeah",
        "uh-huh"
      ],
      "reminder_trigger_ms": 10000,
      "reminder_max_count": 2,
      "ambient_sound_volume": 1,
      "language": "en-US",
      "webhook_url": "https://webhook-url-here",
      "webhook_timeout_ms": 10000,
      "boosted_keywords": [
        "retell",
        "kroger"
      ],
      "data_storage_setting": "everything",
      "data_storage_retention_days": 30,
      "opt_in_signed_url": true,
      "signed_url_expiration_ms": 86400000,
      "pronunciation_dictionary": [
        {
          "word": "actually",
          "alphabet": "ipa",
          "phoneme": "ˈæktʃuəli"
        }
      ],
      "end_call_after_silence_ms": 600000,
      "max_call_duration_ms": 3600000,
      "voicemail_message": "Hi, please give us a callback.",
      "voicemail_detection_timeout_ms": 30000,
      "voicemail_option": {
        "action": {
          "type": "static_text",
          "text": "Please give us a callback tomorrow at 10am."
        }
      },
      "ivr_option": {
        "action": {
          "type": "hangup"
        }
      },
      "call_screening_option": {
        "agent_identity": "Acme Health scheduling team",
        "call_purpose": "confirming your appointment for tomorrow"
      },
      "post_call_analysis_data": [
        {
          "type": "string",
          "name": "customer_name",
          "description": "The name of the customer.",
          "examples": [
            "John Doe",
            "Jane Smith"
          ]
        }
      ],
      "analysis_successful_prompt": "The agent finished the task and the call was complete without being cutoff.",
      "analysis_summary_prompt": "Summarize the outcome of the conversation in two sentences.",
      "analysis_user_sentiment_prompt": "Evaluate the user's sentiment based on their tone and satisfaction level.",
      "begin_message_delay_ms": 1000,
      "ring_duration_ms": 30000,
      "stt_mode": "fast",
      "vocab_specialization": "general",
      "allow_user_dtmf": true,
      "user_dtmf_options": {
        "termination_key": "#"
      },
      "denoising_mode": "noise-cancellation",
      "timezone": "America/New_York"
    },
    "retell_llm": {
      "s2s_model": "gpt-realtime-1.5",
      "model_high_priority": true,
      "tool_call_strict_mode": true,
      "kb_config": {
        "top_k": 3,
        "filter_score": 0.6
      },
      "begin_after_user_silence_ms": 2000,
      "begin_message": "Hey I am a virtual assistant calling from Retell Hospital."
    },
    "conversation_flow": {
      "model_temperature": 0.7,
      "tool_call_strict_mode": true,
      "knowledge_base_ids": [
        "kb_001",
        "kb_002"
      ],
      "kb_config": {
        "top_k": 3,
        "filter_score": 0.6
      },
      "start_speaker": "agent",
      "begin_after_user_silence_ms": 2000
    }
  },
  "retell_llm_dynamic_variables": {
    "customer_name": "John Doe"
  },
  "custom_sip_headers": {
    "X-Custom-Header": "Custom Value"
  },
  "ignore_e164_validation": true
}

Response

Successfully made an outbound call.

call_type'phone_call' required

Type of the call. Used to distinguish between web call and phone call.

from_numberstring required

The caller number.

to_numberstring required

The callee number.

direction'inbound' | 'outbound' required

Direction of the phone call.

call_idstring required

Unique id of the call. Used to identify the call in the LLM websocket and used to authenticate in the audio websocket.

agent_idstring required

Corresponding agent id of this call.

agent_namestring

Name of the agent.

agent_versioninteger required

The version of the agent.

call_status'registered' | 'not_connected' | 'ongoing' | 'ended' | 'error' required

Status of call.

registered: Call id issued, starting to make a call using this id.
ongoing: Call connected and ongoing.
ended: The underlying websocket has ended for the call. Either user or agent hung up, or call transferred.
error: Call encountered error.

metadataobject

retell_llm_dynamic_variablesobject

Add optional dynamic variables in key value pairs of string that injects into your Response Engine prompt and tool description. Only applicable for Response Engine.

collected_dynamic_variablesobject

Dynamic variables collected from the call. Only available after the call ends.

custom_sip_headersobject

Custom SIP headers to be added to the call.

data_storage_setting'everything' | 'everything_except_pii' | 'basic_attributes_only' nullable

Data storage setting for this call's agent. "everything" stores all data, "everything_except_pii" excludes PII when possible, "basic_attributes_only" stores only metadata.

opt_in_signed_urlboolean

Whether this agent opts in for signed URLs for public logs and recordings. When enabled, the generated URLs will include security signatures that restrict access and automatically expire after 24 hours.

start_timestampinteger

Begin timestamp (milliseconds since epoch) of the call. Available after call starts.

end_timestampinteger

End timestamp (milliseconds since epoch) of the call. Available after call ends.

transfer_end_timestampinteger

Transfer end timestamp (milliseconds since epoch) of the call. Available after transfer call ends.

duration_msinteger

Duration of the call in milliseconds. Available after call ends.

transcriptstring

Transcription of the call. Available after call ends.

recording_urlstring

Recording of the call. Available after call ends.

recording_multi_channel_urlstring

Recording of the call, with each party's audio stored in a separate channel. Available after the call ends.

scrubbed_recording_urlstring

Recording of the call without PII. Available after call ends.

scrubbed_recording_multi_channel_urlstring

Recording of the call without PII, with each party's audio stored in a separate channel. Available after the call ends.

public_log_urlstring

Public log of the call, containing details about all the requests and responses received in LLM WebSocket, latency tracking for each turntaking, helpful for debugging and tracing. Available after call ends.

knowledge_base_retrieved_contents_urlstring

URL to the knowledge base retrieved contents of the call. Available after call ends if the call utilizes knowledge base feature. It consists of the respond id and the retrieved contents related to that response. It's already rendered in call history tab of dashboard, and you can also manually download and check against the transcript to view the knowledge base retrieval results.

transfer_destinationstring nullable

The destination number or identifier where the call was transferred to. Only populated when the disconnection reason was call_transfer. Can be a phone number or a SIP URI. SIP URIs are prefixed with "sip:" and may include a ";transport=..." portion (if transport is known) where the transport type can be "tls", "tcp" or "udp".

Example response

{
  "call_type": "phone_call",
  "from_number": "+12137771234",
  "to_number": "+12137771235",
  "direction": "inbound",
  "telephony_identifier": {
    "twilio_call_sid": "CA5d0d0d8047bf685c3f0ff980fe62c123"
  },
  "call_id": "Jabr9TXYYJHfvl6Syypi88rdAHYHmcq6",
  "agent_id": "oBeDLoLOeuAbiuaMFXRtDOLriTJ5tSxD",
  "agent_name": "My Agent",
  "agent_version": 1,
  "call_status": "registered",
  "retell_llm_dynamic_variables": {
    "customer_name": "John Doe"
  },
  "collected_dynamic_variables": {
    "last_node_name": "Test node"
  },
  "custom_sip_headers": {
    "X-Custom-Header": "Custom Value"
  },
  "data_storage_setting": "everything",
  "opt_in_signed_url": true,
  "start_timestamp": 1703302407333,
  "end_timestamp": 1703302428855,
  "transfer_end_timestamp": 1703302628855,
  "duration_ms": 10000,
  "transcript": "Agent: hi how are you doing?\nUser: Doing pretty well. How are you?\nAgent: That's great to hear! I'm doing well too, thanks! What's up?\nUser: I don't have anything in particular.\nAgent: Got it, just checking in!\nUser: Alright. See you.\nAgent: have a nice day\n",
  "transcript_object": [
    {
      "role": "agent",
      "content": "hi how are you doing?",
      "words": [
        {
          "word": "hi",
          "start": 0.7,
          "end": 1.3
        }
      ]
    }
  ],
  "transcript_with_tool_calls": [
    {
      "role": "agent",
      "content": "hi how are you doing?",
      "words": [
        {
          "word": "hi",
          "start": 0.7,
          "end": 1.3
        }
      ]
    }
  ],
  "scrubbed_transcript_with_tool_calls": [
    {
      "role": "agent",
      "content": "hi how are you doing?",
      "words": [
        {
          "word": "hi",
          "start": 0.7,
          "end": 1.3
        }
      ]
    }
  ],
  "recording_url": "https://retellai.s3.us-west-2.amazonaws.com/Jabr9TXYYJHfvl6Syypi88rdAHYHmcq6/recording.wav",
  "recording_multi_channel_url": "https://retellai.s3.us-west-2.amazonaws.com/Jabr9TXYYJHfvl6Syypi88rdAHYHmcq6/recording_multichannel.wav",
  "scrubbed_recording_url": "https://retellai.s3.us-west-2.amazonaws.com/Jabr9TXYYJHfvl6Syypi88rdAHYHmcq6/recording.wav",
  "scrubbed_recording_multi_channel_url": "https://retellai.s3.us-west-2.amazonaws.com/Jabr9TXYYJHfvl6Syypi88rdAHYHmcq6/recording_multichannel.wav",
  "public_log_url": "https://retellai.s3.us-west-2.amazonaws.com/Jabr9TXYYJHfvl6Syypi88rdAHYHmcq6/public_log.txt",
  "knowledge_base_retrieved_contents_url": "https://retellai.s3.us-west-2.amazonaws.com/Jabr9TXYYJHfvl6Syypi88rdAHYHmcq6/kb_retrieved_contents.txt",
  "latency": {
    "e2e": {
      "p50": 800,
      "p90": 1200,
      "p95": 1500,
      "p99": 2500,
      "max": 2700,
      "min": 500,
      "num": 10
    },
    "asr": {
      "p50": 800,
      "p90": 1200,
      "p95": 1500,
      "p99": 2500,
      "max": 2700,
      "min": 500,
      "num": 10
    },
    "llm": {
      "p50": 800,
      "p90": 1200,
      "p95": 1500,
      "p99": 2500,
      "max": 2700,
      "min": 500,
      "num": 10
    },
    "llm_websocket_network_rtt": {
      "p50": 800,
      "p90": 1200,
      "p95": 1500,
      "p99": 2500,
      "max": 2700,
      "min": 500,
      "num": 10
    },
    "tts": {
      "p50": 800,
      "p90": 1200,
      "p95": 1500,
      "p99": 2500,
      "max": 2700,
      "min": 500,
      "num": 10
    },
    "knowledge_base": {
      "p50": 800,
      "p90": 1200,
      "p95": 1500,
      "p99": 2500,
      "max": 2700,
      "min": 500,
      "num": 10
    },
    "s2s": {
      "p50": 800,
      "p90": 1200,
      "p95": 1500,
      "p99": 2500,
      "max": 2700,
      "min": 500,
      "num": 10
    }
  },
  "transfer_destination": "+12137771234",
  "call_analysis": {
    "call_summary": "The agent called the user to ask question about his purchase inquiry. The agent asked several questions regarding his preference and asked if user would like to book an appointment. The user happily agreed and scheduled an appointment next Monday 10am.",
    "user_sentiment": "Positive",
    "call_successful": true
  },
  "call_cost": {
    "product_costs": [
      {
        "product": "elevenlabs_tts",
        "unit_price": 1,
        "cost": 60
      }
    ],
    "total_duration_seconds": 60,
    "total_duration_unit_price": 1,
    "combined_cost": 70
  }
}

Changes

Changed in 21 of the 28 revisions of this API.941966

May 28, 202640402ca870b922See the full diff
- ▲
  added to the ///// response property oneOf list for the response status
  response-property-one-of-added
- ▲
  added to the ///// response property oneOf list for the response status
  response-property-one-of-added
- ●
  changed the pattern of the request property / from ^(latest|(?!(?:v\d+)$)[a-z][a-z0-9_-]{0,19})$ to ^(latest|latest_published|(?!(?:latest|latest_published|v\d+)$)[a-z][a-z0-9_-]{0,19})$
  request-property-pattern-changed
- ●
  added the new no_concurrency_fallback enum value to the //// response property for the response status
  response-property-enum-value-added
May 18, 20266342a999010821See the full diff
- ▲
  added to the ///// response property oneOf list for the response status
  response-property-one-of-added
- ▲
  added to the ///// response property oneOf list for the response status
  response-property-one-of-added
- ●
  removed the request property //
  request-property-removed
May 12, 20266dff2a12f8663See the full diff
- ▲
  the / request property type changed from no type to string
  request-property-type-changed
- ▲
  the ///// response's property type changed from no type to string for status
  response-property-type-changed
- ▲
  the ///// response's property type changed from no type to string for status
  response-property-type-changed
May 11, 20267c30e3ea25363See the full diff
- ○
  added the new gpt-realtime-2 enum value to the request property //
  request-property-enum-value-added
- ○
  added the new s2.1-pro enum value to the request property //
  request-property-enum-value-added
- ○
  added the new sonic-3.5 enum value to the request property //
  request-property-enum-value-added
May 8, 20267dd16ddf69d81See the full diff
- ●
  changed the pattern of the request property / from ^[a-z0-9_-]+$ to ^(latest|(?!(?:v\d+)$)[a-z][a-z0-9_-]{0,19})$
  request-property-pattern-changed
May 7, 2026f1a0d7c1e36c35See the full diff
- ▲
  removed the enum value gemini-2.5-flash of the request property //
  request-property-enum-value-removed
- ▲
  removed the enum value gemini-2.5-flash of the request property ///////
  request-property-enum-value-removed
- ▲
  removed the enum value gemini-2.5-flash of the request property //
  request-property-enum-value-removed
- ○
  added the new optional request property //
  new-optional-request-property
- ○
  added the new optional request property //
  new-optional-request-property
- ○
  added the new optional request property ///
  new-optional-request-property
- ○
  added the new optional request property ///
  new-optional-request-property
- ○
  request property list-of-types was widened by adding types string to media type application/json
  request-property-list-of-types-widened
Apr 28, 20261b4a9d84942a53See the full diff
- ▲
  added to the /// request property allOf list
  request-property-all-of-added
- ▲
  removed the enum value azure of the request property ///
  request-property-enum-value-removed
- ▲
  removed the enum value deepgram of the request property ///
  request-property-enum-value-removed
- ▲
  removed the enum value soniox of the request property ///
  request-property-enum-value-removed
- ▲
  the /// request property type changed from string to no type
  request-property-type-changed
- ○
  added the new gpt-5.5 enum value to the request property //
  request-property-enum-value-added
- ○
  added the new gpt-5.5 enum value to the request property ///////
  request-property-enum-value-added
- ○
  added the new gpt-5.5 enum value to the request property //
  request-property-enum-value-added
Apr 27, 2026a44406f743c2651See the full diff
- ▲
  removed the enum value af-ZA of the request property //
  request-property-enum-value-removed
- ▲
  removed the enum value ar-SA of the request property //
  request-property-enum-value-removed
- ▲
  removed the enum value az-AZ of the request property //
  request-property-enum-value-removed
- ▲
  removed the enum value bg-BG of the request property //
  request-property-enum-value-removed
- ▲
  removed the enum value bs-BA of the request property //
  request-property-enum-value-removed
- ▲
  removed the enum value ca-ES of the request property //
  request-property-enum-value-removed
- ▲
  removed the enum value cs-CZ of the request property //
  request-property-enum-value-removed
- ▲
  removed the enum value cy-GB of the request property //
  request-property-enum-value-removed
- ▲
  removed the enum value da-DK of the request property //
  request-property-enum-value-removed
- ▲
  removed the enum value de-DE of the request property //
  request-property-enum-value-removed
- ▲
  removed the enum value el-GR of the request property //
  request-property-enum-value-removed
- ▲
  removed the enum value en-AU of the request property //
  request-property-enum-value-removed
- ▲
  removed the enum value en-GB of the request property //
  request-property-enum-value-removed
- ▲
  removed the enum value en-IN of the request property //
  request-property-enum-value-removed
- ▲
  removed the enum value en-NZ of the request property //
  request-property-enum-value-removed
- ▲
  removed the enum value en-US of the request property //
  request-property-enum-value-removed
- ▲
  removed the enum value es-419 of the request property //
  request-property-enum-value-removed
- ▲
  removed the enum value es-ES of the request property //
  request-property-enum-value-removed
- ▲
  removed the enum value fa-IR of the request property //
  request-property-enum-value-removed
- ▲
  removed the enum value fi-FI of the request property //
  request-property-enum-value-removed
- ▲
  removed the enum value fil-PH of the request property //
  request-property-enum-value-removed
- ▲
  removed the enum value fr-CA of the request property //
  request-property-enum-value-removed
- ▲
  removed the enum value fr-FR of the request property //
  request-property-enum-value-removed
- ▲
  removed the enum value gl-ES of the request property //
  request-property-enum-value-removed
- ▲
  removed the enum value he-IL of the request property //
  request-property-enum-value-removed
- ▲
  removed the enum value hi-IN of the request property //
  request-property-enum-value-removed
- ▲
  removed the enum value hr-HR of the request property //
  request-property-enum-value-removed
- ▲
  removed the enum value hu-HU of the request property //
  request-property-enum-value-removed
- ▲
  removed the enum value hy-AM of the request property //
  request-property-enum-value-removed
- ▲
  removed the enum value id-ID of the request property //
  request-property-enum-value-removed
- ▲
  removed the enum value is-IS of the request property //
  request-property-enum-value-removed
- ▲
  removed the enum value it-IT of the request property //
  request-property-enum-value-removed
- ▲
  removed the enum value ja-JP of the request property //
  request-property-enum-value-removed
- ▲
  removed the enum value kk-KZ of the request property //
  request-property-enum-value-removed
- ▲
  removed the enum value kn-IN of the request property //
  request-property-enum-value-removed
- ▲
  removed the enum value ko-KR of the request property //
  request-property-enum-value-removed
- ▲
  removed the enum value lt-LT of the request property //
  request-property-enum-value-removed
- ▲
  removed the enum value lv-LV of the request property //
  request-property-enum-value-removed
- ▲
  removed the enum value mk-MK of the request property //
  request-property-enum-value-removed
- ▲
  removed the enum value mr-IN of the request property //
  request-property-enum-value-removed
- ▲
  removed the enum value ms-MY of the request property //
  request-property-enum-value-removed
- ▲
  removed the enum value multi of the request property //
  request-property-enum-value-removed
- ▲
  removed the enum value ne-NP of the request property //
  request-property-enum-value-removed
- ▲
  removed the enum value nl-BE of the request property //
  request-property-enum-value-removed
- ▲
  removed the enum value nl-NL of the request property //
  request-property-enum-value-removed
- ▲
  removed the enum value no-NO of the request property //
  request-property-enum-value-removed
- ▲
  removed the enum value pl-PL of the request property //
  request-property-enum-value-removed
- ▲
  removed the enum value pt-BR of the request property //
  request-property-enum-value-removed
- ▲
  removed the enum value pt-PT of the request property //
  request-property-enum-value-removed
- ▲
  removed the enum value ro-RO of the request property //
  request-property-enum-value-removed
- ▲
  removed the enum value ru-RU of the request property //
  request-property-enum-value-removed
- ▲
  removed the enum value sk-SK of the request property //
  request-property-enum-value-removed
- ▲
  removed the enum value sl-SI of the request property //
  request-property-enum-value-removed
- ▲
  removed the enum value sr-RS of the request property //
  request-property-enum-value-removed
- ▲
  removed the enum value sv-SE of the request property //
  request-property-enum-value-removed
- ▲
  removed the enum value sw-KE of the request property //
  request-property-enum-value-removed
- ▲
  removed the enum value ta-IN of the request property //
  request-property-enum-value-removed
- ▲
  removed the enum value th-TH of the request property //
  request-property-enum-value-removed
- ▲
  removed the enum value tr-TR of the request property //
  request-property-enum-value-removed
- ▲
  removed the enum value uk-UA of the request property //
  request-property-enum-value-removed
- ▲
  removed the enum value ur-IN of the request property //
  request-property-enum-value-removed
- ▲
  removed the enum value vi-VN of the request property //
  request-property-enum-value-removed
- ▲
  removed the enum value yue-CN of the request property //
  request-property-enum-value-removed
- ▲
  removed the enum value zh-CN of the request property //
  request-property-enum-value-removed
- ▲
  the // request property type changed from string to no type
  request-property-type-changed
- ○
  added subschema #2 to the // request property oneOf list
  request-property-one-of-added
Apr 20, 20268ee53928bf3127See the full diff
- ●
  removed the request property //
  request-property-removed
- ●
  added the new manual_stopped enum value to the //// response property for the response status
  response-property-enum-value-added
- ○
  added the new gemini-3.1-flash-lite enum value to the request property //
  request-property-enum-value-added
- ○
  added the new gemini-3.1-flash-lite enum value to the request property ///////
  request-property-enum-value-added
- ○
  added the new gemini-3.1-flash-lite enum value to the request property //
  request-property-enum-value-added
- ○
  added the new s2-pro enum value to the request property //
  request-property-enum-value-added
- ○
  added the new soniox enum value to the request property ///
  request-property-enum-value-added
- ○
  added the optional property ////////// to the response with the status
  response-optional-property-added
- ○
  added the optional property ////////// to the response with the status
  response-optional-property-added
Apr 1, 202656de19127afb13See the full diff
- ▲
  removed from the /// request property oneOf list
  request-property-one-of-removed
- ○
  added the new optional request property //
  new-optional-request-property
- ○
  added the new optional request property //
  new-optional-request-property
- ○
  added to the /// request property oneOf list
  request-property-one-of-added

Full history (21 revisions)