Reject an incoming call
Reject an inbound phone session before it is answered. The session must currently be ringing or in early media; otherwise the request returns 409 Conflict.
Use the reason field to select the caller-facing outcome, such as busy, rejected, number not found.
A 202 Accepted response means the rejection request was accepted for processing; it does not mean the session has ended. Wait for the deferred session.ended webhook to confirm termination.
Tip: Use this endpoint only for an unanswered inbound call. After the call is answered, this endpoint returns 409 Conflict; use Delete session to disconnect a Session whether or not its call has been answered.
Triggered webhooks: session.ended (deferred)
Authentication
Send Authorization: Bearer <app_uuid>:<api_key> using an active API key. See Authentication for details.
Path parameters
Session identifier.
Headers
Optional key for safely retrying mutating requests. An explicitly empty header is treated like omission and does not enable replay protection. See Idempotency for details.
optional client-supplied lowercase RFC-4122 v4 UUID returned as operation_uuid; platform generates one when omitted; correlation metadata distinct from Idempotency-Key.
Request
Public hangup cause for the resulting session.ended event: number_not_found, invalid_number, timeout, busy, or rejected.
Response headers
Server-owned W3C Trace Context for correlating this response with support and observability data. It is present on successful and error responses. A valid incoming traceparent is linked to, but never becomes, the server-owned trace identifier.
Response
Optional. Set to true on idempotent terminal commands when the session was already in a terminal state at the time the request was received. Absent otherwise.