---
title: "Create Phone Call"
method: POST
path: "/voice/phone-call"
tags: ["Voice"]
---

# Create Phone Call

`POST /voice/phone-call`

## Request

- Base URL: `https://api.puppeteerai.com`
- URL: `https://api.puppeteerai.com/voice/phone-call`
- Auth: none declared. Required headers: `Authorization`

Find or create a thread for the given phone number and project, then initiate a phone call.

## Headers

- `Authorization` string, required: API key for your Puppeteer organization.

## Request body

- CreateThreadAndCallInput
  - `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, nullable: Timezone for the thread (e.g., "America/Chicago").
  - `json_data` string, nullable: 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, nullable: ISO 8601 datetime to schedule the call for a future time. If omitted, the call starts immediately.
  - `background` boolean: When true, the call is queued and the endpoint returns 202 immediately. When false (default), the call is initiated synchronously.
  - `retell_account_id` string, nullable: The UUID of the Retell account to use. Required when the project has multiple phone numbers.

## Response `200`

Successful Response

- ThreadAndCallResponse
  - `thread_id` string, required: The unique identifier for the thread (new or existing).
  - `call` PublicCallInfo, required
    - `id` string, required: Unique identifier for the call.
    - `call_type` string, required: Type of call (e.g., "phone_call", "web_call").
    - `status` string, required: Current status of the call (e.g., "queued", "ongoing", "ended", "scheduled").
    - `to_number` string, nullable: The phone number being called (phone calls only).
    - `from_number` string, nullable: The originating phone number (phone calls only).
    - `scheduled_for` string, nullable: ISO 8601 datetime if the call is scheduled.
    - `start_timestamp` integer, nullable: Unix timestamp when the call started.
    - `end_timestamp` integer, nullable: Unix timestamp when the call ended.
    - `duration_ms` integer, nullable: Duration of the call in milliseconds.

## Other responses

- `422`: Validation Error

---

[API](https://skmtc.dev/getpuppeteer/apis/puppeteer-core-api.md) - [All operations](https://skmtc.dev/getpuppeteer/apis/puppeteer-core-api/llms.txt) - [OpenAPI document](https://skmtc.dev/getpuppeteer/apis/puppeteer-core-api/revisions/94b4e928b42f?raw)