---
title: "Create Phone Call"
method: POST
path: "/v2/phone-calls"
tags: ["v2", "phone-calls"]
---

# Create Phone Call

`POST /v2/phone-calls`

## Request

- Base URL: `https://api.mentium.io` (the document declares no server; this is the origin it was published from)
- URL: `https://api.mentium.io/v2/phone-calls`
- Auth: HTTP bearer

Create a phone call record.

Note: In production, calls are created by:
- Outbound API (Package 6)
- Webhooks (Package 5)

This endpoint is primarily for testing purposes.

## Headers

- `mentium-workspace-id` string, nullable

## Request body

- CreatePhoneCallRequest: Request to create a phone call record. Note: In production, calls are created by: - Outbound API (Package 6) - Webhooks (Package 5) This endpoint is primarily for testing purposes.
  - `direction` 'INBOUND' | 'OUTBOUND', required
  - `from_number` string, required
  - `to_number` string, required
  - `ai_agent_id` string, nullable: Internal Mentium ai_agent.id
  - `elevenlabs_agent_id` string, nullable: External ElevenLabs agent ID
  - `external_reference_carrier_id` string, nullable: TMS Carrier ID
  - `external_reference_carrier_name` string, nullable: Carrier display name snapshotted at call creation time
  - `external_reference_load_id` string, nullable: TMS Load ID
  - `conversation_id` string, nullable: ElevenLabs conversation ID
  - `twilio_call_sid` string, nullable: Twilio call SID

## Response `201`

Successful Response

- PhoneCallResponse: Phone call data returned from API
  - `id` string, required
  - `organization_id` string, required
  - `workspace_id` string, required
  - `direction` 'INBOUND' | 'OUTBOUND', required
  - `status` 'INITIATED' | 'RINGING' | 'ACTIVE' | 'COMPLETED' | 'FAILED' | 'NO_ANSWER' | 'BUSY', required
  - `from_number` string, required
  - `to_number` string, required
  - `external_reference_carrier_id` string, nullable
  - `external_reference_carrier_name` string, nullable
  - `external_reference_load_id` string, nullable
  - `ai_agent_id` string, nullable
  - `ai_agent_name` string, nullable
  - `ai_agent_revision_id` string, nullable
  - `ai_agent_revision_number` integer, nullable
  - `elevenlabs_agent_id` string, nullable
  - `conversation_id` string, nullable
  - `twilio_call_sid` string, nullable
  - `carrier_offer_id` string, nullable
  - `carrier_offer` CarrierOfferEmbedded
    - `id` string, required
    - `load_offer_id` string, required
    - `status` string, required
    - `opening_carrier_rate_amount` number, nullable
    - `latest_carrier_rate_amount` number, nullable
    - `current_carrier_rate_amount` number, nullable
    - `booked_at` string, date-time, nullable
    - `currency` string, nullable
    - `load_external_reference_id` string, nullable
    - `load_origin` string, nullable
    - `load_destination` string, nullable
    - `carrier_mc_number` string, nullable
    - `carrier_dot_number` string, nullable
  - `initiated_at` string, date-time, required
  - `answered_at` string, date-time, nullable
  - `ended_at` string, date-time, nullable
  - `duration_seconds` integer, nullable
  - `outcome` 'BOOKED' | 'NEGOTIATING' | 'REJECTED' | 'ERROR' | 'TRANSFERRED'
  - `negotiated_rate` string, nullable
  - `negotiated_rate_currency` string, nullable
  - `notes` string, nullable
  - `recording_url` string, nullable
  - `transfer_leg_sid` string, nullable
  - `transfer_leg_status` string, nullable
  - `transfer_leg_duration_seconds` integer, nullable
  - `transfer_connected_at` string, date-time, nullable
  - `post_transfer_transcript` object[], nullable
  - `post_transfer_transcription_terminal_result` string, nullable
  - `post_transfer_recording_url` string, nullable
  - `notes_spanning_transfer` string, nullable
  - `transfer_result` string, nullable
  - `transfer_detail` string, nullable
  - `transfer_notify_email` string, nullable
  - `transfer_notify_name` string, nullable
  - `transfer_notify_phone` string, nullable
  - `transfer_source` string, nullable
  - `transcript` object[], nullable
  - `metadata` object, nullable
  - `events` PhoneCallEventResponse[]
    - `id` string, required
    - `phone_call_id` string, required
    - `event_type` 'TOOL_CALL' | 'STATUS_CHANGE' | 'CONVERSATION_STARTED' | 'CONVERSATION_ENDED' | 'TRANSFER_NUMBER_ASSIGNED' | 'TRANSFER_LEG_OBSERVED' | 'RECORDING_ARMED' | 'RECORDING_RECEIVED' | 'RECORDING_STORED', required
    - `timestamp` string, date-time, required
    - `data` object, required
  - `estimated_cost_usd` string, nullable
  - `feedback_count` integer
  - `latest_feedback_text` string, nullable
  - `created_at` string, date-time, required
  - `updated_at` string, date-time, required

## Other responses

- `422`: Validation Error

---

[API](https://skmtc.dev/mentium/apis/mentium-api.md) - [All operations](https://skmtc.dev/mentium/apis/mentium-api/llms.txt) - [OpenAPI document](https://skmtc.dev/mentium/apis/mentium-api/revisions/b4ed8e59432e?raw)