REST API

Overview

The REST API lets your own systems do what a sender does in the admin portal: upload a PDF, create a signing request, send it, follow it and download the signed PDF.

  • Base URL: https://api.esoppari.fi
  • Format: JSON in and out, snake_case field names, timestamps in RFC 3339 UTC. Downloads are application/pdf.
  • Authentication: an API key in the Authorization: Bearer header. See Authentication.
  • Errors: RFC 9457 problem documents with a stable code. See Errors.
  • Signers: the service always emails the invitation. The API never returns a signing link, so the identity check of each signer stays with the service.

The flow

  1. POST /v1/documents uploads the PDF and returns its id.
  2. POST /v1/signing-requests creates a draft that names the document and the signers.
  3. POST /v1/signing-requests/{id}/send sends it. The signers get an email and sign with their national eID.
  4. GET /v1/signing-requests/{id} shows the progress. status is completed when everyone signed.
  5. GET /v1/signing-requests/{id}/signed-document downloads the signed PAdES PDF.

The Quickstart does each step with curl.

What a key can do

A key acts for your organisation, not for a person. It reads every signing request of the organisation, as an administrator does. A request it creates goes to the key's group, so the members of that group see it in the portal. A key cannot apply a legal hold, erase data, or change users, billing or other keys. It can manage webhook endpoints, creation sessions and embed origins, and set the colours and the logo of the signing pages; see Branding.

Contract

The API reference lists every endpoint and field. The same contract is available as an OpenAPI 3.1 file at https://api.esoppari.fi/v1/openapi.yaml, for code generators and API clients.