Sign in

v28

latestOpenAPI 3.0.3Apache 2.0raw.githubusercontent.com2026-05-2887246443.7 KB

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

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.

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.

disconnection_reason'user_hangup' | 'agent_hangup' | 'call_transfer' | 'voicemail_reached' | 'ivr_reached' | 'inactivity' | 'max_duration_reached' | 'concurrency_limit_reached' | 'no_concurrency_fallback' | 'no_valid_payment' | 'scam_detected' | 'dial_busy' | 'dial_failed' | 'dial_no_answer' | 'invalid_destination' | 'telephony_provider_permission_denied' | 'telephony_provider_unavailable' | 'sip_routing_error' | 'marked_as_spam' | 'user_declined' | 'error_llm_websocket_open' | 'error_llm_websocket_lost_connection' | 'error_llm_websocket_runtime' | 'error_llm_websocket_corrupt_payload' | 'error_no_audio_received' | 'error_asr' | 'error_retell' | 'error_unknown' | 'error_user_not_joined' | 'registered_call_timeout' | 'transfer_bridged' | 'transfer_cancelled' | 'manual_stopped'
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
  }
}