# Create sender UI for signing session

Create a new Sender UI resource for an existing signing session.
The response includes a one-time URL to the hosted Sender UI.
The URL is valid for 15 minutes and becomes invalid immediately after first successful use.
You must provide a handler URL:
- `return_handler`: the user is redirected to this URL when leaving the Sender UI.

The handler URL is appended with query parameters:
| Parameter | Description |
|  --- | --- |
| `session_id` | Signing session ID |
| `sender_ui_id` | Sender UI ID |

Use this endpoint when you want to create a new Sender UI instance with its own handlers and configuration.

Endpoint: POST /sign/sessions/{session_id}/sender-uis
Version: 1.0.0
Security: APIKey

## Security:

  - `APIKey` (unknown)
    http bearer API Key

## Path parameters:

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

## Header parameters:

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

## Request fields (application/json):

  - `handlers` (object, required)

  - `handlers.return_handler` (object, required)

  - `handlers.return_handler.method` (string, required)
    Enum: "GET"

  - `handlers.return_handler.url` (string, required)

  - `configuration` (object)

  - `configuration.editable_parts` (array)
    Which parts of the signing session can be edited in Sender UI. If omitted, all parts are editable.

  - `configuration.allowed_signing_methods` (array)
    Templates that constrain the `signing_methods` the sender can configure for each
participant in this Sender UI session. Same item shape as a `signing_methods`
entry (`SigningSessionAuthMethod`). If omitted, the sender may configure any
method available to the workspace.
Validation: every entry in `participant.signing_methods` must match some entry in
`allowed_signing_methods` — same `type`, and either the template's `target`
is omitted (any target allowed for this type), or the participant's
`target` equals the template's `target`. To permit multiple target values
for one type (e.g., multiple eID providers), list multiple template
entries.

  - `configuration.allowed_signing_methods.type` (string, required)
    Authentication method type. `password` is only valid for `view_gate`.
    Enum: "password", "otp_email", "otp_sms", "eid"

  - `configuration.allowed_signing_methods.target` (string)
    Optional target value for this type (see schema description).
    Example: fi_nordea

  - `configuration.allow_start` (boolean)
    Whether Sender UI can start the signing session.
    Example: true

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

## Response 201:

  - `201` (unknown)
    Successfully created and authenticated sender UI.

## Response 201 fields (application/json):

  - `data` (object, required)

  - `data.id` (string, required)
    Example: 0196ae5b-2e9d-729f-aba5-fa4db6f88401

  - `data.url` (string, required)
    One-time URL to open the Sender UI. Valid for 15 minutes and single-use.
    Example: https://sign.docue.com/sender-session/0196ae5b-2e9d-729f-aba5-fa4db6f88401#access-code

  - `data.handlers` (object, required)

  - `data.handlers.return_handler` (object, required)

  - `data.handlers.return_handler.method` (string, required)
    Enum: "GET"

  - `data.handlers.return_handler.url` (string, required)

  - `data.configuration` (object)

  - `data.configuration.editable_parts` (array)
    Which parts of the signing session can be edited in Sender UI. If omitted, all parts are editable.

  - `data.configuration.allowed_signing_methods` (array)
    Templates that constrain the `signing_methods` the sender can configure for each
participant in this Sender UI session. Same item shape as a `signing_methods`
entry (`SigningSessionAuthMethod`). If omitted, the sender may configure any
method available to the workspace.
Validation: every entry in `participant.signing_methods` must match some entry in
`allowed_signing_methods` — same `type`, and either the template's `target`
is omitted (any target allowed for this type), or the participant's
`target` equals the template's `target`. To permit multiple target values
for one type (e.g., multiple eID providers), list multiple template
entries.

  - `data.configuration.allowed_signing_methods.type` (string, required)
    Authentication method type. `password` is only valid for `view_gate`.
    Enum: "password", "otp_email", "otp_sms", "eid"

  - `data.configuration.allowed_signing_methods.target` (string)
    Optional target value for this type (see schema description).
    Example: fi_nordea

  - `data.configuration.allow_start` (boolean)
    Whether Sender UI can start the signing session.
    Example: true

  - `data.created_at` (string, required)
    Example: 2026-02-12T10:30:00Z

  - `data.updated_at` (string, required)
    Example: 2026-02-12T10:35:00Z

  - `data.last_authenticated_at` (string, required)
    Timestamp of the latest successful authentication URL issuance.
    Example: 2026-02-12T10:35:00Z

  - `meta` (object, required)

  - `meta.status` (object, required)

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

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

  - `meta.pagination` (object)
    Present when the result is paged. Send the next pointer back to read the following page.

  - `meta.pagination.items` (integer, required)
    How many records are in this page.

  - `meta.pagination.total` (integer | null, required)
    How many records match in total. Empty when the total was not counted.

  - `meta.pagination.last_page` (integer | null, required)
    Last page number for this page size. Empty when the total was not counted.

  - `meta.pagination.page_size` (integer, required)
    Maximum number of records in a page.

  - `meta.pagination.has_pages` (boolean, required)
    Whether another page exists before or after this one.

  - `meta.pagination.is_first` (boolean, required)
    Whether this is the first page.

  - `meta.pagination.pointer` (object, required)

  - `meta.pagination.pointer.previous` (string | null, required)
    Pointer to the previous page. Empty on the first page.

  - `meta.pagination.pointer.current` (string | null, required)
    Pointer for this page. Empty on the first page.

  - `meta.pagination.pointer.next` (string | null, required)
    Pointer to the next page. Empty on the last page.

## 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.