REST API

Quickstart

This guide sends one PDF to one signer. You need an administrator account of your organisation and a PDF of at most 10 MiB.

1. Create a key

In the admin portal, open API keys, select New API key, give it a name and a group, and copy the key. The portal shows it only once.

export ESOPPARI_KEY='esk_live_...'

2. Check the key

curl -s https://api.esoppari.fi/v1/me \
  -H "Authorization: Bearer $ESOPPARI_KEY"

The answer names the key, its group and the rate limit of your plan.

3. Upload the PDF

curl -s https://api.esoppari.fi/v1/documents \
  -H "Authorization: Bearer $ESOPPARI_KEY" \
  -F "file=@contract.pdf;type=application/pdf"

Keep the id of the answer. An upload that no request claims is deleted after 24 hours.

4. Create the signing request

curl -si https://api.esoppari.fi/v1/signing-requests \
  -H "Authorization: Bearer $ESOPPARI_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: crm-contract-1042" \
  -d '{
    "document_id": "<id from step 3>",
    "title": "Employment contract",
    "signers": [
      {"name": "Maija Virtanen", "email": "maija@example.com", "required_eid_country": "FI"}
    ]
  }'

The request is a draft. Every field you leave out, such as the expiry and the retention category, takes the default of the key's group or of your organisation. -i prints the response headers. Keep the id and the ETag header.

5. Send it

curl -s -X POST https://api.esoppari.fi/v1/signing-requests/<id>/send \
  -H "Authorization: Bearer $ESOPPARI_KEY"

Maija gets an email. She opens the link and signs with her Finnish eID.

6. Follow it

curl -s https://api.esoppari.fi/v1/signing-requests/<id> \
  -H "Authorization: Bearer $ESOPPARI_KEY"

status is pending_signatures until everyone signed, then completed.

7. Download the signed PDF

curl -s -o signed.pdf \
  https://api.esoppari.fi/v1/signing-requests/<id>/signed-document \
  -H "Authorization: Bearer $ESOPPARI_KEY"

The file is a PAdES PDF that any PDF reader and the EU DSS validator can check.

Test without cost

There is no separate test environment. A draft that is never sent costs nothing: create, read, replace and delete drafts freely. A sent request uses real eIDs and counts towards your plan, so send to yourself first and cancel a request you do not need.