v1

latestOpenAPI 3.0.0proprietary2026-07-261695971.5 MB

Signature Request

Initiate a new Signature Request

Creates a new Signature Request resource.

post/signature_requests

Request body

Example request

{
  "ordered_signers": true,
  "ordered_approvers": true,
  "custom_recipient_order": true,
  "reminder_settings": {
    "max_occurrences": 5
  },
  "timezone": "Europe/Paris",
  "email_custom_note": "Please sign these documents as soon as possible.",
  "template_id": "9a93d3b5-fb3b-4abf-9e70-26315b33506c",
  "branding_id": "3a93d3b5-fb3b-4abf-9e70-26315b33506b",
  "custom_experience_id": "3a93d3b5-fb3b-4abf-9e70-26315b33506b",
  "documents": [
    "89120884-d29a-4b1a-ac7b-a9e73a872795"
  ],
  "signers": [
    {
      "info": {
        "phone_number": "+41446667700",
        "locale": "fr"
      },
      "fields": [
        {
          "document_id": "9b6ed2f3-244f-487a-baa1-bbe4f51c8748"
        }
      ],
      "redirect_urls": {
        "success": "https://example.com/success",
        "error": "https://example.com/error"
      }
    }
  ],
  "workspace_id": "89120884-d29a-4b1a-ac7b-a9e73a872795",
  "audit_trail_locale": "en",
  "signers_allowed_to_decline": true,
  "email_notification": {
    "custom_note": "Please sign these documents as soon as possible."
  },
  "template_placeholders": {
    "signers": [
      {
        "label": "Employee",
        "info": {
          "phone_number": "+41446667700",
          "locale": "fr"
        },
        "redirect_urls": {
          "success": "https://example.com/success",
          "error": "https://example.com/error",
          "decline": "https://example.com/decline"
        }
      }
    ],
    "read_only_text_fields": [
      {
        "label": "Employee",
        "text": "This is my read_only_text"
      }
    ]
  },
  "labels": [
    "3a93d3b5-fb3b-4abf-9e70-26315b33506b",
    "89120884-d29a-4b1a-ac7b-a9e73a872795"
  ],
  "workflow_session_id": "0ef334d2-7f36-4643-8a2a-4283b4a3e4a4",
  "previous_attempt_id": "9412b83b-b4b9-4a94-97b5-2b43dfa4cde4"
}

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"
    }
  ]
}