Recipients
Recipient lifecycle
Track recipient status through pending, awaiting, sent, completed, and other states
The status property on a recipient indicates where the recipient is in the signing workflow. Status changes happen automatically as the envelope progresses.
Status reference
| Status | Description |
|---|---|
pending | The envelope has not been sent to the recipient yet. This is the initial status when an envelope is created. |
awaiting | The recipient is waiting for one or more earlier recipients to complete. Applies to sequential routing only. |
sent | The invitation has been sent to the recipient. The recipient has not yet completed their ceremony. |
completed | The recipient has finished all required actions (for example, signed or approved). |
rejected | The recipient declined to complete the envelope. |
soft_bounced | The invitation email was temporarily undeliverable (for example, a full mailbox). You can resend the request using the Resend endpoint. |
hard_bounced | The invitation email was permanently undeliverable (for example, an invalid address). Use the Replace endpoint to assign a different recipient. |
failed | An error prevented the email from being sent. |
replaced | This recipient was replaced by a new one using the Replace endpoint. |
Typical flow
For an envelope with sequential routing and a single signer, the recipient moves through these statuses in order:
pending- The envelope is created. The recipient has been registered but not yet notified.sent- The envelope starts processing and the invitation email is sent.completed- The recipient finishes their ceremony.
When an envelope has multiple recipients with sequential routing, later recipients wait in awaiting status until all earlier recipients complete.
Handling delivery problems
Two statuses indicate email delivery problems:
soft_bounced means the email was temporarily rejected. The recipient’s address may be valid. Use the Resend endpoint to try again.
hard_bounced means the email was permanently rejected. The address is likely invalid. Use the Replace endpoint to assign a new recipient with a valid address.
Monitoring status changes
Listen for recipient events to receive real-time notifications when a recipient’s status changes. You can also poll the Get a recipient endpoint to check the current status at any time.