AgentPhone — Phone Call API for AI Agents | Make Calls with One API Request

Introduction

AgentPhone is the phone call API for AI agents. One API call to dial any phone number, handle the conversation with voice AI, and return structured JSON with transcript and summary. First 5 calls are free — no credit card required.

Base URL: https://agentphone.app/api/v1

Authentication

All requests require an API key in the x-api-key header. Get your key from the dashboard.

Header

x-api-key: ak_live_your_key_here

Quickstart

Make your first call in 30 seconds:

curl -X POST https://agentphone.app/api/v1/calls \  -H "x-api-key: YOUR_API_KEY" \  -H "Content-Type: application/json" \  -d '{    "to_phone_number": "+14155551234",    "objective": "Book a table for 2 at 7pm",    "business_name": "Nopa",    "website": "https://nopa-sf.com"  }'

The call is queued immediately. Poll for status:

curl https://agentphone.app/api/v1/calls/CALL_ID \  -H "x-api-key: YOUR_API_KEY"

Create Call

Create an outbound phone call. The AI agent will dial the number and work toward the given objective.

POST/calls

Request body

to_phone_numberstringrequired

E.164 phone number to call, e.g. +14155551234

objectivestringrequired

What the agent should accomplish on the call.

business_namestring

Name of the business being called. Used in the agent's system prompt.

websitestring

Website URL. AgentPhone scrapes it before the call to give the agent business context.

languagestring

Language for the call (e.g. spanish, french). Defaults to English.

curl -X POST https://agentphone.app/api/v1/calls \  -H "x-api-key: YOUR_API_KEY" \  -H "Content-Type: application/json" \  -d '{    "to_phone_number": "+14155551234",    "objective": "Book a table for 2 at 7pm",    "business_name": "Nopa",    "website": "https://nopa-sf.com"  }'

Response (202)

Response

{  "data": {    "call_id": "cl_abc123",    "status": "queued",    "to_phone_number": "+14155551234",    "objective": "Book a table for 2 at 7pm",    "business_name": "Nopa",    "website": "https://nopa-sf.com",    "created_at": "2026-02-20T12:00:00Z"  },  "credits_remaining": 49}

Get Call

Retrieve the current status and details of a specific call.

GET/calls/:call_id

curl https://agentphone.app/api/v1/calls/CALL_ID \  -H "x-api-key: YOUR_API_KEY"

Response (200)

Response

{  "data": {    "call_id": "cl_abc123",    "status": "completed",    "to_phone_number": "+14155551234",    "objective": "Book a table for 2 at 7pm",    "business_name": "Nopa",    "outcome": "achieved",    "outcome_details": "Table confirmed for 2 guests at 7:00 PM tonight under the caller's name.",    "summary": "Successfully booked a table for 2 at 7:00 PM tonight.",    "transcript": "Agent: Hi, I'd like to book a table...\nHost: Sure, for how many?...",    "duration_seconds": 42,    "recording_url": "https://...",    "started_at": "2026-02-20T12:00:05Z",    "ended_at": "2026-02-20T12:00:47Z",    "created_at": "2026-02-20T12:00:00Z"  }}

List Calls

List your recent calls, newest first.

GET/calls

Query parameters

limitinteger

Number of calls to return. Default 50, max 200.

statusstring

Filter by status: queued, dialing, in_progress, completed, canceled, failed

curl "https://agentphone.app/api/v1/calls?limit=10&status=completed" \  -H "x-api-key: YOUR_API_KEY"

Call Lifecycle

Every call progresses through these statuses:

queuedCall created, waiting to be dispatched

dialingPhone is ringing

in_progressCall connected, agent is speaking

completedCall finished. Transcript, summary, and outcome available.

canceledCall was canceled before completion.

failedCall could not be completed. Check error_code.

The outcome field is set on completion: achieved, not_achieved, or partial.

Errors

The API returns structured error responses:

Error response

{  "error": "Missing required field 'to_phone_number'. Expected E.164 phone number like +14155551234",  "code": "validation_error"}

Status codes

400Bad Request

Invalid input. Check the error message for details.

401Unauthorized

Missing or invalid API key.

402Payment Required

Insufficient credits. The response includes a buy_credits_url — a Stripe Checkout link to purchase 10 credits. Surface this URL to the user.

404Not Found

Call not found or doesn't belong to your account.

422Unprocessable Entity

Request body is valid JSON but contains invalid values (e.g. malformed phone number).

429Too Many Requests

Rate limited. Max 10 calls/minute. Check the Retry-After header.

500Internal Server Error

Unexpected error on our end. Retry or contact support.

Error codes

Code	Description
`unauthorized`	Missing or invalid API key.
`invalid_json`	Request body is not valid JSON.
`invalid_body`	Body is not a JSON object.
`missing_field`	A required field (to_phone_number or objective) is missing.
`invalid_phone`	Phone number format is invalid. Expected +1XXXXXXXXXX.
`unsupported_region`	Only US/Canada (+1) numbers are supported.
`emergency_number`	Emergency numbers cannot be called through the API.
`insufficient_credits`	Not enough credits. Response includes buy_credits_url (Stripe Checkout link).
`rate_limit_exceeded`	Too many requests. Wait and retry.
`call_not_found`	The specified call_id does not exist.
`call_failed`	The call could not be dispatched or completed.

Rate limits

The API enforces a limit of 10 calls per minute per API key. When exceeded, the response includes a Retry-After header with the number of seconds to wait.

agentphone.app

OpenAPI GitHub Dashboard