Enveloppen & ontvangers

Een envelop is één contract op weg naar ondertekening: een sjabloonversie gerenderd met uw variabelen, de ontvangers die ermee aan de slag gaan en het bewijs van alles wat er gebeurt. U maakt er een aan met POST /v1/envelopes.

Een envelop aanmaken

Veld	Type	Opmerkingen
`template`	`tpl_…`	Verplicht
`version`	getal of `"latest"`	Standaard `latest`; wordt bij het aanmaken bepaald en vastgelegd. Moet gepubliceerd zijn
`variables`	object	Gevalideerd tegen het JSON Schema van de versie
`recipients`	array	Eén per rol (`role`, `name`, `email`; optioneel `externalUserId`, `verification`, `fields` om vooraf in te vullen per veld-id, `order` om de ondertekenvolgorde te wijzigen)
`subject`, `message`	string	Gebruikt in de ondertekeningsmails en getoond op de ondertekeningspagina
`delivery`	`email` · `embedded` · `none`	Standaard `email`
`expiresAt`	RFC 3339	Moet in de toekomst liggen; de envelop verloopt dan en ondertekenings- en meekijklinks werken niet meer
`cc`	array	Extra CC-ontvangers (`name`, `email`) naast de CC-rollen van het sjabloon; maximaal 50
`viewers`	array	Mensen die de envelop volgen zonder te ondertekenen (`name`, `email`, optioneel `notifyOnSignature`); aantal per envelop beperkt door het abonnement
`viewerDocumentAccess`	boolean	Laat meekijkers het document openen op hun statuspagina. Standaard `false` (alleen status); vanaf het Team-abonnement
`reminders`	object	`{ "enabled": false }` zet herinneringen uit; `{ "enabled": true, "intervalHours": 24 }` wijzigt het interval (1 tot 720)
`externalId`	string	Uw eigen id, maximaal 200 tekens
`dedupeOn`	`"external_id"`	Geeft de bestaande envelop met deze `externalId` terug in plaats van een nieuwe aan te maken
`metadata`	object met strings	Maximaal 500 tekens per waarde; teruggegeven bij de envelop en in webhooks

Elke ontvanger heeft een rol van de versie nodig; elke niet-CC-rol heeft precies één ontvanger nodig. Fouten worden samen gemeld, met pointers zoals /recipients/1/role of /recipients/0/fields/start_date.

Antwoorden: 201 met de envelop en een Location-header; 200 met de bestaande envelop en x-deduplicated: true wanneer dedupeOn overeenkwam; 200 met een samenvatting van de proefrun bij ?dry_run=true; 402 wanneer een Free-workspace de inbegrepen enveloppen heeft verbruikt; 403 plan-upgrade-required wanneer het aantal meekijkers boven wat het abonnement toestaat uitkomt of viewerDocumentAccess niet in het abonnement zit (Abonnementen & limieten). Ook proefruns controleren de limieten van het abonnement.

Elk veld dat na de eerste release is toegevoegd, is optioneel: een request zonder die velden gedraagt zich precies zoals voorheen.

Opties bij verzending

Het sjabloon bepaalt wie in welke volgorde ondertekent. Voor één envelop kunt u dat wijzigen zonder het sjabloon aan te passen:

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

Volgorde: recipients[].order is de stap waarin de ontvanger ondertekent; ontvangers met hetzelfde nummer ondertekenen tegelijk. Zonder dit veld geldt de order van de rol uit het sjabloon. Volgordes zijn positieve gehele getallen; CC-rollen krijgen geen volgorde; elke rol heeft nog steeds een ontvanger nodig (zodat de velden van het sjabloon hun ondertekenaar houden); minstens één ontvanger moet ondertekenen. Het event envelope.created legt routingOverridden: true vast.
CC: extra CC-ontvangers krijgen de e-mail met het voltooide document en ondertekenen nooit. Ze staan in recipients met kind: "cc" en de rol _cc.
Herinneringen: wie aan de beurt is, krijgt elke intervalHours een herinnering (standaard: de REMINDER_INTERVAL_HOURS van de deployment, 72), maximaal drie keer; met enabled: false worden er geen verstuurd. Herinneringen gelden voor bezorging via email.
Authenticatie van de ondertekenaar is per ontvanger: verification overschrijft de methode van de rol. Beschikbaar zijn nu none (alleen de unieke ondertekeningslink, de standaard voor rollen die zelf geen methode instellen) en email_otp (de link plus een code per e-mail); passkey en id_check worden geweigerd omdat ze nog niet beschikbaar zijn. Zie verificatie van de ondertekenaar.
Taal: locale bij een ontvanger, CC of meekijker (of bij de envelop, voor iedereen zonder eigen taal) bepaalt de taal van de ondertekeningspagina en de e-mails, een van de 50 ondertekeningstalen. Zonder dit veld volgt de ondertekeningspagina de browser en zijn e-mails in het Engels.

Het verzendscherm in het dashboard biedt dezelfde opties: stappen eerder of later zetten, Tegelijk ondertekenen aanvinken, CC’s en meekijkers toevoegen, per ondertekenaar de authenticatie (Alleen e-maillink of E-maillink + code) en de taal kiezen, en een vervaldatum en een herinneringsschema instellen.

Bezorging

email: elke ontvanger krijgt een link naar de gehoste ondertekeningspagina per e-mail zodra die aan de beurt is. Ontvangers die nog niet hebben ondertekend, krijgen om de paar dagen een herinnering (maximaal drie), en iedereen krijgt een e-mail wanneer de envelop is voltooid.
embedded: geen e-mail aan ondertekenaars. Maak een ondertekeningssessie aan wanneer de ondertekenaar in uw product is. Meekijkers krijgen hun statuslink nog wel per e-mail.
none: helemaal geen e-mail (ook niet aan meekijkers); gebruik dit wanneer u de links zelf bezorgt (gehoste sessies).

POST /v1/envelopes/{id}/recipients/{recipient}/resend mailt een nieuwe link naar een ontvanger die aan de beurt is (hoogstens één keer per minuut).

Levenscyclus

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

`status`	Betekenis
`rendering`	Wordt voorbereid
`sent`	Bezig: ontvangers ondertekenen in de routeringsvolgorde
`completed`	Alle ontvangers zijn klaar. Het verzegelen begint
`declined`	Een ontvanger heeft geweigerd; de envelop wordt beëindigd
`voided`	U hebt de envelop ingetrokken (`{ "reason": "…" }`); open ondertekeningssessies werken niet meer
`expired`	`expiresAt` is verstreken vóór voltooiing

seal volgt de verzegelde pdf: not_started, pending (voltooid, wordt verzegeld), sealed of failed. Verzegelen blokkeert de voltooiing nooit: de envelop wordt eerst voltooid en direct daarna verzegeld.

Ontvangers en routering

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

De status van een ontvanger is pending (nog niet aan de beurt), sent, viewed, completed of declined, en kind is die van de rol: signer, approver, form_filler of cc. De routering volgt order (die van de rol of de overschrijving bij verzending): alle ontvangers van de laagste nog niet afgeronde volgorde handelen parallel, en de volgende groep begint wanneer zij klaar zijn. CC-ontvangers houden de routering nooit op.

Meekijkers

Een meekijker volgt een envelop zonder te ondertekenen: een manager, een juridisch medewerker, de accounteigenaar aan de kant van de klant. Meekijkers zijn geen ontvangers. Ze hebben geen rol en geen beurt, blokkeren of voltooien nooit iets en staan nooit in de lijst met ondertekenaars op het certificaat.

Wanneer de envelop wordt verstuurd (of wanneer u ze later toevoegt met POST /v1/envelopes/{id}/viewers), krijgt elke meekijker een e-mail in uw huisstijl met een link naar een alleen-lezen statuspagina: de titel van de envelop, de afzender, elke stap met de namen, rollen, status en tijdstippen van de ontvangers, live bijgewerkt terwijl mensen ondertekenen. E-mailadressen van ontvangers worden niet getoond.
Meekijkers krijgen opnieuw een e-mail wanneer de envelop is voltooid, geweigerd of ingetrokken, en na elke handtekening als notifyOnSignature op true staat (standaard uit).
Het document staat alleen op de pagina als u viewerDocumentAccess: true instelt (vanaf het Team-abonnement): het origineel zolang de envelop loopt, de verzegelde pdf zodra die verzegeld is. Anders zien meekijkers alleen de status.
DELETE /v1/envelopes/{id}/viewers/{viewer} trekt een meekijker in: alle links die naar die persoon zijn gestuurd, werken direct niet meer.
Links zijn persoonlijke capability-URL’s. Van elk linktoken wordt alleen een SHA-256 opgeslagen. Een link werkt tot de envelop verloopt (maximaal 90 dagen), tot 30 dagen nadat de envelop is afgerond, en nooit meer zodra de meekijker is ingetrokken.
Toevoegen, openen (eerste weergave van de pagina en van het document) en intrekken worden in de audittrail vastgelegd als viewer.added, viewer.viewed, viewer.document_viewed en viewer.revoked, en dus ook op het certificaat.

De antwoorden voor één envelop (aanmaken, opvragen, intrekken) geven ze weer:

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

Het aantal meekijkers per envelop hangt af van het abonnement (Free 1, Pay-as-you-go 2, Team 5, Business 20, Platform onbeperkt); CC-ontvangers tellen niet mee. Ingetrokken meekijkers maken hun plaats vrij.

Documenten

GET /v1/envelopes/{id}/document?version=… downloadt een pdf, met de SHA-256 ervan in x-document-sha256:

`version`	Bestand
`original` (standaard)	Het gerenderde document zoals het ter ondertekening is verstuurd
`sealed`	De definitieve pdf: waarden afgevlakt, voltooiingscertificaat toegevoegd, documenttijdstempel. Na `envelope.sealed`
`certificate`	Alleen het voltooiingscertificaat

De documentHash van de envelop is de SHA-256 van het origineel en sealedDocumentHash die van het verzegelde bestand; daarop zoekt verificatie.

Audittrail

Elke actie is een event in een hashketen per envelop: hash = SHA-256(prevHash ‖ canonical JSON of the event), waarbij de eerste prevHash uit 64 nullen bestaat. GET /v1/envelopes/{id}/events geeft de events terug en controleert de keten:

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

Naast de webhook-eventtypes bevat de audittrail vermeldingen die alleen voor de audit zijn, zoals session.created, recipient.verified, recipient.reminded en de events van meekijkers (actorsoort viewer wanneer een meekijker de eigen pagina opent).

Voor live status in een UI is GET /v1/envelopes/{id}/events/stream een server-sent-eventstream: de eventnaam van elk frame is het type van het event en het id is de seq; maak opnieuw verbinding met Last-Event-ID om verder te gaan.

Lijsten

GET /v1/envelopes filtert op status, seal, template en q (vrije tekst in namen en e-mailadressen van ontvangers, externalId en het envelop-id). Zoals elke lijst is deze met een cursor gepagineerd:

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

Geef nextCursor terug als cursor; limit is 1 tot 100 (standaard 20).