Create a signing session

Embed API

API Reference

Request

Create a signing session by providing files and participants.

Include signers in the participants array here, or add them later while the session is in pending state.

Files can be provided either by URL or uploaded directly:

JSON request (application/json): provide files as URL references in the files array.
Multipart request (multipart/form-data): upload file content directly as binary parts. The data part contains the JSON payload, and the files parts contain the binary file content. Each uploaded file corresponds by position to an entry in data.files that does not have a url.

Security

APIKey

Acceptstringrequired

Specify the response format.

Value:"application/json"

Body

required

document_namestring, [ 1 .. 200 ] charactersrequired

Name of the document shown in the signing UI.

Example:"Employment Agreement"

document_authorstring, [ 1 .. 100 ] charactersrequired

Author name associated with the document.

Example:"HR Department"

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

Your own identifier for correlating this session in your system.

Example:"deal-42"

expires_atstring, (date-time)(SigningSessionExpirationTime)

Expiration time as an RFC 3339 timestamp, including a timezone. Must be at least one hour and no more than 180 days after creation. Defaults to 180 days.

Example:"2026-03-31T10:30:00.000Z"

ui_domainstring, (hostname)(SigningSessionUiDomain)

A custom domain registered for your workspace. This session's UI is served from it.

Example:"sign.acme.com"

email_fromstring(SigningSessionEmailFrom)

From address for invitation emails sent for this session. The domain must be an email domain registered for your workspace.

Example:"\"Acme\" <sign@mail.acme.com>"

startboolean

Whether the signing session is started immediately after creation. If true, the created session status is started; if false (or omitted), status is pending. Starting a session locks its files (no files can be added or removed) and allows participants to access the signing flow via their links. Queued invitations are sent when the session starts.

Default:false

Example:true

signature_positionstring(SigningSessionSignaturePosition)

Where signatures are placed in the final PDF.

inline: signatures are placed in the provided participant signature_location. Participants without a location remain invisible but are still digitally signed.
start: a separate signature page is attached to the beginning of the PDF.
end: a separate signature page is attached to the end of the PDF.

Enum:"inline""start""end"

Example:"inline"

filesArray of objects(SigningSessionFileInput)

Optional list of files for the signing session. If multiple files are provided, they are merged into a single PDF. When using application/json, each file must include a url. When using multipart/form-data, url can be omitted — files without a url are matched by position to the uploaded binary parts.

participantsArray of objects, <= 40 items(SigningSessionParticipant)

Signers for the signing session, including any added after creation while the session is in a pending state.

webhooksArray of objects, <= 2 items(SigningSessionWebhook)

curl -i -X POST \
  https://api.embed.docue.com/sign/sessions \
  -H 'Accept: application/json' \
  -H 'Authorization: Bearer <YOUR_API Key_HERE>' \
  -H 'Content-Type: application/json' \
  -d '{
    "document_name": "Employment Agreement",
    "document_author": "HR Department",
    "external_id": "deal-42",
    "expires_at": "2026-03-31T10:30:00.000Z",
    "start": true,
    "files": [
      {
        "name": "Employment Agreement.pdf",
        "url": "https://example.com/files/employment-agreement.pdf"
      }
    ],
    "signature_position": "inline",
    "participants": [
      {
        "name": "John Doe",
        "external_id": "user-123",
        "ui_language": "en-GB",
        "signing_order": 0,
        "deliveries": [
          {
            "type": "email",
            "target": "john.doe@example.org",
            "message": "Please sign by Friday."
          },
          {
            "type": "sms",
            "target": "+358401234567",
            "message": "Please sign by Friday."
          }
        ],
        "signing_methods": [
          {
            "type": "eid",
            "target": "fi_nordea"
          },
          {
            "type": "otp_sms"
          }
        ],
        "signature_location": {
          "file_index": 0,
          "page": 1,
          "x": 0.15,
          "y": 0.36,
          "width": 0.31,
          "height": 0.1
        }
      },
      {
        "name": "Jane Roe",
        "ui_language": "sv",
        "signing_order": 1,
        "deliveries": [
          {
            "type": "email",
            "target": "jane.roe@example.org"
          }
        ],
        "signing_methods": [
          {
            "type": "otp_email"
          }
        ]
      }
    ],
    "webhooks": [
      {
        "url": "https://example.com/webhooks/signing",
        "secret": "your-shared-secret"
      },
      {
        "url": "https://example.com/webhooks/signing-audit"
      }
    ]
  }'

Responses

Successful response with details about the signing session.

Bodyapplication/json

dataobject(SigningSessionData)required

Response body. Null when there is nothing to return.

metaobjectrequired

Response

{
  "data": {
    "id": "0196ae5b-2e9d-729f-aba5-fa4db6f881fd",
    "status": "started",
    "document_name": "Employment Agreement",
    "document_author": "HR Department",
    "external_id": "deal-42",
    "expires_at": "2026-03-31T10:30:00.000Z",
    "ui_domain": null,
    "email_from": null,
    "signature_position": "inline",
    "files": [ … ],
    "participants": [ … ],
    "webhooks": [ … ]
  },
  "meta": {
    "status": { … }
  }
}