Add new participant to signing session

Embed API

API Reference

Add new participant to signing session

Request

Add a new participant to an existing signing session. The session must be in pending state.

Security

APIKey

Path

session_idstring, (uuid)required

The UUID of the signing session.

Example:0196ae5b-2e9d-729f-aba5-fa4db6f881fd

Acceptstringrequired

Specify the response format.

Value:"application/json"

Bodyapplication/jsonrequired

namestringrequired

Example:"John Doe"

external_idstring, [ 1 .. 100 ] characters(SigningSessionParticipantExternalId)

Your own identifier for correlating this participant in your system.

Example:"user-123"

ui_languagestring(App.Enums.UiLanguage)

Enum:"en-GB""fi""de""pl""sv"

signing_orderinteger, >= 0

Participants sign in ascending order from 0 to N. Participants sharing the same value sign in parallel.

Default:0

Example:0

deliveriesArray of objects, non-empty(SigningSessionParticipantInvitation)required

How invitations reach this participant. At least one is required. Email and SMS are queued until the session starts.

signing_methodsArray of objects, non-empty(SigningSessionAuthMethod)

List of allowed signature methods for this participant. type: password is rejected with 400 type_not_allowed_for_signing — passwords can only be used in view_gate, not as a signing method.

view_gateobject(SigningSessionAuthMethod)

Optional view gate. The signer must clear this authentication step before the document is exposed. Same shape as a signing_methods entry ({ type, target? }). Supported types: password, otp_email, otp_sms, eid. When omitted, no view gate is enforced.

signature_locationobject(SigningSessionSignatureLocation)

Signature location for this participant. Used when signature_position is inline. If omitted in inline mode, the signature is invisible but still digitally signed.

curl -i -X POST \
  https://api.embed.docue.com/sign/sessions/0196ae5b-2e9d-729f-aba5-fa4db6f881fd/participants \
  -H 'Accept: application/json' \
  -H 'Authorization: Bearer <YOUR_API Key_HERE>' \
  -H 'Content-Type: application/json' \
  -d '{
    "name": "John Doe",
    "external_id": "user-123",
    "ui_language": "en-GB",
    "signing_order": 1,
    "deliveries": [
      {
        "type": "email",
        "target": "john.doe@example.org",
        "message": "Please sign by Friday."
      }
    ],
    "signing_methods": [
      {
        "type": "eid",
        "target": "fi_nordea"
      }
    ]
  }'

Responses

Successfully created the participant.

Bodyapplication/json

dataobject(SigningSessionParticipantData)required

Response body. Null when there is nothing to return.

metaobjectrequired

Response

{
  "data": {
    "id": "0196ae5b-2e9d-729f-aba5-fa4db6f88211",
    "status": "pending",
    "status_changed_at": "2026-02-12T10:30:00Z",
    "name": "John Doe",
    "external_id": "user-123",
    "ui_language": "en-GB",
    "signing_order": 1,
    "invitations": [ … ],
    "signing_methods": [ … ]
  },
  "meta": {
    "status": { … }
  }
}