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:

1. pending - The envelope is created. The recipient has been registered but not yet notified.
2. sent - The envelope starts processing and the invitation email is sent.
3. 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.