Recipient – SignatureAPI Docs

A recipient is a person who receives and acts on an envelope. Every envelope must have at least one recipient.

Recipients have four types, each with a different role:

| Type | Description | | ------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------- | | Signer | Reviews documents and adds a signature or initials. Every envelope must have at least one signing recipient. | | Approver | Reviews and approves documents without signing. Approver actions are not recorded in the audit log. | | Preparer | Fills in document fields before signers receive the envelope. Preparer actions are not recorded in the audit log. | | Automatic Signer | The signature is applied automatically by the system. No ceremony, no email. |

Each recipient participates in the envelope through a ceremony, a guided session where they complete their assigned actions. Automatic signers are the exception: they do not access a ceremony; their signature is applied automatically by the system. A recipient’s status tracks their progress through the workflow. See the recipient lifecycle for details on each status and what triggers a transition.

A recipient belongs to an envelope.

Attributes

Show Signer

string

The unique identifier of the recipient. Recipient IDs use the re_ prefix.

envelope_id

string

The unique identifier of the envelope, in UUID format.

type

enum

The type of the recipient. Determines what actions the recipient can perform during the ceremony.

Type	Description
`signer`	Signs documents. Every envelope must have at least one signing recipient.
`approver`	Reviews and approves documents without signing.
`preparer`	Fills in document fields on behalf of another party.
`automatic_signer`	The signature is applied automatically by the system.

For signers, the type is signer.

key

string

A unique identifier you assign to each recipient in the envelope.

Use it to match recipients with the places they should interact with (such as signature fields) and to identify them in events and webhook notifications.

The key must start with a lowercase letter. It can contain lowercase letters, numbers, and underscores. Maximum 32 characters. It must be unique within the envelope.

name

string

The full name of the recipient. Appears in invitation emails and is pre-filled for typed signatures.

string

The email address of the recipient. SignatureAPI emails the ceremony link to this address when the ceremony uses email_link authentication, and the completed deliverable when delivery_type is email.

status

enum

The current status of the recipient in the signing workflow.

Status	Description
`pending`	The envelope has not been sent to the recipient yet. This is the initial status.
`awaiting`	The recipient is waiting for earlier recipients in the routing order to complete.
`sent`	The invitation has been sent to the recipient.
`completed`	The recipient has completed their 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.
`hard_bounced`	The invitation email was permanently undeliverable (for example, an invalid address). Use the Replace endpoint to assign a new recipient.
`failed`	An error occurred and the invitation could not be sent.
`replaced`	This recipient was replaced with a new one via the Replace endpoint.

ceremony

object

The current ceremony for the recipient.

Show Ceremony

authentication

array of authentication object

Show Email Link Authentication

With email link authentication, the recipient receives an email with a direct link to the ceremony. Clicking the link authenticates the recipient and opens the signing session.

type

enum

The type of authentication. Available values: email_link, email_code, and custom.

For email link authentication, this value is email_link.

subject_override

string | null

The custom subject line used for this recipient's invitation email. null if the envelope title is used.

message_override

string | null

The custom message body used for this recipient's invitation email. null if the envelope message is used.

Show Email Code Authentication

With email code authentication, the recipient receives an email from SignatureAPI containing a 9-digit code. The recipient must enter this code to authenticate and access the ceremony.

type

enum

The type of authentication. Available values: email_link, email_code, and custom.

For email code authentication, this value is email_code.

Show Custom Authentication

With custom authentication, your application authenticates the recipient. SignatureAPI provides a ceremony URL that you share or embed in your application to give the recipient access.

type

enum

The type of authentication. Available values: email_link, email_code, and custom.

For custom authentication, this value is custom.

provider

string

The name of your company or application that authenticated the recipient. This value appears in the envelope audit log as the authentication provider.

data

object

Key-value pairs with metadata about the authentication event, such as timestamps, session IDs, and user identifiers. These values appear in the envelope audit log.

The values in data must be sufficient to verify how the recipient was authenticated. You must retain all records needed to prove the recipient's authentication, such as session information. In cases such as legal proceedings, you may need to provide these records to confirm identity.

Review our Terms & Conditions for details.

redirect_url

string | null

An HTTPS URL to redirect the recipient to after the ceremony finishes.

Learn more in Redirect URL.

redirect_delay

integer | null

The delay in seconds before the ceremony redirects to redirect_url (standalone ceremonies) or emits completion events (embedded ceremonies).

Defaults to 3. Allowed range: 0 to 20.

Learn more in Redirect URL.

url_variant

enum

The format of the ceremony URL.

Available options:

standard (default): Full-length URL. Works for most use cases.
short: Shortened URL. Use this when sharing through space-constrained channels such as SMS or push notifications.

embeddable_in

array of strings

Origins allowed to embed this ceremony in an iframe.

These values set the frame-ancestors directive in the ceremony's Content Security Policy (CSP) header. Sources typically take the form of a scheme and host (for example, https://app.example.com). Wildcards are supported (for example, https://*.example.com). For all available options, see the frame-ancestors documentation.

Defaults to an empty list ([]), which means embedding is not allowed. To allow embedding from all origins (not recommended for production), use ["*"].

Only the origin (scheme and host) is used. Paths are ignored.

url

string | null

The URL where the recipient can access the ceremony. You can share this link with the recipient directly or embed it in your application.

This property is null when:

The ceremony uses email_link authentication. SignatureAPI delivers the URL by email in that case.
The ceremony is not active (for example, it is completed, revoked, or declined).

The URL expires 30 days after creation, or when a new ceremony is created for the same recipient.

delivery_type

enum

Controls whether the completed deliverable is automatically emailed to this recipient.

Value	Description
`email`	The completed deliverable is delivered to this recipient by email. This is the default for signers.
`none`	The completed deliverable is not emailed. Your application is responsible for distributing the deliverable.

signature_options

array of enum

The signature methods available to the signer. The first item in the array is shown as the default.

Option	Description
`typed`	The signer types their name. It is pre-filled from the recipient's `name` property.
`drawn`	The signer draws their signature using a mouse, stylus, or touchscreen.

If not specified, both typed and drawn are available, with typed shown first.

completed_at

timestamp

The time at which the recipient completed their required actions on the envelope (for example, signed or approved), in format. Returns null if the recipient has not yet completed.

status_updated_at

timestamp

The time at which the recipient's status last changed, in format. Updates whenever the recipient transitions to a new status.

Show Deprecated Fields

ceremony_creation

enum

deprecated

How the ceremony is created for the recipient.

Available options are automatic and manual. The default is automatic.

This property is deprecated. Use the ceremony object on the recipient when creating an envelope to control ceremony creation. This property will continue to be supported for backwards compatibility.

Show Preparer

string

The unique identifier of the recipient. Recipient IDs use the re_ prefix.

envelope_id

string

The unique identifier of the envelope, in UUID format.

type

enum

The type of the recipient. Determines what actions the recipient can perform during the ceremony.

Type	Description
`signer`	Signs documents. Every envelope must have at least one signing recipient.
`approver`	Reviews and approves documents without signing.
`preparer`	Fills in document fields on behalf of another party.
`automatic_signer`	The signature is applied automatically by the system.

For preparers, the type is preparer.

key

string

A unique identifier you assign to each recipient in the envelope.

Use it to match recipients with the places they should interact with (such as signature fields) and to identify them in events and webhook notifications.

The key must start with a lowercase letter. It can contain lowercase letters, numbers, and underscores. Maximum 32 characters. It must be unique within the envelope.

name

string

The full name of the recipient. Appears in invitation emails and is pre-filled for typed signatures.

string

status

enum

The current status of the recipient in the signing workflow.

Status	Description
`pending`	The envelope has not been sent to the recipient yet. This is the initial status.
`awaiting`	The recipient is waiting for earlier recipients in the routing order to complete.
`sent`	The invitation has been sent to the recipient.
`completed`	The recipient has completed their 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.
`hard_bounced`	The invitation email was permanently undeliverable (for example, an invalid address). Use the Replace endpoint to assign a new recipient.
`failed`	An error occurred and the invitation could not be sent.
`replaced`	This recipient was replaced with a new one via the Replace endpoint.

ceremony

object

The current ceremony for the recipient.

Show Ceremony

authentication

array of authentication object

Show Email Link Authentication

With email link authentication, the recipient receives an email with a direct link to the ceremony. Clicking the link authenticates the recipient and opens the signing session.

type

enum

The type of authentication. Available values: email_link, email_code, and custom.

For email link authentication, this value is email_link.

subject_override

string | null

The custom subject line used for this recipient's invitation email. null if the envelope title is used.

message_override

string | null

The custom message body used for this recipient's invitation email. null if the envelope message is used.

Show Email Code Authentication

With email code authentication, the recipient receives an email from SignatureAPI containing a 9-digit code. The recipient must enter this code to authenticate and access the ceremony.

type

enum

The type of authentication. Available values: email_link, email_code, and custom.

For email code authentication, this value is email_code.

Show Custom Authentication

With custom authentication, your application authenticates the recipient. SignatureAPI provides a ceremony URL that you share or embed in your application to give the recipient access.

type

enum

The type of authentication. Available values: email_link, email_code, and custom.

For custom authentication, this value is custom.

provider

string

The name of your company or application that authenticated the recipient. This value appears in the envelope audit log as the authentication provider.

data

object

Key-value pairs with metadata about the authentication event, such as timestamps, session IDs, and user identifiers. These values appear in the envelope audit log.

Review our Terms & Conditions for details.

redirect_url

string | null

An HTTPS URL to redirect the recipient to after the ceremony finishes.

Learn more in Redirect URL.

redirect_delay

integer | null

The delay in seconds before the ceremony redirects to redirect_url (standalone ceremonies) or emits completion events (embedded ceremonies).

Defaults to 3. Allowed range: 0 to 20.

Learn more in Redirect URL.

url_variant

enum

The format of the ceremony URL.

Available options:

standard (default): Full-length URL. Works for most use cases.
short: Shortened URL. Use this when sharing through space-constrained channels such as SMS or push notifications.

embeddable_in

array of strings

Origins allowed to embed this ceremony in an iframe.

Defaults to an empty list ([]), which means embedding is not allowed. To allow embedding from all origins (not recommended for production), use ["*"].

Only the origin (scheme and host) is used. Paths are ignored.

url

string | null

The URL where the recipient can access the ceremony. You can share this link with the recipient directly or embed it in your application.

This property is null when:

The ceremony uses email_link authentication. SignatureAPI delivers the URL by email in that case.
The ceremony is not active (for example, it is completed, revoked, or declined).

The URL expires 30 days after creation, or when a new ceremony is created for the same recipient.

delivery_type

enum

Controls whether SignatureAPI emails the completed deliverable to the recipient once the envelope is finished.

Value	Description
`email`	The completed deliverable is delivered to this recipient by email.
`none`	The completed deliverable is not emailed. Your application is responsible for distributing the deliverable. This is the default for approvers and preparers.

completed_at

timestamp

The time at which the recipient completed their required actions on the envelope (for example, signed or approved), in format. Returns null if the recipient has not yet completed.

status_updated_at

timestamp

The time at which the recipient's status last changed, in format. Updates whenever the recipient transitions to a new status.

Show Deprecated Fields

ceremony_creation

enum

deprecated

How the ceremony is created for the recipient.

Available options are automatic and manual. The default is automatic.

Show Approver

string

The unique identifier of the recipient. Recipient IDs use the re_ prefix.

envelope_id

string

The unique identifier of the envelope, in UUID format.

type

enum

The type of the recipient. Determines what actions the recipient can perform during the ceremony.

Type	Description
`signer`	Signs documents. Every envelope must have at least one signing recipient.
`approver`	Reviews and approves documents without signing.
`preparer`	Fills in document fields on behalf of another party.
`automatic_signer`	The signature is applied automatically by the system.

For approvers, the type is approver.

key

string

A unique identifier you assign to each recipient in the envelope.

Use it to match recipients with the places they should interact with (such as signature fields) and to identify them in events and webhook notifications.

The key must start with a lowercase letter. It can contain lowercase letters, numbers, and underscores. Maximum 32 characters. It must be unique within the envelope.

name

string

The full name of the recipient. Appears in invitation emails and is pre-filled for typed signatures.

string

status

enum

The current status of the recipient in the signing workflow.

Status	Description
`pending`	The envelope has not been sent to the recipient yet. This is the initial status.
`awaiting`	The recipient is waiting for earlier recipients in the routing order to complete.
`sent`	The invitation has been sent to the recipient.
`completed`	The recipient has completed their 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.
`hard_bounced`	The invitation email was permanently undeliverable (for example, an invalid address). Use the Replace endpoint to assign a new recipient.
`failed`	An error occurred and the invitation could not be sent.
`replaced`	This recipient was replaced with a new one via the Replace endpoint.

ceremony

object

The current ceremony for the recipient.

Show Ceremony

authentication

array of authentication object

Show Email Link Authentication

With email link authentication, the recipient receives an email with a direct link to the ceremony. Clicking the link authenticates the recipient and opens the signing session.

type

enum

The type of authentication. Available values: email_link, email_code, and custom.

For email link authentication, this value is email_link.

subject_override

string | null

The custom subject line used for this recipient's invitation email. null if the envelope title is used.

message_override

string | null

The custom message body used for this recipient's invitation email. null if the envelope message is used.

Show Email Code Authentication

With email code authentication, the recipient receives an email from SignatureAPI containing a 9-digit code. The recipient must enter this code to authenticate and access the ceremony.

type

enum

The type of authentication. Available values: email_link, email_code, and custom.

For email code authentication, this value is email_code.

Show Custom Authentication

With custom authentication, your application authenticates the recipient. SignatureAPI provides a ceremony URL that you share or embed in your application to give the recipient access.

type

enum

The type of authentication. Available values: email_link, email_code, and custom.

For custom authentication, this value is custom.

provider

string

The name of your company or application that authenticated the recipient. This value appears in the envelope audit log as the authentication provider.

data

object

Key-value pairs with metadata about the authentication event, such as timestamps, session IDs, and user identifiers. These values appear in the envelope audit log.

Review our Terms & Conditions for details.

redirect_url

string | null

An HTTPS URL to redirect the recipient to after the ceremony finishes.

Learn more in Redirect URL.

redirect_delay

integer | null

The delay in seconds before the ceremony redirects to redirect_url (standalone ceremonies) or emits completion events (embedded ceremonies).

Defaults to 3. Allowed range: 0 to 20.

Learn more in Redirect URL.

url_variant

enum

The format of the ceremony URL.

Available options:

standard (default): Full-length URL. Works for most use cases.
short: Shortened URL. Use this when sharing through space-constrained channels such as SMS or push notifications.

embeddable_in

array of strings

Origins allowed to embed this ceremony in an iframe.

Defaults to an empty list ([]), which means embedding is not allowed. To allow embedding from all origins (not recommended for production), use ["*"].

Only the origin (scheme and host) is used. Paths are ignored.

url

string | null

The URL where the recipient can access the ceremony. You can share this link with the recipient directly or embed it in your application.

This property is null when:

The ceremony uses email_link authentication. SignatureAPI delivers the URL by email in that case.
The ceremony is not active (for example, it is completed, revoked, or declined).

The URL expires 30 days after creation, or when a new ceremony is created for the same recipient.

delivery_type

enum

Controls whether SignatureAPI emails the completed deliverable to the recipient once the envelope is finished.

Value	Description
`email`	The completed deliverable is delivered to this recipient by email.
`none`	The completed deliverable is not emailed. Your application is responsible for distributing the deliverable. This is the default for approvers and preparers.

completed_at

timestamp

The time at which the recipient completed their required actions on the envelope (for example, signed or approved), in format. Returns null if the recipient has not yet completed.

status_updated_at

timestamp

The time at which the recipient's status last changed, in format. Updates whenever the recipient transitions to a new status.

Show Deprecated Fields

ceremony_creation

enum

deprecated

How the ceremony is created for the recipient.

Available options are automatic and manual. The default is automatic.

Show Automatic Signer

string

The unique identifier of the recipient. Recipient IDs use the re_ prefix.

envelope_id

string

The unique identifier of the envelope, in UUID format.

type

enum

The type of the recipient. Determines what actions the recipient can perform during the ceremony.

Type	Description
`signer`	Signs documents. Every envelope must have at least one signing recipient.
`approver`	Reviews and approves documents without signing.
`preparer`	Fills in document fields on behalf of another party.
`automatic_signer`	The signature is applied automatically by the system.

For automatic signers, the type is automatic_signer.

key

string

A unique identifier you assign to each recipient in the envelope.

Use it to match recipients with the places they should interact with (such as signature fields) and to identify them in events and webhook notifications.

The key must start with a lowercase letter. It can contain lowercase letters, numbers, and underscores. Maximum 32 characters. It must be unique within the envelope.

name

string

The full name of the signer. Appears in the audit log line that records the automatic signature.

signature

object | null

The signature image applied to the document, as supplied at envelope creation. null if no preset signature was supplied.

Show Preset symbol

type

string

The symbol type. Currently only drawn is supported.

url

string

The URL of the PNG upload referenced when the automatic signer was created.

initials

object | null

The initials image applied to the document, as supplied at envelope creation. null if no preset initials were supplied. Same shape as signature.

mandate

string

A short statement explaining why the initiator was authorized to sign on behalf of this person. This string is shown as-is in the audit log. Maximum 500 characters.

status

enum

The current status of the recipient. An automatic signer transitions from pending or awaiting directly to completed once the envelope is released and the signature is applied. See recipient lifecycle.

completed_at

timestamp

The time at which the recipient's signature was applied, in format. Returns null if the recipient has not yet completed.

status_updated_at

timestamp

The time at which the recipient's status last changed, in format.

Automatic signers do not have email, ceremony, delivery_type, or signature_options properties. They do not receive invitations or access a ceremony.