Skip to main content
POST
/
voice
/
phone-call
Create Phone Call
curl --request POST \
  --url https://api.puppeteerai.com/voice/phone-call \
  --header 'Authorization: <authorization>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "callee": "<string>",
  "project_id": "<string>",
  "timezone": "<string>",
  "json_data": "<string>",
  "scheduled_for": "2023-11-07T05:31:56Z",
  "background": false,
  "retell_account_id": "<string>"
}
'
{
  "thread_id": "<string>",
  "call": {
    "id": "<string>",
    "call_type": "<string>",
    "status": "<string>",
    "to_number": "<string>",
    "from_number": "<string>",
    "scheduled_for": "<string>",
    "start_timestamp": 123,
    "end_timestamp": 123,
    "duration_ms": 123
  }
}

Headers

​
Authorization
string
required

API key for your Puppeteer organization.

Body

application/json
​
callee
string
required

The phone number to call, in E.164 format (e.g., +12025550123).

​
project_id
string
required

The UUID of the Puppeteer project.

​
timezone
string | null

Timezone for the thread (e.g., "America/Chicago").

​
json_data
string | null

JSON data as a string to be sent to the thread upon creation. This data will be processed by the thread's JSON input handler.

​
scheduled_for
string<date-time> | null

ISO 8601 datetime to schedule the call for a future time. If omitted, the call starts immediately.

​
background
boolean
default:false

When true, the call is queued and the endpoint returns 202 immediately. When false (default), the call is initiated synchronously.

​
retell_account_id
string | null

The UUID of the Retell account to use. Required when the project has multiple phone numbers.

Response

Successful Response

​
thread_id
string
required

The unique identifier for the thread (new or existing).

​
call
PublicCallInfo · object
required

Details about the initiated call.