Konvolutter og mottakere

En konvolutt er én kontrakt på vei til å bli signert: en malversjon rendret med variablene dine, mottakerne som skal handle på den, og bevisene for alt som skjer. Opprett en med POST /v1/envelopes.

Opprette en konvolutt

Felt	Type	Merknader
`template`	`tpl_…`	Obligatorisk
`version`	tall eller `"latest"`	Standard `latest`; løses opp og låses ved opprettelse. Må være publisert
`variables`	objekt	Valideres mot versjonens JSON Schema
`recipients`	matrise	Én per rolle (`role`, `name`, `email`; valgfritt `externalUserId`, `verification`, `fields` forhåndsutfylt etter felt-ID, `order` for å endre signeringsrekkefølgen)
`subject`, `message`	streng	Brukes i signeringse-postene og vises på signeringssiden
`delivery`	`email` · `embedded` · `none`	Standard `email`
`expiresAt`	RFC 3339	Må være i fremtiden; konvolutten utløper da, og signerings- og observatørlenker slutter å virke
`cc`	matrise	Ekstra CC-mottakere (`name`, `email`) i tillegg til malens CC-roller; opptil 50
`viewers`	matrise	Personer som følger konvolutten uten å signere (`name`, `email`, valgfritt `notifyOnSignature`); antallet per konvolutt er begrenset etter plan
`viewerDocumentAccess`	boolsk	La observatører åpne dokumentet på statussiden sin. Standard `false` (bare status); Team-planen og høyere
`reminders`	objekt	`{ "enabled": false }` slår av påminnelser; `{ "enabled": true, "intervalHours": 24 }` endrer intervallet (1 til 720)
`externalId`	streng	Din egen ID, opptil 200 tegn
`dedupeOn`	`"external_id"`	Returner den eksisterende konvolutten med denne `externalId` i stedet for å opprette en ny
`metadata`	objekt med strenger	Opptil 500 tegn per verdi; returneres på konvolutten og i webhooks

Hver mottaker må ha en rolle fra versjonen; hver rolle som ikke er CC, må ha nøyaktig én mottaker. Feil rapporteres samlet, med pekere som /recipients/1/role eller /recipients/0/fields/start_date.

Svar: 201 med konvolutten og en Location-header; 200 med den eksisterende konvolutten og x-deduplicated: true når dedupeOn fant et treff; 200 med et sammendrag av testkjøringen for ?dry_run=true; 402 når et Free-arbeidsområde har brukt opp de inkluderte konvoluttene; 403 plan-upgrade-required når observatørene overstiger det planen tillater, eller viewerDocumentAccess ikke er med i planen (Planer og grenser). Testkjøringer kontrollerer også plangrensene.

Alle felt som er lagt til etter den første utgivelsen, er valgfrie: en forespørsel uten dem oppfører seg nøyaktig som før.

Valg ved sending

Malen definerer hvem som signerer i hvilken rekkefølge. For én enkelt konvolutt kan du endre dette uten å røre malen:

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

Rekkefølge: recipients[].order er steget mottakeren signerer i; mottakere med samme tall signerer samtidig. Uten den gjelder rollens order fra malen. Rekkefølger er positive heltall; CC-roller kan ikke gis en rekkefølge; hver rolle må fortsatt ha sin mottaker (slik at malens felt beholder sin signatar); minst én mottaker må signere. Hendelsen envelope.created registrerer routingOverridden: true.
CC: ekstra CC-mottakere får e-posten med det fullførte dokumentet og signerer aldri. De vises i recipients med kind: "cc" og rollen _cc.
Påminnelser: den som har tur, får en påminnelse hver intervalHours (standard: installasjonens REMINDER_INTERVAL_HOURS, 72), høyst tre ganger; enabled: false sender ingen. Påminnelser gjelder for levering med email.
Autentisering av signatarer angis per mottaker: verification overstyrer rollens metode. none (bare den unike signeringslenken, standard for roller som ikke angir noe) og email_otp (lenken pluss en kode på e-post) er tilgjengelige i dag; passkey og id_check avvises fordi de ikke er tilgjengelige ennå. Se verifisering av signatarer.
Språk: locale på en mottaker, CC eller observatør (eller på konvolutten, for alle som ikke har sin egen) angir språket for signeringssiden og e-postene deres, ett av de 50 signeringsspråkene. Uten den følger signeringssiden nettleseren, og e-postene er på engelsk.

Sendeskjermen i dashbordet har de samme valgene: flytt steg tidligere eller senere, kryss av for Signer samtidig, legg til CC-er og observatører, velg autentisering (Bare e-postlenke eller E-postlenke + kode) og språk for hver signatar, og angi en utløpsdato og en plan for påminnelser.

Levering

email: hver mottaker får på e-post en lenke til den hostede signeringssiden når det er deres tur. Mottakere som ikke har signert, får en påminnelse med noen dagers mellomrom (opptil tre), og alle får en e-post når konvolutten er fullført.
embedded: ingen e-post til signatarer. Opprett en signeringsøkt når signataren er i produktet ditt. Observatører får fortsatt statuslenken sin på e-post.
none: ingen e-post i det hele tatt (heller ikke til observatører); bruk dette når du leverer lenkene selv (hostede økter).

POST /v1/envelopes/{id}/recipients/{recipient}/resend sender en ny lenke på e-post til en mottaker som har tur (høyst én gang i minuttet).

Livsløp

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

`status`	Betydning
`rendering`	Klargjøres
`sent`	Underveis: mottakerne signerer i rutingrekkefølge
`completed`	Alle mottakerne er ferdige. Forseglingen starter
`declined`	En mottaker avslo; konvolutten avsluttes
`voided`	Du annullerte den (`{ "reason": "…" }`); åpne signeringsøkter slutter å virke
`expired`	`expiresAt` passerte før fullføring

seal følger den forseglede PDF-en: not_started, pending (fullført, forsegles), sealed eller failed. Forseglingen blokkerer aldri fullføringen: konvolutten fullføres først og forsegles rett etterpå.

Mottakere og ruting

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

Mottakerens status er pending (ikke deres tur ennå), sent, viewed, completed eller declined, og kind er rollens signer, approver, form_filler eller cc. Rutingen følger order (rollens, eller overstyringen ved sending): alle mottakere i den laveste uferdige rekkefølgen handler parallelt, og neste gruppe starter når de er ferdige. CC-mottakere blokkerer aldri rutingen.

Observatører

En observatør følger en konvolutt uten å signere: en leder, en juridisk assistent, kontoansvarlig hos kunden. Observatører er ikke mottakere. De har ingen rolle og ingen tur, blokkerer eller fullfører aldri noe og vises aldri i sertifikatets liste over signatarer.

Når konvolutten sendes (eller når du legger dem til senere med POST /v1/envelopes/{id}/viewers), får hver observatør en e-post med merkevareprofil og en lenke til en skrivebeskyttet statusside: konvoluttens tittel, avsenderen, hvert steg med mottakernes navn, roller, status og tidsstempler, oppdatert fortløpende mens folk signerer. Mottakernes e-postadresser vises ikke.
Observatører får en ny e-post når konvolutten er fullført, avslått eller annullert, og etter hver signatur hvis notifyOnSignature er true (standard av).
Dokumentet vises bare på siden når du angir viewerDocumentAccess: true (Team-planen og høyere): originalen mens den er underveis, den forseglede PDF-en når den er forseglet. Ellers ser observatørene bare statusen.
DELETE /v1/envelopes/{id}/viewers/{viewer} tilbakekaller en observatør: alle lenker de har fått, slutter å virke umiddelbart.
Lenkene er personlige kapabilitets-URL-er. Bare en SHA-256 av hvert lenketoken lagres. En lenke virker til konvolutten utløper (høyst 90 dager), i 30 dager etter at konvolutten ble avsluttet, og aldri etter at observatøren er tilbakekalt.
Å legge til, åpne (første visning av siden og av dokumentet) og tilbakekalle registreres i revisjonssporet som viewer.added, viewer.viewed, viewer.document_viewed og viewer.revoked, og dermed også på sertifikatet.

Svarene for én enkelt konvolutt (opprett, hent, annuller) lister dem opp:

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

Antall observatører per konvolutt avhenger av planen (Free 1, Pay-as-you-go 2, Team 5, Business 20, Platform ubegrenset); CC-mottakere teller ikke. Tilbakekalte observatører frigjør plassen sin.

Dokumenter

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

`version`	Fil
`original` (standard)	Det rendrede dokumentet slik det ble sendt til signering
`sealed`	Den endelige PDF-en: verdiene flatet ut, fullføringssertifikatet lagt til, dokumenttidsstempel. Etter `envelope.sealed`
`certificate`	Fullføringssertifikatet alene

Konvoluttens documentHash er SHA-256 av originalen, og sealedDocumentHash er SHA-256 av den forseglede filen; det er disse verifiseringen slår opp.

Revisjonsspor

Hver handling er en hendelse i en hashkjede per konvolutt: hash = SHA-256(prevHash ‖ canonical JSON of the event), der den første prevHash er 64 nuller. GET /v1/envelopes/{id}/events returnerer hendelsene og kontrollerer kjeden:

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

I tillegg til hendelsestypene for webhooks har sporet oppføringer som bare finnes i revisjonen, for eksempel session.created, recipient.verified, recipient.reminded og observatørhendelsene (aktørtypen viewer når en observatør åpner siden sin).

For direkte status i et brukergrensesnitt er GET /v1/envelopes/{id}/events/stream en strøm av server-sent events: hver rammes hendelsesnavn er hendelsens type og ID-en er seq; koble til på nytt med Last-Event-ID for å fortsette.

Liste opp

GET /v1/envelopes filtrerer på status, seal, template og q (fritekst i mottakernes navn og e-postadresser, externalId og konvolutt-ID-en). Som alle lister er den paginert med markør:

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

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