# Add new participant to existing session

Add a new participant to an existing Builder session.

This is useful for collaboration flows where multiple users can access and draft
the same document session.

The response includes a one-time URL that authenticates the added participant into
the existing session. After creating the participant, redirect that user to the
returned URL.

The Builder handles real-time collaboration automatically. All participants stay in
sync without manual page refreshes.

If any participant finalizes the document, all active participants are redirected to
the success handler that was configured when the session was created.

Endpoint: POST /api/builder/sessions/{session_id}/participants
Version: 1.0.0
Security: APIKey

## Security:

  - `APIKey` (unknown)
    http bearer API Key

## Path parameters:

  - `session_id` (string, required)
    The UUID of the session.

## Header parameters:

  - `Accept` (string, required)
    Specify the response format.

## Request fields (application/json):

  - `participant` (object, required)

  - `participant.display_name` (string)

  - `participant.email` (string)

  - `participant.external_id` (string)

  - `ui_language` (string)
    Enum: "en-GB", "fi", "de", "pl", "sv"

## Response 201:

  - `201` (unknown)
    Successful response with details about the added participant.

## Response 201 fields (application/json):

  - `data` (object)

  - `data.id` (string, required)

  - `data.participant` (object, required)

  - `data.participant.display_name` (string | null, required)

  - `data.participant.email` (string | null, required)

  - `data.participant.external_id` (string | null, required)

  - `data.participant._data_type` (string | null)

  - `data.participant.id` (string, required)

  - `data.participant.token` (string)

  - `data.url` (string, required)

## Response 404:

  - `404` (unknown)
    Resource not found.

## Response 404 fields (application/json):

  - `data` (null, required)
    Always null for error responses.

  - `meta` (object, required)

  - `meta.status` (object, required)

  - `meta.status.code` (integer, required)

  - `meta.status.text` (string, required)

  - `meta.error` (object, required)

  - `meta.error.text` (string, required)

  - `meta.error.details` (object)
    Validation details, when available, as a map of what failed to a message or a list of messages.

## Response 422:

  - `422` (unknown)
    Validation error in request payload.

## Response 422 fields (application/json):

  - `data` (null, required)
    Always null for error responses.

  - `meta` (object, required)

  - `meta.status` (object, required)

  - `meta.status.code` (integer, required)

  - `meta.status.text` (string, required)

  - `meta.error` (object, required)

  - `meta.error.text` (string, required)

  - `meta.error.details` (object)
    Validation details, when available, as a map of what failed to a message or a list of messages.