---
title: "Record Incoming Call"
method: POST
path: "/api/v2/phone-service/calls"
tags: ["api-v2-phone-service"]
---

# Record Incoming Call

`POST /api/v2/phone-service/calls`

## Request

- Base URL: `https://api.lev.com` (the document declares no server; this is the origin it was published from)
- URL: `https://api.lev.com/api/v2/phone-service/calls`
- Auth: none declared

Record a call that came in to this company's Lev number, answered or not.

Reported once the call has ended, so the record survives a call nobody answered and a call
nothing ever transcribed. Safe to retry: the phone service's own call id is the idempotency
key, and the same call reported twice returns the one record it already has.

## Request body

- RecordIncomingCallRequest: A finished call into a company's Lev number, as the phone service saw it.
  - `phone_service_call_id` string, required: The phone service's own identity for this call; the idempotency key
  - `account_id` integer, required: The company that owns the Lev number that was called
  - `received_by_user_id` integer, nullable: The broker who was rung, when the call reached one
  - `caller_phone` string, nullable: The outside caller's number; absent when they withheld caller ID
  - `dial_status` string, nullable
  - `answered_by` string, nullable
  - `duration_seconds` integer, nullable
  - `started_at` string, date-time, nullable
  - `ended_at` string, date-time, nullable
  - `voicemail` boolean: Whether the caller left a message; the dial status describes the broker's device either way

## Response `200`

Successful Response

- IncomingCallRecordResponse: The backend call record an incoming call was filed under.
  - `phone_call_id` string, uuid, required: The backend's durable record of this call

## Other responses

- `422`: Validation Error

## Changes

- **2026-09-25** `04c60da269dc`: 1 info
  - added the new optional request property `voicemail`
- **2026-09-18** `717348e9ff46`: 1 info
  - endpoint added

[Operation history](https://skmtc.dev/lev/apis/lev-api/changes/api/v2/phone-service/calls/post.md)

---

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