---
title: "Add Participant"
method: POST
path: "/conferences/{id}/participants"
tags: ["Conferences > participants"]
---

# Add Participant

`POST /conferences/{id}/participants`

## Request

- Base URL: `https://api.pinnacle.sh`
- URL: `https://api.pinnacle.sh/conferences/{id}/participants`
- Auth: API key in header `PINNACLE-API-KEY`

Add someone: dial a new number (`to` + `from`) or pull in a call you already have (`call_id`).

A dialed participant is returned with status `dialing` and joins when they answer; you'll get `participant.joined` (or `participant.failed` if they don't answer). With `announce`, they hear it alone before joining.

## Path parameters

- `id` string, required

## Headers

- `Idempotency-Key` string

## Request body

- union: Either dial someone (`to` + `from`) or pull in an existing call (`call_id`). `muted` and `whisper_to` can't be combined.
  - DialParticipantParams: Dial someone new. This creates a new outbound call, exactly like `POST /calls`.
    - `to` string, required: E.164 number to dial.
    - `from` string, required: One of your voice-enabled numbers.
    - `label` string: A name you choose for the participant, unique within the conference. Anywhere a participant is referenced you can use its label instead of its `call_id`. Can't start with `call_` or `leg_`.
    - `muted` boolean
    - `on_hold` boolean
    - `whisper_to` string[]: Only these participants (call IDs or labels) can hear this one; it still hears everyone. `null` means everyone hears it (the default). Stored as call IDs, so relabeling someone doesn't change who hears a whisper.
    - `end_conference_on_leave` boolean
    - `announce` union: Played to a dialed participant when they answer, before they join. Nobody else hears it. If it can't be played, they join without it.
      - Announce0
        - `text` string, required
        - `voice` string: Text-to-speech voice. Defaults to `AWS.Polly.Joanna`.
      - Announce1
        - `url` string, uri, required: Public `https` URL of an audio file.
    - `ring_timeout_secs` integer
    - `record` boolean: Same as `record` on `POST /calls`.
    - `metadata` CallMetadata: String metadata carried on future call events. Maximum serialized size is 2 KB.
  - ExistingCallParticipantParams: Pull in a call your team already has. It must be answered and not in another conference.
    - `call_id` string, required
    - `label` string: A name you choose for the participant, unique within the conference. Anywhere a participant is referenced you can use its label instead of its `call_id`. Can't start with `call_` or `leg_`.
    - `muted` boolean
    - `on_hold` boolean
    - `whisper_to` string[]: Only these participants (call IDs or labels) can hear this one; it still hears everyone. `null` means everyone hears it (the default). Stored as call IDs, so relabeling someone doesn't change who hears a whisper.
    - `end_conference_on_leave` boolean

## Response `201`

Participant added.

- Participant: A call in a conference.
  - `call_id` string, required: The participant is this call; every call API works on it.
  - `conference_id` string, required
  - `label` string, nullable, required
  - `status` 'dialing' | 'ringing' | 'joined' | 'left' | 'failed', required: - `dialing`: A dialed participant whose call hasn't answered yet. - `ringing`: Answered and being connected (or hearing its `announce`). - `joined`: In the conference. - `left`: Hung up or was removed. - `failed`: Never connected (busy, no answer, rejected, or an error).
  - `from` string, nullable, required
  - `to` string, nullable, required
  - `muted` boolean, required: Nobody hears this participant; they still hear everyone.
  - `on_hold` boolean, required: They hear hold audio and nobody hears them.
  - `whisper_to` string[], nullable, required: Call IDs of the only participants who can hear this one, or `null` for everyone.
  - `end_conference_on_leave` boolean, required: When this participant leaves, the conference ends for everyone.
  - `joined_at` string, date-time, nullable, required
  - `left_at` string, date-time, nullable, required
  - `left_reason` 'hangup' | 'removed' | 'busy' | 'no_answer' | 'rejected' | 'failed' | 'conference_ended', required

## Other responses

- `400`: Validation failed. The payload has missing required fields and/or invalid types. <br> See https://zod.dev/error-formatting for more information.
- `401`: The request lacks valid authentication credentials or the provided credentials are invalid. <br> Ensure you're including a valid API key in the request headers and that your account has the necessary permissions to access this endpoint.
- `404`: The requested resource could not be found. <br> This may occur if the identifier is incorrect, the resource has been deleted, or you don't have permission to access it.
- `409`: The conference has ended or is full, the label is taken, or the call isn't answered or is already in a conference.
- `500`: An unexpected error occurred on Pinnacle's servers while processing your request. <br> If this error persists, please contact support with the request details.
- `502`: One of Pinnacle's providers failed. Please try again later.

---

[API](https://skmtc.dev/pinnacle/apis/pinnacle-2.md) - [All operations](https://skmtc.dev/pinnacle/apis/pinnacle-2/llms.txt) - [OpenAPI document](https://skmtc.dev/pinnacle/apis/pinnacle-2/revisions/45416dadab79?raw)