Core concepts

Documents and recipients

A document (envelope) is one PDF sent to one or more recipients. It moves through a small set of statuses; each recipient has their own status inside it.

Document statuses#

DRAFT ──send──> PENDING ──all signed──> COMPLETED
  │               │
  │               ├── a recipient declines ──> REJECTED
  │               ├── expires_at passes ─────> EXPIRED
  └──── cancel ───┴── cancel ────────────────> CANCELLED

Status	Meaning
`DRAFT`	Created, editable (fields, recipients corrections). Nobody has been emailed.
`PENDING`	Sent; waiting for signers and approvers.
`COMPLETED`	Everyone signed; the sealed PDF is available (`has_signed_pdf: true`).
`REJECTED`	A recipient declined, optionally with a reason.
`EXPIRED`	`expires_at` passed before completion (default 90 days after creation, at most 365).
`CANCELLED`	The sender voided it; signing links stop working.

Every transition emits a webhook event.

Recipient roles#

Role	Behaviour
`SIGNER`	Invited on send, must sign. Needs at least one `SIGNATURE` field.
`APPROVER`	Invited on send, must act before the document completes; counts as a signing party.
`VIEWER`	Listed on the document; not invited to sign.
`CC`	Receives notices (for example cancellation) and the completed copy.
`PREPARER`	Reserved for preparing a document before sending; not invited to sign when the document is sent.

A document needs at least one SIGNER or APPROVER to be sent (422 document_no_signers).

Recipient statuses#

NOT_SENT, SENT, VIEWED, SIGNED, REJECTED, EXPIRED, BOUNCED (the invitation email bounced or was marked as spam), DELEGATED (the recipient handed off signing to someone else; requires allow_delegation).

Signing order#

PARALLEL (default): all signers and approvers are invited at once.
SEQUENTIAL: recipients act one at a time in the order of the recipients array (signing_order_index); the next one is invited when the previous one finishes.

Fields#

Fields are placed with PUT /documents/{id}/fields, which replaces the full set (up to 200) while the document is a draft. Each field has a type, page (from 1), position_x/position_y (0-100, percent from the top-left corner), width/height (1-100, percent of the page), optional recipient_id (must be a recipient of this document, else 422 field_recipient_invalid), required (default true), label, options (for DROPDOWN, up to 50) and show_if ({"field_id": "...", "equals": "..."} to show a field only when another field has a given value).

Type	Filled with
`SIGNATURE`, `INITIALS`	Drawn, typed or uploaded signature image.
`TEXT`, `NUMBER`, `EMAIL`, `DATE`	Typed values, validated by type.
`CHECKBOX`, `DROPDOWN`	Choice; dropdown values must be one of `options`.
`COMPANY`	Company details (tax ID, name, address) filled in one step.

POST /documents/{id}/detect-fields suggests field positions for the uploaded PDF using AI; it returns candidates (with a confidence) and does not save them.

Working with a sent document#

Action	Endpoint	Notes
Read	`GET /documents/{id}`	Recipients, fields, statuses, timestamps.
Remind	`POST /documents/{id}/remind`	`PENDING` only (else `409 document_not_pending`). Emails whoever's turn it is; returns `{reminded, recipients}`. Pending recipients not contacted for 3 days are also reminded automatically once a day.
Resend one invite	`POST /documents/{id}/recipients/{recipient_id}/resend`	`204`.
Correct a recipient	`PATCH /documents/{id}/recipients/{recipient_id}`	Fix `email`, `name` or `phone` while they have not signed (else `409 recipient_not_correctable`). Changing email or phone invalidates the old link; resend afterwards.
Signing link	`GET /documents/{id}/recipients/{recipient_id}/signing-link`	See Signing links.
Cancel	`POST /documents/{id}/cancel`	Body `{"reason": "...", "copy_as_draft": false}`; reason 3-500 characters. `DRAFT`/`PENDING` only (else `409 document_not_cancellable`). Everyone already involved is told why. With `copy_as_draft: true` the response includes `copy_document_id`, a fresh draft to fix and resend.
Audit trail	`GET /documents/{id}/audit`, `/audit.csv`	Every event with actor, IP and metadata.
Signatures	`GET /documents/{id}/signatures`	Who signed, when, from where, with the evidence hash.
Files	`GET /documents/{id}/original.pdf`, `/signed.pdf`	`signed.pdf` falls back to the original until the document is completed.
Delete	`DELETE /documents/{id}`	Soft delete (`204`); organization admins can list the trash (`GET /documents/trash/list`) and restore (`POST /documents/{id}/restore`). Permanent deletion is handled by platform support.

curl -sS -X POST "https://api.sign.yt/v1/documents/$DOC_ID/cancel" \
  -H "Authorization: Bearer $SIGNYT_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"reason": "Wrong rent amount, sending a corrected version", "copy_as_draft": true}' \
  | jq '{status, copy_document_id}'

import os
from signyt import Signyt

client = Signyt(os.environ["SIGNYT_API_KEY"])
doc_id = os.environ["DOC_ID"]

cancelled = client.documents.cancel(doc_id, "Wrong rent amount, sending a corrected version", copy_as_draft=True)
print(cancelled.status)  # CANCELLED

import { Signyt } from "@signyt/sdk";

const client = new Signyt(process.env.SIGNYT_API_KEY!);
const docId = process.env.DOC_ID!;

const cancelled = await client.documents.cancel(docId, "Wrong rent amount, sending a corrected version", true);
console.log(cancelled.status); // CANCELLED

Verification of signers#

verification_type sets how signers prove control of their contact details before signing: NONE, EMAIL_OTP (6-digit code by email), SMS_OTP (code by SMS; each signer needs phone in E.164 and the plan must include SMS), or BOTH_OTP. Organizations with identity verification enabled can also require an ID check (ID_VERIFIED, see Identity verification); each recipient's latest check is returned as recipients[].identity_verification. Whatever happens is recorded in the audit trail; see Verification and evidence.

Metadata#

Attach your own identifiers in metadata at creation (for example a CRM deal ID), up to 4 KB of JSON and 3 levels deep. A few keys used internally by sign.yt (such as template_id, campaign_id, flow_run_id and keys starting with bulk) are reserved and silently dropped.