API-dokumentation

Q: Findes der et testmiljø?

Ja. Nøgler, der starter med sk_test_, underskriver mod testmiljøet med testidentiteter — samme API, ingen betaling og ingen juridisk bindende underskrift.

Q: Hvordan ved jeg, at en webhook kommer fra esigner.dk?

Hver levering har headeren Esigner-Signature med en HMAC-SHA256 over tidsstemplet og den rå body, lavet med endpointets hemmelighed. Se eksempler i Node.js, PHP og Python under Webhooks.

Q: Kan underskriveren komme tilbage til min side efter underskrift?

Ja. Send returnUrl med, når du opretter anmodningen, så sendes hver underskriver dertil efter MitID — med signature_request_id og signer_id tilføjet.

Q: Kan jeg begrænse, hvilke eID'er der tilbydes?

Ja, med signingEids, for eksempel ["dk_mitid"] for kun MitID. Eller gem valget på kontoen eller virksomheden, så gælder det alle anmodninger.

Byg MitID-underskrift ind i dit eget system. Upload et dokument, opret en underskriftsanmodning, og få besked via webhook, når den er underskrevet.

Opret API-nøgle →OpenAPI-specifikation

Base-URL: https://esigner.dk/api/v1
Godkendelse: Bearer sk_live_… / sk_test_…
Format: JSON · PDF som multipart
Webhooks: HMAC-SHA256-signeret

Kom godt i gang#

1Lav en testnøgle under Konto → Udvikler. Testnøgler (sk_test_…) underskriver mod testmiljøet: rigtigt underskriftsforløb, men ingen betaling, ingen kvote og ingen rigtige penge.
2Upload PDF'en med POST /v1/documents.
3Opret underskriften med POST /v1/signature_requests. Uden paymentMethod venter den på betaling, og ingen inviteres, før den er betalt: så er payment_required true, og next_action.url er betalingslinket. Send paymentMethod: "balance", "card" eller "auto" for at betale uden betalingsside.
4Registrer et webhook-endpoint, så siger vi til, når dokumentet er færdigunderskrevet.
5Skift til en live-nøgle (sk_live_…), når alt virker.

Officielle SDK'er#

Færdige klienter, der klarer godkendelse, idempotensnøgler, genforsøg, paginering og webhook-verificering — typet efter den samme specifikation som denne side.

Node.js og TypeScript

Node 18+, Bun, Deno og edge — ingen afhængigheder.

npm

npm install @esigner/sdk

npm ↗GitHub ↗

PHP og WordPress

PHP 8.1+, kun ext-curl — passer direkte ind i WordPress.

Composer

composer require esigner/sdk

Packagist ↗GitHub ↗

Godkendelse#

Send nøglen som bearer-token. Hver nøgle har et sæt tilladelser (scopes) — den når ikke frem til endpoints, den ikke har fået adgang til, og en nøgle kan aldrig lave en ny nøgle.

Tilladelserne vælger du, når du laver nøglen. Hvert endpoint herunder siger, hvilken det kræver — mangler nøglen den, får du 403 insufficient_scope, og WWW-Authenticate siger, hvad der skulle til.

Hvad der trækkes fra kvoten, og hvad der sker ved annullering og udløb: Priser og optælling af underskrifter →

HTTP

Authorization: Bearer sk_live_...

Idempotens#

Send en Idempotency-Key på alle POST-kald. Falder nettet ud midt i et kald, kan du trygt prøve igen med samme nøgle: du får det oprindelige svar tilbage i stedet for en ny underskriftsanmodning. Samme nøgle med et andet indhold giver 422 — det er en fejl hos dig, og den skjuler vi ikke.

curl https://esigner.dk/api/v1/signature_requests \
  -X POST \
  -H "Authorization: Bearer $ESIGNER_API_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{
    "documentId": "3f7c1e42-9b0a-4d7e-8c31-2a5f6b9d0e11",
    "signers": [
      {
        "name": "Ola Nordmann",
        "email": "ola@example.no"
      }
    ],
    "useSubscription": true,
    "deadlineDays": 14,
    "copyEmails": [
      "ola@example.no"
    ],
    "returnUrl": "https://app.example.com/contracts/123/signed",
    "signingEids": [
      "no_bankid"
    ]
  }'

Testmiljø#

Nøgler med præfikset sk_test_ kører mod testmiljøet. Alt fungerer som i produktion, men underskrivningen sker mod Iduras testmiljø med en testidentitet, og underskriften er ikke juridisk bindende. Testbestillinger koster ingenting og trækker ikke fra din kvote.

Testidentiteter pr. eID

Testmiljøet accepterer kun testbrugere — et rigtigt MitID, BankID eller andet eID virker ikke der, og den svenske BankID-app melder for eksempel «ugyldig QR-kode». Sådan får underskriveren en testidentitet: Iduras oversigt over testbrugere ↗

MitID (Danmark)Idura ↗MitID Test Tool ↗: Opret en testidentitet i MitID Test Tool, og godkend med app-simulatoren der — der skal ingen telefon til. MitIDs egen test-app virker også; på Android kan den ikke ligge ved siden af den rigtige app.
BankID (Norge)Idura ↗BankID RA preprod ↗: Opret en testbruger i norsk BankIDs preprod-portal (RA preprod); talgeneratoren der giver et gyldigt norsk personnummer. Underskriv i browseren med engangskoden otp og adgangskoden qwer1234. En ny testbruger kan være op til en time om at blive aktiv.
BankID (Sverige)Idura ↗BankID for test ↗BankID test portal ↗: BankID-appen skal konfigureres om til testmiljøet (se «BankID for test»), og den kan ikke være test og produktion på én gang — brug en ekstra telefon. Udsted derefter et test-BankID i BankIDs testportal med et opdigtet, men gyldigt personnummer. En almindelig BankID-app, der scanner QR-koden, melder den ugyldig.
FTN (Finland)Idura ↗: Idura offentliggør færdige testlogins pr. bank, for eksempel DEMOUSER1 hos Nordea. Alt foregår i browseren; der skal ingen app til.
iDIN (Nederlandene)Idura ↗: Idura offentliggør ingen testbrugere til iDIN. Skriv til os, før du tester, så sætter vi det op sammen med dig.
OneID (Storbritannien)Idura ↗: OneIDs sandkasse simulerer banken («model bank»): vælg en af dens testidentiteter i browseren. Der skal ingen app til.
Personalausweis (Tyskland)Idura ↗AusweisApp ↗: Brug AusweisApp med den indbyggede kortsimulator, der altid svarer som testpersonen «Erika Mustermann». Slå udviklertilstand til (tryk ti gange på versionsnummeret), derefter testtilstand og den interne kortsimulator. Simulatoren skal slås fra igen, før appen kan læse et rigtigt kort.

Testmiljøet sender rigtige e-mails og rigtige SMS'er til de modtagere, du angiver. E-mails får «[TEST]» i emnefeltet, og SMS starter med «[TEST]», så ingen tror, en testbesked er ægte. Testdokumenter får aldrig påmindelser.

Da testbeskeder er gratis for dig og sendes fra vores domæne og vores telefonnummer, er mængden begrænset pr. konto: 50 e-mails og 10 SMS'er pr. rullende døgn. Når budgettet er brugt op, sker der ingen fejl — bestillingen oprettes, og signUrl virker som normalt. Beskeden sendes bare ikke, og svaret siger til i testMode-blokken.

// POST /orders  (test key)
{
  "orderId": "c8841198-bb5d-4a28-a121-9f61e31ffd95",
  "signUrl": "https://esigner.no/sign/hGLw0u0Cr6_eIkLI",
  "testMode": {
    "email": { "used": 50, "limit": 50, "suppressed": true,  "resetsAt": "2026-09-03T09:14:22Z" },
    "sms":   { "used": 3,  "limit": 10, "suppressed": false, "resetsAt": "2026-09-03T08:02:11Z" }
  }
}

// GET /api-keys/test-quota  — the same block, on demand
{
  "email": { "used": 50, "limit": 50, "suppressed": true,  "resetsAt": "2026-09-03T09:14:22Z" },
  "sms":   { "used": 3,  "limit": 10, "suppressed": false, "resetsAt": "2026-09-03T08:02:11Z" }
}

Dokumenter#

POST/api/v1/documents

Upload the PDF(s) to be signed

Step one of every integration. Upload as multipart/form-data; the id you get back is what POST /signature_requests takes. An sk_test_ key produces a test-mode document, and a test document can only ever be signed by a test key.

Kræver tilladelse: documents:write

Headere

Idempotency-Keystring
Makes the write retry-safe: a retry with the same key replays the original response instead of creating a second signature request. Same key + a different body is a 422.

Forespørgsel `multipart/form-data`

ownerEmailstringpåkrævet
Where the receipt and the signed PDF are sent. Must contain an @.
post@firma.no
filesbinarypåkrævet
The document. Repeat the field to upload several — they are merged in the order sent. PDF and Word (.docx) are accepted; a Word file is converted to PDF on upload. Older .doc, .odt and .rtf must be saved as .docx or PDF first. Per-file and per-request limits apply (25 MB per file, 10 files, by default).
templateSlugstring
Optional. The /maler template the document was filled from — echoed on the completion surfaces.
leieavtale

Svar 200`Document`

The uploaded document

iduuidpåkrævet
Pass this as documentId when you create the signature request.
filenamestringpåkrævet
Name of the first uploaded file.
avtale.pdf
sizeBytesintegerpåkrævet
Total size across every uploaded file.
184320
attachmentsobject[]påkrævet
One entry per uploaded PDF.
positionintegerpåkrævet
0-based. Also the order the PDFs are merged in.
filenamestringpåkrævet
vedlegg.pdf
sizeBytesintegerpåkrævet
92160

Fejlsvar

400The upload failed validation — error carries the sentence, e.g. pdf or word (.docx) files only, <name> must be saved as .docx or pdf first, ownerEmail required.
401unauthorized — no API key, or it has been revoked.
403insufficient_scope — the key is valid but was not granted the scope this endpoint declares.
409idempotency_key_in_progress — the first request with this Idempotency-Key is still running. Retry.
413A file exceeded the per-file size limit, or converting it to PDF produced a file that does.
422A Word file could not be converted to PDF — it is damaged or password-protected.
429too_many_requests — rate limited. Retry after the Retry-After header.
503Maintenance. New uploads and signature requests are paused; existing ones keep running.

curl https://esigner.dk/api/v1/documents \
  -X POST \
  -H "Authorization: Bearer $ESIGNER_API_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -F "ownerEmail=post@firma.no" \
  -F "files=@avtale.pdf;type=application/pdf"

Svar

{
  "id": "3f7c1e42-9b0a-4d7e-8c31-2a5f6b9d0e11",
  "filename": "avtale.pdf",
  "sizeBytes": 184320,
  "attachments": [
    {
      "position": 0,
      "filename": "vedlegg.pdf",
      "sizeBytes": 92160
    }
  ]
}

Underskriftsanmodninger#

POST/api/v1/signature_requests

Create a signature request

Sends the document to each signer for BankID/eID signing and returns the request in its initial state. Each signer is emailed (or texted) their own signing link. Pass useSubscription: true to draw the signature from the account's quota: the invitations go out immediately and no money moves. Without it (and without paymentMethod) the request is created in pending_payment and the response carries a payment_url — send the sender there, and the invitations go out once they've paid. That response is still a 201, so check payment_required: while it is true, nobody has been invited. To pay without a payment page, name paymentMethod: balance, card, or auto for whatever the account pays with. How the quota is drawn: one signature per signer, taken when the request is created — not when it completes. The number of files doesn't matter. Cancel a request before anyone signs and they all come back (POST /signature_requests/{id}/cancel); an expired request keeps them. A document whose request was cancelled can be sent again with the same documentId. The response carries each signer's own sign_url and sign_url_direct. Combine them with notifySigners: false to run the whole notification side yourself — see those fields.

Kræver tilladelse: orders:write

Headere

Idempotency-Keystring
Makes the write retry-safe: a retry with the same key replays the original response instead of creating a second signature request. Same key + a different body is a 422.

Forespørgsel `application/json`

documentIduuidpåkrævet
From POST /documents. Must belong to the same account as the key.
signersobject[]påkrævet
At least one signer, invited in the order given. There is no upper limit.
namestring
Shown in the invitation. The legal identity comes from the eID, not from this.
Ola Nordmann
emailstring
ola@example.no
phonestring
E.164 or a local number, e.g. +47 912 34 567. Only honoured while SMS delivery is enabled for the account.
birthDatestring
Lock this signer to a date of birth (YYYY-MM-DD). The eID provider compares it with the date of birth in the signer's BankID/MitID and refuses anyone else: they see an error in the signing window, and the request is unchanged, so the right person can still sign. Works with sign_url and sign_url_direct. While any signer is locked, the request is signed with the market's national eID only. Norway, Denmark, Finland and Germany; elsewhere 400 birthdate_lock_unsupported. A malformed date is 400 invalid_birthdate.
useSubscriptionboolean
Draw the signature from the account's quota instead of a payment. 409 quota_exceeded when the quota is spent. Equivalent to paymentMethod: "subscription".
true
paymentMethodstring (5 values)
How to pay. Omitted: the request waits in pending_payment with a payment_url, unless useSubscription: true — the same as before this field existed, so an existing integration never starts spending quota or money without asking for it. - subscription — the quota. Same as useSubscription: true. - balance — the prepaid balance, at the pay-per-use price (signers × unit price, plus the SMS add-on when smsDelivery is on). The invitations go out immediately; 402 insufficient_balance when it doesn't cover the request. Check it with GET /balance. - card — the card saved under /konto/betaling, charged immediately at the pay-per-use price. A declined card refuses the request (402 payment_method_declined, or payment_method_action_required when the bank wants the customer present — the card then has to be saved again). Nothing is created for a declined card. - checkout — always a payment_url, even on an account with a subscription. - auto — whatever this account pays with: its subscription quota when it has one (never falling back to money when the quota runs out), else the way it chose under /konto/betaling. Never a checkout link: 409 no_payment_method when there is nothing to charge. Use it from a server that has no human to send to a payment page.
mode"merged" | "separate"
Sign the uploads as one merged PDF (default) or as separate documents.
deadlineDaysinteger
Days until the request expires. Defaults to the account's configured deadline.
14
passwordstring
Shared secret a signer must enter before the document is shown.
includePasswordInEmailboolean
Whether that password is included in the invitation email. Defaults to true.
smsDeliveryboolean
Also text the signing link. Free on subscription-covered requests, a surcharge on pay-per-use. Defaults to true on a subscription (the quota includes it) and false otherwise — so pass false explicitly if you never want us to text your signers. A phone-only signer is texted regardless, since it is their only channel; to silence that too, use notifySigners: false.
notifySignersboolean
Whether we message the signers at all: the invitation, its SMS, the reminder sequence and the completion email. Defaults to true. Set false when your own product owns the conversation — otherwise your customer receives two invitations, from two senders, for one signature. You then have to deliver signers[].sign_url (or sign_url_direct) yourself: with this off, that link is the only way anyone reaches the signing page.
notifySenderboolean
Whether we email the sender (ownerEmail) the receipt, the progress updates and the completed document. Defaults to true. The status and payment URLs are in this response and the signed PDF is downloadable over the API, so an integration loses nothing by turning it off.
copyEmailsemail[]
Up to five addresses that receive the completion email — the signed PDF attached, the download links, and Reply-To set to ownerEmail — without being a party to the signing: an accountant, a lawyer, the counterparty's office. They get no invitation and cannot sign. Lowercased and de-duplicated; the sender and the signers are dropped because they receive that email already. Read back as copy_emails.
["regnskap@example.no"]
returnUrluri
Where each signer is sent after the eID step, instead of our status page — so they come back to your product. We add signature_request_id and signer_id as query parameters. Must be https; plain http is accepted with a test key, for localhost. The redirect says who came back, not how it went: the signing page sends a signer here after a refusal too. Read the outcome from GET /signature_requests/{id} or the signer.signed / signer.declined webhooks. Read back as return_url.
https://app.example.com/contracts/123/signed
signingEidsstring (7 values)[]
Restrict which eIDs the signing page offers. ["no_bankid"] makes Norwegian BankID the only choice; no other method appears. Omitted or empty follows your account's stored choice (set under /konto), then the deployment default — which, unless the operator changed it, is no restriction: every eID the signing provider has enabled is offered. Ids: no_bankid (Norway), se_bankid (Sweden), dk_mitid (Denmark), fi_ftn (Finland), nl_idin (the Netherlands), uk_oneid (the UK), de_personalausweis (Germany). GET /config lists the ones this deployment offers under signingEids.available; one it does not offer is refused with 400 signing_eid_unavailable rather than silently dropped. Read back as signing_eids.
sealFooterboolean
Stamp a seal band across the bottom of every page: the parties who sign it on the left, "Forseglet via esigner" on the right — the shape Posten's signing product uses. Off by default. The band goes into the file before anyone has signed, so it names the parties rather than announcing a completed signature. It locks the signer roster. The band has to go into the PDF before the eID hand-off, because a PAdES signature covers the whole file and nothing can be added afterwards; a signer added later would be missing from a roster already sealed inside the signed document. So POST /orders/{id}/signers/* returns 409 seal_footer_locked for the life of the request. Decide the signer list up front. The band names each signer as Name (email) — or just the email or phone number when you gave no name — exactly what you supplied here. It carries no signing dates and no eID-verified legal names: those are only known after signing, and they are on the provider's attest page inside the same file. Only the copy sent for signing is stamped; the source PDF you uploaded is left untouched.

Svar 201`SignatureRequest`

The created signature request

iduuidpåkrævet
The signature request id — pass it to GET /signature_requests/{id}.
object"signature_request"påkrævet
statusstringpåkrævet
draft | pending_payment | in_progress | completed | expired | cancelled | signing_failed. in_progress means the signers have been invited; cancelled means it was stopped before anyone signed (see POST /signature_requests/{id}/cancel); signing_failed means the eID provider rejected the handoff and the request can be retried.
documentobjectpåkrævet
The document being signed.
iduuidpåkrævet
filenamestringpåkrævet
avtale.pdf
signersobject[]påkrævet
In invitation order.
iduuidpåkrævet
Stable id for this signer within the request.
namestringpåkrævet| null
Ola Nordmann
emailstringpåkrævet| null
null for a signer reached only by SMS.
ola@example.no
statusstringpåkrævet
pending | notified | viewed | signed | declined | expired
signed_atstringpåkrævet| null
ISO 8601, null until this signer has signed.
2026-07-13T10:24:00.000Z
verified_namestringpåkrævet| null
The signer's name as their eID (BankID, MitID, …) verified it — not the name you sent. Set when the whole request is completed: the eID provider releases the evidence only then. null before that, and for a signature whose evidence carried no name.
Ola Nordmann
verified_birth_datestringpåkrævet| null
The signer's date of birth (YYYY-MM-DD) as their eID verified it. Set at completion, like verified_name. Always null for Swedish BankID, which does not issue a date of birth.
1990-01-31
birth_date_lockstringpåkrævet| null
The date of birth this signer was locked to (signers[].birthDate at creation), or null.
1990-01-31
sign_urlstringpåkrævet| null
This signer's private signing page — the document, the deadline, and the button that starts BankID/MitID. It is the same URL the invitation email carries, so it is safe to send even when we also mailed it; with notifySigners: false it is the ONLY copy that exists and you must deliver it yourself. Treat it as a credential: the token in the path is what authorises the signature, so anyone holding the link can sign as that person. Send it to the signer, never anywhere public. null until the request has been handed to the eID provider (i.e. while it is still pending_payment), and on requests created before this field existed.
https://esigner.no/sign/9f1c0f4e3d2b4a719f3a1c0…
sign_url_directstringpåkrævet| null
Same signer, one step shorter: a redirect that takes them straight into BankID/MitID with no esigner page in between. For a flow whose own UI already showed the document and collected the approval click. Falls back to sign_url by redirecting there whenever it cannot skip — the request is password-protected, expired, cancelled, or the eID hand-off has not finished — so it is always safe to link. Note the signer then never sees the document on OUR surface: in the hosted eID flow the provider still presents it before signing, so use this when your own product has already put the document in front of them.
https://esigner.no/api/sign/9f1c0f4e3d2b4a719f3…
paymentobjectpåkrævet
How this request was paid for.
methodstringpåkrævet
subscription | balance | checkout | comped | test
amount_oreintegerpåkrævet
What this request cost in minor units (øre), VAT included. 0 on a subscription, comped or in test mode.
5800
currencystringpåkrævet
NOK
livemodebooleanpåkrævet
false for signature requests created with an sk_test_ key.
createdstringpåkrævet
ISO 8601.
2026-07-13T10:12:00.000Z
payment_urlstringpåkrævet| null
Where to send the sender to pay, while status is pending_payment. null on a subscription-covered request, and once the payment has gone through. Safe to hand to a human at any time: it resumes the checkout if the request is still unpaid and lands on the status page if it isn't.
https://esigner.no/api/orders/3f7c1e42-9b0a-4d7…
payment_requiredbooleanpåkrævet
true while the request waits for a payment and no signer has been invited. The same condition as status: "pending_payment", as a flag you can branch on: a 201 does not mean the invitations went out. Read next_action for what to do.
false
next_actionobjectpåkrævet| null
What has to happen before the request can proceed, or null when nothing does. Present exactly when payment_required is true. The hosted checkout behind url expires after a few minutes if nobody completes it; the URL itself does not, and opens a fresh checkout. To pay without a human, create the request with paymentMethod: "balance", "card" or "auto" instead.
type"pay"påkrævet
Always pay for now. Switch on it; other types may be added.
urlstringpåkrævet
Same as payment_url.
https://esigner.no/api/orders/3f7c1e42-9b0a-4d7…
messagestringpåkrævet
A human-readable explanation, in English, safe to log or show a developer.
signed_documents_urlstringpåkrævet| null
Where to list the signed PDFs, once status is completed. null before that. Requires the same API key — unlike the links in our completion email, this is not a public URL.
https://esigner.no/api/v1/signature_requests/3f…
download_expires_atstringpåkrævet| null
ISO 8601. When the PUBLIC download links (the ones in the completion email and on the status page) stop working. The API download does not expire on it — your account keeps its archive — but treat it as the deadline for fetching and storing your own copy.
2026-08-13T10:24:00.000Z
copy_emailsstring[]påkrævet
Addresses that receive the completion email with the signed PDF without being signers, as given in copyEmails on creation — lowercased, de-duplicated, and without the sender or any signer. Empty when none were given.
["regnskap@example.no"]
return_urlstringpåkrævet| null
Where each signer is sent after the eID step, as given in returnUrl. null = our status page.
https://app.example.com/contracts/123/signed
signing_eidsstring[]påkrævet| null
The eIDs the signing page offers on this request, as given in signingEids or resolved from your account and the deployment default. null = no restriction: every eID the signing provider has enabled is offered.
["no_bankid"]

Fejlsvar

400validation — the request body failed schema validation. issues carries the field-level detail.
401unauthorized — no API key, or it has been revoked.
403insufficient_scope, or cross_owner_document — the document belongs to another account.
404not_found — no such document.
409quota_exceeded, no_subscription, topup_in_progress, topup_cooldown, document already has an order, or idempotency_key_in_progress.
422idempotency_key_reused — the same Idempotency-Key was already used with a different request body.
429too_many_requests — rate limited. Retry after the Retry-After header.
502signing_failed — the eID provider rejected the handoff. The document is left in signing_failed and the request can be retried.
503Maintenance. New uploads and signature requests are paused; existing ones keep running.

curl https://esigner.dk/api/v1/signature_requests \
  -X POST \
  -H "Authorization: Bearer $ESIGNER_API_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{
    "documentId": "3f7c1e42-9b0a-4d7e-8c31-2a5f6b9d0e11",
    "signers": [
      {
        "name": "Ola Nordmann",
        "email": "ola@example.no"
      }
    ],
    "useSubscription": true,
    "deadlineDays": 14,
    "copyEmails": [
      "ola@example.no"
    ],
    "returnUrl": "https://app.example.com/contracts/123/signed",
    "signingEids": [
      "no_bankid"
    ]
  }'

Svar

{
  "id": "3f7c1e42-9b0a-4d7e-8c31-2a5f6b9d0e11",
  "object": "signature_request",
  "status": "in_progress",
  "document": {
    "id": "3f7c1e42-9b0a-4d7e-8c31-2a5f6b9d0e11",
    "filename": "avtale.pdf"
  },
  "signers": [
    {
      "id": "3f7c1e42-9b0a-4d7e-8c31-2a5f6b9d0e11",
      "name": "Ola Nordmann",
      "email": "ola@example.no",
      "status": "signed",
      "signed_at": "2026-07-13T10:24:00.000Z",
      "verified_name": "Ola Nordmann",
      "verified_birth_date": "1990-01-31",
      "birth_date_lock": "1990-01-31",
      "sign_url": "https://esigner.no/sign/9f1c0f4e3d2b4a719f3a1c0e5b8d2a44",
      "sign_url_direct": "https://esigner.no/api/sign/9f1c0f4e3d2b4a719f3a1c0e5b8d2a44/start"
    }
  ],
  "payment": {
    "method": "balance",
    "amount_ore": 5800,
    "currency": "NOK"
  },
  "livemode": true,
  "created": "2026-07-13T10:12:00.000Z",
  "payment_url": "https://esigner.no/api/orders/3f7c1e42-9b0a-4d7e-8c31-2a5f6b9d0e11/pay",
  "payment_required": false,
  "next_action": {
    "type": "pay",
    "url": "https://esigner.no/api/orders/3f7c1e42-9b0a-4d7e-8c31-2a5f6b9d0e11/pay",
    "message": "string"
  },
  "signed_documents_url": "https://esigner.no/api/v1/signature_requests/3f7c1e42-9b0a-4d7e-8c31-2a5f6b9d0e11/signed_documents",
  "download_expires_at": "2026-08-13T10:24:00.000Z",
  "copy_emails": [
    "regnskap@example.no"
  ],
  "return_url": "https://app.example.com/contracts/123/signed",
  "signing_eids": [
    "no_bankid"
  ]
}

GET/api/v1/signature_requests/{id}

Retrieve a signature request

Poll this for status, or subscribe to document.completed and skip the polling.

Kræver tilladelse: orders:read

Sti-parametre

iduuidpåkrævet
The id returned by POST /signature_requests.

Svar 200`SignatureRequest`

The signature request

Vis felterne i SignatureRequest

iduuidpåkrævet
The signature request id — pass it to GET /signature_requests/{id}.
object"signature_request"påkrævet
statusstringpåkrævet
draft | pending_payment | in_progress | completed | expired | cancelled | signing_failed. in_progress means the signers have been invited; cancelled means it was stopped before anyone signed (see POST /signature_requests/{id}/cancel); signing_failed means the eID provider rejected the handoff and the request can be retried.
documentobjectpåkrævet
The document being signed.
iduuidpåkrævet
filenamestringpåkrævet
avtale.pdf
signersobject[]påkrævet
In invitation order.
iduuidpåkrævet
Stable id for this signer within the request.
namestringpåkrævet| null
Ola Nordmann
emailstringpåkrævet| null
null for a signer reached only by SMS.
ola@example.no
statusstringpåkrævet
pending | notified | viewed | signed | declined | expired
signed_atstringpåkrævet| null
ISO 8601, null until this signer has signed.
2026-07-13T10:24:00.000Z
verified_namestringpåkrævet| null
The signer's name as their eID (BankID, MitID, …) verified it — not the name you sent. Set when the whole request is completed: the eID provider releases the evidence only then. null before that, and for a signature whose evidence carried no name.
Ola Nordmann
verified_birth_datestringpåkrævet| null
The signer's date of birth (YYYY-MM-DD) as their eID verified it. Set at completion, like verified_name. Always null for Swedish BankID, which does not issue a date of birth.
1990-01-31
birth_date_lockstringpåkrævet| null
The date of birth this signer was locked to (signers[].birthDate at creation), or null.
1990-01-31
sign_urlstringpåkrævet| null
This signer's private signing page — the document, the deadline, and the button that starts BankID/MitID. It is the same URL the invitation email carries, so it is safe to send even when we also mailed it; with notifySigners: false it is the ONLY copy that exists and you must deliver it yourself. Treat it as a credential: the token in the path is what authorises the signature, so anyone holding the link can sign as that person. Send it to the signer, never anywhere public. null until the request has been handed to the eID provider (i.e. while it is still pending_payment), and on requests created before this field existed.
https://esigner.no/sign/9f1c0f4e3d2b4a719f3a1c0…
sign_url_directstringpåkrævet| null
Same signer, one step shorter: a redirect that takes them straight into BankID/MitID with no esigner page in between. For a flow whose own UI already showed the document and collected the approval click. Falls back to sign_url by redirecting there whenever it cannot skip — the request is password-protected, expired, cancelled, or the eID hand-off has not finished — so it is always safe to link. Note the signer then never sees the document on OUR surface: in the hosted eID flow the provider still presents it before signing, so use this when your own product has already put the document in front of them.
https://esigner.no/api/sign/9f1c0f4e3d2b4a719f3…
paymentobjectpåkrævet
How this request was paid for.
methodstringpåkrævet
subscription | balance | checkout | comped | test
amount_oreintegerpåkrævet
What this request cost in minor units (øre), VAT included. 0 on a subscription, comped or in test mode.
5800
currencystringpåkrævet
NOK
livemodebooleanpåkrævet
false for signature requests created with an sk_test_ key.
createdstringpåkrævet
ISO 8601.
2026-07-13T10:12:00.000Z
payment_urlstringpåkrævet| null
Where to send the sender to pay, while status is pending_payment. null on a subscription-covered request, and once the payment has gone through. Safe to hand to a human at any time: it resumes the checkout if the request is still unpaid and lands on the status page if it isn't.
https://esigner.no/api/orders/3f7c1e42-9b0a-4d7…
payment_requiredbooleanpåkrævet
true while the request waits for a payment and no signer has been invited. The same condition as status: "pending_payment", as a flag you can branch on: a 201 does not mean the invitations went out. Read next_action for what to do.
false
next_actionobjectpåkrævet| null
What has to happen before the request can proceed, or null when nothing does. Present exactly when payment_required is true. The hosted checkout behind url expires after a few minutes if nobody completes it; the URL itself does not, and opens a fresh checkout. To pay without a human, create the request with paymentMethod: "balance", "card" or "auto" instead.
type"pay"påkrævet
Always pay for now. Switch on it; other types may be added.
urlstringpåkrævet
Same as payment_url.
https://esigner.no/api/orders/3f7c1e42-9b0a-4d7…
messagestringpåkrævet
A human-readable explanation, in English, safe to log or show a developer.
signed_documents_urlstringpåkrævet| null
Where to list the signed PDFs, once status is completed. null before that. Requires the same API key — unlike the links in our completion email, this is not a public URL.
https://esigner.no/api/v1/signature_requests/3f…
download_expires_atstringpåkrævet| null
ISO 8601. When the PUBLIC download links (the ones in the completion email and on the status page) stop working. The API download does not expire on it — your account keeps its archive — but treat it as the deadline for fetching and storing your own copy.
2026-08-13T10:24:00.000Z
copy_emailsstring[]påkrævet
Addresses that receive the completion email with the signed PDF without being signers, as given in copyEmails on creation — lowercased, de-duplicated, and without the sender or any signer. Empty when none were given.
["regnskap@example.no"]
return_urlstringpåkrævet| null
Where each signer is sent after the eID step, as given in returnUrl. null = our status page.
https://app.example.com/contracts/123/signed
signing_eidsstring[]påkrævet| null
The eIDs the signing page offers on this request, as given in signingEids or resolved from your account and the deployment default. null = no restriction: every eID the signing provider has enabled is offered.
["no_bankid"]

Fejlsvar

401unauthorized — no API key, or it has been revoked.
403insufficient_scope — the key is valid but was not granted the scope this endpoint declares.
404not_found — no such signature request, or it belongs to another account. The two are deliberately indistinguishable.
429too_many_requests — rate limited. Retry after the Retry-After header.

curl https://esigner.dk/api/v1/signature_requests/3f7c1e42-9b0a-4d7e-8c31-2a5f6b9d0e11 \
  -H "Authorization: Bearer $ESIGNER_API_KEY"

Svar

{
  "id": "3f7c1e42-9b0a-4d7e-8c31-2a5f6b9d0e11",
  "object": "signature_request",
  "status": "in_progress",
  "document": {
    "id": "3f7c1e42-9b0a-4d7e-8c31-2a5f6b9d0e11",
    "filename": "avtale.pdf"
  },
  "signers": [
    {
      "id": "3f7c1e42-9b0a-4d7e-8c31-2a5f6b9d0e11",
      "name": "Ola Nordmann",
      "email": "ola@example.no",
      "status": "signed",
      "signed_at": "2026-07-13T10:24:00.000Z",
      "verified_name": "Ola Nordmann",
      "verified_birth_date": "1990-01-31",
      "birth_date_lock": "1990-01-31",
      "sign_url": "https://esigner.no/sign/9f1c0f4e3d2b4a719f3a1c0e5b8d2a44",
      "sign_url_direct": "https://esigner.no/api/sign/9f1c0f4e3d2b4a719f3a1c0e5b8d2a44/start"
    }
  ],
  "payment": {
    "method": "balance",
    "amount_ore": 5800,
    "currency": "NOK"
  },
  "livemode": true,
  "created": "2026-07-13T10:12:00.000Z",
  "payment_url": "https://esigner.no/api/orders/3f7c1e42-9b0a-4d7e-8c31-2a5f6b9d0e11/pay",
  "payment_required": false,
  "next_action": {
    "type": "pay",
    "url": "https://esigner.no/api/orders/3f7c1e42-9b0a-4d7e-8c31-2a5f6b9d0e11/pay",
    "message": "string"
  },
  "signed_documents_url": "https://esigner.no/api/v1/signature_requests/3f7c1e42-9b0a-4d7e-8c31-2a5f6b9d0e11/signed_documents",
  "download_expires_at": "2026-08-13T10:24:00.000Z",
  "copy_emails": [
    "regnskap@example.no"
  ],
  "return_url": "https://app.example.com/contracts/123/signed",
  "signing_eids": [
    "no_bankid"
  ]
}

POST/api/v1/signature_requests/{id}/cancel

Cancel a signature request

Stops a request that nobody has signed yet. The signing links stop working and the request ends in cancelled. - Subscription: every signature it drew goes back to the quota — including signers added later. - Pay-per-use: the payment is returned (refunded if captured, released if only authorised). - Test mode: nothing was spent, so nothing comes back. Once anyone has signed, it can no longer be cancelled (409 already_signed). A request that has expired cannot be cancelled, and the signatures it drew are not returned — cancel requests you know won't be signed rather than letting them lapse. Correcting a mistake: cancel, then create a new signature request. Pass the same documentId to reuse the upload, or upload the corrected file. It is counted once. Idempotent: cancelling a request that is already cancelled returns 200 with already_cancelled: true and returns nothing a second time.

Kræver tilladelse: orders:write

Sti-parametre

iduuidpåkrævet

Headere

Idempotency-Keystring
Makes the write retry-safe: a retry with the same key replays the original response instead of creating a second signature request. Same key + a different body is a 422.

Forespørgsel `application/json`

reasonstring
Optional. Why it was cancelled — kept in the request's audit trail, never shown to the signers.
Wrong signer email — resending

Svar 200`object`

The request is cancelled

signature_requestSignatureRequestpåkrævet
iduuidpåkrævet
The signature request id — pass it to GET /signature_requests/{id}.
object"signature_request"påkrævet
statusstringpåkrævet
draft | pending_payment | in_progress | completed | expired | cancelled | signing_failed. in_progress means the signers have been invited; cancelled means it was stopped before anyone signed (see POST /signature_requests/{id}/cancel); signing_failed means the eID provider rejected the handoff and the request can be retried.
documentobjectpåkrævet
The document being signed.
iduuidpåkrævet
filenamestringpåkrævet
avtale.pdf
signersobject[]påkrævet
In invitation order.
iduuidpåkrævet
Stable id for this signer within the request.
namestringpåkrævet| null
Ola Nordmann
emailstringpåkrævet| null
null for a signer reached only by SMS.
ola@example.no
statusstringpåkrævet
pending | notified | viewed | signed | declined | expired
signed_atstringpåkrævet| null
ISO 8601, null until this signer has signed.
2026-07-13T10:24:00.000Z
verified_namestringpåkrævet| null
The signer's name as their eID (BankID, MitID, …) verified it — not the name you sent. Set when the whole request is completed: the eID provider releases the evidence only then. null before that, and for a signature whose evidence carried no name.
Ola Nordmann
verified_birth_datestringpåkrævet| null
The signer's date of birth (YYYY-MM-DD) as their eID verified it. Set at completion, like verified_name. Always null for Swedish BankID, which does not issue a date of birth.
1990-01-31
birth_date_lockstringpåkrævet| null
The date of birth this signer was locked to (signers[].birthDate at creation), or null.
1990-01-31
sign_urlstringpåkrævet| null
This signer's private signing page — the document, the deadline, and the button that starts BankID/MitID. It is the same URL the invitation email carries, so it is safe to send even when we also mailed it; with notifySigners: false it is the ONLY copy that exists and you must deliver it yourself. Treat it as a credential: the token in the path is what authorises the signature, so anyone holding the link can sign as that person. Send it to the signer, never anywhere public. null until the request has been handed to the eID provider (i.e. while it is still pending_payment), and on requests created before this field existed.
https://esigner.no/sign/9f1c0f4e3d2b4a719f3a1c0…
sign_url_directstringpåkrævet| null
Same signer, one step shorter: a redirect that takes them straight into BankID/MitID with no esigner page in between. For a flow whose own UI already showed the document and collected the approval click. Falls back to sign_url by redirecting there whenever it cannot skip — the request is password-protected, expired, cancelled, or the eID hand-off has not finished — so it is always safe to link. Note the signer then never sees the document on OUR surface: in the hosted eID flow the provider still presents it before signing, so use this when your own product has already put the document in front of them.
https://esigner.no/api/sign/9f1c0f4e3d2b4a719f3…
paymentobjectpåkrævet
How this request was paid for.
methodstringpåkrævet
subscription | balance | checkout | comped | test
amount_oreintegerpåkrævet
What this request cost in minor units (øre), VAT included. 0 on a subscription, comped or in test mode.
5800
currencystringpåkrævet
NOK
livemodebooleanpåkrævet
false for signature requests created with an sk_test_ key.
createdstringpåkrævet
ISO 8601.
2026-07-13T10:12:00.000Z
payment_urlstringpåkrævet| null
Where to send the sender to pay, while status is pending_payment. null on a subscription-covered request, and once the payment has gone through. Safe to hand to a human at any time: it resumes the checkout if the request is still unpaid and lands on the status page if it isn't.
https://esigner.no/api/orders/3f7c1e42-9b0a-4d7…
payment_requiredbooleanpåkrævet
true while the request waits for a payment and no signer has been invited. The same condition as status: "pending_payment", as a flag you can branch on: a 201 does not mean the invitations went out. Read next_action for what to do.
false
next_actionobjectpåkrævet| null
What has to happen before the request can proceed, or null when nothing does. Present exactly when payment_required is true. The hosted checkout behind url expires after a few minutes if nobody completes it; the URL itself does not, and opens a fresh checkout. To pay without a human, create the request with paymentMethod: "balance", "card" or "auto" instead.
type"pay"påkrævet
Always pay for now. Switch on it; other types may be added.
urlstringpåkrævet
Same as payment_url.
https://esigner.no/api/orders/3f7c1e42-9b0a-4d7…
messagestringpåkrævet
A human-readable explanation, in English, safe to log or show a developer.
signed_documents_urlstringpåkrævet| null
Where to list the signed PDFs, once status is completed. null before that. Requires the same API key — unlike the links in our completion email, this is not a public URL.
https://esigner.no/api/v1/signature_requests/3f…
download_expires_atstringpåkrævet| null
ISO 8601. When the PUBLIC download links (the ones in the completion email and on the status page) stop working. The API download does not expire on it — your account keeps its archive — but treat it as the deadline for fetching and storing your own copy.
2026-08-13T10:24:00.000Z
copy_emailsstring[]påkrævet
Addresses that receive the completion email with the signed PDF without being signers, as given in copyEmails on creation — lowercased, de-duplicated, and without the sender or any signer. Empty when none were given.
["regnskap@example.no"]
return_urlstringpåkrævet| null
Where each signer is sent after the eID step, as given in returnUrl. null = our status page.
https://app.example.com/contracts/123/signed
signing_eidsstring[]påkrævet| null
The eIDs the signing page offers on this request, as given in signingEids or resolved from your account and the deployment default. null = no restriction: every eID the signing provider has enabled is offered.
["no_bankid"]
already_cancelledbooleanpåkrævet
True when an earlier call had already cancelled it. Nothing was returned by this call.
released_signaturesintegerpåkrævet
Signatures returned to the subscription's quota by this call.
2
refunded_oreintegerpåkrævet
Pay-per-use amount no longer charged by this call, in minor units (øre), VAT included.
0
returned_to_balance_oreintegerpåkrævet
Amount put back on the prepaid balance by this call, in minor units (øre).
0

Fejlsvar

401unauthorized — no API key, or it has been revoked.
403insufficient_scope — the key is valid but was not granted the scope this endpoint declares.
404not_found — no such signature request, or it belongs to another account.
409already_signed — at least one signer has signed. not_cancellable — the request is no longer open (completed, expired, failed, or locked by an administrator).
429too_many_requests — rate limited. Retry after the Retry-After header.
502payment_reversal_failed — the payment could not be returned, so the request was left open and nothing changed. Retry.

curl https://esigner.dk/api/v1/signature_requests/3f7c1e42-9b0a-4d7e-8c31-2a5f6b9d0e11/cancel \
  -X POST \
  -H "Authorization: Bearer $ESIGNER_API_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{
    "reason": "Wrong signer email — resending"
  }'

Svar

{
  "signature_request": {
    "id": "3f7c1e42-9b0a-4d7e-8c31-2a5f6b9d0e11",
    "object": "signature_request",
    "status": "in_progress",
    "document": {
      "id": "3f7c1e42-9b0a-4d7e-8c31-2a5f6b9d0e11",
      "filename": "avtale.pdf"
    },
    "signers": [
      {
        "id": "3f7c1e42-9b0a-4d7e-8c31-2a5f6b9d0e11",
        "name": "Ola Nordmann",
        "email": "ola@example.no",
        "status": "signed",
        "signed_at": "2026-07-13T10:24:00.000Z",
        "verified_name": "Ola Nordmann",
        "verified_birth_date": "1990-01-31",
        "birth_date_lock": "1990-01-31",
        "sign_url": "https://esigner.no/sign/9f1c0f4e3d2b4a719f3a1c0e5b8d2a44",
        "sign_url_direct": "https://esigner.no/api/sign/9f1c0f4e3d2b4a719f3a1c0e5b8d2a44/start"
      }
    ],
    "payment": {
      "method": "balance",
      "amount_ore": 5800,
      "currency": "NOK"
    },
    "livemode": true,
    "created": "2026-07-13T10:12:00.000Z",
    "payment_url": "https://esigner.no/api/orders/3f7c1e42-9b0a-4d7e-8c31-2a5f6b9d0e11/pay",
    "payment_required": false,
    "next_action": {
      "type": "pay",
      "url": "https://esigner.no/api/orders/3f7c1e42-9b0a-4d7e-8c31-2a5f6b9d0e11/pay",
      "message": "string"
    },
    "signed_documents_url": "https://esigner.no/api/v1/signature_requests/3f7c1e42-9b0a-4d7e-8c31-2a5f6b9d0e11/signed_documents",
    "download_expires_at": "2026-08-13T10:24:00.000Z",
    "copy_emails": [
      "regnskap@example.no"
    ],
    "return_url": "https://app.example.com/contracts/123/signed",
    "signing_eids": [
      "no_bankid"
    ]
  },
  "already_cancelled": true,
  "released_signatures": 2,
  "refunded_ore": 0,
  "returned_to_balance_ore": 0
}

GET/api/v1/signature_requests/{id}/signed_documents

List the signed PDFs

Available once status is completed. One entry in merged mode (the default), one per uploaded file in separate mode. Poll GET /signature_requests/{id} for completed, or subscribe to document.completed and come straight here.

Kræver tilladelse: documents:readorders:read(én af dem er nok)

Sti-parametre

iduuidpåkrævet

Svar 200`object`

The signed PDFs

dataSignedDocument[]påkrævet
positionintegerpåkrævet
0-based. Pass it to GET /signature_requests/{id}/signed_documents/{position}. In merged mode there is exactly one entry, position 0, covering every uploaded file; in separate mode there is one per upload, in upload order.
filenamestringpåkrævet
signert-avtale.pdf
size_bytesintegerpåkrævet| null
null if the size could not be read.
214016
sha256stringpåkrævet| null
Hex SHA-256 of the signed PDF, captured at completion. Verify your download against it.
9f86d081884c7d659a2feaa0c55ad015a3bf4f1b2b0b822…
urlstringpåkrævet
Authenticated download for this file. Same API key, application/pdf in response.
https://esigner.no/api/v1/signature_requests/3f…
download_expires_atstringpåkrævet| null
When the PUBLIC links expire. These API downloads do not — see the field on SignatureRequest.

Fejlsvar

401unauthorized — no API key, or it has been revoked.
403insufficient_scope — the key is valid but was not granted the scope this endpoint declares.
404not_found — no such signature request, or it belongs to another account.
409not_completed — not every signer has signed yet. detail names the current status.
410gone (the files have been deleted) or revoked (an administrator locked the document).
429too_many_requests — rate limited. Retry after the Retry-After header.

curl https://esigner.dk/api/v1/signature_requests/3f7c1e42-9b0a-4d7e-8c31-2a5f6b9d0e11/signed_documents \
  -H "Authorization: Bearer $ESIGNER_API_KEY"

Svar

{
  "data": [
    {
      "position": 0,
      "filename": "signert-avtale.pdf",
      "size_bytes": 214016,
      "sha256": "9f86d081884c7d659a2feaa0c55ad015a3bf4f1b2b0b822cd15d6c15b0f00a08",
      "url": "https://esigner.no/api/v1/signature_requests/3f7c1e42-9b0a-4d7e-8c31-2a5f6b9d0e11/signed_documents/0"
    }
  ],
  "download_expires_at": "string"
}

GET/api/v1/signature_requests/{id}/signed_documents/{position}

Download a signed PDF

Returns application/pdf — the completed, eID-signed file, with the provider's attest page and its PAdES signature intact. Byte-for-byte what a signer downloads, so a signature check in any PDF reader (or at /kontroller-signatur) validates against it.

Kræver tilladelse: documents:readorders:read(én af dem er nok)

Sti-parametre

iduuidpåkrævet
positioninteger
From the list endpoint. Always 0 in merged mode.

Query-parametre

download"0" | "1"
1 sets Content-Disposition: attachment instead of inline.

Svar 200

The signed PDF

Frit JSON-objekt — indholdet varierer.

Fejlsvar

401unauthorized — no API key, or it has been revoked.
403insufficient_scope — the key is valid but was not granted the scope this endpoint declares.
404not_found — no such signature request or position, or it belongs to another account.
409not_completed — not every signer has signed yet.
410gone or revoked — see the list endpoint.
429too_many_requests — rate limited. Retry after the Retry-After header.

curl https://esigner.dk/api/v1/signature_requests/3f7c1e42-9b0a-4d7e-8c31-2a5f6b9d0e11/signed_documents/0 \
  -H "Authorization: Bearer $ESIGNER_API_KEY"

Saldo#

GET/api/v1/balance

Retrieve the prepaid balance

What paymentMethod: "balance" draws from. Each top-up is spendable for 12 months; lots lists what is still spendable and when each part expires, oldest first — the order it is drawn in. A test-mode key always sees zero: test requests never touch the balance.

Kræver tilladelse: billing:read

Svar 200`object`

The balance

object"balance"påkrævet
livemodebooleanpåkrævet
balance_oreintegerpåkrævet
Spendable now, in minor units (øre).
120000
currencystringpåkrævet
NOK
lotsobject[]påkrævet
remaining_oreintegerpåkrævet
expires_atstringpåkrævet| null
ISO 8601.

Fejlsvar

401unauthorized — no API key, or it has been revoked.
403insufficient_scope — the key is valid but was not granted the scope this endpoint declares.
429too_many_requests — rate limited. Retry after the Retry-After header.

curl https://esigner.dk/api/v1/balance \
  -H "Authorization: Bearer $ESIGNER_API_KEY"

Svar

{
  "object": "balance",
  "livemode": true,
  "balance_ore": 120000,
  "currency": "NOK",
  "lots": [
    {
      "remaining_ore": 0,
      "expires_at": "string"
    }
  ]
}

GET/api/v1/balance/transactions

List balance transactions

Every movement on the prepaid balance, newest first: top-ups, draws for signature requests, money returned by a cancel, refunds and expiry. amount_ore is signed.

Kræver tilladelse: billing:read

Query-parametre

limitinteger
cursorstring
The previous page's next_cursor.

Svar 200`object`

A page of transactions

dataobject[]påkrævet
iduuidpåkrævet
typestringpåkrævet
topup | draw | draw_return | withdrawal | withdrawal_reversal | refund | refund_reversal | expiry
amount_oreintegerpåkrævet
balance_after_oreintegerpåkrævet
signature_request_iduuidpåkrævet| null
createdstringpåkrævet
next_cursorstringpåkrævet| null

Fejlsvar

401unauthorized — no API key, or it has been revoked.
403insufficient_scope — the key is valid but was not granted the scope this endpoint declares.
429too_many_requests — rate limited. Retry after the Retry-After header.

curl https://esigner.dk/api/v1/balance/transactions?limit=25 \
  -H "Authorization: Bearer $ESIGNER_API_KEY"

Svar

{
  "data": [
    {
      "id": "3f7c1e42-9b0a-4d7e-8c31-2a5f6b9d0e11",
      "type": "string",
      "amount_ore": 0,
      "balance_after_ore": 0,
      "signature_request_id": "3f7c1e42-9b0a-4d7e-8c31-2a5f6b9d0e11",
      "created": "string"
    }
  ],
  "next_cursor": "string"
}

Hændelser#

GET/api/v1/events

List events

The same events delivered to your webhook endpoints, newest first. Useful for backfilling after downtime.

Kræver tilladelse: webhooks:readorders:read(én af dem er nok)

Query-parametre

limitinteger
Page size. Defaults to 25.
cursorstring
Pass the previous page's next_cursor to continue. Returns events strictly older than it.
typestring
Return only this event type.

Svar 200`object`

A page of events

dataEvent[]påkrævet
iduuidpåkrævet
object"event"påkrævet
typestringpåkrævet
document.completed | document.signing_failed | order.captured
livemodebooleanpåkrævet
false for activity produced by an sk_test_ key.
createdstringpåkrævet
ISO 8601. Also the pagination cursor — pass it as cursor to get the next page.
2026-07-13T10:24:00.000Z
dataobjectpåkrævet
The same payload the webhook delivery carries for this event type.
next_cursorstringpåkrævet| null
null on the last page. Otherwise pass it back as cursor.

Fejlsvar

401unauthorized — no API key, or it has been revoked.
403insufficient_scope — the key is valid but was not granted the scope this endpoint declares.
429too_many_requests — rate limited. Retry after the Retry-After header.

curl https://esigner.dk/api/v1/events?limit=25&type=document.completed \
  -H "Authorization: Bearer $ESIGNER_API_KEY"

Svar

{
  "data": [
    {
      "id": "3f7c1e42-9b0a-4d7e-8c31-2a5f6b9d0e11",
      "object": "event",
      "type": "document.completed",
      "livemode": true,
      "created": "2026-07-13T10:24:00.000Z",
      "data": {}
    }
  ],
  "next_cursor": "string"
}

Fuld maskinlæsbar specifikation (OpenAPI 3.1): /api/v1/openapi.json

Fejl#

Alle fejl svarer med JSON og en stabil kode i error. Koderne herunder er dem, du kan møde — byg logikken på dem, ikke på teksten.

Status	Kode	Betyder
400	validation	The request body failed schema validation. `issues` carries the field-level detail.
401	unauthorized	Missing, malformed or revoked API key.
403	insufficient_scope	The key is valid but lacks the scope the endpoint declares. `WWW-Authenticate` names what was needed.
403	cross_owner_document	The documentId belongs to a different account than the key.
404	not_found	No such resource — or it belongs to another account. Deliberately indistinguishable.
409	quota_exceeded	The subscription has too few signatures left for this request. `remaining` says how many there are. Every plan has a hard limit — Team's is a per-seat monthly pool shared by the whole company.
400	payment_method_conflict	`paymentMethod` contradicts `useSubscription` or a free-signing link. Send one or the other.
409	no_payment_method	`paymentMethod: "auto"` but the account has no subscription or payment method to charge.
402	insufficient_balance	The prepaid balance doesn't cover the request. `balanceOre` and `requiredOre` say by how much. Nothing was created.
402	payment_method_declined	The saved card was declined. `declineCode` carries the bank's reason. Nothing was created.
402	payment_method_action_required	The bank requires the cardholder to be present. Save the card again under /konto/betaling.
503	payment_unconfirmed	The card charge's outcome could not be confirmed. `orderId` is returned — read it before retrying, so a held payment isn't doubled.
400	invalid_return_url	`returnUrl` is not an absolute https URL (http only with a test key), or it carries credentials. `message` says which.
400	invalid_birthdate	A `signers[].birthDate` is not a real date in the past in YYYY-MM-DD. `message` names the signer. Nothing was created.
400	birthdate_lock_unsupported	`signers[].birthDate` was sent in a market whose eID cannot be checked against a date of birth (currently Norway, Denmark, Finland and Germany can). Nothing was created.
400	signing_eid_unavailable	`signingEids` names an eID this deployment does not offer. `unavailable` lists them and `available` lists what you may use. Nothing was created.
409	payment_method_unavailable	The named `paymentMethod` is not offered on this deployment.
409	already_signed	Cancel was refused: at least one signer has already signed.
409	not_cancellable	Cancel was refused: the request is no longer open (completed, expired, failed, or locked).
502	payment_reversal_failed	Cancel could not return the pay-per-use payment, so the request was left open. Retry.
409	no_subscription	`useSubscription: true` but the account has no active subscription.
409	topup_in_progress	An automatic top-up is already running. Retry shortly.
409	topup_cooldown	A renewal failed recently; automatic top-up is on a 24h cool-down.
409	not_completed	The signed PDF was requested before every signer had signed. `detail` names the current status.
409	seal_footer_locked	Signers cannot be added to a request created with `sealFooter: true` — the roster is inside the signed file.
409	signer_roster_full	The request has room for no more signers: someone has already signed, and the signing provider sizes the signature pages before the first signature. Create a new request for the extra signers.
410	gone	The files behind this signature request have been deleted.
410	revoked	This document is locked — by its sender or by an administrator.
409	idempotency_key_in_progress	The first request with this Idempotency-Key hasn't finished. Retry.
413	—	A single uploaded file exceeded the size limit.
422	idempotency_key_reused	The same Idempotency-Key was used with a different request body. That's a caller bug, so we surface it.
429	too_many_requests	Rate limited. `Retry-After` says how long to wait.
502	signing_failed	The eID provider rejected the handoff. The document lands in `signing_failed` and can be retried.
503	—	Maintenance. New uploads and signature requests are paused; existing ones keep running.

Fejl

{
  "error": "quota_exceeded",
  "remaining": 0
}

Webhooks#

Vi POSTer hændelser til din adresse og signerer hver levering med Esigner-Signature: t=<unix>,v1=<hmac>. HMAC'en er over <t>.<rå body>, så en opsnappet besked ikke kan afspilles igen med et andet tidsstempel. Verificér altid, før du stoler på indholdet.

Fejler en levering, prøver vi igen med stigende mellemrum (1 min → 6 t). Svarer endpointet ikke over tid, deaktiverer vi det og siger til på e-mail — hændelserne går ikke tabt, og du kan sende dem igen.

Konvolutten

iduuidpåkrævet
Also sent as the Esigner-Event-Id header. Dedupe on it — a retry reuses the id.
typestringpåkrævet
Also sent as the Esigner-Event-Type header.
document.completed
livemodebooleanpåkrævet
createdintegerpåkrævet
Unix seconds. Note: GET /events returns this field as an ISO string instead.
1784000000
dataobjectpåkrævet
Per event type — see below.

// Verificér Esigner-Signature: t=<unix>,v1=<hmac>
import { createHmac, timingSafeEqual } from "node:crypto";

// rawBody: the body exactly as received, before JSON.parse
function verify(rawBody, header, secret, toleranceSec = 300) {
  const parts = Object.fromEntries(header.split(",").map((p) => p.split("=", 2)));
  const expected = createHmac("sha256", secret).update(`${parts.t}.${rawBody}`).digest("hex");
  const fresh = Math.abs(Date.now() / 1000 - Number(parts.t)) <= toleranceSec;
  return fresh && parts.v1?.length === expected.length
    && timingSafeEqual(Buffer.from(parts.v1), Buffer.from(expected));
}

`document.completed`#

Every signer has signed. The signed PDF is available until downloadExpiresAt.

data

documentIduuidpåkrævet
orderIduuidpåkrævet
The same id as SignatureRequest.id.
filenamestringpåkrævet
avtale.pdf
mode"merged" | "separate"påkrævet
Whether the uploads were signed as one merged PDF or individually.
downloadExpiresAtstringpåkrævet
ISO 8601. Fetch the signed PDF before this.
2026-08-13T10:24:00.000Z
signersobject[]påkrævet
namestringpåkrævet| null
Ola Nordmann
emailstringpåkrævet| null
ola@example.no
signedAtstringpåkrævet| null
ISO 8601.
2026-07-13T10:24:00.000Z
verifiedNamestringpåkrævet| null
The name as the signer's eID verified it.
Ola Nordmann
verifiedBirthDatestringpåkrævet| null
YYYY-MM-DD, as the signer's eID verified it. Null for Swedish BankID, which issues none.
1990-01-31
birthDateLockstringpåkrævet| null
The date of birth the signer was locked to, or null.
1990-01-31

document.completed

{
  "id": "3f7c1e42-9b0a-4d7e-8c31-2a5f6b9d0e11",
  "type": "document.completed",
  "livemode": true,
  "created": 1784000000,
  "data": {
    "documentId": "3f7c1e42-9b0a-4d7e-8c31-2a5f6b9d0e11",
    "orderId": "3f7c1e42-9b0a-4d7e-8c31-2a5f6b9d0e11",
    "filename": "avtale.pdf",
    "mode": "merged",
    "downloadExpiresAt": "2026-08-13T10:24:00.000Z",
    "signers": [
      {
        "name": "Ola Nordmann",
        "email": "ola@example.no",
        "signedAt": "2026-07-13T10:24:00.000Z",
        "verifiedName": "Ola Nordmann",
        "verifiedBirthDate": "1990-01-31",
        "birthDateLock": "1990-01-31"
      }
    ]
  }
}

`document.signing_failed`#

The eID provider rejected the handoff. The sender can retry the document.

data

documentIduuidpåkrævet
orderIduuidpåkrævet
messagestringpåkrævet
Why the eID provider rejected the handoff.
signature order rejected

document.signing_failed

{
  "id": "3f7c1e42-9b0a-4d7e-8c31-2a5f6b9d0e11",
  "type": "document.signing_failed",
  "livemode": true,
  "created": 1784000000,
  "data": {
    "documentId": "3f7c1e42-9b0a-4d7e-8c31-2a5f6b9d0e11",
    "orderId": "3f7c1e42-9b0a-4d7e-8c31-2a5f6b9d0e11",
    "message": "signature order rejected"
  }
}

`document.cancelled`#

The request was cancelled before anyone signed — over the API or from the account. Its signing links no longer work.

data

documentIduuidpåkrævet
orderIduuidpåkrævet
The same id as SignatureRequest.id.
releasedSignaturesintegerpåkrævet
Signatures returned to the subscription's quota. 0 on pay-per-use and in test mode.
3
refundedOreintegerpåkrævet
Pay-per-use amount no longer charged, in minor units (øre), VAT included. 0 on a subscription.
returnedToBalanceOreintegerpåkrævet
Amount put back on the prepaid balance, in minor units (øre). 0 unless the request was paid from balance.

document.cancelled

{
  "id": "3f7c1e42-9b0a-4d7e-8c31-2a5f6b9d0e11",
  "type": "document.cancelled",
  "livemode": true,
  "created": 1784000000,
  "data": {
    "documentId": "3f7c1e42-9b0a-4d7e-8c31-2a5f6b9d0e11",
    "orderId": "3f7c1e42-9b0a-4d7e-8c31-2a5f6b9d0e11",
    "releasedSignatures": 3,
    "refundedOre": 0,
    "returnedToBalanceOre": 0
  }
}

`signer.signed`#

One signer has signed. Sent once per signer, before document.completed for the last one — follow a request with several parties as it goes.

data

orderIduuidpåkrævet
The same id as SignatureRequest.id.
documentIduuidpåkrævet
signerobjectpåkrævet
iduuidpåkrævet
The same id as SignatureRequest.signers[].id.
namestringpåkrævet| null
Ola Nordmann
emailstringpåkrævet| null
ola@example.no
phonestringpåkrævet| null
+4791234567
positionintegerpåkrævet
0-based order in the request's signer list.
signedAtstringpåkrævet
ISO 8601.
2026-07-13T10:24:00.000Z
signersSignedintegerpåkrævet
How many of the request's signers have signed, this one included.
1
signersTotalintegerpåkrævet
3

signer.signed

{
  "id": "3f7c1e42-9b0a-4d7e-8c31-2a5f6b9d0e11",
  "type": "signer.signed",
  "livemode": true,
  "created": 1784000000,
  "data": {
    "orderId": "3f7c1e42-9b0a-4d7e-8c31-2a5f6b9d0e11",
    "documentId": "3f7c1e42-9b0a-4d7e-8c31-2a5f6b9d0e11",
    "signer": {
      "id": "3f7c1e42-9b0a-4d7e-8c31-2a5f6b9d0e11",
      "name": "Ola Nordmann",
      "email": "ola@example.no",
      "phone": "+4791234567",
      "position": 0
    },
    "signedAt": "2026-07-13T10:24:00.000Z",
    "signersSigned": 1,
    "signersTotal": 3
  }
}

`signer.declined`#

One signer refused to sign. The request stays open; cancel it or send a new one.

data

orderIduuidpåkrævet
The same id as SignatureRequest.id.
documentIduuidpåkrævet
signerobjectpåkrævet
iduuidpåkrævet
The same id as SignatureRequest.signers[].id.
namestringpåkrævet| null
Ola Nordmann
emailstringpåkrævet| null
ola@example.no
phonestringpåkrævet| null
+4791234567
positionintegerpåkrævet
0-based order in the request's signer list.
reasonstringpåkrævet| null
What the signer wrote, when the signing page asked.
signersSignedintegerpåkrævet
signersTotalintegerpåkrævet

signer.declined

{
  "id": "3f7c1e42-9b0a-4d7e-8c31-2a5f6b9d0e11",
  "type": "signer.declined",
  "livemode": true,
  "created": 1784000000,
  "data": {
    "orderId": "3f7c1e42-9b0a-4d7e-8c31-2a5f6b9d0e11",
    "documentId": "3f7c1e42-9b0a-4d7e-8c31-2a5f6b9d0e11",
    "signer": {
      "id": "3f7c1e42-9b0a-4d7e-8c31-2a5f6b9d0e11",
      "name": "Ola Nordmann",
      "email": "ola@example.no",
      "phone": "+4791234567",
      "position": 0
    },
    "reason": "string",
    "signersSigned": 0,
    "signersTotal": 0
  }
}

`order.captured`#

A pay-per-use payment was captured. Not emitted for subscription-covered requests.

data

orderIduuidpåkrævet
documentIduuidpåkrævet
amountOreintegerpåkrævet
Captured amount in minor units (øre), VAT included.
3625

order.captured

{
  "id": "3f7c1e42-9b0a-4d7e-8c31-2a5f6b9d0e11",
  "type": "order.captured",
  "livemode": true,
  "created": 1784000000,
  "data": {
    "orderId": "3f7c1e42-9b0a-4d7e-8c31-2a5f6b9d0e11",
    "documentId": "3f7c1e42-9b0a-4d7e-8c31-2a5f6b9d0e11",
    "amountOre": 3625
  }
}

AI-assistenter (MCP)#

Skal en AI-assistent oprette underskrifterne i stedet, har vi en MCP-server: esigner.dk er en godkendt app i ChatGPT, og adressen kan indsættes som egen forbindelse i Claude og andre MCP-klienter. Se hvordan du forbinder.

Ofte stillede spørgsmål#

Hvad koster API'et?

Det koster ikke noget at bruge API'et. Underskrifter betales som på hjemmesiden: én underskrift pr. underskriver, trukket fra abonnementets kvote eller betalt pr. underskrift. Testnøgler er gratis og trækker ikke fra kvoten.

Findes der et testmiljø?

Ja. Nøgler, der starter med sk_test_, underskriver mod testmiljøet med testidentiteter — samme API, ingen betaling og ingen juridisk bindende underskrift.

Hvordan ved jeg, at en webhook kommer fra esigner.dk?

Hver levering har headeren Esigner-Signature med en HMAC-SHA256 over tidsstemplet og den rå body, lavet med endpointets hemmelighed. Se eksempler i Node.js, PHP og Python under Webhooks.

Kan underskriveren komme tilbage til min side efter underskrift?

Ja. Send returnUrl med, når du opretter anmodningen, så sendes hver underskriver dertil efter MitID — med signature_request_id og signer_id tilføjet.

Kan jeg begrænse, hvilke eID'er der tilbydes?

Ja, med signingEids, for eksempel ["dk_mitid"] for kun MitID. Eller gem valget på kontoen eller virksomheden, så gælder det alle anmodninger.

Sidder du fast? Tag kontakt — vi svarer gerne på integrationsspørgsmål.

Kom godt i gang#

Officielle SDK'er#

Node.js og TypeScript

PHP og WordPress

Godkendelse#

Idempotens#

Testmiljø#

Testidentiteter pr. eID

Dokumenter#

Upload the PDF(s) to be signed

Headere

Forespørgsel multipart/form-data

Svar 200Document

Fejlsvar

Underskriftsanmodninger#

Create a signature request

Headere

Forespørgsel application/json

Svar 201SignatureRequest

Fejlsvar

Retrieve a signature request

Sti-parametre

Svar 200SignatureRequest

Fejlsvar

Cancel a signature request

Sti-parametre

Headere

Forespørgsel application/json

Svar 200object

Fejlsvar

List the signed PDFs

Sti-parametre

Svar 200object

Fejlsvar

Download a signed PDF

Sti-parametre

Query-parametre

Svar 200

Fejlsvar

Saldo#

Retrieve the prepaid balance

Svar 200object

Fejlsvar

List balance transactions

Query-parametre

Svar 200object

Fejlsvar

Hændelser#

List events

Query-parametre

Svar 200object

Fejlsvar

Fejl#

Webhooks#

Konvolutten

document.completed#

document.signing_failed#

document.cancelled#

signer.signed#

signer.declined#

order.captured#

AI-assistenter (MCP)#

Ofte stillede spørgsmål#

Hvad koster API'et?

Findes der et testmiljø?

Hvordan ved jeg, at en webhook kommer fra esigner.dk?

Kan underskriveren komme tilbage til min side efter underskrift?

Kan jeg begrænse, hvilke eID'er der tilbydes?

Forespørgsel `multipart/form-data`

Svar 200`Document`

Forespørgsel `application/json`

Svar 201`SignatureRequest`

Svar 200`SignatureRequest`

Forespørgsel `application/json`

Svar 200`object`

Svar 200`object`

Svar 200`object`

Svar 200`object`

Svar 200`object`

`document.completed`#

`document.signing_failed`#

`document.cancelled`#

`signer.signed`#

`signer.declined`#

`order.captured`#