---
title: "Update Recipients"
method: PATCH
path: "/api/v1/documents/{id}/recipients"
tags: ["Document"]
---

# Update Recipients

`PATCH /api/v1/documents/{id}/recipients`

Updates one or more recipients on a document that has already been sent. Only recipients who have not started signing may be updated. Recipient IDs must be retrieved from the Get Document response. Allowed document statuses: sent, viewed, pending, bounced. For non-embedded documents, updated recipients will receive a new notification email. For embedded signing documents, email behavior follows each recipient's send_email setting.

## Path parameters

- `id` string, uuid, required — Unique identifier for a document.

## Request body

- UpdateRecipientsRequest
  - `recipients` object[], required — List of recipients to update on the document.
    - `id` string, required — The recipient's unique identifier from the Get Document response.
    - `name` string, required — Updated name for the recipient.
    - `email` string, email, required — Updated email address for the recipient.
    - `subject` string — Updated email subject for the signature request that this recipient will see.
    - `message` string — Updated email message for the signature request that this recipient will see.
    - `passcode` string — Updated passcode for the recipient. If set, the signer will be required to enter the passcode before viewing and completing the document.
    - `passcode_delivery` object — Passcode delivery settings.
      - `enabled` boolean — Enable or disable passcode delivery.
      - `methods` string[] — Delivery methods. Defaults to ["email"].
      - `expire_after_access` boolean — Clear passcode after successful authentication. If passcode_delivery is also enabled, a new passcode is auto-generated on the next send request. Otherwise the recipient will no longer need a passcode.

## Response `200`

successful

- DocumentResponse
  - `test_mode` boolean, required
  - `id` string, required
  - `api_application_id` string, uuid, nullable
  - `requester_email_address` string, email
  - `custom_requester_name` string, nullable
  - `custom_requester_email` string, email, nullable
  - `name` string
  - `subject` string
  - `message` string
  - `metadata` object, nullable
  - `created_at` string, date-time
  - `updated_at` string, date-time
  - `recipients` object[]
    - `id` string
    - `name` string, required
    - `email` string, required
    - `body` string
    - `message` string, nullable
    - `subject` string, nullable
    - `send_email` boolean, nullable
    - `send_email_delay` integer, nullable
    - `signing_order` integer
    - `signing_url` string, url, nullable
    - `embedded_signing_url` string, url, nullable
    - `bounced` boolean, nullable
    - `bounced_details` string, nullable
    - `attachment_requests` AttachmentRequestInfo[]
      - `name` string, required — Name of the attachment request
      - `url` string, url — URL of the uploaded attachment (when available)
      - `required` boolean, required — Whether the attachment is required
    - `passcode` string, nullable
    - `passcode_delivery` object
      - `enabled` boolean
      - `methods` string[], nullable
      - `expire_after_access` boolean
    - `status` string, nullable
  - `status` string — Possible values: Draft, Created, Sending, Sent, Pending, Viewed, Completed, Manually completed, Declined, Canceled, Bounced, Blocked, Error, Expired
  - `reminders` boolean
  - `archived` boolean
  - `embedded_signing` boolean
  - `embedded_edit_url` string, url, nullable
  - `embedded_preview_url` string, url, nullable
  - `apply_signing_order` boolean
  - `redirect_url` string, url, nullable
  - `decline_redirect_url` string, url, nullable
  - `language` string
  - `expires_in` integer
  - `decline_message` string, nullable
  - `error_message` string, nullable
  - `template_id` string, nullable
  - `template_ids` string[]
  - `embedded_signing_notifications` boolean
  - `attachment_requests` object[]
    - `name` string, required
    - `recipient_id` string, required
    - `required` boolean
  - `files` FileInfo[]
    - `name` string, required — File name
    - `pages_number` integer, required — Number of pages in the file
  - `copied_contacts` CopiedContactInfo[]
    - `id` string — Contact ID
    - `name` string — Contact name
    - `email` string, email, required — Contact email
  - `fields` array[]
    - object[]
      - `x` number, float, required
      - `y` number, float, required
      - `page` integer, required
      - `recipient` object
        - `email` string, email, required
        - `name` string, required
      - `api_id` string, uuid
      - `name` string, nullable
      - `date_format` 'MM/DD/YYYY' | 'DD/MM/YYYY' | 'YYYY/MM/DD' | 'Month DD, YYYY' | 'MM/DD/YYYY hh:mm:ss a' — Date format for date fields. Valid values: MM/DD/YYYY, DD/MM/YYYY, YYYY/MM/DD, Month DD, YYYY, MM/DD/YYYY hh:mm:ss a. Default: MM/DD/YYYY
      - `fixed_width` boolean
      - `formula` string
      - `label` string
      - `lock_sign_date` boolean
      - `required` boolean
      - `type` 'initials' | 'signature' | 'checkbox' | 'date' | 'select' | 'text' | 'dropdown' | 'autofill_company' | 'autofill_email' | 'autofill_first_name' | 'autofill_last_name' | 'autofill_name' | 'autofill_phone' | 'autofill_title' | 'autofill_date_signed' — Type of signing field
      - `validation` 'no_text_validation' | 'numbers' | 'letters' | 'email_address' | 'us_phone_number' | 'us_zip_code' | 'us_ssn' | 'us_age' | 'alphanumeric' | 'us_bank_routing_number' | 'us_bank_account_number' | 'custom' — Validation rule for text fields
      - `validation_regex` string — Text fields with custom validation only: the regex pattern used to validate field values. Required when validation is set to custom.
      - `validation_regex_error_message` string — Text fields with custom validation only: the error message shown to the recipient when their input doesn't match the regex pattern. Required when validation is set to custom.
      - `value` union
        - string
        - boolean
        - number
      - `height` string
      - `width` string
      - `recipient_id` string, nullable
      - `signing_elements_group_id` string, uuid
      - `placeholder_name` string
      - `options` object[] — Dropdown options (for dropdown/select fields)
        - `name` string
        - `api_id` string
        - `is_other` boolean
      - `default_option` string — Default selected option
      - `allow_other` boolean — Whether "Other" option is allowed
  - `allow_decline` boolean, nullable
  - `allow_reassign` boolean, nullable
  - `labels` LabelInfo[]
    - `id` string — Label ID
    - `name` string — Label name
  - `checkbox_groups` CheckboxGroupInfo[]
    - `id` string, uuid, required — Checkbox group ID
    - `group_name` string, nullable — Name of the checkbox group
    - `recipient_id` string, nullable — Recipient ID associated with the group
    - `checkbox_ids` string[], required — IDs of checkboxes in this group
    - `validation` 'minimum' | 'maximum' | 'range' | 'exact' — Validation rule for checkbox groups
    - `required` boolean, required — Whether at least one checkbox must be checked
    - `min_value` integer — Minimum number of checkboxes to check
    - `max_value` integer — Maximum number of checkboxes to check
    - `exact_value` integer — Exact number of checkboxes that must be checked
  - `conditional_rules` ConditionalRuleInfo[]
    - `id` string, required — Conditional rule ID
    - `target_id` string, required — api_id of the field that owns the rule, or the external_id of a checkbox group when the rule is owned by a group (groups have no api_id)
    - `action_type` 'show' | 'hide' | 'require', required — Action applied to action_field_ids when the conditions are met
    - `action_field_ids` string[] — api_ids of fields the rule affects when triggered
    - `conditions` object[]
      - `condition_type` 'any_of' | 'all_of' | 'none_of' | 'not_all_of' — How field_api_ids combine within this condition
      - `status` 'completed' | 'not_completed' — Field state that satisfies this condition
      - `join_operator` 'and_operator' | 'or_operator' — How this condition joins with the next one in the rule
      - `field_api_ids` string[] — api_ids of fields evaluated by this condition
      - `position` integer — Order of this condition within the rule
  - `conditional_logic_decisions` ConditionalLogicDecisionInfo[]
    - `rule_id` string, required — External ID of the conditional rule that fired
    - `field_api_id` string, required — api_id of the field the decision applies to
    - `decision_type` 'kept_signature' | 'cleared_value', required — Whether the signer kept the existing signature or the value was cleared
    - `decided_at` string, date-time, required — When the decision was recorded
    - `description` string — Human-readable summary of the decision

## Other responses

- `400` — bad request - invalid structure
- `404` — not found
- `409` — conflict - document not in eligible state
- `422` — unprocessable entity - business rule violation
- `429` — rate limit exceeded

---

[API](https://skmtc.net/signwell/apis/signwell-developer-api.md) · [All operations](https://skmtc.net/signwell/apis/signwell-developer-api/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/signwell/signwell-developer-api/revisions/debef5796b62/schema)