---
title: "End one owned outbound task call with verified native identity"
method: POST
path: "/v1/calls/{id}/hangup"
---

# End one owned outbound task call with verified native identity

`POST /v1/calls/{id}/hangup`

## Request

- Base URL: `https://volai.cz`
- URL: `https://volai.cz/v1/calls/{id}/hangup`
- Auth: HTTP bearer

Ends one owned native outbound task call. Send all four expected bindings: `expectedAgentId`, `expectedTaskId`, `expectedItemId` and `expectedPhoneSha256` (lowercase SHA-256 of the exact E.164 destination). The server verifies task history, dispatch context, native room, tenant, agent, direction and start time before sending one native hangup. A permanent per-call claim prevents duplicate provider requests, including concurrent requests and timeouts; an `Idempotency-Key` is unnecessary. The response has `callId`, `outcome` and `endConfirmed`: `hung_up` means the native engine acknowledged the exact call, `already_ended` requires a terminal stored call plus absence on all nodes, and `unknown` never means success. After an unknown result, inspect live activity and stored call state; repeating this endpoint only reads back and never sends another hangup. Recheck active calls after termination. Inbound calls, other tenants, standalone calls and other providers are rejected. Campaign scope, calling windows and deadlines belong to the calling controller; this endpoint does not change billing or task state.

## Path parameters

- `id` string, required

## Request body

- object
  - `expectedAgentId` string, required: Expected owned agent ID bound to the call and task.
  - `expectedTaskId` string, required: Expected owned outbound task ID whose attempt history contains this call.
  - `expectedItemId` string, required: Expected recipient item ID inside that task.
  - `expectedPhoneSha256` string, required: Lowercase SHA-256 of the exact stored E.164 destination; no raw phone number is accepted.

## Response `200`

Hangup confirmation or explicit uncertainty

- object
  - `data` object, required
    - `callId` string, required
    - `outcome` 'hung_up' | 'already_ended' | 'unknown', required
    - `endConfirmed` boolean, required

## Other responses

- `400`: Error codes: validation (request).
- `401`: Error codes: unauthorized (request).
- `403`: Error codes: account_suspended (account).
- `404`: Error codes: call_not_found (account).
- `429`: Error codes: rate_limited (busy).
- `500`: Error codes: internal_error (service).
- `502`: Error codes: engine_unavailable (service).
- `503`: Error codes: engine_not_configured (service).

---

[API](https://skmtc.dev/volai/apis/volai-rest-api.md) · [All operations](https://skmtc.dev/volai/apis/volai-rest-api/llms.txt) · [OpenAPI document](https://skmtc.dev/volai/apis/volai-rest-api/revisions/12029b05e2fa?raw)