API-dokumentasjon

Bygg BankID-signering inn i ditt eget system. Last opp et dokument, opprett en signeringsforespørsel, og få beskjed via webhook når den er signert.

Base-URL
https://esigner.no/api/v1
Autentisering
Bearer sk_live_… / sk_test_…
Format
JSON · PDF som multipart
Webhooks
HMAC-SHA256-signert

Kom i gang#

  1. 1Lag en testnøkkel under Konto → Utvikler. Testnøkler (sk_test_…) signerer mot testmiljøet: ekte signeringsflyt, men ingen betaling, ingen kvote og ingen ekte penger.
  2. 2Last opp PDF-en med POST /v1/documents.
  3. 3Opprett signeringen med POST /v1/signature_requests. Uten paymentMethod venter den på betaling, og ingen inviteres før den er betalt: da er payment_required true og next_action.url er betalingslenken. Send paymentMethod: "balance", "card" eller "auto" for å betale uten betalingsside.
  4. 4Registrer et webhook-endepunkt, så sier vi fra når dokumentet er ferdig signert.
  5. 5Bytt til en live-nøkkel (sk_live_…) når alt virker.

Offisielle SDK-er#

Ferdige klienter som tar seg av autentisering, idempotensnøkler, nye forsøk, paginering og webhook-verifisering — typet etter den samme spesifikasjonen som denne siden.

Node.js og TypeScript

Node 18+, Bun, Deno og edge — ingen avhengigheter.

npm

npm install @esigner/sdk

npm ↗GitHub ↗

PHP og WordPress

PHP 8.1+, bare ext-curl — passer rett inn i WordPress.

Composer

composer require esigner/sdk

Packagist ↗GitHub ↗

Autentisering#

Send nøkkelen som bearer-token. Hver nøkkel har et sett tilganger (scopes) — den kommer ikke til endepunkter den ikke har fått tilgang til, og en nøkkel kan aldri lage en ny nøkkel.

Tilgangene velger du når du lager nøkkelen. Hvert endepunkt under sier hvilken det krever — mangler nøkkelen den, får du 403 insufficient_scope, og WWW-Authenticate sier hva som skulle til.

Hva som trekkes fra kvoten, og hva som skjer ved kansellering og utløp: Priser og telling av signaturer →

HTTP

Authorization: Bearer sk_live_...

Idempotens#

Send en Idempotency-Key på alle POST-kall. Faller nettet ut midt i et kall, kan du trygt prøve på nytt med samme nøkkel: du får det opprinnelige svaret tilbake i stedet for en ny signeringsforespørsel. Samme nøkkel med et annet innhold gir 422 — det er en feil hos deg, og vi skjuler den ikke.

curl https://esigner.no/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"
    ],
    "preserveOriginal": false
  }'

Testmiljø#

Nøkler med prefikset sk_test_ kjører mot testmiljøet. Alt fungerer som i produksjon — dokumentet lastes opp, bestillingen opprettes, signeringen starter — men signeringen skjer mot Iduras testmiljø med en testidentitet, og signaturen er ikke juridisk bindende. Testbestillinger koster ingenting og trekker ikke fra kvoten din. Det signerte dokumentet får en tydelig forside som sier at det er en test, og signaturkontrollen merker det som testsignatur.

Testidentiteter per eID

Testmiljøet godtar bare testbrukere — en ekte BankID, MitID eller annen eID virker ikke der, og den svenske BankID-appen melder for eksempel «ugyldig QR-kode». Slik får den som signerer en testidentitet: Iduras oversikt over testbrukere ↗

BankID (Norge)Idura ↗BankID RA preprod ↗
Lag en testbruker i BankIDs preprod-portal (RA preprod); tallgeneratoren der gir et gyldig fødselsnummer. Signer i nettleseren med engangskoden otp og passordet qwer1234. En ny testbruker kan bruke opptil en time på å bli aktiv.
BankID (Sverige)Idura ↗BankID for test ↗BankID test portal ↗
BankID-appen må konfigureres om til testmiljøet (se «BankID for test»), og den kan ikke være test og produksjon samtidig — bruk en ekstra telefon. Utsted deretter en test-BankID i BankIDs testportal med et oppdiktet, men gyldig personnummer. En vanlig BankID-app som skanner QR-koden, melder at den er ugyldig.
MitID (Danmark)Idura ↗MitID Test Tool ↗
Lag en testidentitet i MitID Test Tool og godkjenn med app-simulatoren der — det trengs ingen telefon. MitIDs egen test-app virker også; på Android kan den ikke ligge ved siden av den ekte appen.
FTN (Finland)Idura ↗
Idura publiserer ferdige testinnlogginger per bank, for eksempel DEMOUSER1 hos Nordea. Alt skjer i nettleseren; ingen app trengs.
iDIN (Nederland)Idura ↗
Idura publiserer ingen testbrukere for iDIN. Skriv til oss før du tester, så setter vi det opp sammen med deg.
OneID (Storbritannia)Idura ↗
OneIDs sandkasse simulerer banken («model bank»): velg en av testidentitetene i nettleseren. Ingen app trengs.
Personalausweis (Tyskland)Idura ↗AusweisApp ↗
Bruk AusweisApp med den innebygde kortsimulatoren, som alltid svarer som testpersonen «Erika Mustermann». Slå på utviklermodus (trykk ti ganger på versjonsnummeret), deretter testmodus og den interne kortsimulatoren. Simulatoren må slås av igjen før appen kan lese et ekte kort.

Testmiljøet sender ekte e-post og ekte SMS til mottakerne du oppgir — det er poenget med å teste. E-post får «[TEST]» i emnefeltet og SMS starter med «[TEST — ikke bindende]», så ingen tror en testmelding er ekte. Testdokumenter får aldri påminnelser.

Fordi testmeldinger er gratis for deg og sendes fra vårt domene og vårt telefonnummer, er volumet begrenset per konto: 50 e-poster og 10 SMS per rullerende døgn. Når budsjettet er brukt opp skjer det ingen feil — bestillingen opprettes, signeringen starter og signUrl virker som vanlig. Den eneste forskjellen er at meldingen ikke sendes, og at svaret sier fra i testMode-blokken. Du kan når som helst spørre GET /api-keys/test-quota, siden det også sendes meldinger etter at bestillingen er opprettet.

// 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.

Krever tilgang: 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ørsel multipart/form-data

  • ownerEmailstringpåkrevd

    Where the receipt and the signed PDF are sent. Must contain an @.

    post@firma.no

  • filesbinarypåkrevd

    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 200Document

The uploaded document

  • iduuidpåkrevd

    Pass this as documentId when you create the signature request.

  • filenamestringpåkrevd

    Name of the first uploaded file.

    avtale.pdf

  • sizeBytesintegerpåkrevd

    Total size across every uploaded file.

    184320

  • attachmentsobject[]påkrevd

    One entry per uploaded PDF.

  • positionintegerpåkrevd

    0-based. Also the order the PDFs are merged in.

  • filenamestringpåkrevd

    vedlegg.pdf

  • sizeBytesintegerpåkrevd

    92160

Feilsvar

  • 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.no/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
    }
  ]
}

Signeringsforespørsler#

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.

Krever tilgang: 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ørsel application/json

  • documentIduuidpåkrevd

    From POST /documents. Must belong to the same account as the key.

  • signersobject[]påkrevd

    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

    Signing deadline: whole days from now until the request expires, 1 to 90. Signers who have not signed by then can no longer sign. Omit it for the standard deadline — 14 days unless the operator has set another default for this market.

  • 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. A signer with only a name is never messaged even while this is true; see signers.

  • 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.

  • preserveOriginalboolean

    Sign the PDF exactly as you uploaded it. By default the file is saved again before signing (the content is kept; form fields and any existing signatures are removed) and the signing provider adds a page with the signature seals. With preserveOriginal: true nothing is re-saved, a signature or certification the file already carries is kept, and every party's signature is added on top of it — for a document someone else has already signed, such as the salgsmelding Statens vegvesen issues with its own seal. No page is added: each signer's seal is placed in a row along the foot of the last page, so leave that band empty. Off by default. It excludes sealFooter and merging several files into one (400 preserve_original_conflict), a test-mode request gets no test-mode cover page, and the signer list is fixed at creation (adding a signer later is 409 preserve_original_locked). If the signing provider cannot sign the file untouched, the request ends in signing_failed rather than signing an altered copy. Read back as preserve_original.

    false

  • 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 201SignatureRequest

The created signature request

  • iduuidpåkrevd

    The signature request id — pass it to GET /signature_requests/{id}.

  • object"signature_request"påkrevd
  • statusstringpåkrevd

    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åkrevd

    The document being signed.

  • iduuidpåkrevd
  • filenamestringpåkrevd

    avtale.pdf

  • signersobject[]påkrevd

    In invitation order.

  • iduuidpåkrevd

    Stable id for this signer within the request.

  • namestringpåkrevd| null

    Ola Nordmann

  • emailstringpåkrevd| null

    null for a signer reached only by SMS, or created with only a name (we contact that signer by no channel at all — see sign_url).

    ola@example.no

  • statusstringpåkrevd

    pending | notified | viewed | signed | declined | expired | removed (taken off the request by our support so it could complete)

  • signed_atstringpåkrevd| null

    ISO 8601, null until this signer has signed.

    2026-07-13T10:24:00.000Z

  • verified_namestringpåkrevd| 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åkrevd| 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åkrevd| null

    The date of birth this signer was locked to (signers[].birthDate at creation), or null.

    1990-01-31

  • sign_urlstringpåkrevd| 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. The same goes for a signer you created with only a name (no email, no phone), whatever notifySigners says: we never invite, remind or send that signer the signed copy, so this link (or sign_url_direct) reaches them only if you deliver it. Afterwards, fetch the signed PDF for them from GET /signature_requests/{id}/signed_documents. 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åkrevd| 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åkrevd

    How this request was paid for.

  • methodstringpåkrevd

    subscription | balance | checkout | comped | test

  • amount_oreintegerpåkrevd

    What this request cost in minor units (øre), VAT included. 0 on a subscription, comped or in test mode.

    5800

  • currencystringpåkrevd

    NOK

  • livemodebooleanpåkrevd

    false for signature requests created with an sk_test_ key.

  • createdstringpåkrevd

    ISO 8601.

    2026-07-13T10:12:00.000Z

  • payment_urlstringpåkrevd| 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åkrevd

    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åkrevd| 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åkrevd

    Always pay for now. Switch on it; other types may be added.

  • urlstringpåkrevd

    Same as payment_url.

    https://esigner.no/api/orders/3f7c1e42-9b0a-4d7…

  • messagestringpåkrevd

    A human-readable explanation, in English, safe to log or show a developer.

  • signed_documents_urlstringpåkrevd| 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åkrevd| 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åkrevd

    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åkrevd| 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åkrevd| 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"]

  • preserve_originalbooleanpåkrevd

    Whether the PDF is signed exactly as uploaded, as given in preserveOriginal.

    false

  • lockedbooleanpåkrevd

    True while the request is locked — by you (POST /signature_requests/{id}/lock) or by an administrator. Nobody can sign and nothing can be downloaded until it is unlocked.

    false

  • locked_atstringpåkrevd| null

    ISO 8601 time it was locked, or null.

  • expires_atstringpåkrevd| null

    ISO 8601. The signing deadline: a signer who has not signed by then no longer can, and the request ends in expired. Set from deadlineDays at creation; move it later with POST /signature_requests/{id}/deadline. null on a draft.

    2026-07-27T10:12:00.000Z

Feilsvar

  • 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.no/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"
    ],
    "preserveOriginal": false
  }'

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"
  ],
  "preserve_original": false,
  "locked": false,
  "locked_at": null,
  "expires_at": "2026-07-27T10:12:00.000Z"
}
GET/api/v1/signature_requests/{id}

Retrieve a signature request

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

Krever tilgang: orders:read

Sti-parametere

  • iduuidpåkrevd

    The id returned by POST /signature_requests.

Svar 200SignatureRequest

The signature request

Vis feltene i SignatureRequest
  • iduuidpåkrevd

    The signature request id — pass it to GET /signature_requests/{id}.

  • object"signature_request"påkrevd
  • statusstringpåkrevd

    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åkrevd

    The document being signed.

  • iduuidpåkrevd
  • filenamestringpåkrevd

    avtale.pdf

  • signersobject[]påkrevd

    In invitation order.

  • iduuidpåkrevd

    Stable id for this signer within the request.

  • namestringpåkrevd| null

    Ola Nordmann

  • emailstringpåkrevd| null

    null for a signer reached only by SMS, or created with only a name (we contact that signer by no channel at all — see sign_url).

    ola@example.no

  • statusstringpåkrevd

    pending | notified | viewed | signed | declined | expired | removed (taken off the request by our support so it could complete)

  • signed_atstringpåkrevd| null

    ISO 8601, null until this signer has signed.

    2026-07-13T10:24:00.000Z

  • verified_namestringpåkrevd| 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åkrevd| 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åkrevd| null

    The date of birth this signer was locked to (signers[].birthDate at creation), or null.

    1990-01-31

  • sign_urlstringpåkrevd| 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. The same goes for a signer you created with only a name (no email, no phone), whatever notifySigners says: we never invite, remind or send that signer the signed copy, so this link (or sign_url_direct) reaches them only if you deliver it. Afterwards, fetch the signed PDF for them from GET /signature_requests/{id}/signed_documents. 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åkrevd| 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åkrevd

    How this request was paid for.

  • methodstringpåkrevd

    subscription | balance | checkout | comped | test

  • amount_oreintegerpåkrevd

    What this request cost in minor units (øre), VAT included. 0 on a subscription, comped or in test mode.

    5800

  • currencystringpåkrevd

    NOK

  • livemodebooleanpåkrevd

    false for signature requests created with an sk_test_ key.

  • createdstringpåkrevd

    ISO 8601.

    2026-07-13T10:12:00.000Z

  • payment_urlstringpåkrevd| 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åkrevd

    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åkrevd| 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åkrevd

    Always pay for now. Switch on it; other types may be added.

  • urlstringpåkrevd

    Same as payment_url.

    https://esigner.no/api/orders/3f7c1e42-9b0a-4d7…

  • messagestringpåkrevd

    A human-readable explanation, in English, safe to log or show a developer.

  • signed_documents_urlstringpåkrevd| 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åkrevd| 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åkrevd

    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åkrevd| 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åkrevd| 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"]

  • preserve_originalbooleanpåkrevd

    Whether the PDF is signed exactly as uploaded, as given in preserveOriginal.

    false

  • lockedbooleanpåkrevd

    True while the request is locked — by you (POST /signature_requests/{id}/lock) or by an administrator. Nobody can sign and nothing can be downloaded until it is unlocked.

    false

  • locked_atstringpåkrevd| null

    ISO 8601 time it was locked, or null.

  • expires_atstringpåkrevd| null

    ISO 8601. The signing deadline: a signer who has not signed by then no longer can, and the request ends in expired. Set from deadlineDays at creation; move it later with POST /signature_requests/{id}/deadline. null on a draft.

    2026-07-27T10:12:00.000Z

Feilsvar

  • 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.no/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"
  ],
  "preserve_original": false,
  "locked": false,
  "locked_at": null,
  "expires_at": "2026-07-27T10:12:00.000Z"
}
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.

Krever tilgang: orders:write

Sti-parametere

  • iduuidpåkrevd

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ørsel 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 200object

The request is cancelled

  • signature_requestSignatureRequestpåkrevd
  • iduuidpåkrevd

    The signature request id — pass it to GET /signature_requests/{id}.

  • object"signature_request"påkrevd
  • statusstringpåkrevd

    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åkrevd

    The document being signed.

  • iduuidpåkrevd
  • filenamestringpåkrevd

    avtale.pdf

  • signersobject[]påkrevd

    In invitation order.

  • iduuidpåkrevd

    Stable id for this signer within the request.

  • namestringpåkrevd| null

    Ola Nordmann

  • emailstringpåkrevd| null

    null for a signer reached only by SMS, or created with only a name (we contact that signer by no channel at all — see sign_url).

    ola@example.no

  • statusstringpåkrevd

    pending | notified | viewed | signed | declined | expired | removed (taken off the request by our support so it could complete)

  • signed_atstringpåkrevd| null

    ISO 8601, null until this signer has signed.

    2026-07-13T10:24:00.000Z

  • verified_namestringpåkrevd| 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åkrevd| 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åkrevd| null

    The date of birth this signer was locked to (signers[].birthDate at creation), or null.

    1990-01-31

  • sign_urlstringpåkrevd| 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. The same goes for a signer you created with only a name (no email, no phone), whatever notifySigners says: we never invite, remind or send that signer the signed copy, so this link (or sign_url_direct) reaches them only if you deliver it. Afterwards, fetch the signed PDF for them from GET /signature_requests/{id}/signed_documents. 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åkrevd| 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åkrevd

    How this request was paid for.

  • methodstringpåkrevd

    subscription | balance | checkout | comped | test

  • amount_oreintegerpåkrevd

    What this request cost in minor units (øre), VAT included. 0 on a subscription, comped or in test mode.

    5800

  • currencystringpåkrevd

    NOK

  • livemodebooleanpåkrevd

    false for signature requests created with an sk_test_ key.

  • createdstringpåkrevd

    ISO 8601.

    2026-07-13T10:12:00.000Z

  • payment_urlstringpåkrevd| 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åkrevd

    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åkrevd| 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åkrevd

    Always pay for now. Switch on it; other types may be added.

  • urlstringpåkrevd

    Same as payment_url.

    https://esigner.no/api/orders/3f7c1e42-9b0a-4d7…

  • messagestringpåkrevd

    A human-readable explanation, in English, safe to log or show a developer.

  • signed_documents_urlstringpåkrevd| 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åkrevd| 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åkrevd

    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åkrevd| 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åkrevd| 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"]

  • preserve_originalbooleanpåkrevd

    Whether the PDF is signed exactly as uploaded, as given in preserveOriginal.

    false

  • lockedbooleanpåkrevd

    True while the request is locked — by you (POST /signature_requests/{id}/lock) or by an administrator. Nobody can sign and nothing can be downloaded until it is unlocked.

    false

  • locked_atstringpåkrevd| null

    ISO 8601 time it was locked, or null.

  • expires_atstringpåkrevd| null

    ISO 8601. The signing deadline: a signer who has not signed by then no longer can, and the request ends in expired. Set from deadlineDays at creation; move it later with POST /signature_requests/{id}/deadline. null on a draft.

    2026-07-27T10:12:00.000Z

  • already_cancelledbooleanpåkrevd

    True when an earlier call had already cancelled it. Nothing was returned by this call.

  • released_signaturesintegerpåkrevd

    Signatures returned to the subscription's quota by this call.

    2

  • refunded_oreintegerpåkrevd

    Pay-per-use amount no longer charged by this call, in minor units (øre), VAT included.

    0

  • returned_to_balance_oreintegerpåkrevd

    Amount put back on the prepaid balance by this call, in minor units (øre).

    0

Feilsvar

  • 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.no/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"
    ],
    "preserve_original": false,
    "locked": false,
    "locked_at": null,
    "expires_at": "2026-07-27T10:12:00.000Z"
  },
  "already_cancelled": true,
  "released_signatures": 2,
  "refunded_ore": 0,
  "returned_to_balance_ore": 0
}
POST/api/v1/signature_requests/{id}/deadline

Extend the signing deadline

Gives the signers more time on a request that is already in_progress — for instance when a counterparty is away. Send exactly one of days (counted from now) or expires_at (an exact moment). The new deadline must be later than the current expires_at and at most 90 days from now; a deadline can only be moved later, never earlier. The signing links stay the same, and the eID provider's order is extended too. Reminders follow the new date, including the last-day notice. Nothing is charged. Idempotent: asking for the deadline the request already has returns 200 with unchanged: true. With days, a retry computes from the new now — send an Idempotency-Key to replay the first answer instead.

Krever tilgang: orders:write

Sti-parametere

  • iduuidpåkrevd

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ørsel application/json

  • daysinteger

    The new deadline as whole days from now. At most 90.

    30

  • expires_atdate-time

    The new deadline as an exact ISO 8601 moment, with a time zone. At most 90 days from now.

    2026-08-31T21:59:00.000Z

Svar 200object

The deadline was moved. signature_request.expires_at is the new one.

  • signature_requestSignatureRequestpåkrevd
  • iduuidpåkrevd

    The signature request id — pass it to GET /signature_requests/{id}.

  • object"signature_request"påkrevd
  • statusstringpåkrevd

    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åkrevd

    The document being signed.

  • iduuidpåkrevd
  • filenamestringpåkrevd

    avtale.pdf

  • signersobject[]påkrevd

    In invitation order.

  • iduuidpåkrevd

    Stable id for this signer within the request.

  • namestringpåkrevd| null

    Ola Nordmann

  • emailstringpåkrevd| null

    null for a signer reached only by SMS, or created with only a name (we contact that signer by no channel at all — see sign_url).

    ola@example.no

  • statusstringpåkrevd

    pending | notified | viewed | signed | declined | expired | removed (taken off the request by our support so it could complete)

  • signed_atstringpåkrevd| null

    ISO 8601, null until this signer has signed.

    2026-07-13T10:24:00.000Z

  • verified_namestringpåkrevd| 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åkrevd| 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åkrevd| null

    The date of birth this signer was locked to (signers[].birthDate at creation), or null.

    1990-01-31

  • sign_urlstringpåkrevd| 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. The same goes for a signer you created with only a name (no email, no phone), whatever notifySigners says: we never invite, remind or send that signer the signed copy, so this link (or sign_url_direct) reaches them only if you deliver it. Afterwards, fetch the signed PDF for them from GET /signature_requests/{id}/signed_documents. 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åkrevd| 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åkrevd

    How this request was paid for.

  • methodstringpåkrevd

    subscription | balance | checkout | comped | test

  • amount_oreintegerpåkrevd

    What this request cost in minor units (øre), VAT included. 0 on a subscription, comped or in test mode.

    5800

  • currencystringpåkrevd

    NOK

  • livemodebooleanpåkrevd

    false for signature requests created with an sk_test_ key.

  • createdstringpåkrevd

    ISO 8601.

    2026-07-13T10:12:00.000Z

  • payment_urlstringpåkrevd| 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åkrevd

    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åkrevd| 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åkrevd

    Always pay for now. Switch on it; other types may be added.

  • urlstringpåkrevd

    Same as payment_url.

    https://esigner.no/api/orders/3f7c1e42-9b0a-4d7…

  • messagestringpåkrevd

    A human-readable explanation, in English, safe to log or show a developer.

  • signed_documents_urlstringpåkrevd| 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åkrevd| 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åkrevd

    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åkrevd| 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åkrevd| 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"]

  • preserve_originalbooleanpåkrevd

    Whether the PDF is signed exactly as uploaded, as given in preserveOriginal.

    false

  • lockedbooleanpåkrevd

    True while the request is locked — by you (POST /signature_requests/{id}/lock) or by an administrator. Nobody can sign and nothing can be downloaded until it is unlocked.

    false

  • locked_atstringpåkrevd| null

    ISO 8601 time it was locked, or null.

  • expires_atstringpåkrevd| null

    ISO 8601. The signing deadline: a signer who has not signed by then no longer can, and the request ends in expired. Set from deadlineDays at creation; move it later with POST /signature_requests/{id}/deadline. null on a draft.

    2026-07-27T10:12:00.000Z

  • previous_expires_atstringpåkrevd

    ISO 8601. The deadline before this call.

    2026-07-27T10:12:00.000Z

  • unchangedbooleanpåkrevd

    True when the request already had this deadline. Nothing was changed.

Feilsvar

  • 400validation — the body failed schema validation. invalid_deadline — send exactly one of days and expires_at.
  • 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_in_progress — the request has not been sent to its signers yet (draft, unpaid, or the hand-off failed). already_completed, already_expired, already_cancelled — the request is closed; an expired request cannot be reopened, create a new one.
  • 422deadline_shortening — the new deadline is earlier than the current one. deadline_too_far — it is more than 90 days from now.
  • 429too_many_requests — rate limited. Retry after the Retry-After header.
  • 502deadline_extend_failed — the eID provider refused the extension. Nothing changed; retry.
curl https://esigner.no/api/v1/signature_requests/3f7c1e42-9b0a-4d7e-8c31-2a5f6b9d0e11/deadline \
  -X POST \
  -H "Authorization: Bearer $ESIGNER_API_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{
    "days": 30,
    "expires_at": "2026-08-31T21:59:00.000Z"
  }'

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"
    ],
    "preserve_original": false,
    "locked": false,
    "locked_at": null,
    "expires_at": "2026-07-27T10:12:00.000Z"
  },
  "previous_expires_at": "2026-07-27T10:12:00.000Z",
  "unchanged": true
}
POST/api/v1/signature_requests/{id}/lock

Lock a signature request

Stops a request from going any further without cancelling it — for instance when something in the contract turns out to be wrong and it must not end up fully signed. While locked, the signing links stop working, nobody can sign, and the document and the signed PDF cannot be downloaded. Signatures already made stay. Nothing is refunded or returned to the quota: to get the signatures back on a request nobody has signed, use POST /signature_requests/{id}/cancel. Works on in_progress and completed requests. Idempotent: locking a locked request returns 200. Undo with POST /signature_requests/{id}/unlock.

Krever tilgang: orders:write

Sti-parametere

  • iduuidpåkrevd

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ørsel application/json

  • reasonstring

    Optional. Why — kept in the request's audit trail, never shown to the signers.

    Wrong rent in § 3 — correcting before anyone el…

Svar 200object

The request is locked

  • signature_requestSignatureRequestpåkrevd
  • iduuidpåkrevd

    The signature request id — pass it to GET /signature_requests/{id}.

  • object"signature_request"påkrevd
  • statusstringpåkrevd

    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åkrevd

    The document being signed.

  • iduuidpåkrevd
  • filenamestringpåkrevd

    avtale.pdf

  • signersobject[]påkrevd

    In invitation order.

  • iduuidpåkrevd

    Stable id for this signer within the request.

  • namestringpåkrevd| null

    Ola Nordmann

  • emailstringpåkrevd| null

    null for a signer reached only by SMS, or created with only a name (we contact that signer by no channel at all — see sign_url).

    ola@example.no

  • statusstringpåkrevd

    pending | notified | viewed | signed | declined | expired | removed (taken off the request by our support so it could complete)

  • signed_atstringpåkrevd| null

    ISO 8601, null until this signer has signed.

    2026-07-13T10:24:00.000Z

  • verified_namestringpåkrevd| 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åkrevd| 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åkrevd| null

    The date of birth this signer was locked to (signers[].birthDate at creation), or null.

    1990-01-31

  • sign_urlstringpåkrevd| 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. The same goes for a signer you created with only a name (no email, no phone), whatever notifySigners says: we never invite, remind or send that signer the signed copy, so this link (or sign_url_direct) reaches them only if you deliver it. Afterwards, fetch the signed PDF for them from GET /signature_requests/{id}/signed_documents. 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åkrevd| 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åkrevd

    How this request was paid for.

  • methodstringpåkrevd

    subscription | balance | checkout | comped | test

  • amount_oreintegerpåkrevd

    What this request cost in minor units (øre), VAT included. 0 on a subscription, comped or in test mode.

    5800

  • currencystringpåkrevd

    NOK

  • livemodebooleanpåkrevd

    false for signature requests created with an sk_test_ key.

  • createdstringpåkrevd

    ISO 8601.

    2026-07-13T10:12:00.000Z

  • payment_urlstringpåkrevd| 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åkrevd

    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åkrevd| 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åkrevd

    Always pay for now. Switch on it; other types may be added.

  • urlstringpåkrevd

    Same as payment_url.

    https://esigner.no/api/orders/3f7c1e42-9b0a-4d7…

  • messagestringpåkrevd

    A human-readable explanation, in English, safe to log or show a developer.

  • signed_documents_urlstringpåkrevd| 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åkrevd| 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åkrevd

    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åkrevd| 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åkrevd| 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"]

  • preserve_originalbooleanpåkrevd

    Whether the PDF is signed exactly as uploaded, as given in preserveOriginal.

    false

  • lockedbooleanpåkrevd

    True while the request is locked — by you (POST /signature_requests/{id}/lock) or by an administrator. Nobody can sign and nothing can be downloaded until it is unlocked.

    false

  • locked_atstringpåkrevd| null

    ISO 8601 time it was locked, or null.

  • expires_atstringpåkrevd| null

    ISO 8601. The signing deadline: a signer who has not signed by then no longer can, and the request ends in expired. Set from deadlineDays at creation; move it later with POST /signature_requests/{id}/deadline. null on a draft.

    2026-07-27T10:12:00.000Z

Feilsvar

  • 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.
  • 409order_closed — only in_progress and completed requests can be locked or unlocked (not drafts, unpaid, cancelled, expired, failed or refunded ones, or one whose files are deleted).
  • 429too_many_requests — rate limited. Retry after the Retry-After header.
  • 502signing_lock_failed — the eID provider could not be updated. A lock is kept on our side regardless; retry to finish it. An unlock changed nothing; retry.
curl https://esigner.no/api/v1/signature_requests/3f7c1e42-9b0a-4d7e-8c31-2a5f6b9d0e11/lock \
  -X POST \
  -H "Authorization: Bearer $ESIGNER_API_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{
    "reason": "Wrong rent in § 3 — correcting before anyone else signs"
  }'

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"
    ],
    "preserve_original": false,
    "locked": false,
    "locked_at": null,
    "expires_at": "2026-07-27T10:12:00.000Z"
  }
}
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.

Krever tilgang: documents:readorders:read(én av dem holder)

Sti-parametere

  • iduuidpåkrevd

Svar 200object

The signed PDFs

  • dataSignedDocument[]påkrevd
  • positionintegerpåkrevd

    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åkrevd

    signert-avtale.pdf

  • size_bytesintegerpåkrevd| null

    null if the size could not be read.

    214016

  • sha256stringpåkrevd| null

    Hex SHA-256 of the signed PDF, captured at completion. Verify your download against it.

    9f86d081884c7d659a2feaa0c55ad015a3bf4f1b2b0b822…

  • urlstringpåkrevd

    Authenticated download for this file. Same API key, application/pdf in response.

    https://esigner.no/api/v1/signature_requests/3f…

  • download_expires_atstringpåkrevd| null

    When the PUBLIC links expire. These API downloads do not — see the field on SignatureRequest.

Feilsvar

  • 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 (the document is locked — by you or by an administrator).
  • 429too_many_requests — rate limited. Retry after the Retry-After header.
curl https://esigner.no/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.

Krever tilgang: documents:readorders:read(én av dem holder)

Sti-parametere

  • iduuidpåkrevd
  • positioninteger

    From the list endpoint. Always 0 in merged mode.

Spørringsparametere

  • download"0" | "1"

    1 sets Content-Disposition: attachment instead of inline.

Svar 200

The signed PDF

Fritt JSON-objekt — innholdet varierer.

Feilsvar

  • 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.no/api/v1/signature_requests/3f7c1e42-9b0a-4d7e-8c31-2a5f6b9d0e11/signed_documents/0 \
  -H "Authorization: Bearer $ESIGNER_API_KEY"
POST/api/v1/signature_requests/{id}/unlock

Unlock a signature request

Lifts a lock, set by you or by an administrator, and lets the request continue where it stopped: the same signing links work again. Idempotent: unlocking a request that is not locked returns 200.

Krever tilgang: orders:write

Sti-parametere

  • iduuidpåkrevd

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ørsel application/json

  • reasonstring

    Optional. Why — kept in the request's audit trail, never shown to the signers.

    Corrected

Svar 200object

The request is unlocked

  • signature_requestSignatureRequestpåkrevd
  • iduuidpåkrevd

    The signature request id — pass it to GET /signature_requests/{id}.

  • object"signature_request"påkrevd
  • statusstringpåkrevd

    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åkrevd

    The document being signed.

  • iduuidpåkrevd
  • filenamestringpåkrevd

    avtale.pdf

  • signersobject[]påkrevd

    In invitation order.

  • iduuidpåkrevd

    Stable id for this signer within the request.

  • namestringpåkrevd| null

    Ola Nordmann

  • emailstringpåkrevd| null

    null for a signer reached only by SMS, or created with only a name (we contact that signer by no channel at all — see sign_url).

    ola@example.no

  • statusstringpåkrevd

    pending | notified | viewed | signed | declined | expired | removed (taken off the request by our support so it could complete)

  • signed_atstringpåkrevd| null

    ISO 8601, null until this signer has signed.

    2026-07-13T10:24:00.000Z

  • verified_namestringpåkrevd| 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åkrevd| 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åkrevd| null

    The date of birth this signer was locked to (signers[].birthDate at creation), or null.

    1990-01-31

  • sign_urlstringpåkrevd| 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. The same goes for a signer you created with only a name (no email, no phone), whatever notifySigners says: we never invite, remind or send that signer the signed copy, so this link (or sign_url_direct) reaches them only if you deliver it. Afterwards, fetch the signed PDF for them from GET /signature_requests/{id}/signed_documents. 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åkrevd| 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åkrevd

    How this request was paid for.

  • methodstringpåkrevd

    subscription | balance | checkout | comped | test

  • amount_oreintegerpåkrevd

    What this request cost in minor units (øre), VAT included. 0 on a subscription, comped or in test mode.

    5800

  • currencystringpåkrevd

    NOK

  • livemodebooleanpåkrevd

    false for signature requests created with an sk_test_ key.

  • createdstringpåkrevd

    ISO 8601.

    2026-07-13T10:12:00.000Z

  • payment_urlstringpåkrevd| 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åkrevd

    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åkrevd| 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åkrevd

    Always pay for now. Switch on it; other types may be added.

  • urlstringpåkrevd

    Same as payment_url.

    https://esigner.no/api/orders/3f7c1e42-9b0a-4d7…

  • messagestringpåkrevd

    A human-readable explanation, in English, safe to log or show a developer.

  • signed_documents_urlstringpåkrevd| 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åkrevd| 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åkrevd

    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åkrevd| 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åkrevd| 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"]

  • preserve_originalbooleanpåkrevd

    Whether the PDF is signed exactly as uploaded, as given in preserveOriginal.

    false

  • lockedbooleanpåkrevd

    True while the request is locked — by you (POST /signature_requests/{id}/lock) or by an administrator. Nobody can sign and nothing can be downloaded until it is unlocked.

    false

  • locked_atstringpåkrevd| null

    ISO 8601 time it was locked, or null.

  • expires_atstringpåkrevd| null

    ISO 8601. The signing deadline: a signer who has not signed by then no longer can, and the request ends in expired. Set from deadlineDays at creation; move it later with POST /signature_requests/{id}/deadline. null on a draft.

    2026-07-27T10:12:00.000Z

Feilsvar

  • 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.
  • 409order_closed — only in_progress and completed requests can be locked or unlocked (not drafts, unpaid, cancelled, expired, failed or refunded ones, or one whose files are deleted).
  • 429too_many_requests — rate limited. Retry after the Retry-After header.
  • 502signing_lock_failed — the eID provider could not be updated. A lock is kept on our side regardless; retry to finish it. An unlock changed nothing; retry.
curl https://esigner.no/api/v1/signature_requests/3f7c1e42-9b0a-4d7e-8c31-2a5f6b9d0e11/unlock \
  -X POST \
  -H "Authorization: Bearer $ESIGNER_API_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{
    "reason": "Corrected"
  }'

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"
    ],
    "preserve_original": false,
    "locked": false,
    "locked_at": null,
    "expires_at": "2026-07-27T10:12:00.000Z"
  }
}

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.

Krever tilgang: billing:read

Svar 200object

The balance

  • object"balance"påkrevd
  • livemodebooleanpåkrevd
  • balance_oreintegerpåkrevd

    Spendable now, in minor units (øre).

    120000

  • currencystringpåkrevd

    NOK

  • lotsobject[]påkrevd
  • remaining_oreintegerpåkrevd
  • expires_atstringpåkrevd| null

    ISO 8601.

Feilsvar

  • 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.no/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.

Krever tilgang: billing:read

Spørringsparametere

  • limitinteger
  • cursorstring

    The previous page's next_cursor.

Svar 200object

A page of transactions

  • dataobject[]påkrevd
  • iduuidpåkrevd
  • typestringpåkrevd

    topup | draw | draw_return | withdrawal | withdrawal_reversal | refund | refund_reversal | expiry

  • amount_oreintegerpåkrevd
  • balance_after_oreintegerpåkrevd
  • signature_request_iduuidpåkrevd| null
  • createdstringpåkrevd
  • next_cursorstringpåkrevd| null

Feilsvar

  • 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.no/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"
}

Data processing agreements#

GET/api/v1/data_processing_agreements

List data processing agreements

The agreements this account has requested, newest first, with where each one is.

Krever tilgang: account:read

Svar 200object

The requests

  • dataDataProcessingAgreement[]påkrevd
  • iduuidpåkrevd
  • object"data_processing_agreement"påkrevd
  • status"received" | "sent_for_signing" | "signed" | "closed"påkrevd

    received — we have it and are reviewing it. sent_for_signing — the signing invitation is out to the contact person. signed — everyone has signed; the signed agreement went to the contact person by email. closed — withdrawn without a signature.

  • companyobjectpåkrevd
  • namestringpåkrevd
  • org_numberstringpåkrevd
  • contactobjectpåkrevd| null
  • namestringpåkrevd
  • emailstringpåkrevd
  • languagestringpåkrevd| null

    nb-NO

  • requested_atstringpåkrevd

    ISO 8601.

  • sent_for_signing_atstringpåkrevd| null
  • signed_atstringpåkrevd| null

Feilsvar

  • 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.no/api/v1/data_processing_agreements \
  -H "Authorization: Bearer $ESIGNER_API_KEY"

Svar

{
  "data": [
    {
      "id": "3f7c1e42-9b0a-4d7e-8c31-2a5f6b9d0e11",
      "object": "data_processing_agreement",
      "status": "received",
      "company": {
        "name": "string",
        "org_number": "string"
      },
      "contact": {
        "name": "string",
        "email": "string"
      },
      "language": "nb-NO",
      "requested_at": "string",
      "sent_for_signing_at": "string",
      "signed_at": "string"
    }
  ]
}
POST/api/v1/data_processing_agreements

Request a data processing agreement

Asks us for our data processing agreement (GDPR art. 28), with your company as controller and us as processor. Send who you are and who should sign; we prepare the agreement with those details, review it and send it for signing to contact.email, usually within one working day. When everyone has signed, the contact person gets the signed agreement by email. Poll GET /data_processing_agreements for the status. Only the fields below are yours to fill; the rest of the text is our standard agreement. A key that belongs to a company account may leave out company — the account's own name and org number are used. One open request per organisation: while one is not yet signed, asking again returns it (200) instead of creating a second. Not available with a test key.

Krever tilgang: account: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ørsel application/json

  • companyobject

    The controller. Optional for a company account's key.

  • namestringpåkrevd

    Eksempel AS

  • org_numberstringpåkrevd

    912 345 678

  • contactobjectpåkrevd

    The person who signs for the controller and receives the signed agreement.

  • namestringpåkrevd

    Kari Nordmann

  • emailemailpåkrevd

    kari@eksempel.no

  • languagestring (7 values)

    The agreement's language. Default: this market's.

  • instructionsstring

    Optional documented instructions from the controller (clause on instructions). Plain text.

Svar 200DataProcessingAgreement

A request for this organisation was already open; it is returned unchanged

  • iduuidpåkrevd
  • object"data_processing_agreement"påkrevd
  • status"received" | "sent_for_signing" | "signed" | "closed"påkrevd

    received — we have it and are reviewing it. sent_for_signing — the signing invitation is out to the contact person. signed — everyone has signed; the signed agreement went to the contact person by email. closed — withdrawn without a signature.

  • companyobjectpåkrevd
  • namestringpåkrevd
  • org_numberstringpåkrevd
  • contactobjectpåkrevd| null
  • namestringpåkrevd
  • emailstringpåkrevd
  • languagestringpåkrevd| null

    nb-NO

  • requested_atstringpåkrevd

    ISO 8601.

  • sent_for_signing_atstringpåkrevd| null
  • signed_atstringpåkrevd| null

Feilsvar

  • 400validation — see issues. company_required — a personal account's key must send company.
  • 401unauthorized — no API key, or it has been revoked.
  • 403test_mode — data processing agreements are real agreements; use a live key.
  • 429too_many_requests — rate limited. Retry after the Retry-After header.
curl https://esigner.no/api/v1/data_processing_agreements \
  -X POST \
  -H "Authorization: Bearer $ESIGNER_API_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{
    "contact": {
      "name": "Kari Nordmann",
      "email": "kari@eksempel.no"
    }
  }'

Svar

{
  "id": "3f7c1e42-9b0a-4d7e-8c31-2a5f6b9d0e11",
  "object": "data_processing_agreement",
  "status": "received",
  "company": {
    "name": "string",
    "org_number": "string"
  },
  "contact": {
    "name": "string",
    "email": "string"
  },
  "language": "nb-NO",
  "requested_at": "string",
  "sent_for_signing_at": "string",
  "signed_at": "string"
}

Hendelser#

GET/api/v1/events

List events

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

Krever tilgang: webhooks:readorders:read(én av dem holder)

Spørringsparametere

  • 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 200object

A page of events

  • dataEvent[]påkrevd
  • iduuidpåkrevd
  • object"event"påkrevd
  • typestringpåkrevd

    document.completed | document.signing_failed | order.captured

  • livemodebooleanpåkrevd

    false for activity produced by an sk_test_ key.

  • createdstringpåkrevd

    ISO 8601. Also the pagination cursor — pass it as cursor to get the next page.

    2026-07-13T10:24:00.000Z

  • dataobjectpåkrevd

    The same payload the webhook delivery carries for this event type.

  • next_cursorstringpåkrevd| null

    null on the last page. Otherwise pass it back as cursor.

Feilsvar

  • 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.no/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"
}

Full maskinlesbar spesifikasjon (OpenAPI 3.1): /api/v1/openapi.json

Feil#

Alle feil svarer med JSON og en stabil kode i error. Kodene under er de du kan møte — bygg logikken på dem, ikke på teksten.

StatusKodeBetyr
400validationThe request body failed schema validation. issues carries the field-level detail.
401unauthorizedMissing, malformed or revoked API key.
403insufficient_scopeThe key is valid but lacks the scope the endpoint declares. WWW-Authenticate names what was needed.
403cross_owner_documentThe documentId belongs to a different account than the key.
404not_foundNo such resource — or it belongs to another account. Deliberately indistinguishable.
409quota_exceededThe 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.
400payment_method_conflictpaymentMethod contradicts useSubscription or a free-signing link. Send one or the other.
409no_payment_methodpaymentMethod: "auto" but the account has no subscription or payment method to charge.
402insufficient_balanceThe prepaid balance doesn't cover the request. balanceOre and requiredOre say by how much. Nothing was created.
402payment_method_declinedThe saved card was declined. declineCode carries the bank's reason. Nothing was created.
402payment_method_action_requiredThe bank requires the cardholder to be present. Save the card again under /konto/betaling.
503payment_unconfirmedThe card charge's outcome could not be confirmed. orderId is returned — read it before retrying, so a held payment isn't doubled.
400invalid_return_urlreturnUrl is not an absolute https URL (http only with a test key), or it carries credentials. message says which.
400signer_needs_email_or_phoneA signer has no name, email or phone. signer is its 0-based index. Nothing was created.
400invalid_birthdateA signers[].birthDate is not a real date in the past in YYYY-MM-DD. message names the signer. Nothing was created.
400birthdate_lock_unsupportedsigners[].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.
400preserve_original_conflictpreserveOriginal: true was combined with sealFooter: true, or with several files in mode: "merged" — both change the file. Nothing was created.
400signing_eid_unavailablesigningEids names an eID this deployment does not offer. unavailable lists them and available lists what you may use. Nothing was created.
409payment_method_unavailableThe named paymentMethod is not offered on this deployment.
409already_signedCancel was refused: at least one signer has already signed.
409not_cancellableCancel was refused: the request is no longer open (completed, expired, failed, or locked).
502payment_reversal_failedCancel could not return the pay-per-use payment, so the request was left open. Retry.
409no_subscriptionuseSubscription: true but the account has no active subscription.
409topup_in_progressAn automatic top-up is already running. Retry shortly.
409topup_cooldownA renewal failed recently; automatic top-up is on a 24h cool-down.
409not_completedThe signed PDF was requested before every signer had signed. detail names the current status.
409seal_footer_lockedSigners cannot be added to a request created with sealFooter: true — the roster is inside the signed file.
409preserve_original_lockedSigners cannot be added to a request created with preserveOriginal: true — each signer's seal was given its place in the file at creation.
409signer_roster_fullThe 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.
410goneThe files behind this signature request have been deleted.
409order_closedLock or unlock was refused: only in_progress and completed requests can be locked.
502signing_lock_failedThe eID provider could not be updated during a lock or unlock. A lock is kept on our side regardless; retry.
409not_in_progressThe deadline can only be moved on a request that is in_progress — sent to its signers and not yet finished.
409already_completedThe deadline of a completed request cannot be moved.
409already_expiredThe request has expired; its deadline cannot be moved. Create a new request.
409already_cancelledThe request was cancelled or refunded; its deadline cannot be moved.
422deadline_shorteningA deadline can only be moved later. The new one is earlier than the current expires_at.
422deadline_too_farThe new deadline is more than 90 days from now.
400invalid_deadlineSend exactly one of days and expires_at.
502deadline_extend_failedThe eID provider refused to extend the request. Nothing changed; retry.
410revokedThis document is locked — by its sender or by an administrator.
409idempotency_key_in_progressThe first request with this Idempotency-Key hasn't finished. Retry.
413—A single uploaded file exceeded the size limit.
422idempotency_key_reusedThe same Idempotency-Key was used with a different request body. That's a caller bug, so we surface it.
429too_many_requestsRate limited. Retry-After says how long to wait.
502signing_failedThe 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.

Feil

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

Webhooks#

Vi POSTer hendelser til adressen din og signerer hver leveranse med Esigner-Signature: t=<unix>,v1=<hmac>. HMAC-en er over <t>.<rå body>, så en fanget melding ikke kan spilles av på nytt med et annet tidsstempel. Verifiser alltid før du stoler på innholdet.

Feiler en levering, prøver vi på nytt med økende mellomrom (1 min → 6 t). Svarer endepunktet ikke over tid, deaktiverer vi det og sier fra på e-post — hendelsene går ikke tapt, og du kan sende dem på nytt.

Konvolutten

  • iduuidpåkrevd

    Also sent as the Esigner-Event-Id header. Dedupe on it — a retry reuses the id.

  • typestringpåkrevd

    Also sent as the Esigner-Event-Type header.

    document.completed

  • livemodebooleanpåkrevd
  • createdintegerpåkrevd

    Unix seconds. Note: GET /events returns this field as an ISO string instead.

    1784000000

  • dataobjectpåkrevd

    Per event type — see below.

// Verifiser 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åkrevd
  • orderIduuidpåkrevd

    The same id as SignatureRequest.id.

  • filenamestringpåkrevd

    avtale.pdf

  • mode"merged" | "separate"påkrevd

    Whether the uploads were signed as one merged PDF or individually.

  • downloadExpiresAtstringpåkrevd

    ISO 8601. Fetch the signed PDF before this.

    2026-08-13T10:24:00.000Z

  • signersobject[]påkrevd
  • namestringpåkrevd| null

    Ola Nordmann

  • emailstringpåkrevd| null

    ola@example.no

  • signedAtstringpåkrevd| null

    ISO 8601.

    2026-07-13T10:24:00.000Z

  • verifiedNamestringpåkrevd| null

    The name as the signer's eID verified it.

    Ola Nordmann

  • verifiedBirthDatestringpåkrevd| null

    YYYY-MM-DD, as the signer's eID verified it. Null for Swedish BankID, which issues none.

    1990-01-31

  • birthDateLockstringpåkrevd| 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åkrevd
  • orderIduuidpåkrevd
  • messagestringpåkrevd

    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åkrevd
  • orderIduuidpåkrevd

    The same id as SignatureRequest.id.

  • releasedSignaturesintegerpåkrevd

    Signatures returned to the subscription's quota. 0 on pay-per-use and in test mode.

    3

  • refundedOreintegerpåkrevd

    Pay-per-use amount no longer charged, in minor units (øre), VAT included. 0 on a subscription.

  • returnedToBalanceOreintegerpåkrevd

    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åkrevd

    The same id as SignatureRequest.id.

  • documentIduuidpåkrevd
  • signerobjectpåkrevd
  • iduuidpåkrevd

    The same id as SignatureRequest.signers[].id.

  • namestringpåkrevd| null

    Ola Nordmann

  • emailstringpåkrevd| null

    ola@example.no

  • phonestringpåkrevd| null

    +4791234567

  • positionintegerpåkrevd

    0-based order in the request's signer list.

  • signedAtstringpåkrevd

    ISO 8601.

    2026-07-13T10:24:00.000Z

  • signersSignedintegerpåkrevd

    How many of the request's signers have signed, this one included.

    1

  • signersTotalintegerpåkrevd

    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åkrevd

    The same id as SignatureRequest.id.

  • documentIduuidpåkrevd
  • signerobjectpåkrevd
  • iduuidpåkrevd

    The same id as SignatureRequest.signers[].id.

  • namestringpåkrevd| null

    Ola Nordmann

  • emailstringpåkrevd| null

    ola@example.no

  • phonestringpåkrevd| null

    +4791234567

  • positionintegerpåkrevd

    0-based order in the request's signer list.

  • reasonstringpåkrevd| null

    What the signer wrote, when the signing page asked.

  • signersSignedintegerpåkrevd
  • signersTotalintegerpåkrevd

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åkrevd
  • documentIduuidpåkrevd
  • amountOreintegerpåkrevd

    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 opprette signeringene i stedet, har vi en MCP-server: esigner.no er en godkjent app i ChatGPT, og adressen kan legges inn som egen tilkobling i Claude og andre MCP-klienter. Se hvordan du kobler til.

Ofte stilte spørsmål#

Hva koster API-et?

Det koster ingenting å bruke API-et. Signeringene betales som på nettsiden: én signatur per undertegner, trukket fra abonnementets kvote eller betalt per signering. Testnøkler er gratis og trekker ikke fra kvoten.

Finnes det et testmiljø?

Ja. Nøkler som starter med sk_test_, signerer mot testmiljøet med testidentiteter — samme API, ingen betaling og ingen juridisk bindende signatur.

Hvordan vet jeg at en webhook kommer fra esigner.no?

Hver leveranse har headeren Esigner-Signature med en HMAC-SHA256 over tidsstempelet og rå body, laget med endepunktets hemmelighet. Se eksempler i Node.js, PHP og Python under Webhooks.

Kan undertegneren komme tilbake til min side etter signering?

Ja. Send med returnUrl når du oppretter forespørselen, så sendes hver undertegner dit etter BankID — med signature_request_id og signer_id lagt til.

Kan jeg begrense hvilke eID-er som tilbys?

Ja, med signingEids, for eksempel ["no_bankid"] for bare norsk BankID. Eller lagre valget på kontoen eller virksomheten, så gjelder det alle forespørsler.

Står du fast? Ta kontakt — vi svarer gjerne på integrasjonsspørsmål.