Document Status & Lifecycle

Every ZipZign document moves through a predictable series of statuses. Webhooks fire at each transition.

All status codes

Status	Description
`created`	Document just created, PDF is being rendered
`draft`	Document created in draft mode, emails not yet sent
`hosted`	`readable` document — PDF ready, no further action needed
`awaiting_signatures`	Emails sent to signers, waiting for all to sign
`all_signed`	All signers have signed; if no payment, transitions to `complete`
`awaiting_payment`	Payment link sent, waiting for payer
`paid`	Payment received
`complete`	Document fully finalized — signed and/or paid
`error`	An error occurred during processing
`deleted`	Document has been deleted

Status paths by document type

readable:              created → hosted
signable:              created → awaiting_signatures → all_signed → complete
payable:               created → awaiting_payment → paid → complete
signable + payment:    created → awaiting_signatures → all_signed → awaiting_payment → paid → complete
draft:                 draft → [above paths after /send]

Checking document status

curl https://zipzign.com/api/documents/doc_abc123 \
  -H "Authorization: Bearer YOUR_API_KEY"

{
  "id": "doc_abc123",
  "status": "awaiting_signatures",
  "signers": [
    { "id": "sgn_1", "name": "Alice", "status": "signed", "signedAt": "2026-04-15T14:00:00Z" },
    { "id": "sgn_2", "name": "Bob", "status": "pending" }
  ]
}

Signer statuses

Status	Meaning
`pending`	Invitation sent, not yet signed
`viewed`	Signer opened the signing page
`signed`	Signer completed signing

Webhooks for status changes

ZipZign fires webhooks at each status change. The document.status_changed event fires on every transition. Type-specific events also fire:

document.signed — a signer signed
document.paid — payment received
document.completed — document finalized

See Webhooks Setup & Events for full details.

Error handling

If a document reaches error status, the GET /api/documents/:id response includes an errorMessage field with details.

Updated on: 16/04/2026

Was this article helpful?

Thank you!