REST API

Creation sessions

A creation session is one eSoppari page on which a person of your app reviews and sends one signing request. The person needs no eSoppari account.

The flow has four steps:

1. Your server uploads the PDF (optional) and opens the session with your API key.
2. Your server gives the session url to your browser code. It never gives the API key.
3. The person reviews the document and the signers on the page, and clicks Send to signers. The page is either a full page (hosted) or a frame in your app (embedded): see Embedding and hosted pages.
4. Your server gets the creation_session.completed webhook, with the id of the signing request that the send created.

The placeholders in the examples

Open a session

curl -X POST https://api.esoppari.fi/v1/creation-sessions \
  -H "Authorization: Bearer $ESOPPARI_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "ui_mode": "hosted",
    "success_url": "https://app.example.com/contracts/done?session={SESSION_ID}",
    "cancel_url": "https://app.example.com/contracts",
    "document_id": "<document id>",
    "title": "Lease agreement, flat 114",
    "signers": [{"name": "Anna Korhonen", "email": "anna@example.com"}]
  }'

Fields of the session

Only the first three are required.

Fields of the request

The session also takes the fields of a signing request create. They are the prefill, and the request that the send creates gets them.

A field that you omit takes the default of the group, then of your organisation, as a create does. The page shows the last day to sign and the reminders, and cannot change any field of this table except title and signers.

Signers

Each row of signers:

Each item of capacities:

What the person can change. On the page, the person edits the name, the email and the capacities of each signer, and can add and remove rows. A signer whose email stays the same keeps required_eid_country, language and message. The rows keep your order only while the list of emails stays the same and in the same order; after any other change, each row signs at its position on the page. A new row gets the defaults.

The answer

A 201 with the session. Only this answer has url and client_secret, so keep url on your server for the browser of this person.

{
  "id": "<session id>",
  "status": "open",
  "ui_mode": "hosted",
  "url": "https://create.esoppari.fi/c/<session id>#cs_...",
  "client_secret": "cs_...",
  "success_url": "https://app.example.com/contracts/done?session={SESSION_ID}",
  "cancel_url": "https://app.example.com/contracts",
  "allow_edit_signers": true,
  "expires_at": "2026-10-16T10:00:00Z",
  "created_at": "2026-10-16T09:00:00Z"
}

Errors

The life of a session

A session sends once. A reload of the page keeps the prefill and the uploaded PDF, not the changes that the person did not send.

cancel_reason:

When the API key expires, the page of its open sessions closes at once, but their status stays open until expires_at, and then becomes expired.

Know that it was sent

Trust the creation_session.completed webhook, not the redirect to success_url or the browser callback: a person can open success_url themselves.

To check by hand, read the session:

curl https://api.esoppari.fi/v1/creation-sessions/<session id> \
  -H "Authorization: Bearer $ESOPPARI_KEY"

It gives the fields of the create answer without url and client_secret, plus signing_request_id once it is completed, cancel_reason once it is cancelled, and closed_at once it is closed. A session of another organisation, or no session, is a 404 creation_session_not_found. 30 days after a session closes, eSoppari deletes it, and a read gives that 404 too.

Embed origins

An embed origin is the scheme, the host and the port of the page of your app that shows the frame: https://app.example.com, or https://app.example.com:8443. It has no path. It must be https, and it cannot be an IP address or have a wildcard. Your organisation can have 10.

Add one on the API keys page of the admin portal, or:

curl -X POST https://api.esoppari.fi/v1/embed-origins \
  -H "Authorization: Bearer $ESOPPARI_KEY" \
  -H "Content-Type: application/json" \
  -d '{"origin": "https://app.example.com"}'