Skip to main content
POST
What creating an envelope would say about your values, without creating one.

Authorizations

Authorization
string
header
required

Authorization: Bearer vsk_live_…. Chosen over a bespoke X-API-KEY header because every client, proxy and log-redaction rule already knows this one. What a key may DO is its scopes — see x-scopes at the root of this document and x-required-scope on each operation. The scope list is not written here because OpenAPI reserves a requirement’s scope array for oauth2 and openIdConnect and requires it to be empty for an http scheme.

Path Parameters

templateId
string<uuid>
required

The template’s id, as returned by the list endpoint. A template id.

Example:

"01960000-0000-4000-8000-0000000007e1"

Body

application/json

The values and subjects you would send to create, and nothing else.

The values to judge.

values
object[]

Optional. Values to prefill, as triples. Omitted means none. ⚠️ A signature, a date_signed, a signer_name and a signer_email may not be prefilled — they are acts, or they are written by this system.

subjects
object

Optional. WHO THIS ENVELOPE IS ABOUT, as a map from a subject key the template declares to true (on this envelope) or false (not). A field addressed to a subject that is not on the envelope is hidden from the signer and not required.

A subject you do not name takes the template’s own rule: a required subject is on every envelope, and a conditional one is absent unless somebody says otherwise. Omitting subjects altogether opens the same sections as naming nobody — but see the next paragraph, because the two are not the same request. A key the template does not declare is refused, and so is false for a required subject — both invalid_request, and nothing is created.

⚠️ IT SETS WHAT THE DOCUMENT OPENS WITH, NOT WHAT IT MUST STAY. The signer can switch a conditional subject on or off on the signing page, in either direction, and every such change is recorded in the envelope’s audit history.

⚠️ NAME AS true EVERY conditional SUBJECT YOU PREFILL. A value in values for a conditional subject you did not name as present is handled in one of two ways, depending on whether subjects is in the request at all:

  • subjects sent (even {}): the subject is absent — by false, or by the template’s rule when unnamed — so the value contradicts the request and is refused with invalid_request. Nothing is created.
  • subjects omitted: the value is accepted and stored, but the subject is absent by the template’s rule when the envelope is sent, so the prefilled section opens HIDDEN until the signer switches it on.

See Subjects.

Example:

Response

A verdict for every entry of values, in the order sent, and ok saying whether create would accept them all. A refused entry is still a 200: the request was well formed.

The verdicts.

ok
boolean
required

true only when every entry is ok: create would accept these values.

results
object[]
required

One result per entry of values, in the same order.