Concepts

A tour of the objects the API works with. The API and the web app use the same vocabulary — an envelope is an envelope in both.

Envelope

An envelope is the unit of work: one or more documents, one or more signers, and the rules that bind them. It always lives in a vault and always has an owner, who receives the notifications about it.

An envelope can be created empty; the "at least one document and one signer" rule is enforced at publish, not at create.

Field	Notes
`vaultId`	Required. There is no default vault — create one first.
`name`	Required, 2–200 characters.
`language`	Required. `EnUs`, `PtBr`, `EsEs`, `FrFr`, `DeDe`, `ItIt`. Drives every message the signer sees.
`jurisdictionCountryCode`	Required. ISO 3166-1 alpha-2, e.g. `BR`, `US`. Selects the legal framework. Can only be changed while the envelope is `Draft`.
`publicDescription`	Visible to signers.
`privateDescription`	Internal only. A good place to keep your own reference id.
`message`	Included in the invitation email.
`signInOrder`	When true, signers are released one at a time, in the order you send them.
`expiresAtUtc`	Stored as a date: the time of day you send is discarded.
`toBePublishedAtUtc`	Not just metadata — setting it moves the envelope to `PublishScheduled` immediately. No future-date check is applied.
`reviewReminder`	Daily reminders while the signer is waiting. See below.
`expirationReminder`	Daily reminders as expiry approaches.
`markupOrientation`	Where the Signater markup is stamped. `None`, `Bottom`, `Top`, `Left`, `Right`.
`isLtvEnabled`	Long-term validation on the certification seal.
`isAiChatForSignersEnabled`	Lets signers ask questions about the document before signing.
`redirectUrl`	Where to send the signer afterwards.

redirectUrl is what closes the loop for an embedded flow. It is a client-side redirect after a short countdown, not a server 302, and it fires on success, rejection and MFA failure alike. Signater appends envelopeId and signerId as query parameters, overwriting those names in any casing if you already used them; your other parameters are preserved.

A PUT is a full replace. Signers, documents and sign marks you leave out of the body are removed. Update is accepted while the envelope is Draft, Hold, PublishScheduled, Cancelled, CancelledBySignerMfaError or Expired — never once it is Published, Signed or Rejected.

Reminders

Reminders are email only, at most one per signer per day, and they stop after seven.

The review ladder runs for eight days from the moment the signer became able to act — not from publication, which matters under signInOrder, and it restarts if you re-invite them. The expiration ladder runs for the eight days before expiresAtUtc. When both are due on the same day, the expiration reminder wins and only one email goes out.

Signers can opt out through a link carried in the automatic reminders. Opting out suppresses reminders only — invitations, one-time codes and lifecycle notifications still reach them.

Document

A document is one file inside an envelope, with its own name (required, 2–200 — the uploaded filename is not inherited), descriptions, and optional language and markupOrientation overrides.

Documents are uploaded first and referenced by the id the upload returns. A document belongs to one envelope; it must belong to your account and not already be attached elsewhere.

Everything that is not already a PDF is converted to one. The upload ceiling is 100 MB for every plan.

Markup is the strip Signater stamps on every page: the Signater mark, the document id, a public verification link and a QR code pointing at it. It carries no signer names, timestamps or hashes. markupOrientation decides where it goes — Left and Right rotate the strip; None leaves the file untouched.

Signer

Field	Notes
`name`	Required, 2–200.
`email`	Optional. Without it, generate a signature link and deliver it yourself.
`phoneIdd` / `phoneNumber`	Country code and number, separately. Required together.
`title`	Free text, e.g. `Lawyer`, `Company Director`.
`documentType`	`GenericIdentification`, `BrazilianCpf`, `BrazilianIdentity`, `Passport`. Required when `documentValue` is present.
`emailCommunicationMode`	Required. `None`, `InvitationOnly` or `Full`.
`smsCommunicationMode`	Required. Same values.
`whatsAppCommunicationMode`	Required. Same values.

Signing order is the position in the array you send; there is no index input. The response exposes index so you can read the order back.

Full is required for lifecycle notifications; InvitationOnly sends the invitation and still allows reminders; None sends nothing on that channel. Setting all three to None is the supported "I will deliver the link myself" path — the envelope owner is emailed to say no channel was available.

See Signer states for what happens to a signer after publication.

Validation factors

Each factor is an independent boolean. Combine as many as the situation calls for; all of them are available on every plan that can reach the API.

Field	What the signer does
`shouldEnforceEmailValidation`	Enters a one-time code sent by email.
`shouldEnforceSmsValidation`	Enters a one-time code sent by SMS.
`shouldEnforceWhatsAppValidation`	Enters a one-time code sent by WhatsApp.
`shouldEnforcePixValidation`	Pays a token Pix charge, proving control of a bank account in their name.
`shouldEnforcePasscodeValidation`	Enters a passcode you set, with an optional `passcodeHint` shown to them.
`shouldEnforceCustomDigitalCertificateValidation`	Signs with their own certificate, such as an eCPF or eCNPJ. Adds a real signature to the PDF — see below.
`shouldEnforceSimpleSelfieValidation`	Takes a selfie at signing time.
`shouldEnforceVerifiedSelfieValidation`	Takes a selfie with active liveness detection.
`shouldEnforceIdentityDocumentCapture`	Photographs an identity document.
`shouldEnforceFaceMatch`	Their selfie is compared against that document. Requires both of the two factors above.

The verified selfie and face match run on Amazon Rekognition — Face Liveness for the challenge, CompareFaces for the comparison. Rekognition Face Liveness has passed iBeta Level 1 and Level 2 presentation-attack-detection testing against ISO/IEC 30107-3; the certification belongs to that service. Liveness confidence and face-match similarity scores are recorded in the audit certificate alongside the images.

Two things are always captured and cannot be switched off: a per-signer access link, and the IP address and derived location of every action. Both appear in the audit certificate.

Pix and WhatsApp validation can be disabled per account, and are disabled by default outside Brazil. Requesting them on an account where they are off returns 403.

Sign marks

A sign mark is a placed element on a page, positioned by documentId, page, x, y, width, height and rotation. Beyond signatures, this is how you collect data during signing.

Type	Purpose
`Signature`	Full signature.
`Rubric`	Initials.
`Invisible`	Not accepted on input; it is what the platform uses internally.
`Text` / `LongText`	Free text, optionally constrained to an email, phone, CPF, CNPJ or CEP.
`Number` / `Currency`	Numeric entry; `Currency` requires an ISO-4217 code.
`Date`	Date entry, in one of four formats.
`Checkbox` / `RadioButton` / `Dropdown`	Choices, configured through `schemaJson`.
`Attachment`	The signer uploads a file, which you download afterwards.
`LegacyRectangleRubric`	Kept for older envelopes.

isRequired defaults to true. Coordinates are clamped to the page, not rejected — a mark placed off the edge is moved, silently. A page the document does not have is a 400.

schemaJson carries the per-type configuration: label, placeholder, description, default value, font, alignment, colour, and the type-specific rules. Dropdown, RadioButton and Currency require it. Options must number between 2 and 50, with no blanks and no case-insensitive duplicates.

Vault

A vault stores envelopes and templates and decides who inside the account can reach them. There is no default vault: a new account has none, and vaultId is required, so create one before your first envelope.

API value	Label in the app	Who can see it
`Account`	Account	Everyone in the account.
`UserAccount`	Personal	Only its owner.
`UserAccountGroup`	Group	Only the users granted access.

Administrators reach every vault in the account regardless of type. See Vaults for the ownership and membership rules, which have sharp edges.

Template

A template is a reusable document skeleton with named fields. Through the public API templates are read and consume only — you create and edit them in the app.

POST /v1/ecm/documents/templates fills the fields and renders a real document you can attach to an envelope like any upload. Fields are matched by alias, so an alias used in several places is filled everywhere at once. A field you leave out is not substituted, and its placeholder is rendered into the PDF as-is — send every field you want filled.

How Signater signs

The signed PDF is built in incremental revisions, each one appended without rewriting what came before.

Every signer who uses their own digital certificate adds one revision: an invisible PAdES-BES approval signature in a field named for that signer, carrying their name and the moment they confirmed, timestamped.

Signater then closes the document with one certification seal: a PAdES-B-LT signature at DocMDP level P=1 — no changes allowed. It is the last revision, and it covers everything before it.

So a document signed by three people, none of whom brought a certificate, carries one signature. If two of them used their own certificates, it carries three: their two, then the seal.

Visible signatures, initials and form fields are page content, not signatures. They are covered by the seal like the rest of the document.

The seal is timestamped by Signater's own RFC-3161 authority, and the timestamp's real metadata — trusted time, serial, policy, authority — is read back out of the finished file rather than assumed. If the timestamp service is unreachable the document is still sealed, without one, and the degradation is recorded and alerted rather than failing your request.

With isLtvEnabled, the revocation data for the seal's own chain and the timestamp chain is embedded in the same revision, so the seal stays verifiable after those certificates expire. It is best-effort: when revocation data cannot be gathered the seal is applied without it. A signer's own certificate chain is not covered.

Any change to the document after the seal invalidates it, and validators say so — Adobe Acrobat reports both no changes allowed and, when LTV was applied, that the signature carries its own validation material.

Envelope#

Reminders#

Document#

Signer#

Validation factors#

Sign marks#

Vault#

Template#

How Signater signs#