Kuverter og modtagere

En kuvert er én kontrakt på vej til at blive underskrevet: en skabelonversion, der er renderet med dine variabler, de modtagere, der skal handle på den, og beviserne for alt, hvad der sker. Du opretter en med POST /v1/envelopes.

Oprettelse af en kuvert

Felt	Type	Bemærkninger
`template`	`tpl_…`	Påkrævet
`version`	tal eller `"latest"`	Standard `latest`; slås op og fastlåses ved oprettelsen. Skal være udgivet
`variables`	objekt	Valideres mod versionens JSON Schema
`recipients`	array	Én pr. rolle (`role`, `name`, `email`; valgfrit `externalUserId`, `verification`, `fields` til forudfyldning pr. felt-id, `order` til at ændre underskriftsrækkefølgen)
`subject`, `message`	streng	Bruges i underskrifts-e-mails og vises på underskriftssiden
`delivery`	`email` · `embedded` · `none`	Standard `email`
`expiresAt`	RFC 3339	Skal ligge i fremtiden; kuverten udløber på det tidspunkt, og underskrifts- og observatørlinks holder op med at virke
`cc`	array	Ekstra CC-modtagere (`name`, `email`) ud over skabelonens CC-roller; op til 50
`viewers`	array	Personer, der følger kuverten uden at underskrive (`name`, `email`, valgfrit `notifyOnSignature`); antallet pr. kuvert begrænses af planen
`viewerDocumentAccess`	boolesk	Lader observatører åbne dokumentet på deres statusside. Standard `false` (kun status); Team-planen og op
`reminders`	objekt	`{ "enabled": false }` slår påmindelser fra; `{ "enabled": true, "intervalHours": 24 }` ændrer intervallet (1 til 720)
`externalId`	streng	Dit eget id, op til 200 tegn
`dedupeOn`	`"external_id"`	Returnér den eksisterende kuvert med dette `externalId` i stedet for at oprette en ny
`metadata`	objekt med strenge	Op til 500 tegn pr. værdi; returneres på kuverten og i webhooks

Hver modtager skal have en rolle i versionen; hver rolle, der ikke er CC, skal have præcis én modtager. Fejl rapporteres samlet med pointere som /recipients/1/role eller /recipients/0/fields/start_date.

Svar: 201 med kuverten og en Location-header; 200 med den eksisterende kuvert og x-deduplicated: true, når dedupeOn gav et match; 200 med en opsummering af prøvekørslen ved ?dry_run=true; 402, når et Free-workspace har brugt sine inkluderede kuverter; 403 plan-upgrade-required, når observatørerne overstiger planens kvote, eller viewerDocumentAccess ikke indgår i planen (Planer og grænser). Prøvekørsler tjekker også planens grænser.

Alle felter, der er tilføjet efter den første udgivelse, er valgfrie: en anmodning uden dem opfører sig præcis som før.

Indstillinger ved afsendelse

Skabelonen fastlægger, hvem der underskriver i hvilken rækkefølge. For en enkelt kuvert kan du ændre det uden at røre skabelonen:

{
  "template": "tpl_9fK2mQ7xLp",
  "variables": { "client": { "name": "Jane Doe" } },
  "recipients": [
    { "role": "client", "name": "Jane Doe", "email": "jane@acme.dev", "order": 2 },
    { "role": "company", "name": "Sam Lee", "email": "sam@bonafide.dev", "order": 1 },
    { "role": "witness", "name": "Kim Park", "email": "kim@acme.dev", "order": 1 }
  ],
  "cc": [{ "name": "Legal", "email": "legal@acme.dev" }],
  "viewers": [{ "name": "Alex Chen", "email": "alex@acme.dev", "notifyOnSignature": true }],
  "reminders": { "enabled": true, "intervalHours": 48 },
  "expiresAt": "2026-11-30T23:59:59Z"
}

Rækkefølge: recipients[].order er det trin, modtageren underskriver i; modtagere med samme nummer underskriver samtidig. Uden den gælder rollens order fra skabelonen. Rækkefølger er positive heltal; CC-roller kan ikke placeres i rækkefølgen; hver rolle skal stadig have sin modtager (så skabelonens felter beholder deres underskriver); mindst én modtager skal underskrive. Hændelsen envelope.created registrerer routingOverridden: true.
CC: ekstra CC-modtagere får e-mailen med det fuldførte dokument og underskriver aldrig. De vises i recipients med kind: "cc" og rollen _cc.
Påmindelser: den, hvis tur det er, mindes om det for hver intervalHours (standard: installationens REMINDER_INTERVAL_HOURS, 72), højst tre gange; enabled: false sender ingen. Påmindelser gælder for levering via email.
Godkendelse af underskrivere angives pr. modtager: verification tilsidesætter rollens metode. none (kun det unikke underskriftslink, standard for roller, der ikke angiver en metode) og email_otp (linket plus en kode pr. e-mail) er tilgængelige i dag; passkey og id_check afvises, da de endnu ikke er tilgængelige. Se verificering af underskrivere.
Sprog: locale på en modtager, CC eller observatør (eller på kuverten, for alle uden deres eget) angiver sproget på vedkommendes underskriftsside og e-mails, et af de 50 underskriftssprog. Uden den følger underskriftssiden browseren, og e-mails sendes på engelsk.

Afsendelsesskærmen i dashboardet har de samme muligheder: flyt trin tidligere eller senere, markér Underskriv samtidig, tilføj CC’er og observatører, vælg hver underskrivers godkendelse (Kun e-maillink eller E-maillink + kode) og sprog, og angiv en udløbsdato og en tidsplan for påmindelser.

Levering

email: hver modtager får et link til den hostede underskriftsside pr. e-mail, når det er vedkommendes tur. Modtagere, der ikke har underskrevet, får en påmindelse med få dages mellemrum (højst tre), og alle får en e-mail, når kuverten fuldføres.
embedded: ingen e-mails til underskrivere. Opret en signeringssession, når underskriveren er i dit produkt. Observatører får stadig deres statuslink pr. e-mail.
none: ingen e-mails overhovedet (heller ikke til observatører); brug den, når du selv leverer links (hostede sessioner).

POST /v1/envelopes/{id}/recipients/{recipient}/resend sender et nyt link pr. e-mail til en modtager, hvis tur det er (højst én gang i minuttet).

Livscyklus

          ┌──────────── declined (a signer declined)
          │
sent ─────┼──────────── voided   (POST /v1/envelopes/{id}/void)
          │
          ├──────────── expired  (expiresAt passed)
          │
          └──────────── completed ──► seal: pending ──► sealed

`status`	Betydning
`rendering`	Forberedes
`sent`	I gang: modtagerne underskriver i den fastlagte rækkefølge
`completed`	Alle modtagere er færdige. Forseglingen starter
`declined`	En modtager afviste; kuverten afsluttes
`voided`	Du annullerede den (`{ "reason": "…" }`); åbne signeringssessioner holder op med at virke
`expired`	`expiresAt` blev passeret før fuldførelsen

seal følger den forseglede PDF: not_started, pending (fuldført, forsegles), sealed eller failed. Forseglingen blokerer aldrig fuldførelsen: kuverten fuldføres først og forsegles lige derefter.

Modtagere og rækkefølge

{
  "id": "rcp_5Jw0pLs9Xe",
  "role": "client",
  "name": "Jane Doe",
  "email": "jane@acme.dev",
  "order": 1,
  "status": "viewed",
  "verification": "email_otp",
  "completedAt": null
}

Modtagerens status er pending (endnu ikke vedkommendes tur), sent, viewed, completed eller declined, og kind er rollens signer, approver, form_filler eller cc. Rækkefølgen styres af order (rollens eller tilsidesættelsen ved afsendelse): alle modtagere i det laveste ufærdige trin handler parallelt, og den næste gruppe starter, når de er færdige. CC-modtagere blokerer aldrig rækkefølgen.

Observatører

En observatør følger en kuvert uden at underskrive: en leder, en advokatsekretær, kundeansvarlig hos kunden. Observatører er ikke modtagere. De har ingen rolle og ingen tur, blokerer eller fuldfører aldrig noget og vises aldrig på certifikatets liste over underskrivere.

Når kuverten sendes (eller når du tilføjer dem senere med POST /v1/envelopes/{id}/viewers), får hver observatør en e-mail med dit brand og et link til en skrivebeskyttet statusside: kuvertens titel, afsenderen, hvert trin med modtagernes navne, roller, status og tidsstempler, opdateret live, mens folk underskriver. Modtagernes e-mailadresser vises ikke.
Observatører får en ny e-mail, når kuverten fuldføres, afvises eller annulleres, og efter hver underskrift, hvis notifyOnSignature er true (slået fra som standard).
Dokumentet er kun på siden, når du angiver viewerDocumentAccess: true (Team-planen og op): originalen, mens kuverten er i gang, og den forseglede PDF, når den er forseglet. Ellers ser observatører kun status.
DELETE /v1/envelopes/{id}/viewers/{viewer} tilbagekalder en observatør: alle links, vedkommende har fået, holder straks op med at virke.
Links er personlige adgangs-URL’er. Kun en SHA-256 af hvert linktoken gemmes. Et link virker, indtil kuverten udløber (højst 90 dage), i 30 dage efter at kuverten er afsluttet, og aldrig efter at observatøren er tilbagekaldt.
Tilføjelser, åbninger (første visning af siden og af dokumentet) og tilbagekaldelser registreres i revisionssporet som viewer.added, viewer.viewed, viewer.document_viewed og viewer.revoked og dermed på certifikatet.

Svarene for enkelte kuverter (opret, hent, annullér) viser dem:

{
  "viewers": [
    {
      "id": "vwr_2Hc8sQ1nVt",
      "name": "Alex Chen",
      "email": "alex@acme.dev",
      "notifyOnSignature": true,
      "status": "active",
      "invitedAt": "2026-10-13T13:58:04.512Z",
      "firstViewedAt": "2026-10-13T14:05:41.090Z",
      "lastViewedAt": "2026-10-13T15:12:09.337Z",
      "revokedAt": null,
      "createdAt": "2026-10-13T13:58:04.512Z"
    }
  ],
  "viewerDocumentAccess": false
}

Antallet af observatører pr. kuvert afhænger af planen (Free 1, Pay-as-you-go 2, Team 5, Business 20, Platform ubegrænset); CC-modtagere tæller ikke med. Tilbagekaldte observatører frigiver deres plads.

Dokumenter

GET /v1/envelopes/{id}/document?version=… downloader en PDF med dens SHA-256 i x-document-sha256:

`version`	Fil
`original` (standard)	Det renderede dokument, som det blev sendt til underskrift
`sealed`	Den endelige PDF: værdierne indbrændt, fuldførelsescertifikatet tilføjet, dokumenttidsstempel. Efter `envelope.sealed`
`certificate`	Fuldførelsescertifikatet alene

Kuvertens documentHash er SHA-256 af originalen og sealedDocumentHash den for den forseglede fil; det er dem, verificeringen slår op.

Revisionsspor

Hver handling er en hændelse i en hashkæde pr. kuvert: hash = SHA-256(prevHash ‖ canonical JSON of the event), hvor den første prevHash er 64 nuller. GET /v1/envelopes/{id}/events returnerer hændelserne og tjekker kæden:

{
  "data": [
    {
      "id": "evt_…",
      "envelope": "env_8Gm2kQ4rT1",
      "seq": 1,
      "type": "envelope.created",
      "createdAt": "2026-10-13T13:58:04.512Z",
      "recipient": null,
      "actor": { "kind": "api_key", "id": "…", "name": null, "email": null },
      "ip": "203.0.113.7",
      "userAgent": null,
      "data": { "template": "tpl_…", "templateVersion": 3, "documentHash": "9f2c…" },
      "hash": "4b1d…",
      "prevHash": "0000000000000000000000000000000000000000000000000000000000000000"
    }
  ],
  "chain": { "valid": true, "brokenAt": null }
}

Ud over webhook-hændelsestyperne har sporet poster, der kun findes i revisionssporet, f.eks. session.created, recipient.verified, recipient.reminded og observatørhændelserne (aktørtype viewer, når en observatør åbner sin side).

Til livestatus i en brugerflade er GET /v1/envelopes/{id}/events/stream en strøm af server-sent events: hver rammes hændelsesnavn er hændelsens type og dens id seq; forbind igen med Last-Event-ID for at fortsætte.

Visning af lister

GET /v1/envelopes filtrerer på status, seal, template og q (fritekst i modtagernes navne og e-mailadresser, externalId og kuvertens id). Som alle lister pagineres den med en cursor:

{ "data": [ … ], "hasMore": true, "nextCursor": "…" }

Send nextCursor tilbage som cursor; limit er 1 til 100 (standard 20).