Kuvert och mottagare

Ett kuvert är ett avtal på väg att signeras: en mallversion som renderats med dina variabler, de mottagare som ska agera på den och bevisen för allt som händer. Du skapar ett med POST /v1/envelopes.

Skapa ett kuvert

Fält	Typ	Kommentar
`template`	`tpl_…`	Obligatoriskt
`version`	tal eller `"latest"`	Standard `latest`; slås upp och låses när kuvertet skapas. Måste vara publicerad
`variables`	objekt	Valideras mot versionens JSON Schema
`recipients`	array	En per roll (`role`, `name`, `email`; valfritt `externalUserId`, `verification`, `fields` för förifyllning per fält-id, `order` för att ändra signeringsordningen)
`subject`, `message`	sträng	Används i signeringsmejlen och visas på signeringssidan
`delivery`	`email` · `embedded` · `none`	Standard `email`
`expiresAt`	RFC 3339	Måste ligga i framtiden; kuvertet går ut då, och signerings- och observatörslänkar slutar fungera
`cc`	array	Extra CC-mottagare (`name`, `email`) utöver mallens CC-roller; upp till 50
`viewers`	array	Personer som följer kuvertet utan att signera (`name`, `email`, valfritt `notifyOnSignature`); antalet per kuvert begränsas av planen
`viewerDocumentAccess`	boolesk	Låter observatörer öppna dokumentet på sin statussida. Standard `false` (bara status); Team-planen och uppåt
`reminders`	objekt	`{ "enabled": false }` stänger av påminnelser; `{ "enabled": true, "intervalHours": 24 }` ändrar intervallet (1 till 720)
`externalId`	sträng	Ditt eget id, upp till 200 tecken
`dedupeOn`	`"external_id"`	Returnera det befintliga kuvertet med detta `externalId` i stället för att skapa ett till
`metadata`	objekt med strängar	Upp till 500 tecken per värde; returneras på kuvertet och i webhooks

Varje mottagare behöver en roll i versionen; varje roll som inte är CC behöver exakt en mottagare. Fel rapporteras tillsammans, med pekare som /recipients/1/role eller /recipients/0/fields/start_date.

Svar: 201 med kuvertet och en Location-rubrik; 200 med det befintliga kuvertet och x-deduplicated: true när dedupeOn gav träff; 200 med en sammanfattning av testkörningen för ?dry_run=true; 402 när en arbetsyta på Free har förbrukat sina inkluderade kuvert; 403 plan-upgrade-required när observatörerna överskrider planens tilldelning eller viewerDocumentAccess inte ingår i planen (Planer och gränser). Testkörningar kontrollerar också planens gränser.

Alla fält som har lagts till efter den första versionen är valfria: en begäran utan dem fungerar exakt som tidigare.

Alternativ vid utskick

Mallen anger vem som signerar i vilken ordning. För ett enskilt kuvert kan du ändra det utan att röra mallen:

{
  "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"
}

Ordning: recipients[].order är det steg där mottagaren signerar; mottagare med samma nummer signerar samtidigt. Utan det gäller rollens order från mallen. Ordningar är positiva heltal; CC-roller kan inte ordnas; varje roll behöver fortfarande sin mottagare (så att mallens fält behåller sin undertecknare); minst en mottagare måste signera. Händelsen envelope.created registrerar routingOverridden: true.
CC: extra CC-mottagare får mejlet med det slutförda dokumentet och signerar aldrig. De visas i recipients med kind: "cc" och rollen _cc.
Påminnelser: den som står på tur påminns var intervalHours timme (standard: driftmiljöns REMINDER_INTERVAL_HOURS, 72), högst tre gånger; enabled: false skickar inga. Påminnelser gäller leverans via email.
Autentisering av undertecknare anges per mottagare: verification åsidosätter rollens metod. none (enbart den unika signeringslänken, standard för roller som inte anger någon) och email_otp (länken plus en kod via e-post) finns i dag; passkey och id_check avvisas eftersom de inte är tillgängliga än. Se verifiering av undertecknare.
Språk: locale på en mottagare, CC eller observatör (eller på kuvertet, för alla som inte har ett eget) anger språket för personens signeringssida och mejl, ett av de 50 signeringsspråken. Utan det följer signeringssidan webbläsaren och mejlen skickas på engelska.

Utskicksskärmen i instrumentpanelen har samma alternativ: flytta steg tidigare eller senare, markera Signera samtidigt, lägg till CC och observatörer, välj varje undertecknares autentisering (Endast e-postlänk eller E-postlänk + kod) och språk, och ange ett utgångsdatum och ett schema för påminnelser.

Leverans

email: varje mottagare får en länk till den hostade signeringssidan via e-post när det är hens tur. Mottagare som inte har signerat får en påminnelse med några dagars mellanrum (högst tre), och alla får ett mejl när kuvertet slutförs.
embedded: inga mejl till undertecknare. Skapa en signeringssession när undertecknaren är i din produkt. Observatörer får fortfarande sin statuslänk via e-post.
none: inga mejl alls (inte heller till observatörer); använd det när du själv levererar länkarna (hostade sessioner).

POST /v1/envelopes/{id}/recipients/{recipient}/resend mejlar en ny länk till en mottagare som står på tur (högst en gång i minuten).

Livscykel

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

`status`	Betydelse
`rendering`	Förbereds
`sent`	Pågår: mottagarna signerar i dirigeringsordning
`completed`	Alla mottagare är klara. Förseglingen startar
`declined`	En mottagare avböjde; kuvertet avslutas
`voided`	Du makulerade det (`{ "reason": "…" }`); öppna signeringssessioner slutar fungera
`expired`	`expiresAt` passerades innan kuvertet slutfördes

seal följer den förseglade PDF:en: not_started, pending (slutfört, förseglas), sealed eller failed. Förseglingen blockerar aldrig slutförandet: kuvertet slutförs först och förseglas direkt därefter.

Mottagare och dirigering

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

Mottagarens status är pending (inte hens tur än), sent, viewed, completed eller declined, och kind är rollens signer, approver, form_filler eller cc. Dirigeringen sker efter order (rollens, eller åsidosättningen vid utskick): alla mottagare i den lägsta oavslutade ordningen agerar parallellt, och nästa grupp startar när de är klara. CC-mottagare blockerar aldrig dirigeringen.

Observatörer

En observatör följer ett kuvert utan att signera: en chef, en juristassistent, kundansvarig på kundens sida. Observatörer är inte mottagare. De har ingen roll och ingen tur, blockerar eller slutför aldrig något och visas aldrig i certifikatets lista över undertecknare.

När kuvertet skickas (eller när du lägger till dem senare med POST /v1/envelopes/{id}/viewers) får varje observatör ett mejl med ditt varumärke och en länk till en skrivskyddad statussida: kuvertets titel, avsändaren, varje steg med mottagarnas namn, roller, status och tidsstämplar, uppdaterat live medan folk signerar. Mottagarnas e-postadresser visas inte.
Observatörer får ett nytt mejl när kuvertet slutförs, avböjs eller makuleras, och efter varje signatur om notifyOnSignature är true (avstängt som standard).
Dokumentet finns bara på sidan när du anger viewerDocumentAccess: true (Team-planen och uppåt): originalet medan kuvertet pågår, den förseglade PDF:en när det har förseglats. Annars ser observatörer bara status.
DELETE /v1/envelopes/{id}/viewers/{viewer} återkallar en observatör: alla länkar personen har fått slutar fungera omedelbart.
Länkarna är personliga behörighets-URL:er. Bara en SHA-256 av varje länktoken lagras. En länk fungerar tills kuvertet går ut (högst 90 dagar), i 30 dagar efter att kuvertet avslutats, och aldrig efter att observatören har återkallats.
Tillägg, öppningar (första visningen av sidan och av dokumentet) och återkallelser registreras i granskningsloggen som viewer.added, viewer.viewed, viewer.document_viewed och viewer.revoked, och därmed i certifikatet.

Svaren för enskilda kuvert (skapa, hämta, makulera) listar 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
}

Antalet observatörer per kuvert beror på planen (Free 1, Pay-as-you-go 2, Team 5, Business 20, Platform obegränsat); CC-mottagare räknas inte. Återkallade observatörer frigör sin plats.

Dokument

GET /v1/envelopes/{id}/document?version=… laddar ned en PDF, med dess SHA-256 i x-document-sha256:

`version`	Fil
`original` (standard)	Det renderade dokumentet som det skickades för signering
`sealed`	Den slutliga PDF:en: värdena inbrända, slutförandecertifikatet bifogat, dokumenttidsstämpel. Efter `envelope.sealed`
`certificate`	Enbart slutförandecertifikatet

Kuvertets documentHash är SHA-256 för originalet och sealedDocumentHash den för den förseglade filen; det är dem som verifieringen slår upp.

Granskningslogg

Varje åtgärd är en händelse i en hashkedja per kuvert: hash = SHA-256(prevHash ‖ canonical JSON of the event), där den första prevHash är 64 nollor. GET /v1/envelopes/{id}/events returnerar händelserna och kontrollerar kedjan:

{
  "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 }
}

Utöver webhookhändelsetyperna har loggen poster som bara finns i granskningsloggen, till exempel session.created, recipient.verified, recipient.reminded och observatörshändelserna (aktörstyp viewer när en observatör öppnar sin sida).

För livestatus i ett användargränssnitt är GET /v1/envelopes/{id}/events/stream en ström av server-sent events: varje rams händelsenamn är händelsens type och dess id är seq; anslut igen med Last-Event-ID för att fortsätta.

Listning

GET /v1/envelopes filtrerar på status, seal, template och q (fritext över mottagarnas namn och e-postadresser, externalId och kuvertets id). Som alla listor pagineras den med markör:

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

Skicka tillbaka nextCursor som cursor; limit är 1 till 100 (standard 20).