Replace a recipient

Replaces an existing recipient with a new one.

POST /v1/recipients/{recipient_id}/replace

Request

// POST https://api.signatureapi.com/v1/recipients/{recipient_id}/replace
// X-API-Key: key_test_...
// Content-Type: application/json

{
  "name": "Jane Doe",
  "email": "[e-mail]"
}

Response

// HTTP Status 201

{
  "id": "re_8Unml6TyhNN8923Rminm40",
  "envelope_id": "52872f0e-b919-4d69-89cd-e7e56af00548",
  "type": "signer",
  "key": "client",
  "name": "Jane Doe",
  "email": "[e-mail]",
  "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"
}

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.

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

Path Parameters

recipient_id · string · required

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

Body Parameters

name · string · required

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

email · string · required

The email address of the recipient. Used to send invitation emails when delivery_type is email.

Returns

Returns a 201 Created status code along with the new recipient object if successful, or an error otherwise.

Request

// POST https://api.signatureapi.com/v1/recipients/{recipient_id}/replace
// X-API-Key: key_test_...
// Content-Type: application/json

{
  "name": "Jane Doe",
  "email": "[e-mail]"
}

Response

// HTTP Status 201

{
  "id": "re_8Unml6TyhNN8923Rminm40",
  "envelope_id": "52872f0e-b919-4d69-89cd-e7e56af00548",
  "type": "signer",
  "key": "client",
  "name": "Jane Doe",
  "email": "[e-mail]",
  "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"
}