--- title: "Add a participant to a call" method: POST path: "/v3/voice/calls/{id}/participants" tags: ["Voice"] --- # Add a participant to a call `POST /v3/voice/calls/{id}/participants` ## Request - Base URL: `https://api.sent.dm` - URL: `https://api.sent.dm/v3/voice/calls/{id}/participants` - Auth: one of: - API key in header `x-api-key` - HTTP bearer Dials one of your app users or a phone number into a call that is in a conference room, and answers with the participant's own call record. The participant is a call of their own: it has its own id, can be looked up and hung up, and is billed and reported through call.completed and call.failed like any other call. Every participant needs a positive balance. A phone participant is called from caller_id, which must be one of your numbers, or from the call's owning number when omitted, and needs a destination you may call. Only a call your answer connected to a conference can take participants: a call connected to a user or a number answers 409. ## Path parameters - `id` string, required ## Headers - `Idempotency-Key` string - `x-profile-id` string, uuid ## Request body - SentDmServicesEndpointsCustomerAPIv3VoiceCallsRequestsAddCallParticipantRequest: Request to add a participant to one of your live calls - `sandbox` boolean: Sandbox flag - when true, the operation is simulated without side effects Useful for testing integrations without actual execution - `to` SentDmServicesEndpointsCustomerAPIv3VoiceCallsRequestsCallParticipantTarget, required: A participant to add to a call - `kind` string: user for one of your app users, number for a phone number - `value` string: The app user's identity, or the phone number in E.164 format - `caller_id` string, nullable: The number shown to a phone participant as the caller, in E.164 format. Must be one of your numbers. The call's owning number when omitted ## Response `202` The participant is being dialed; the body is their call record - SentDmServicesEndpointsCustomerAPIv3SharedApiResponseOfCallResponse: Standard API response envelope for all v3 endpoints - `success` boolean: Indicates whether the request was successful - `data` SentDmServicesEndpointsCustomerAPIv3VoiceCallsResponsesCallResponse: A call record - `id` string: The call id, the same one carried by the call.request question and every call webhook - `mode` string: The calling mode: inapp for a call between people in your app and phone numbers, routed by your number's callback URL; agent for a call one of your voice agents answered - `agent_id` string, nullable: The voice agent that answered the call, such as agent_9f2ab000-0000-4000-8000-000000000001. Null for an inapp call - `direction` string: outbound for a call placed from your app, inbound for a call to one of your numbers - `from` SentDmServicesEndpointsCustomerAPIv3VoiceCallsResponsesCallParty: One end of a call - `kind` string: user for one of your app users, number for a phone number, conference for a room, anonymous for a caller who withheld their number - `value` string, nullable: The app user's identity, the phone number in E.164 format, or the room name. Null when the kind is anonymous - `to` SentDmServicesEndpointsCustomerAPIv3VoiceCallsResponsesCallParty: One end of a call - `kind` string: user for one of your app users, number for a phone number, conference for a room, anonymous for a caller who withheld their number - `value` string, nullable: The app user's identity, the phone number in E.164 format, or the room name. Null when the kind is anonymous - `number` string: Your number that owns the call, in E.164 format: the dialed number for an inbound call, the caller's bound number for a call placed from your app - `connected_number` string, nullable: The phone number the call was connected to, in E.164 format: the number your answer dialed, or the fallback number a call to one of your voice agents reached. Null when the call was not connected to a phone number - `caller_id_used` string, nullable: The caller id shown on the phone leg, in E.164 format: the one your answer chose, or the owning number when it chose none. Null for a call with no phone leg - `status` string: INITIATED, RINGING, ANSWERED, COMPLETED, FAILED, NO_ANSWER or REJECTED - `failure_reason` string, nullable: Why the call did not complete: callback_timeout, invalid_answer, insufficient_balance, destination_blocked, callback_not_configured, rejected, no_answer, or for an agent call agent_busy or agent_unreachable. Null while the call is live, when it completed, and when it failed without a recorded reason - `started_at` string, date-time: When the call was placed (UTC) - `answered_at` string, date-time, nullable: When the call was answered (UTC). Null until then, and always null for a call between two of your app users - `ended_at` string, date-time, nullable: When the call ended (UTC). Null while the call is live - `duration_seconds` integer, nullable: Billable duration in seconds. Null while the call is live - `price` number, nullable: What the call cost. Null until it has been priced - `legs` SentDmServicesEndpointsCustomerAPIv3VoiceCallsResponsesCallLegResponse[], nullable: The legs the price covers, one entry per billed leg, each with its own cost: a call your answer connected to a phone number ran the caller's leg to your number and the leg to the connected number at once, and both are billed. Null until the call has been priced - `direction` string: inbound for the caller's leg to your number, outbound for a leg placed on your behalf - `number` string, nullable: The phone number the leg reached, in E.164 format: your number for the inbound leg, the number dialed for an outbound one. Null for a leg to one of your app users or a room - `billed_minutes` integer: The whole minutes the leg was billed for - `cost` number: What the leg cost, in the same unit as the call's price - `currency` string: The currency of the cost: USD - `recording_available` boolean: True once a recording of the call is available - `timeline` SentDmServicesEndpointsCustomerAPIv3VoiceCallsResponsesCallTimelineEntry[], nullable: When the call entered each status, oldest first. Only returned when reading one call - `status` string: INITIATED, RINGING, ANSWERED, COMPLETED, FAILED, NO_ANSWER or REJECTED - `timestamp` string, date-time: When the call entered this status (UTC) - `error` SentDmServicesEndpointsCustomerAPIv3SharedApiError: Error information - `code` string: Machine-readable error code (e.g., "RESOURCE_001") - `message` string: Human-readable error message - `details` object, nullable: Additional validation error details (field-level errors) - `doc_url` string, nullable: URL to documentation about this error - `meta` SentDmServicesEndpointsCustomerAPIv3SharedApiMeta: Request and response metadata - `request_id` string: Unique identifier for this request (for tracing and support) - `timestamp` string, date-time: Server timestamp when the response was generated - `version` string: API version used for this request ## Other responses - `400`: Invalid id, participant or caller id; a caller id you do not own; a destination country that is not allowed; or the participant could not be dialed (BUSINESS_025) - `401`: Unauthorized - Invalid API credentials - `402`: Insufficient balance; checked for every participant, app user or phone - `403`: Forbidden - `404`: No call with this id belongs to your account - `409`: The call has already ended, or is not in a conference - `500`: Internal server error ## Changes - **2026-10-28** `41acb2ceb84d`: 4 info - added the optional property `data/allOf[#/components/schemas/SentDmServicesEndpointsCustomerAPIv3VoiceCallsResponsesCallResponse]/agent_id` to the response with the `202` status - added the optional property `data/allOf[#/components/schemas/SentDmServicesEndpointsCustomerAPIv3VoiceCallsResponsesCallResponse]/caller_id_used` to the response with the `202` status - added the optional property `data/allOf[#/components/schemas/SentDmServicesEndpointsCustomerAPIv3VoiceCallsResponsesCallResponse]/connected_number` to the response with the `202` status - added the optional property `data/allOf[#/components/schemas/SentDmServicesEndpointsCustomerAPIv3VoiceCallsResponsesCallResponse]/legs` to the response with the `202` status - **2026-10-23** `1a451bbb5736`: 1 info - endpoint added [Operation history](https://skmtc.dev/sentdm/apis/sent-dm-api-v3/changes/v3/voice/calls/:id/participants/post.md) --- [API](https://skmtc.dev/sentdm/apis/sent-dm-api-v3.md) - [All operations](https://skmtc.dev/sentdm/apis/sent-dm-api-v3/llms.txt) - [OpenAPI document](https://skmtc.dev/sentdm/apis/sent-dm-api-v3/revisions/bdcca958cac7?raw)