Envelopes

An envelope is the signing transaction: the documents, the people who act on them, and the fields they fill or sign. You assemble it in draft, then send it to start the flow.

Lifecycle

An envelope moves through these states:

draft — being assembled; add documents, participants and fields.
sent / in_progress / partially_signed — out with participants and collecting signatures.
completed — everyone required has signed.
declined · cancelled · expired — terminal states that end the flow.

The envelope object

Field	Type	Description
`id`	uuid	Unique identifier of the envelope.
`title`	string	Human-readable title.
`message`	string \| null	Optional message shown to participants.
`status`	enum	draft · ready · sent · in_progress · partially_signed · completed · declined · cancelled · expired · failed
`signing_order`	enum	parallel · sequential · mixed (participants sharing an order_index sign together; groups run in sequence).
`allow_delegation`	boolean	Whether signers may hand their turn over to someone else (name + email). Every hand-over is audited. Defaults to false.
`language`	string \| null	Language for participant-facing content.
`jurisdiction`	enum \| null	br, us, or intl — the law invoked for the transaction. intl is the generic/worldwide regime (br is an accepted alias with identical behavior, kept for existing integrations).
`expires_at`	datetime \| null	When the envelope expires (UTC).
`sent_at`	datetime \| null	When it was sent.
`completed_at`	datetime \| null	When every participant finished.
`created_at`	datetime	Creation timestamp (UTC).

Create an envelope

POST /envelopes

Requires the envelopes:write scope. Returns the envelope in draft.

Body parameters

Parameter	Type	Description
`title` required	string	1–255 characters.
`signing_order`	enum	parallel (default) · sequential · mixed.
`allow_delegation`	boolean	Allow signers to delegate their turn. Defaults to false.
`message`	string	Up to 4000 characters.
`expires_in_days`	integer	1–365. Defaults to 30.
`language`	string	e.g. "pt-BR", "en".
`jurisdiction`	enum	br, us, or intl. Defaults to the tenant's jurisdiction (intl for new tenants).
`field_placement`	enum	report (default over the API) — no marks on the document; every signature is recorded on the evidence report attached to the signed package. fields — you position signature fields yourself with POST /envelopes/{id}/fields.

Example

curl -X POST 'https://api.sign.quathos.com/api/v1/envelopes' \
  -H 'Authorization: Bearer $QUATHOS_SIGN_TOKEN' \
  -H 'Content-Type: application/json' \
  -d '{
    "title": "Service Agreement",
    "message": "Please review and sign.",
    "signing_order": "sequential",
    "expires_in_days": 14
  }'

Add a document

POST /envelopes/{id}/documents

Attach a document to the envelope. You can reference a document you already uploaded (see Documents). Requires envelopes:write.

Add participants

POST /envelopes/{id}/participants

Add the people who must act on the envelope. Each participant has a role, an authentication method and a signature modality. Requires envelopes:write.

Body parameters

Parameter	Type	Description
`name` required	string	1–255 characters.
`email` required	string	Participant's email address.
`role`	enum	signatario (default) · aprovador · observador · testemunha.
`order_index`	integer	Signing position (1–999). In sequential order it is the queue position; in mixed order, participants sharing the same value form a group that signs together.
`auth_method`	enum	email (default) · otp_email · otp_sms · cpf · kba · identity_match. Every signer gets a one-time code; cpf, kba and identity_match add a second factor on top of it. "none" is rejected.
`modality`	enum	simples · avancada (default) · qualificada — the signer signs with their own ICP-Brasil digital certificate.
`cpf`	string	Brazilian CPF, required for cpf auth (validated).
`ssn_last4`	string	Last 4 digits of the US SSN.
`phone`	string	Required for otp_sms. International E.164 format with country code (e.g. +5511999990000).

Qualified signatures (ICP-Brasil)

With modality: "qualificada" the signer signs with their own ICP-Brasil digital certificate, provided at the moment of signing — the certificate itself proves identity, so no separate authentication step applies. Qualified participants consume ICP-Brasil credits, a balance separate from regular signature credits: sending an envelope with a qualified participant fails with 402 if that balance is insufficient.

Example

cURL

curl -X POST \
  'https://api.sign.quathos.com/api/v1/envelopes/6b1d.../participants' \
  -H 'Authorization: Bearer $QUATHOS_SIGN_TOKEN' \
  -H 'Content-Type: application/json' \
  -d '{
    "name": "Maria Silva",
    "email": "maria@example.com",
    "role": "signatario",
    "order_index": 1,
    "auth_method": "otp_email",
    "modality": "avancada"
  }'

Add fields (optional)

POST /envelopes/{id}/fields

You usually do not need this

Envelopes created with an API token default to field_placement: "report": nothing is drawn on the document, and each signature is recorded on the evidence report attached to the signed package. Skip straight to Send the envelope. This endpoint is for the case where you want the signature stamped at a specific spot and already know the coordinates — pass field_placement: "fields" when creating the envelope to enable it.

Place fields where each participant signs or fills in data. Coordinates are normalized to the page: 0 is the left/top edge and 1 the right/bottom. A field may not extend past the page. Requires envelopes:write.

On a report envelope this endpoint returns 409 fields_not_allowed_in_report_placement — accepting a field that would never be stamped would be worse than the error.

Body parameters

Parameter	Type	Description
`participant_id` required	uuid	Who fills or signs this field.
`document_id` required	uuid	Which document the field is placed on.
`page` required	integer	Page number, starting at 1.
`x` required	float	Left position, normalized 0–1.
`y` required	float	Top position, normalized 0–1.
`width` required	float	Width, normalized 0–1.
`height` required	float	Height, normalized 0–1.
`type`	enum	assinatura (default) · rubrica · nome · cpf · cargo · empresa · data · texto · checkbox · numero · calculado · anexo. nome/data/cpf are auto-filled at signing time; anexo asks the signer for a file (PDF/PNG/JPEG, up to 10 MB, hash recorded in the evidence).
`required`	boolean	Whether the field must be filled. Defaults to true.
`condition_field_id`	uuid	Makes the field conditional: it is only shown (and required) based on the state of this checkbox field, which must belong to the same participant.
`condition_trigger`	enum	checked or unchecked — the checkbox state that activates the field. Required together with condition_field_id.
`formula`	string	calculado only: arithmetic over numero fields referenced as {field_id}, e.g. "{a} + {b} * 2". Evaluated server-side at signing.

Example

cURL

curl -X POST \
  'https://api.sign.quathos.com/api/v1/envelopes/6b1d.../fields' \
  -H 'Authorization: Bearer $QUATHOS_SIGN_TOKEN' \
  -H 'Content-Type: application/json' \
  -d '{
    "participant_id": "a1b2...",
    "document_id": "c3d4...",
    "page": 1,
    "x": 0.15, "y": 0.82,
    "width": 0.3, "height": 0.06,
    "type": "assinatura"
  }'

Send the envelope

POST /envelopes/{id}/send

Transition the envelope out of draft and invite the participants. With sequential order, only the first participant is invited; the next is invited as each one completes. Requires the envelopes:send scope.

cURL

curl -X POST \
  'https://api.sign.quathos.com/api/v1/envelopes/6b1d.../send' \
  -H 'Authorization: Bearer $QUATHOS_SIGN_TOKEN'

Estimate the cost first

POST /envelopes/{id}/calculate-cost returns what sending will consume, so you can confirm before committing credits.

Retrieve & list

GET /envelopes/{id}

Returns the full envelope with its documents, participants and fields. Participant CPF and SSN are masked in responses. Requires envelopes:read.

GET /envelopes

Lists your envelopes, most recent first. Requires envelopes:read.

Evidence & dossier

GET /envelopes/{id}/evidence

The evidence report — the chained audit trail for the envelope.

GET /envelopes/{id}/dossier

The probative dossier bundling the signed documents and their evidence. Both require envelopes:read.

Signer attachments

GET /envelopes/{id}/attachments/{field_id}

Downloads the file a signer delivered on an anexo field, via a short-lived signed URL. The file's SHA-256, size and type are part of the signed evidence. Requires envelopes:read.

Cancel

POST /envelopes/{id}/cancel

Cancel an envelope in progress, optionally with a reason. This is terminal. Requires the envelopes:cancel scope.

Previous Going to production Next Templates