POST
/
v1
/
calls
/
dial-outbound-phone-call
{
  "_id": "<string>",
  "ai_agent_id": "<string>",
  "ai_agent_name": "<string>",
  "call_status": "registered",
  "override_ai_agent_id": "<string>",
  "metadata": {},
  "pia_llm_dynamic_data": {},
  "call_start_time": "2023-11-07T05:31:56Z",
  "call_end_time": "2023-11-07T05:31:56Z",
  "messages": [
    {
      "role": "agent",
      "content": "<string>"
    }
  ],
  "recorded_call_audio_url": "<string>",
  "access_token": "<string>",
  "call_duration_seconds": 123,
  "call_type": "phone_call",
  "from_number": "<string>",
  "to_number": "<string>",
  "direction": "inbound",
  "call_finish_reason": "user_ended_call"
}

Body

application/json
​
from_number
string
required

The phone number initiating the call (E.164 format)

​
to_number
string
required

The phone number receiving the call (E.164 format)

​
direction
enum<string>
required

Specifies whether this is an incoming or outgoing call

Available options:
inbound,
outbound
​
call_id
string | null

Optional custom identifier for the call, if not provided, one will be generated

​
override_ai_agent_id
string | null

Optional alternative AI agent identifier for special handling scenarios

​
metadata
object | null

Custom key-value pairs for storing call-specific information

​
pia_llm_dynamic_data
object | null

Dynamic data to be used by the AI agent during this call

Response

201
application/json
Successful Response
​
call_status
enum<string>
required

Current status of the call: 'registered' for initialized calls, 'ongoing' for active calls, 'ended' for completed calls, 'error' for failed calls

Available options:
registered,
ongoing,
ended,
error
​
from_number
string
required

The phone number that initiated the call (E.164 format)

​
to_number
string
required

The phone number that received the call (E.164 format)

​
direction
enum<string>
required

Indicates whether the call was received by or initiated from the Pia Platform

Available options:
inbound,
outbound
​
_id
string

Unique identifier for the call session, automatically generated as a MongoDB ObjectId

​
ai_agent_id
string | null

Identifier of the AI agent handling this call

​
ai_agent_name
string | null

Name of the AI agent handling this call

​
override_ai_agent_id
string | null

Optional identifier for an alternative AI agent handling this call

​
metadata
object | null

Custom key-value pairs storing additional information about the call

​
pia_llm_dynamic_data
object | null

Dynamic data used by the AI agent during the call

​
call_start_time
string | null

Timestamp when the call was initiated, in UTC

​
call_end_time
string | null

Timestamp when the call was terminated, in UTC

​
messages
object[] | null

Chronological list of messages exchanged during the call

​
recorded_call_audio_url
string | null

URL to access the recorded audio file of the call

​
access_token
string | null

Security token for accessing call-related resources

​
call_duration_seconds
integer | null

Duration of the call in seconds

​
call_type
string
default:phone_call

Indicates this response is for a telephone call

Allowed value: "phone_call"
​
call_finish_reason
enum<string> | null

Detailed reason why the phone call ended, if applicable

Available options:
user_ended_call,
agent_ended_call,
call_transferred,
voicemail_detected,
inactivity_timeout,
answering_machine_detected,
maximum_duration_exceeded,
concurrent_call_limit_reached,
invalid_payment,
potential_scam_detected,
inbound_webhook_error,
line_busy,
call_failed,
no_answer,
llm_websocket_initialization_error,
llm_websocket_connection_lost,
llm_websocket_runtime_error,
llm_websocket_payload_corruption,
frontend_payload_corruption,
twilio_service_error,
no_audio_input,
speech_recognition_error,
retell_service_error,
unknown_error,
user_connection_failure,
registered_call_timed_out