> ## 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.

# Replace a recipient

> Replaces an existing recipient with a new one.

Replaces a recipient with a new person. The original recipient's status changes to `replaced`, and a new recipient is created with the provided name and email.

Use this endpoint when a recipient can no longer complete the envelope, for example after a hard bounce or if the wrong person was assigned. The new recipient inherits the original recipient's type, key, routing position, and assigned places. A new ceremony is created and the invitation is sent according to the recipient's `delivery_type`.

<Note>Recipients can only be replaced if they have not completed yet and the envelope status is `processing` or `in_progress`.</Note>

### Path Parameters

<ParamField path="recipient_id" type="string" required={true}>
  The unique identifier of the recipient. Recipient IDs use the `re_` prefix.
</ParamField>

### Body Parameters

<ParamField body="name" type="string" required={true}>
  The full name of the recipient. Appears in invitation emails and is pre-filled for typed signatures.
</ParamField>

<ParamField body="email" type="string" required={true}>
  The email address of the recipient. Used to send invitation emails when `delivery_type` is `email`.
</ParamField>

### Returns

Returns a `201 Created` status code along with the new [recipient object](/docs/api/resources/recipients/object) if successful, or an [error](/docs/api/errors) otherwise.

<RequestExample>
  ```json Request theme={null}
  // POST https://api.signatureapi.com/v1/recipients/{recipient_id}/replace
  // X-API-Key: key_test_...
  // Content-Type: application/json

  {
    "name": "Jane Doe",
    "email": "jane@example.com"
  }
  ```
</RequestExample>

<ResponseExample>
  ```json Response theme={null}
  // HTTP Status 201

  {
    "id": "re_8Unml6TyhNN8923Rminm40",
    "envelope_id": "52872f0e-b919-4d69-89cd-e7e56af00548",
    "type": "signer",
    "key": "client",
    "name": "Jane Doe",
    "email": "jane@example.com",
    "status": "pending",
    "status_updated_at": "2025-12-31T16:00:00.000Z",
    "completed_at": null,
    "delivery_type": "email",
    "signature_options": ["typed", "drawn"],
    "ceremony": {
      "authentication": [
        {
          "type": "email_link",
          "subject_override": null,
          "message_override": null
        }
      ],
      "redirect_url": null,
      "redirect_delay": 3,
      "embeddable_in": [],
      "url_variant": "standard",
      "url": null
    },
    "ceremony_creation": "automatic"
  }
  ```
</ResponseExample>