REST API
API reference
Version 1.0.0. Base URL https://api.esoppari.fi. The machine-readable contract: openapi.yaml.
Every endpoint needs an API key unless it says otherwise. Each error answer is a
problem document.
Account
GET /v1/me
Describe the API key that makes the call
Responses
| Status | Description | Body |
|---|
200 |
The key, its organisation and its rate limit. |
application/json Me
|
4xx / 5xx |
An error. code says which one; see the error guide. |
application/problem+json Problem
|
Documents
POST /v1/documents
Upload a PDF for a signing request
Upload the PDF first, then name its id as document_id when you
create the signing request. The PDF must be at most 10 MiB, not
encrypted and not signed already. An upload that no signing request
claims is deleted after 24 hours.
Request body
multipart/form-data
| Field | Type | Description |
|---|
file required |
string (binary) |
The PDF. |
Responses
| Status | Description | Body |
|---|
201 |
The upload is stored. |
application/json Document
|
4xx / 5xx |
An error. code says which one; see the error guide. |
application/problem+json Problem
|
DELETE /v1/documents/{document_id}
Delete an upload that no signing request claimed
Parameters
| Name | In | Type | Description |
|---|
document_id required |
path |
string (uuid) |
|
Responses
| Status | Description | Body |
|---|
204 |
The upload is deleted, or was already gone. |
|
4xx / 5xx |
An error. code says which one; see the error guide. |
application/problem+json Problem
|
Signing requests
GET /v1/signing-requests
List signing requests, newest first
Parameters
| Name | In | Type | Description |
|---|
status |
query |
SigningRequestStatus |
|
created_from |
query |
string (date-time) |
Only requests created at or after this instant. |
created_to |
query |
string (date-time) |
Only requests created before this instant. |
cursor |
query |
string |
The next_cursor of the previous page. Leave out for the first page. |
limit |
query |
integer |
|
Responses
| Status | Description | Body |
|---|
200 |
One page. |
application/json SigningRequestList
|
4xx / 5xx |
An error. code says which one; see the error guide. |
application/problem+json Problem
|
POST /v1/signing-requests
Create a draft signing request
Creates a draft. Nothing is sent: call send next. Every field you
leave out takes the default of the key's group, then of the organisation.
Send an Idempotency-Key to make a retry safe: the same key returns
the request that the first call created, with status 200.
Parameters
| Name | In | Type | Description |
|---|
Idempotency-Key |
header |
string |
Any string up to 255 characters, unique per signing request you mean
to create. Keys are unique per organisation, not per API key: prefix them
with the name of your system. |
Request body
application/json: SigningRequestCreate
Responses
| Status | Description | Body |
|---|
200 |
A retry with the same Idempotency-Key. The body is the request the first call created. |
application/json SigningRequest
|
201 |
The draft is created. |
application/json SigningRequest
|
4xx / 5xx |
An error. code says which one; see the error guide. |
application/problem+json Problem
|
GET /v1/signing-requests/{signing_request_id}
Get a signing request and its signers
Parameters
| Name | In | Type | Description |
|---|
signing_request_id required |
path |
string (uuid) |
|
Responses
| Status | Description | Body |
|---|
200 |
The request. |
application/json SigningRequest
|
4xx / 5xx |
An error. code says which one; see the error guide. |
application/problem+json Problem
|
PUT /v1/signing-requests/{signing_request_id}
Replace a draft
Replaces every field of a draft, the signer list included. Send the
ETag of your last read as If-Match; a draft that changed since
then is refused with 412, and a call without If-Match with 428.
If-Match: * replaces whatever version is current. To keep the PDF,
leave out document_id.
Parameters
| Name | In | Type | Description |
|---|
signing_request_id required |
path |
string (uuid) |
|
If-Match required |
header |
string |
The ETag of your last read of the draft. |
Request body
application/json: SigningRequestUpdate
Responses
| Status | Description | Body |
|---|
200 |
The draft after the change. |
application/json SigningRequest
|
4xx / 5xx |
An error. code says which one; see the error guide. |
application/problem+json Problem
|
DELETE /v1/signing-requests/{signing_request_id}
Delete a draft
Only a draft can be deleted. A sent request is cancelled instead.
Parameters
| Name | In | Type | Description |
|---|
signing_request_id required |
path |
string (uuid) |
|
Responses
| Status | Description | Body |
|---|
204 |
The draft is deleted. |
|
4xx / 5xx |
An error. code says which one; see the error guide. |
application/problem+json Problem
|
POST /v1/signing-requests/{signing_request_id}/cancel
Cancel a sent request
A cancelled request has the status declined and a cancelled
event. A signer decline has a declined event instead. A second call
on a request that is already cancelled returns 200.
Parameters
| Name | In | Type | Description |
|---|
signing_request_id required |
path |
string (uuid) |
|
Responses
| Status | Description | Body |
|---|
200 |
The request is cancelled. |
application/json SigningRequest
|
4xx / 5xx |
An error. code says which one; see the error guide. |
application/problem+json Problem
|
GET /v1/signing-requests/{signing_request_id}/events
List what happened to a request, newest first
One page at a time. Pass the next_cursor of a page as cursor to
read the next one; the last page has a null next_cursor.
Parameters
| Name | In | Type | Description |
|---|
signing_request_id required |
path |
string (uuid) |
|
cursor |
query |
string |
The next_cursor of the previous page. Leave out for the first page. |
limit |
query |
integer |
|
Responses
| Status | Description | Body |
|---|
200 |
A page of the events. |
application/json object
|
4xx / 5xx |
An error. code says which one; see the error guide. |
application/problem+json Problem
|
POST /v1/signing-requests/{signing_request_id}/send
Send a draft to its signers
The service prepares the document and emails the first signers. A
second call on a request that waits for signatures or is completed
returns 200 and does nothing; on a declined or expired request it is
409 request_not_draft.
Parameters
| Name | In | Type | Description |
|---|
signing_request_id required |
path |
string (uuid) |
|
Responses
| Status | Description | Body |
|---|
200 |
The request is sent. |
application/json SigningRequest
|
4xx / 5xx |
An error. code says which one; see the error guide. |
application/problem+json Problem
|
GET /v1/signing-requests/{signing_request_id}/signed-document
Download the signed PDF
The PAdES PDF with every signature. It exists once the request is
completed, and for a declined or expired request that has at least one
signature. Before that the answer is 404 with code
signed_document_not_ready.
Parameters
| Name | In | Type | Description |
|---|
signing_request_id required |
path |
string (uuid) |
|
Responses
| Status | Description | Body |
|---|
200 |
The signed PDF. |
application/pdf string (binary)
|
4xx / 5xx |
An error. code says which one; see the error guide. |
application/problem+json Problem
|
POST /v1/signing-requests/{signing_request_id}/signers/{signer_id}/resend-invitation
Email the invitation to a signer again
Schedules the email; it goes out within seconds. The
invitation_resent event of the request shows when it went out. At
least once: a retry can send a second email, and two calls while the
first waits send one. Only a signer in the invited status can get a
new invitation. A signer gets one invitation email in 3 minutes at
most: a resend sooner gives 429 resend_too_soon with Retry-After.
Parameters
| Name | In | Type | Description |
|---|
signing_request_id required |
path |
string (uuid) |
|
signer_id required |
path |
string (uuid) |
|
Responses
| Status | Description | Body |
|---|
204 |
The invitation is accepted for sending. |
|
4xx / 5xx |
An error. code says which one; see the error guide. |
application/problem+json Problem
|
POST /v1/signing-requests/{signing_request_id}/signers/{signer_id}/withdraw
Remove a signer who has not signed
The signer moves to the withdrawn status and their link stops
working; the request goes on without them. In a sequential order the
next signer is invited when the withdrawn one held the turn. When no
unsigned signer is left and at least one signed, the request
completes with the signatures it has. When nobody signed, the call
is refused with 409 withdraw_leaves_no_signature: cancel the
request instead. Only a signer in the pending or invited status
can be withdrawn; a second call on a withdrawn signer returns 200.
Parameters
| Name | In | Type | Description |
|---|
signing_request_id required |
path |
string (uuid) |
|
signer_id required |
path |
string (uuid) |
|
Responses
| Status | Description | Body |
|---|
200 |
The request after the withdrawal. |
application/json SigningRequest
|
4xx / 5xx |
An error. code says which one; see the error guide. |
application/problem+json Problem
|
GET /v1/signing-requests/{signing_request_id}/source-document
Download the PDF of a draft as it was uploaded
Available while the request is a draft. After the send, download the
signed PDF instead.
Parameters
| Name | In | Type | Description |
|---|
signing_request_id required |
path |
string (uuid) |
|
Responses
| Status | Description | Body |
|---|
200 |
The PDF. |
application/pdf string (binary)
|
4xx / 5xx |
An error. code says which one; see the error guide. |
application/problem+json Problem
|
Branding
GET /v1/branding
Get the theme of the signing pages
The colours and the logo that signers see. A field that is absent
or null uses the platform colour or, for the logo, the initials of
your organisation.
Responses
| Status | Description | Body |
|---|
200 |
The theme. |
application/json Branding
|
4xx / 5xx |
An error. code says which one; see the error guide. |
application/problem+json Problem
|
PUT /v1/branding/colours
Replace the theme colours
Send all five colours as #rrggbb, or null for the platform colour.
A refused colour is a 422 that names its field, and nothing is
stored. The rules:
primary_colour: 3:1 contrast against white, also on hover and when
pressed. It must not be a red, and must look different from the
Decline button. Codes primary_low_contrast, primary_like_decline.decline_colour: a red, with 3:1 contrast against white, also on
hover and when pressed. Codes decline_not_red,
decline_low_contrast.secondary_colour: the text of base buttons, 4.5:1 against white
and against a pressed button. Code secondary_low_contrast.link_colour: links that are not buttons, 4.5:1 against white.
Code link_low_contrast.chrome_colour: any colour.
The text on each fill turns black or white for contrast.
Request body
application/json: BrandColours
Responses
| Status | Description | Body |
|---|
200 |
The theme after the change. |
application/json Branding
|
4xx / 5xx |
An error. code says which one; see the error guide. |
application/problem+json Problem
|
PUT /v1/branding/logo
Replace the logo
PNG, JPEG or WebP, at most 1 MiB, 4096 pixels a side and 1 megapixel. The logo is
fitted into 480 x 128 pixels and stored as PNG. SVG is refused. Your
organisation name stays beside the logo.
Request body
multipart/form-data
| Field | Type | Description |
|---|
file required |
string (binary) |
The image. |
Responses
| Status | Description | Body |
|---|
200 |
The theme after the change. |
application/json Branding
|
4xx / 5xx |
An error. code says which one; see the error guide. |
application/problem+json Problem
|
DELETE /v1/branding/logo
Remove the logo
Responses
| Status | Description | Body |
|---|
204 |
The logo is removed, or there was none. |
|
4xx / 5xx |
An error. code says which one; see the error guide. |
application/problem+json Problem
|
Webhooks
GET /v1/events/{event_id}
Get an event and the payload that went out
Parameters
| Name | In | Type | Description |
|---|
event_id required |
path |
string (uuid) |
The event id. The webhook-id header of a delivery is evt_ and this id. |
Responses
| Status | Description | Body |
|---|
200 |
The event. |
application/json WebhookEvent
|
4xx / 5xx |
An error. code says which one; see the error guide. |
application/problem+json Problem
|
GET /v1/webhook-deliveries/{delivery_id}
Get a delivery and its attempts
Parameters
| Name | In | Type | Description |
|---|
delivery_id required |
path |
string (uuid) |
|
Responses
| Status | Description | Body |
|---|
200 |
The delivery. |
application/json WebhookDeliveryDetail
|
4xx / 5xx |
An error. code says which one; see the error guide. |
application/problem+json Problem
|
POST /v1/webhook-deliveries/{delivery_id}/redeliver
Send a delivery again
The same webhook-id goes out again, so a receiver that dropped the
first one by its id drops this one too. A delivery that is still
pending, or one whose endpoint is disabled, is refused with 409; a
webhook.test delivery goes to a disabled endpoint too, but not
after a 410 Gone until you enable the endpoint again. A
webhook.test delivery is also refused with 409 while another test
of the endpoint waits.
Parameters
| Name | In | Type | Description |
|---|
delivery_id required |
path |
string (uuid) |
|
Responses
| Status | Description | Body |
|---|
202 |
The delivery is queued again. |
|
4xx / 5xx |
An error. code says which one; see the error guide. |
application/problem+json Problem
|
GET /v1/webhook-endpoints
List the webhook endpoints
Responses
| Status | Description | Body |
|---|
200 |
Every endpoint of the organisation, oldest first. An organisation has 10 at most. |
application/json WebhookEndpointList
|
4xx / 5xx |
An error. code says which one; see the error guide. |
application/problem+json Problem
|
POST /v1/webhook-endpoints
Register a webhook endpoint
The URL must be https on port 443, with a host name, not an IP
address. A host that resolves to a private or loopback address is
refused. The answer carries the signing secret once; store it, then
verify each delivery with it (Standard Webhooks).
Request body
application/json: WebhookEndpointInput
Responses
| Status | Description | Body |
|---|
201 |
The endpoint and its secret. |
application/json WebhookEndpointWithSecret
|
4xx / 5xx |
An error. code says which one; see the error guide. |
application/problem+json Problem
|
GET /v1/webhook-endpoints/{endpoint_id}
Get a webhook endpoint
Parameters
| Name | In | Type | Description |
|---|
endpoint_id required |
path |
string (uuid) |
|
Responses
| Status | Description | Body |
|---|
200 |
The endpoint. |
application/json WebhookEndpoint
|
4xx / 5xx |
An error. code says which one; see the error guide. |
application/problem+json Problem
|
PUT /v1/webhook-endpoints/{endpoint_id}
Replace the URL, the description and the event filter
Parameters
| Name | In | Type | Description |
|---|
endpoint_id required |
path |
string (uuid) |
|
Request body
application/json: WebhookEndpointInput
Responses
| Status | Description | Body |
|---|
200 |
The endpoint after the change. |
application/json WebhookEndpoint
|
4xx / 5xx |
An error. code says which one; see the error guide. |
application/problem+json Problem
|
DELETE /v1/webhook-endpoints/{endpoint_id}
Delete a webhook endpoint and its delivery log
Parameters
| Name | In | Type | Description |
|---|
endpoint_id required |
path |
string (uuid) |
|
Responses
| Status | Description | Body |
|---|
204 |
The endpoint is deleted. Deliveries still queued are not sent. |
|
4xx / 5xx |
An error. code says which one; see the error guide. |
application/problem+json Problem
|
GET /v1/webhook-endpoints/{endpoint_id}/deliveries
List the deliveries of an endpoint, newest first
The log keeps 30 days.
Parameters
| Name | In | Type | Description |
|---|
endpoint_id required |
path |
string (uuid) |
|
cursor |
query |
string |
The next_cursor of the previous page. Leave out for the first page. |
limit |
query |
integer |
|
Responses
| Status | Description | Body |
|---|
200 |
One page. |
application/json WebhookDeliveryList
|
4xx / 5xx |
An error. code says which one; see the error guide. |
application/problem+json Problem
|
POST /v1/webhook-endpoints/{endpoint_id}/disable
Disable an endpoint
Parameters
| Name | In | Type | Description |
|---|
endpoint_id required |
path |
string (uuid) |
|
Responses
| Status | Description | Body |
|---|
200 |
The endpoint. Deliveries still queued are cancelled when they come due. |
application/json WebhookEndpoint
|
4xx / 5xx |
An error. code says which one; see the error guide. |
application/problem+json Problem
|
POST /v1/webhook-endpoints/{endpoint_id}/enable
Enable an endpoint
Also enables an endpoint that the service disabled after 72 hours of
failures or a 410 Gone, and starts its failure clock again. The
service records no event for an endpoint while it is disabled, so
read the current state of your requests through the API. Then send
the failed and cancelled deliveries again with recover.
Parameters
| Name | In | Type | Description |
|---|
endpoint_id required |
path |
string (uuid) |
|
Responses
| Status | Description | Body |
|---|
200 |
The endpoint. |
application/json WebhookEndpoint
|
4xx / 5xx |
An error. code says which one; see the error guide. |
application/problem+json Problem
|
POST /v1/webhook-endpoints/{endpoint_id}/recover
Send the failed and cancelled deliveries again
A delivery is cancelled when its endpoint is disabled before an
attempt. Enable the endpoint first: an endpoint that is disabled
gives 409 webhook_endpoint_disabled. One call sends 1000
deliveries at most, oldest first; call again for the next ones.
A webhook.test delivery is not sent again.
Parameters
| Name | In | Type | Description |
|---|
endpoint_id required |
path |
string (uuid) |
|
Request body
application/json: WebhookRecoverInput
Responses
| Status | Description | Body |
|---|
202 |
How many deliveries are queued again. |
application/json WebhookRecoverResult
|
4xx / 5xx |
An error. code says which one; see the error guide. |
application/problem+json Problem
|
POST /v1/webhook-endpoints/{endpoint_id}/rotate-secret
Make a new signing secret
For 24 hours, each delivery carries two signatures: one with the new
secret and one with the old. Deploy the new secret within that time.
A second rotation within the 24 hours ends the oldest secret at once.
Parameters
| Name | In | Type | Description |
|---|
endpoint_id required |
path |
string (uuid) |
|
Responses
| Status | Description | Body |
|---|
200 |
The endpoint and its new secret. |
application/json WebhookEndpointWithSecret
|
4xx / 5xx |
An error. code says which one; see the error guide. |
application/problem+json Problem
|
POST /v1/webhook-endpoints/{endpoint_id}/test
Send a webhook.test event
The test goes through the normal delivery path, and also to an
endpoint that is disabled. A test makes one attempt, with no retry.
While a test of the endpoint waits for its attempt, a new call
returns that test. A 410 Gone to a test disables the endpoint, as
for any event, and after a 410 Gone a test gives 409
webhook_endpoint_disabled until you enable the endpoint again.
Parameters
| Name | In | Type | Description |
|---|
endpoint_id required |
path |
string (uuid) |
|
Responses
| Status | Description | Body |
|---|
202 |
The delivery is queued. |
application/json WebhookDelivery
|
4xx / 5xx |
An error. code says which one; see the error guide. |
application/problem+json Problem
|
Creation sessions
POST /v1/creation-sessions
Open a creation session
A creation session is one page on which a person of your app reviews
and sends one signing request, with no eSoppari account. Send the
person to url (hosted), or mount url in your app with
esoppari.js (embedded). The session lasts
expires_in_minutes and sends once. A hosted page then sends the
person to success_url or cancel_url; an embedded page calls the
callbacks of esoppari.js. Trust the creation_session.completed
webhook, not the redirect.
The workflow fields (expiry, reminders, retention and the others)
take the group and organisation defaults as a create does, and the page
cannot change them. The page can change the title, and the signers
when allow_edit_signers is true. With no document_id, the person
uploads the PDF on the page.
An organisation has 100 open sessions at most; one more gives
422 creation_session_limit_reached.
Request body
application/json: CreationSessionCreate
Responses
| Status | Description | Body |
|---|
201 |
The session, its page URL and its client secret. Both carry the secret and are in this answer only. |
application/json CreationSessionWithSecret
|
4xx / 5xx |
An error. code says which one; see the error guide. |
application/problem+json Problem
|
GET /v1/creation-sessions/{creation_session_id}
Get a creation session
Parameters
| Name | In | Type | Description |
|---|
creation_session_id required |
path |
string (uuid) |
|
Responses
| Status | Description | Body |
|---|
200 |
The session, with no secret. |
application/json CreationSession
|
4xx / 5xx |
An error. code says which one; see the error guide. |
application/problem+json Problem
|
GET /v1/embed-origins
List the embed origins
Responses
| Status | Description | Body |
|---|
200 |
The origins that may frame an embedded session, oldest first. An organisation has 10 at most. |
application/json EmbedOriginList
|
4xx / 5xx |
An error. code says which one; see the error guide. |
application/problem+json Problem
|
POST /v1/embed-origins
Add an embed origin
An https origin with no path, for example
https://app.example.com. An embedded session names one of these
origins, and only that origin can frame its page.
Request body
application/json: EmbedOriginInput
Responses
| Status | Description | Body |
|---|
201 |
The origin as it is stored. |
application/json EmbedOrigin
|
4xx / 5xx |
An error. code says which one; see the error guide. |
application/problem+json Problem
|
DELETE /v1/embed-origins
Remove an embed origin
An open session that names the origin closes at once, and its page cannot be framed.
Parameters
| Name | In | Type | Description |
|---|
origin required |
query |
string |
|
Responses
| Status | Description | Body |
|---|
204 |
The origin is removed. |
|
4xx / 5xx |
An error. code says which one; see the error guide. |
application/problem+json Problem
|
Spec
GET /v1/openapi.yaml
This document
No API key needed.
Responses
| Status | Description | Body |
|---|
200 |
The OpenAPI document. |
application/yaml string
|
Schemas
BrandColours
Send all five fields. Null is the platform colour; a missing field is a 422, so a change of one colour cannot clear another.
| Field | Type | Description |
|---|
chrome_colour required |
string | null |
|
decline_colour required |
string | null |
|
link_colour required |
string | null |
|
primary_colour required |
string | null |
|
secondary_colour required |
string | null |
|
BrandLogo
Absent when there is no logo.
| Field | Type | Description |
|---|
height required |
integer |
|
sha256 required |
string |
The SHA-256 of the stored PNG, in lowercase hex. |
size_bytes required |
integer |
|
width required |
integer |
|
Branding
| Field | Type | Description |
|---|
chrome_colour required |
string | null |
The top bar of every signing page. Null is the platform colour. |
decline_colour required |
string | null |
The fill of the Decline buttons. Null is the platform red. |
link_colour required |
string | null |
Links that are not buttons. Null is the platform colour. |
logo |
BrandLogo |
|
primary_colour required |
string | null |
The fill of the call-to-action buttons. Null is the platform colour. |
secondary_colour required |
string | null |
The text of base buttons, such as Cancel, Back and Close. Null is the platform colour. |
CompletionDelivery
What the signers get when everyone signed.One of copy, notice, none.
CreationCancelReason
What cancelled the session: the person (person), the revoke of its key, the removal of its embed origin, or the erasure of its request.One of person, api_key_revoked, embed_origin_removed, request_erased.
CreationSession
| Field | Type | Description |
|---|
allow_edit_signers required |
boolean |
|
cancel_reason |
CreationCancelReason |
Set for a cancelled session only. |
cancel_url required |
string |
|
closed_at |
string | null |
|
created_at required |
string (date-time) |
|
embed_origin |
string | null |
|
expires_at required |
string (date-time) |
|
id required |
string (uuid) |
|
signing_request_id |
string | null |
The request that the send created; absent until the session is completed. |
status required |
CreationSessionStatus |
|
success_url required |
string |
|
ui_mode required |
CreationUIMode |
|
CreationSessionCreate
| Field | Type | Description |
|---|
allow_edit_signers |
boolean |
When false, the page shows the signers and cannot change them, and signers is required. |
cancel_url required |
string |
An https URL, as success_url. |
completion_delivery |
CompletionDelivery |
|
description |
string |
|
document_id |
string (uuid) |
The id of an upload. The page shows it and cannot replace it. |
embed_origin |
string |
Required for embedded, and only then. One of the organisation's embed origins. |
expires_in_minutes |
integer |
|
expires_on |
string (date) |
The last day the signers can sign. Defaults from the group or organisation. |
external_reference |
string |
Your own id for the request, for example a case number. It is shown in lists and is not unique. |
group_id |
string (uuid) |
An active group of the organisation. A create without it uses the key's group. A replace without it keeps the draft's group. |
language |
string one of en, fi, sv |
The language of the document. |
legal_basis |
string |
The retention ground that an erasure weighs. |
locale |
string one of en, fi, sv |
The language of the page. Defaults to the browser's. |
order_type |
OrderType |
|
processing_basis |
ProcessingBasis |
|
processing_purpose |
string |
|
reminder_interval_days |
integer |
0 sends no reminders. |
retention_category |
string |
The code of one of the organisation's active retention categories. |
signers |
array of SignerInput |
|
success_url required |
string |
An https URL. {SESSION_ID} in it is replaced with the session id. |
title |
string |
|
ui_mode required |
CreationUIMode |
|
CreationSessionStatus
One of open, completed, cancelled, expired.
CreationSessionWithSecret
| Field | Type | Description |
|---|
allow_edit_signers required |
boolean |
|
cancel_reason |
CreationCancelReason |
Set for a cancelled session only. |
cancel_url required |
string |
|
client_secret required |
string |
cs_ and the secret of the session. Shown in this answer only. |
closed_at |
string | null |
|
created_at required |
string (date-time) |
|
embed_origin |
string | null |
|
expires_at required |
string (date-time) |
|
id required |
string (uuid) |
|
signing_request_id |
string | null |
The request that the send created; absent until the session is completed. |
status required |
CreationSessionStatus |
|
success_url required |
string |
|
ui_mode required |
CreationUIMode |
|
url required |
string |
The page, with the client secret in the fragment. Open it (hosted), or pass it to esoppari.js (embedded). |
CreationUIMode
One of hosted, embedded.
Document
| Field | Type | Description |
|---|
expires_at required |
string (date-time) |
The upload is deleted at this instant unless a request claims it. |
filename required |
string |
|
id required |
string (uuid) |
|
page_count required |
integer |
|
size_bytes required |
integer |
|
EmbedOrigin
| Field | Type | Description |
|---|
created_at required |
string (date-time) |
|
origin required |
string |
|
EmbedOriginList
| Field | Type | Description |
|---|
data required |
array of EmbedOrigin |
|
FieldError
| Field | Type | Description |
|---|
code required |
string |
|
pointer required |
string |
JSON Pointer (RFC 6901) to the field. |
Me
| Field | Type | Description |
|---|
api_key required |
object |
|
rate_limit required |
object |
|
tenant_id required |
string (uuid) |
|
OrderType
sequential invites signers by order; equal orders sign in parallel.One of sequential, parallel.
Problem
An RFC 9457 problem document.
| Field | Type | Description |
|---|
code required |
string |
Stable machine code. |
detail |
string |
|
errors |
array of FieldError |
One entry per invalid field, when code is validation_failed. |
request_id required |
string |
|
status required |
integer |
|
title required |
string |
|
type required |
string (uri-reference) |
|
ProcessingBasis
The GDPR Art. 6(1) ground that the signer notice states in your name.One of consent, contract, legal_obligation, vital_interests, public_task, legitimate_interests.
Signer
| Field | Type | Description |
|---|
email required |
string |
|
id required |
string (uuid) |
|
invited_at |
string | null |
|
language |
string |
|
name required |
string |
|
order required |
integer |
|
required_eid_country |
string |
|
signed_at |
string | null |
|
status required |
SignerStatus |
|
SignerStatus
One of pending, invited, signed, declined, expired, withdrawn.
SigningCapacity
| Field | Type | Description |
|---|
organisation_id |
string |
The business ID of the organisation. |
organisation_name |
string |
Required for representative. |
type required |
string one of personal, representative |
|
SigningEvent
| Field | Type | Description |
|---|
id required |
string (uuid) |
|
occurred_at required |
string (date-time) |
|
signer_id |
string | null |
|
type required |
string one of created, signer_invited, signed, declined, expired, completed, cancelled, invitation_resent, privacy_notice_acknowledged, signer_withdrawn |
|
SigningRequest
| Field | Type | Description |
|---|
completed_at |
string | null |
|
completion_delivery |
CompletionDelivery |
|
created_at required |
string (date-time) |
|
description |
string |
|
document required |
object |
|
draft_incomplete |
boolean |
True while a draft cannot be sent yet. Always false after the send. |
expires_at required |
string (date-time) |
|
external_reference |
string |
|
group_id |
string | null |
|
id required |
string (uuid) |
|
language |
string |
|
legal_hold |
boolean |
Set and released by an administrator in the portal only. |
order_type required |
OrderType |
|
processing_basis |
ProcessingBasis |
|
processing_purpose |
string |
|
reminder_interval_days required |
integer |
|
retention_category |
string |
|
signers |
array of Signer |
Present on a single request. A list leaves it out; get the request for its signers. |
status required |
SigningRequestStatus |
|
title required |
string |
|
updated_at required |
string (date-time) |
|
SigningRequestCreate
| Field | Type | Description |
|---|
completion_delivery |
CompletionDelivery |
|
description |
string |
|
document_id required |
string (uuid) |
The id of an upload. |
expires_on |
string (date) |
The last day the signers can sign. Defaults from the group or organisation. |
external_reference |
string |
Your own id for the request, for example a case number. It is shown in lists and is not unique. |
group_id |
string (uuid) |
An active group of the organisation. A create without it uses the key's group. A replace without it keeps the draft's group. |
language |
string one of en, fi, sv |
The language of the document. |
legal_basis |
string |
The retention ground that an erasure weighs. |
order_type |
OrderType |
|
processing_basis |
ProcessingBasis |
|
processing_purpose |
string |
|
reminder_interval_days |
integer |
0 sends no reminders. |
retention_category |
string |
The code of one of the organisation's active retention categories. |
signers required |
array of SignerInput |
|
title |
string |
|
SigningRequestFields
| Field | Type | Description |
|---|
completion_delivery |
CompletionDelivery |
|
description |
string |
|
expires_on |
string (date) |
The last day the signers can sign. Defaults from the group or organisation. |
external_reference |
string |
Your own id for the request, for example a case number. It is shown in lists and is not unique. |
group_id |
string (uuid) |
An active group of the organisation. A create without it uses the key's group. A replace without it keeps the draft's group. |
language |
string one of en, fi, sv |
The language of the document. |
legal_basis |
string |
The retention ground that an erasure weighs. |
order_type |
OrderType |
|
processing_basis |
ProcessingBasis |
|
processing_purpose |
string |
|
reminder_interval_days |
integer |
0 sends no reminders. |
retention_category |
string |
The code of one of the organisation's active retention categories. |
signers |
array of SignerInput |
|
title |
string |
|
SigningRequestList
| Field | Type | Description |
|---|
data required |
array of SigningRequest |
|
next_cursor required |
string | null |
Send it as cursor for the next page. Null on the last page. |
SigningRequestStatus
One of draft, pending_signatures, completed, declined, expired, erased.
SigningRequestUpdate
| Field | Type | Description |
|---|
completion_delivery |
CompletionDelivery |
|
description |
string |
|
document_id |
string (uuid) |
A new upload that replaces the PDF. Leave out to keep it. |
expires_on |
string (date) |
The last day the signers can sign. Defaults from the group or organisation. |
external_reference |
string |
Your own id for the request, for example a case number. It is shown in lists and is not unique. |
group_id |
string (uuid) |
An active group of the organisation. A create without it uses the key's group. A replace without it keeps the draft's group. |
language |
string one of en, fi, sv |
The language of the document. |
legal_basis |
string |
The retention ground that an erasure weighs. |
order_type |
OrderType |
|
processing_basis |
ProcessingBasis |
|
processing_purpose |
string |
|
reminder_interval_days |
integer |
0 sends no reminders. |
retention_category |
string |
The code of one of the organisation's active retention categories. |
signers required |
array of SignerInput |
|
title |
string |
|
WebhookAttempt
| Field | Type | Description |
|---|
attempt required |
integer |
|
attempted_at required |
string (date-time) |
|
duration_ms required |
integer |
|
http_status |
integer | null |
|
outcome required |
WebhookAttemptOutcome |
|
WebhookAttemptOutcome
One of succeeded, http_error, gone, timeout, network_error, blocked.
WebhookDelivery
| Field | Type | Description |
|---|
attempts required |
integer |
Attempts since the delivery was created or last sent again. 8 at most. |
created_at required |
string (date-time) |
|
endpoint_id required |
string (uuid) |
|
event_id required |
string (uuid) |
|
event_type required |
string |
An event type, or webhook.test. |
id required |
string (uuid) |
|
last_http_status |
integer | null |
|
last_outcome |
WebhookOutcome |
|
next_attempt_at |
string | null |
|
status required |
WebhookDeliveryStatus |
|
succeeded_at |
string | null |
|
WebhookDeliveryDetail
| Field | Type | Description |
|---|
attempt_log required |
array of WebhookAttempt |
Every attempt, oldest first. No response body is kept. |
attempts required |
integer |
Attempts since the delivery was created or last sent again. 8 at most. |
created_at required |
string (date-time) |
|
endpoint_id required |
string (uuid) |
|
event_id required |
string (uuid) |
|
event_type required |
string |
An event type, or webhook.test. |
id required |
string (uuid) |
|
last_http_status |
integer | null |
|
last_outcome |
WebhookOutcome |
|
next_attempt_at |
string | null |
|
status required |
WebhookDeliveryStatus |
|
succeeded_at |
string | null |
|
WebhookDeliveryList
| Field | Type | Description |
|---|
data required |
array of WebhookDelivery |
|
next_cursor required |
string | null |
|
WebhookDeliveryStatus
One of pending, succeeded, failed, cancelled.
WebhookEndpoint
| Field | Type | Description |
|---|
created_at required |
string (date-time) |
|
description required |
string |
|
event_types required |
array of WebhookEventType |
|
failing_since |
string | null |
The first failure since the last success, or since a gap of more than 24 hours with no failure. |
id required |
string (uuid) |
|
status required |
WebhookEndpointStatus |
|
updated_at required |
string (date-time) |
|
url required |
string |
|
WebhookEndpointStatus
disabled_failing: the service disabled it after 72 hours of failures or a 410 Gone.One of enabled, disabled, disabled_failing.
WebhookEndpointWithSecret
| Field | Type | Description |
|---|
created_at required |
string (date-time) |
|
description required |
string |
|
event_types required |
array of WebhookEventType |
|
failing_since |
string | null |
The first failure since the last success, or since a gap of more than 24 hours with no failure. |
id required |
string (uuid) |
|
secret required |
string |
The signing secret, whsec_ and base64. Shown in this answer only. |
status required |
WebhookEndpointStatus |
|
updated_at required |
string (date-time) |
|
url required |
string |
|
WebhookEvent
| Field | Type | Description |
|---|
id required |
string (uuid) |
|
occurred_at required |
string (date-time) |
|
payload required |
object |
The JSON body that went out. It names the resource and its status only. |
type required |
string |
|
WebhookEventType
One of signing_request.sent, signing_request.completed, signing_request.declined, signing_request.cancelled, signing_request.expired, signer.signed, signer.declined, signer.withdrawn, creation_session.completed, creation_session.expired, creation_session.cancelled.
WebhookOutcome
One of succeeded, http_error, gone, timeout, network_error, blocked,
WebhookRecoverResult
| Field | Type | Description |
|---|
deliveries required |
integer |
|
