---
title: "Update and Send Document"
method: POST
path: "/api/v1/documents/{id}/send"
tags: ["Document"]
---

# Update and Send Document

`POST /api/v1/documents/{id}/send`

Updates a draft document and sends it to be signed by recipients.

## Path parameters

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

## Request body

- UpdateDocumentAndSendRequest
  - `test_mode` boolean — Set to `true` to enable Test Mode. Documents created with Test Mode do not count towards API billing and are not legally binding. Defaults to `false`
  - `name` string — The name of the document.
  - `subject` string — Email subject for the signature request that recipients will see. Defaults to the default system subject or a template subject (if the document is created from a template).
  - `message` string — Email message for the signature request that recipients will see. Defaults to the default system message or a template message (if the document is created from a template).
  - `expires_in` integer — Number of days before the signature request expires. Defaults to the account expiration setting or template expiration (if the document is created from a template).
  - `reminders` boolean — Whether to send signing reminders to recipients. Reminders are sent on day 3, day 6, and day 10 if set to `true`. Defaults to `true`.
  - `apply_signing_order` boolean — When set to `true` recipients will sign one at a time in the order of the `recipients` collection of this request.
  - `api_application_id` string, uuid — Unique identifier for API Application settings to use. API Applications are optional and mainly used when isolating OAuth apps or for more control over embedded API settings
  - `embedded_signing` boolean — When set to `true` it enables embedded signing in your website/web application. Embedded functionality works with an iFrame and email authentication is disabled. :embedded_signinig defaults to `false`.
  - `embedded_signing_notifications` boolean — On embedding signing, document owners (and CC'd contacts) do not get a notification email when documents have been completed. Setting this param to `true` will send out those final completed notifications. Default is `false`
  - `custom_requester_name` string — Sets the custom requester name for the document. When set, this is the name used for all email communications, signing notifications, and in the audit file.
  - `custom_requester_email` string, email — Sets the custom requester email for the document. When set, this is the email used for all email communications, signing notifications, and in the audit file.
  - `redirect_url` string, url — A URL that recipients are redirected to after successfully signing a document.
  - `allow_decline` boolean — Whether to allow recipients the option to decline signing a document. If multiple signers are involved in a document, any single recipient can cancel the entire document signing process by declining to sign.
  - `allow_reassign` boolean — In some cases a signer is not the right person to sign and may need to reassign their signing responsibilities to another person. This feature allows them to reassign the document to someone else.
  - `decline_redirect_url` string, url — A URL that recipients are redirected to if the document is declined.
  - `conditional_rules` ConditionalRuleRequest[] — Conditional logic rules that show, hide, or require fields based on what a signer does to other fields. Every identifier is a field api_id. At most 10 rules per document or template.
    - `id` string — The rule's persistent ID. Ignored on create (every rule is new). On an update (template update or document update-and-send) include it to modify an existing rule, or pair it with `deleted: true` to remove the rule; omit it to add a new rule.
    - `deleted` boolean — Only meaningful on an update (template update or document update-and-send): set to true together with the rule's `id` to remove that rule. Ignored on create — there is no existing rule to delete.
    - `target_id` string — 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). Cannot also appear in action_field_ids (self-reference is forbidden).
    - `action_type` 'show' | 'hide' | 'require' — Action applied to action_field_ids when the conditions are met: `show`, `hide`, or `require`.
    - `action_field_ids` string[] — api_ids of the fields the action applies to. List a checkbox group's member api_ids to target the whole group.
    - `conditions` object[] — The conditions that trigger the rule. At least 1, at most 5.
      - `condition_type` 'any_of' | 'all_of' | 'none_of' | 'not_all_of', required — How the field_api_ids combine within a condition: `any_of`, `all_of`, `none_of`, or `not_all_of`.
      - `status` 'completed' | 'not_completed', required — The field state the condition tests for: `completed` or `not_completed`.
      - `join_operator` 'and_operator' | 'or_operator' — How this condition joins the next one in the rule: `and_operator` or `or_operator`. The first condition's value is ignored.
      - `field_api_ids` string[], required — api_ids of the trigger fields the condition watches.
      - `position` integer — 1-indexed order of the condition within the rule.
  - `metadata` object — Optional key-value data that can be associated with the document. If set, will be available every time the document data is returned.
  - `labels` LabelRequest[] — Labels can be used to organize documents in a way that can make it easy to find using the document search in SignWell. A document can have multiple labels. Updating labels on a document will replace any existing labels for that document.
    - `name` string, required
  - `checkbox_groups` object[] — Checkbox fields that are placed on a document can be grouped with selection requirements. At least 2 checkbox fields in an array of fields must be assigned to the same recipient.
    - `group_name` string, required — A unique identifier for the checkbox group.
    - `recipient_id` string, required — The recipient ID associated with the checkbox group.
    - `checkbox_ids` string[], required
    - `validation` 'minimum' | 'maximum' | 'range' | 'exact' — Validation rule for checkbox groups
    - `required` boolean — Whether the group must be completed by the recipient. Defaults to false.
    - `min_value` integer — The minimum number of checkboxes that must be checked in the group. (Only for validation: minimum and range)
    - `max_value` integer — The maximum number of checkboxes that can be checked in the group. (Only for validation: maximum and range)
    - `exact_value` integer — The exact number of checkboxes that must be checked in the group. (Only for validation: exact)

## Response `201`

created

- 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

- `422` — unprocessable entity
- `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)