> ## Documentation Index
> Fetch the complete documentation index at: https://signatureapi-daf4ee54.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# Recipient events

> Monitor recipient actions and status changes including signing, bounces, and replacements.

Recipient events track key actions and status changes for recipients within an envelope. This page describes each event type, when it fires, and the additional data included in the payload.

## recipient.released

Fires when a recipient becomes ready to receive an invitation. The recipient status changes to `pending`.

This event fires after all previous recipients in the routing order have completed, or immediately for the first recipient when the envelope starts.

<Accordion title="Example payload">
  ```json JSON theme={null}
  {
      "id": "evt_1a2b3c4d5e6f7g8h9i0j",
      "type": "recipient.released",
      "timestamp": "2025-12-31T23:59:59.999Z",
      "data": {
          "object_id": "re_00ZeZjRaXCgT30n1eBx53N",
          "object_type": "recipient",
          "envelope_id": "e387553d-cbb7-4924-abd8-b2d89699e9b5",
          "envelope_metadata": {
              "deal_id": "50055",
              "deal_owner": "Jane C."
          },
          "recipient_type": "signer",
          "recipient_key": "client"
      }
  }
  ```
</Accordion>

## recipient.sent

Fires when SignatureAPI sends the invitation email to a recipient. The recipient status changes to `sent`.

This event only fires for recipients with `delivery_type` set to `email`.

<Accordion title="Example payload">
  ```json JSON theme={null}
  {
      "id": "evt_2b3c4d5e6f7g8h9i0j1k",
      "type": "recipient.sent",
      "timestamp": "2025-12-31T23:59:59.999Z",
      "data": {
          "object_id": "re_00ZeZjRaXCgT30n1eBx53N",
          "object_type": "recipient",
          "envelope_id": "e387553d-cbb7-4924-abd8-b2d89699e9b5",
          "envelope_metadata": {
              "deal_id": "50055",
              "deal_owner": "Jane C."
          },
          "recipient_type": "signer",
          "recipient_key": "client"
      }
  }
  ```
</Accordion>

## recipient.accessed

Fires when a recipient opens the ceremony URL. To reduce duplicate events, this fires at most once every 60 seconds for the same IP address and user agent combination. The recipient has not yet authenticated at this point.

The `data` object includes the recipient's `ip` address, `user_agent`, and a `session_id`. Use `session_id` to correlate multiple events from the same ceremony session.

<Note>
  Some security platforms access the ceremony URL to prefetch content or scan for threats. These requests can trigger `recipient.accessed` before the intended recipient opens the link. To confirm that the human recipient has accessed the ceremony, use the `recipient.viewed` event instead.
</Note>

<Accordion title="Example payload">
  ```json JSON theme={null}
  {
      "id": "evt_2b3c4d5e6f7g8h9i0j1k",
      "type": "recipient.accessed",
      "timestamp": "2025-12-31T23:59:59.999Z",
      "data": {
          "object_id": "re_00ZeZjRaXCgT30n1eBx53N",
          "object_type": "recipient",
          "envelope_id": "e387553d-cbb7-4924-abd8-b2d89699e9b5",
          "envelope_metadata": {
              "deal_id": "50055",
              "deal_owner": "Jane C."
          },
          "recipient_type": "signer",
          "recipient_key": "client",
          "ip": "123.122.990.22",
          "user_agent": "Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/120.0.0.0 Safari/537.36",
          "session_id": "ses_2X6eHBCL84MDGrLQX0mHI72"
      }
  }
  ```
</Accordion>

## recipient.viewed

Fires after a recipient authenticates and the documents are displayed in the ceremony. This confirms the recipient passed all authentication steps and can view the documents.

The `data` object includes a `session_id`. Use it to correlate multiple events from the same ceremony session.

<Accordion title="Example payload">
  ```json JSON theme={null}
  {
      "id": "evt_2b3c4d5e6f7g8h9i0j1k",
      "type": "recipient.viewed",
      "timestamp": "2025-12-31T23:59:59.999Z",
      "data": {
          "object_id": "re_00ZeZjRaXCgT30n1eBx53N",
          "object_type": "recipient",
          "envelope_id": "e387553d-cbb7-4924-abd8-b2d89699e9b5",
          "envelope_metadata": {
              "deal_id": "50055",
              "deal_owner": "Jane C."
          },
          "recipient_type": "signer",
          "recipient_key": "client",
          "session_id": "ses_2X6eHBCL84MDGrLQX0mHI72"
      }
  }
  ```
</Accordion>

## recipient.completed

Fires when a recipient finishes all required actions in the ceremony. The recipient status changes to `completed`.

For signers, this means they have signed and finalized. For approvers and preparers, this means they have reviewed and submitted their inputs.

The `data` object includes a `session_id`. Use it to correlate multiple events from the same ceremony session.

<Accordion title="Example payload">
  ```json JSON theme={null}
  {
      "id": "evt_3c4d5e6f7g8h9i0j1k2l",
      "type": "recipient.completed",
      "timestamp": "2025-12-31T23:59:59.999Z",
      "data": {
          "object_id": "re_00ZeZjRaXCgT30n1eBx53N",
          "object_type": "recipient",
          "envelope_id": "e387553d-cbb7-4924-abd8-b2d89699e9b5",
          "envelope_metadata": {
              "deal_id": "50055",
              "deal_owner": "Jane C."
          },
          "recipient_type": "signer",
          "recipient_key": "client",
          "session_id": "ses_2X6eHBCL84MDGrLQX0mHI72"
      }
  }
  ```
</Accordion>

## recipient.rejected

Fires when a recipient declines the envelope. When a recipient rejects, the entire envelope is voided.

The `data.reason` property contains the recipient's explanation if they provided one. It is an empty string if no reason was given. The `data` object also includes a `session_id`.

<Accordion title="Example payload">
  ```json JSON theme={null}
  {
      "id": "evt_4d5e6f7g8h9i0j1k2l3m",
      "type": "recipient.rejected",
      "timestamp": "2025-12-31T23:59:59.999Z",
      "data": {
          "object_id": "re_00ZeZjRaXCgT30n1eBx53N",
          "object_type": "recipient",
          "envelope_id": "e387553d-cbb7-4924-abd8-b2d89699e9b5",
          "envelope_metadata": {
              "deal_id": "50055",
              "deal_owner": "Jane C."
          },
          "recipient_type": "signer",
          "recipient_key": "client",
          "reason": "Not the terms we agreed to on June.",
          "session_id": "ses_2X6eHBCL84MDGrLQX0mHI72"
      }
  }
  ```
</Accordion>

## recipient.soft\_bounced

Fires when the invitation email is temporarily undeliverable. The recipient status changes to `soft_bounced`. Common causes include a full mailbox or a temporary server issue.

The `data.detail` property contains the bounce reason from the remote email server. Use the [Resend Request](/docs/api/resources/recipients/resend) endpoint to try delivering the invitation again.

<Accordion title="Example payload">
  ```json JSON theme={null}
  {
      "id": "evt_5e6f7g8h9i0j1k2l3m4n",
      "type": "recipient.soft_bounced",
      "timestamp": "2025-12-31T23:59:59.999Z",
      "data": {
          "object_id": "re_00ZeZjRaXCgT30n1eBx53N",
          "object_type": "recipient",
          "envelope_id": "e387553d-cbb7-4924-abd8-b2d89699e9b5",
          "envelope_metadata": {
              "deal_id": "50055",
              "deal_owner": "Jane C."
          },
          "recipient_type": "signer",
          "recipient_key": "client",
          "detail": "Server 123.122.990.22 responded with: Mailbox Full"
      }
  }
  ```
</Accordion>

## recipient.hard\_bounced

Fires when the invitation email is permanently undeliverable. The recipient status changes to `hard_bounced`. Common causes include an invalid or nonexistent email address.

The `data.detail` property contains the bounce reason from the remote email server. You can view further details, such as SMTP responses, in the Dashboard.

<Note>
  After a hard bounce, you cannot resend to this recipient. Use the [Replace Recipient](/docs/api/resources/recipients/replace) endpoint to assign a new person with a valid email address.
</Note>

<Accordion title="Example payload">
  ```json JSON theme={null}
  {
      "id": "evt_6f7g8h9i0j1k2l3m4n5o",
      "type": "recipient.hard_bounced",
      "timestamp": "2025-12-31T23:59:59.999Z",
      "data": {
          "object_id": "re_00ZeZjRaXCgT30n1eBx53N",
          "object_type": "recipient",
          "envelope_id": "e387553d-cbb7-4924-abd8-b2d89699e9b5",
          "envelope_metadata": {
              "deal_id": "50055",
              "deal_owner": "Jane C."
          },
          "recipient_type": "signer",
          "recipient_key": "client",
          "detail": "Permanent/General, diagnostic code: smtp; 550 5.1.1 As requested: user unknown"
      }
  }
  ```
</Accordion>

## recipient.failed

Fires when an error prevents the invitation from being sent to a recipient. The recipient status changes to `failed`.

The `data.detail` property contains a description of the failure, such as the recipient's email being on a blocklist.

<Note>
  You may need to use the [Replace Recipient](/docs/api/resources/recipients/replace) endpoint to assign a different person.
</Note>

<Accordion title="Example payload">
  ```json JSON theme={null}
  {
      "id": "evt_7g8h9i0j1k2l3m4n5o6p",
      "type": "recipient.failed",
      "timestamp": "2025-12-31T23:59:59.999Z",
      "data": {
          "object_id": "re_00ZeZjRaXCgT30n1eBx53N",
          "object_type": "recipient",
          "envelope_id": "e387553d-cbb7-4924-abd8-b2d89699e9b5",
          "envelope_metadata": {
              "deal_id": "50055",
              "deal_owner": "Jane C."
          },
          "recipient_type": "signer",
          "recipient_key": "client",
          "detail": "Recipient in email blocklist."
      }
  }
  ```
</Accordion>

## recipient.replaced

Fires when a recipient is replaced through the [Replace Recipient](/docs/api/resources/recipients/replace) endpoint. The original recipient's status changes to `replaced`.

The `data` object includes `new_recipient_id` and `new_recipient_name` identifying the replacement recipient.

<Accordion title="Example payload">
  ```json JSON theme={null}
  {
      "id": "evt_8h9i0j1k2l3m4n5o6p7q",
      "type": "recipient.replaced",
      "timestamp": "2025-12-31T23:59:59.999Z",
      "data": {
          "object_id": "re_00ZeZjRaXCgT30n1eBx53N",
          "object_type": "recipient",
          "envelope_id": "e387553d-cbb7-4924-abd8-b2d89699e9b5",
          "envelope_metadata": {
              "deal_id": "50055",
              "deal_owner": "Jane C."
          },
          "recipient_type": "signer",
          "recipient_key": "client",
          "new_recipient_id": "re_5SfFjI3eVfDokAXXDSjJlz",
          "new_recipient_name": "John Doe"
      }
  }
  ```
</Accordion>

## recipient.resent

Fires when the invitation email is resent to a recipient via the [Resend Request](/docs/api/resources/recipients/resend) endpoint. The recipient status remains `sent`.

<Accordion title="Example payload">
  ```json JSON theme={null}
  {
      "id": "evt_9i0j1k2l3m4n5o6p7q8r",
      "type": "recipient.resent",
      "timestamp": "2025-12-31T23:59:59.999Z",
      "data": {
          "object_id": "re_00ZeZjRaXCgT30n1eBx53N",
          "object_type": "recipient",
          "envelope_id": "e387553d-cbb7-4924-abd8-b2d89699e9b5",
          "envelope_metadata": {
              "deal_id": "50055",
              "deal_owner": "Jane C."
          },
          "recipient_type": "signer",
          "recipient_key": "client"
      }
  }
  ```
</Accordion>