v1

latestOpenAPI 3.0.0proprietary2026-07-261695971.5 MB

Signature Request

Update a Signature Request

Updates a given Signature Request. Any parameters not provided are left unchanged.

patch/signature_requests/{signatureRequestId}

Path parameters

signatureRequestIdstring uuid required

The unique identifier for a resource.

Example:9a93d3b5-fb3b-4abf-9e70-26315b33506c

Signature Request Id

Request body

namestring safe-string

This property is a Safe String.

delivery_mode'none' | 'email'

Delivery mode to notify signers.

ordered_signersboolean

Enable an ordered workflow, each signer will be requested to sign in a sequential order

ordered_approversboolean

When enabled, Approvers are requested to approve sequentially. Each Approver will be invited to approve only once the previous one has completed their approval.

timezonestring

Time zone of the dates and times displayed in emails, the Signature Request expiration date, and the PDF Audit Trail. Format: tz database. Default is set to Europe/Paris.

email_custom_notestring safe-string nullable

This property is a Safe String allowing email.

expiration_datestring date

Due date of the Signature Request (yyyy-mm-dd). The date cannot be in the past and cannot be more than one year after initiation.

external_idstring nullable

branding_idstring uuid nullable

custom_experience_idstring uuid nullable

Use a specific Custom Experience to customize the signature experience.

signers_allowed_to_declineboolean

Allowing signers to decline to sign.

workspace_idstring uuid nullable

Transfer the Signature Request into a given Workspace.

audit_trail_locale'de' | 'en' | 'es' | 'fr' | 'it' | 'pt' | 'ro'

labelsstring[]

List of Labels to associate with the Signature Request. Labels are identified by their ID.

Example request

{
  "ordered_signers": true,
  "ordered_approvers": true,
  "reminder_settings": {
    "max_occurrences": 5
  },
  "timezone": "Europe/Paris",
  "email_custom_note": "Please sign these documents as soon as possible.",
  "branding_id": "3a93d3b5-fb3b-4abf-9e70-26315b33506b",
  "custom_experience_id": "3a93d3b5-fb3b-4abf-9e70-26315b33506b",
  "signers_allowed_to_decline": true,
  "workspace_id": "3a93d3b5-fb3b-4abf-9e70-26315b33506b",
  "audit_trail_locale": "en",
  "email_notification": {
    "custom_note": "Please sign these documents as soon as possible."
  },
  "labels": [
    "3a93d3b5-fb3b-4abf-9e70-26315b33506b",
    "89120884-d29a-4b1a-ac7b-a9e73a872795"
  ]
}

Response

idstring uuid required

Unique identifier of the Signature Request.

Status of the Signature Request.

namestring required

Name of the Signature Request.

delivery_mode'email' | 'none' required

Specifies who is in charge to notify the Signature Request's participant when an event occurs. In Delivery Mode email, the Signer is notified by Youtrust that they have to sign a document. In Delivery Mode none, you will be in charge to notify the Signer that a document is ready to be signed.

created_atstring date-time required

Signature Request creation date and time.

activated_atstring date-time required

Timestamp indicating when the Signature Request was activated and made available to its recipients.
Returns null if the Signature Request is still in draft.

completed_atstring date-time required

Timestamp indicating when the Signature Request reached the done status, i.e. all required Signers have signed and all Approvers have approved.
Returns null if the Signature Request is not yet complete.

approved_atstring date-time required

Timestamp indicating when all Approvers have approved the Signature Request when custom recipient flow is not enabled.
Returns null if no approvers are configured, or if at least one approver has not yet approved or when custom_recipient_order is enabled.

deleted_atstring date-time required

Signature Request deletion date and time.

timezonestring required

Time zone of the dates and times displayed in emails, the Signature Request expiration date, and the PDF Audit Trail. Format: tz database. Default is set to Europe/Paris.

email_custom_notestring required

A custom note added to emails sent to signers. Deprecated.

expiration_datestring date-time required

Due date of the Signature Request.

source'app' | 'public_api' | 'hubspot_integration' | 'connector_zapier_api' required

Signature Request initialization source.

ordered_signersboolean required

Specifies if each signer will be requested to sign in a sequential order.

external_idstring required

Custom identifier added to webhooks and appended to redirect urls.

workspace_idstring uuid required

Specifies which Workspace the Signature Request is into.

Example response

{
  "id": "0ef334d2-7f36-4643-8a2a-4283b4a3e4a4",
  "status": "ongoing",
  "name": "My Signature Request",
  "delivery_mode": "email",
  "created_at": "2024-01-18T22:59:00Z",
  "activated_at": "2024-01-18T22:59:00Z",
  "completed_at": "2024-01-18T22:59:00Z",
  "approved_at": "2024-01-18T22:59:00Z",
  "deleted_at": "2024-01-18T22:59:00Z",
  "timezone": "Europe/Paris",
  "email_custom_note": "Please sign these documents as soon as possible.",
  "expiration_date": "2024-01-18T22:59:59Z",
  "source": "public_api",
  "ordered_signers": true,
  "external_id": "ref#1234",
  "workspace_id": "0ef334d2-7f36-4643-8a2a-4283b4a3e4a4",
  "sender": {
    "id": "550e8402-e29b-41d4-a716-446655440000",
    "email": "john.doe@example.com"
  },
  "reminder_settings": {
    "interval_in_days": 1,
    "max_occurrences": 2
  },
  "signers": [
    {
      "id": "550e8402-e29b-41d4-a716-446655440000",
      "status": "notified",
      "delivery_mode": "email",
      "answers": [
        {
          "field_id": "89d519d7-63bd-45d2-8539-a10a9172368a",
          "name": "Street Address",
          "question": "What is your address?",
          "answer": "42 Elm St, Rivertown, NY 10567",
          "default_value": "47 Elm Street, Rivertown, NY 10567",
          "read_only": true
        }
      ]
    }
  ],
  "approvers": [
    {
      "id": "550e8402-e29b-41d4-a716-446655440000",
      "status": "approved"
    }
  ],
  "labels": [
    {
      "id": "0ef334d2-7f36-4643-8a2a-4283b4a3e4a4",
      "name": "Invoices"
    }
  ],
  "documents": [
    {
      "id": "0ef334d2-7f36-4643-8a2a-4283b4a3e4a4",
      "nature": "signable_document"
    }
  ],
  "custom_properties": [
    {
      "id": "0ef334d2-7f36-4643-8a2a-4283b4a3e4a4",
      "name": "Department",
      "type": "text",
      "value": "Marketing"
    }
  ]
}