--- title: "Initiate a new Signature Request" method: POST path: "/signature_requests" tags: ["Signature Request"] --- # Initiate a new Signature Request `POST /signature_requests` Creates a new Signature Request resource. ## Request body - union - object — Create a new Signature Request from scratch - `name` string, safe-string, required — Name of the signature request.\ This property is a [Safe String](https://developers.youtrust.com/reference/oas-specification#safe-string). - `delivery_mode` 'none' | 'email', required — Delivery mode to notify Signers. - `ordered_signers` boolean — Enable an ordered workflow, each Signer will be requested to sign in a sequential order - `ordered_approvers` boolean — When enabled, Approvers are requested to approve sequentially. Each Approver will be invited to approve only once the previous one has completed their approval. - `custom_recipient_order` boolean — When enabled, Approvers and Signers are requested to approve depending of a sequence composed of stages. Every recipients present in a stage will be invited to approve or sign parallelly, and stages are sequential each other. When `custom_recipient_order` is enabled, `ordered_approvers` and `ordered_signers` are ignored. - `reminder_settings` NewSignatureRequestFromScratchReminderSettings, nullable — Enable automatic reminders for pending Signers. - `interval_in_days` 1 | 2 | 7 | 14, required - `max_occurrences` integer, required - `timezone` string — 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_note` string, safe-string, nullable — A custom note added to emails sent to signers.\ This property is a [Safe String](https://developers.youtrust.com/reference/oas-specification#safe-string) allowing email and leading or trailing whitespaces. - `expiration_date` string, date — Due date of the Signature Request (yyyy-mm-dd). Defaults to 6 months after initiation. The date cannot be in the past and cannot be more than one year after initiation. - `template_id` string, uuid — Create a Signature Request from an existing template. - `external_id` string, nullable — Store a custom id that will be added to webhooks & appended to redirect urls. - `branding_id` string, uuid, nullable — Use a specific branding to customize the signature experience. - `custom_experience_id` string, uuid, nullable — Use a specific Custom Experience to customize the signature experience. - `documents` string[] — You can directly attach orphan Documents to the Signature Request. - `signers` NewSignatureRequestFromScratchSignersInner[] — Can only be used if you add documents at the same time. - union — Create signers - SignatureRequestSignerFromInfoInput — Create a signer from info - `info` SignatureRequestSignerFromInfoInputInfo, required — create new signer - `first_name` string, required - `last_name` string, required - `email` string, email, required - `phone_number` string, nullable — E.164 format. Becomes mandatory if `signature_authentication_mode` requires a phone number. - `locale` 'en' | 'fr' | 'de' | 'it' | 'nl' | 'es' | 'pl' | 'pt' | 'ro', required — Locale settings used for communication. - `fields` FieldsInput[] - union - … - `signature_level` 'electronic_signature' | 'advanced_electronic_signature' | 'qualified_electronic_signature', required - `signature_authentication_mode` 'null' | 'otp_email' | 'otp_sms' | 'no_otp', nullable — Method to authenticate the Signers. Authentication via SMS one-time password (otp_sms) is unavailable for phone numbers in China. - `redirect_urls` SignatureRequestSignerFromInfoInputRedirectUrls - `success` string, uri, nullable - `error` string, uri, nullable - `custom_text` SignatureRequestSignerFromInfoInputCustomText - `request_subject` string, nullable - `request_body` string, nullable - `reminder_subject` string, nullable - `reminder_body` string, nullable - `pre_identity_verification_required` boolean — Defines the way the Signer's Identity Documents will be uploaded for Verification. If set to `true`, `signature_level`should be equal to `advanced_electronic_signature` and `delivery_mode` set to `none`. - SignatureRequestSignerFromUserIdInput — Create a signer from a user - `user_id` string, uuid, required — Create signer from an existing user - `fields` FieldsInput[] - union - … - `signature_level` 'electronic_signature' | 'advanced_electronic_signature' | 'qualified_electronic_signature', required - `signature_authentication_mode` 'null' | 'otp_email' | 'otp_sms' | 'no_otp', nullable — Method to authenticate the Signers. Authentication via SMS one-time password (otp_sms) is unavailable for phone numbers in China. - `redirect_urls` SignatureRequestSignerFromInfoInputRedirectUrls - `success` string, uri, nullable - `error` string, uri, nullable - `custom_text` SignatureRequestSignerFromInfoInputCustomText - `request_subject` string, nullable - `request_body` string, nullable - `reminder_subject` string, nullable - `reminder_body` string, nullable - `pre_identity_verification_required` boolean — Defines the way the Signer's Identity Documents will be uploaded for Verification. If set to `true`, `signature_level`should be equal to `advanced_electronic_signature` and `delivery_mode` set to `none`. - SignatureRequestSignerFromContactIdInput — Create signer from a contact - `contact_id` string, uuid, required — Create signer from an existing contact - `fields` FieldsInput[] - union - … - `signature_level` 'electronic_signature' | 'advanced_electronic_signature' | 'qualified_electronic_signature', required - `signature_authentication_mode` 'null' | 'otp_email' | 'otp_sms' | 'no_otp', nullable — Method to authenticate the Signers. Authentication via SMS one-time password (otp_sms) is unavailable for phone numbers in China. - `redirect_urls` SignatureRequestSignerFromInfoInputRedirectUrls - `success` string, uri, nullable - `error` string, uri, nullable - `custom_text` SignatureRequestSignerFromInfoInputCustomText - `request_subject` string, nullable - `request_body` string, nullable - `reminder_subject` string, nullable - `reminder_body` string, nullable - `pre_identity_verification_required` boolean — Defines the way the Signer's Identity Documents will be uploaded for Verification. If set to `true`, `signature_level`should be equal to `advanced_electronic_signature` and `delivery_mode` set to `none`. - `workspace_id` string, uuid, nullable — Scope the signature request to a specific workspace. If template_id is filled and Template is already linked to a Workspace, keep this field to null ; the created Signature Request will be scoped to Template's Workspace. - `audit_trail_locale` 'de' | 'en' | 'es' | 'fr' | 'it' | 'pt' | 'ro' - `signers_allowed_to_decline` boolean — Allowing signers to decline to sign. - `email_notification` SignatureRequestEmailNotification, nullable - `sender` SignatureRequestEmailNotificationSender - `type` 'organization' | 'workspace' | 'custom' | 'user' - `custom_name` string, safe-string, nullable — To use in association with sender type custom to precise the name.\ This property is a [Safe String](https://developers.youtrust.com/reference/oas-specification#safe-string). - `custom_note` string, safe-string, nullable — This property is a [Safe String](https://developers.youtrust.com/reference/oas-specification#safe-string) allowing email and leading or trailing whitespaces. - `custom_text` SignatureRequestEmailNotificationCustomText, nullable - `request_subject` string, safe-string, nullable — This property is a [Safe String](https://developers.youtrust.com/reference/oas-specification#safe-string) allowing email and leading or trailing whitespaces. - `request_body` string, safe-string, nullable — This property is a [Safe String](https://developers.youtrust.com/reference/oas-specification#safe-string) allowing email and leading or trailing whitespaces. - `reminder_subject` string, safe-string, nullable — This property is a [Safe String](https://developers.youtrust.com/reference/oas-specification#safe-string) allowing email and leading or trailing whitespaces. - `reminder_body` string, safe-string, nullable — This property is a [Safe String](https://developers.youtrust.com/reference/oas-specification#safe-string) allowing email and leading or trailing whitespaces. - `template_placeholders` NewSignatureRequestFromScratchTemplatePlaceholders, nullable — When creating a signature request from a template, all substituting data for placeholders defined in the given template. - `signers` NewSignatureRequestFromScratchTemplatePlaceholdersSignersInner[] — Substituting data for placeholder signers. - union - SignatureRequestPlaceholderSignerSubstituteFromInfoInput — Create a placeholder signer substitute from info - `label` string, required - `info` SignatureRequestPlaceholderSignerSubstituteFromInfoInputInfo, required — Create new signer - … - `signature_level` 'electronic_signature' | 'advanced_electronic_signature' | 'qualified_electronic_signature' - `signature_authentication_mode` 'null' | 'otp_email' | 'otp_sms' | 'no_otp', nullable — Method to authenticate the Signers. Authentication via SMS one-time password (otp_sms) is unavailable for phone numbers in China. - `redirect_urls` SignatureRequestPlaceholderSignerSubstituteFromInfoInputRedirectUrls - … - `custom_text` SignatureRequestSignerFromInfoInputCustomText - … - `delivery_mode` 'email' | 'none', nullable — Override the delivery mode of the Signature Request for this Signer - SignatureRequestPlaceholderSignerSubstituteFromUserIdInput — Create a placeholder signer substitute from a user - `label` string, required - `user_id` string, uuid, required — Create signer from an existing user - `signature_level` 'electronic_signature' | 'advanced_electronic_signature' | 'qualified_electronic_signature' - `signature_authentication_mode` 'null' | 'otp_email' | 'otp_sms' | 'no_otp', nullable — Method to authenticate the Signers. Authentication via SMS one-time password (otp_sms) is unavailable for phone numbers in China. - `redirect_urls` SignatureRequestPlaceholderSignerSubstituteFromInfoInputRedirectUrls - … - `custom_text` SignatureRequestSignerFromInfoInputCustomText - … - `delivery_mode` 'email' | 'none', nullable — Override the delivery mode of the Signature Request for this Signer - SignatureRequestPlaceholderSignerSubstituteFromContactIdInput — Create a placeholder signer substitute from a contact - `label` string, required - `contact_id` string, uuid, required — Create signer from an existing contact - `signature_level` 'electronic_signature' | 'advanced_electronic_signature' | 'qualified_electronic_signature' - `signature_authentication_mode` 'null' | 'otp_email' | 'otp_sms' | 'no_otp', nullable — Method to authenticate the Signers. Authentication via SMS one-time password (otp_sms) is unavailable for phone numbers in China. - `redirect_urls` SignatureRequestPlaceholderSignerSubstituteFromInfoInputRedirectUrls - … - `custom_text` SignatureRequestSignerFromInfoInputCustomText - … - `delivery_mode` 'email' | 'none', nullable — Override the delivery mode of the Signature Request for this Signer - `read_only_text_fields` SignatureRequestPlaceholderReadOnlyTextFieldSubstituteInput[] — Substituting data for placeholder read_only_text fields. - `label` string, required - `text` string, required - `archiving` 'archive' | 'archive_y', nullable — Once the signature request completed, archive its documents in a secure digital safe - `labels` string[] — List of Labels to associate with the Signature Request. Labels are identified by their ID. - `workflow_session_id` string, uuid, nullable — Unique identifier of a Workflow Session. When provided, an Action is created in the Workflow Session, and this resource is associated with that Action. - `previous_attempt_id` string, uuid, nullable — ID of the previous attempt within the same `workflow_session_id`. Allows continuity between multiple attempts of the same Action. Null if this is the first attempt. - object — Duplicate a Signature Request. It will be added to the same workspace as the original. - `signature_request_id` string, uuid, required — ID of the signature request to duplicate. - `name` string — The name of the new Signature Request. - `workflow_session_id` string, uuid, nullable — Unique identifier of a Workflow Session. When provided, an Action is created in the Workflow Session, and this resource is associated with that Action. - `previous_attempt_id` string, uuid, nullable — ID of the previous attempt within the same `workflow_session_id`. Allows continuity between multiple attempts of the same Action. Null if this is the first attempt. ## Response `201` OK - SignatureRequest — Signature Request that triggered the webhook event. - `id` string, uuid, required — Unique identifier of the Signature Request. - `status` 'draft' | 'ongoing' | 'done' | 'deleted' | 'expired' | 'canceled' | 'approval' | 'rejected' | 'declined' | 'paused', required — Status of the Signature Request. - `name` string, 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_at` string, date-time, required — Signature Request creation date and time. - `activated_at` string, 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_at` string, 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_at` string, 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_at` string, date-time, required — Signature Request deletion date and time. - `timezone` string, 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_note` string, required — A custom note added to emails sent to signers. Deprecated. - `expiration_date` string, date-time, required — Due date of the Signature Request. - `source` 'app' | 'public_api' | 'hubspot_integration' | 'connector_zapier_api', required — Signature Request initialization source. - `ordered_signers` boolean, required — Specifies if each signer will be requested to sign in a sequential order. - `external_id` string, required — Custom identifier added to webhooks and appended to redirect urls. - `workspace_id` string, uuid, required — Specifies which Workspace the Signature Request is into. - `sender` UserEmbedded, required - `id` string, uuid, required — Unique identifier of the User. - `email` string, email, required — Email of the User. - `reminder_settings` ReminderSettings, required - `interval_in_days` unknown, required - `max_occurrences` integer, required — Total number of automatic reminders to send. - `signers` SignerEmbedded[], required — Array containing all Signers of the Signature Request. - `id` string, uuid, required — Unique identifier of the Signer. - `status` 'initiated' | 'notified' | 'consent_given' | 'verified' | 'processing' | 'signed' | 'error' | 'aborted' | 'declined', required — Current status of the Signer in the Signature Request process. - `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. - `answers` union[], required — The values entered by the Signer in the Fields. - union - FieldAnswerText — Value provided by the Signer. - `field_id` string, uuid, required — Unique identifier of the Field. - `field_type` unknown, required - `name` string, required — Name of the Field. - `question` string, required — Instruction or question shown to the Signer when filling out the Field. - `answer` string, required — Answer given by the Signer. - `default_value` string, required — Pre-filled value that appears in the field before the Signer provides an answer. - `read_only` boolean, required — Indicates whether the field is read-only and cannot be modified by the signer. - FieldAnswerCheckbox — Value provided by the Signer. - `field_id` string, uuid, required — Unique identifier of the Field. - `field_type` unknown, required - `name` string, required — Name of the Field. - `checked` boolean, required — Indicates whether the checkbox was checked by the Signer. - `optional` boolean, required — Indicates whether the field was optional. - `read_only` boolean, required — Indicates whether the field is read-only and cannot be modified by the signer. - `default_checked` boolean, required — Indicates whether the checkbox was checked by default. - FieldAnswerRadioGroup — Value provided by the Signer. - `field_id` string, uuid, required — Unique identifier of the Field. - `field_type` unknown, required - `name` string, required — Name for the radio button group. - `optional` boolean, required — Indicates whether the field was optional. - `read_only` boolean, required — Indicates whether the field is read-only and cannot be modified by the signer. - `radios` object[], required — List of radio button options within the group, including selected state and name for each option. - `id` string, uuid, required — Unique identifier of the radio option. - `name` string, required — Name of the radio option. - `x` integer, required — X-coordinate for positioning the radio option in the document. - `y` integer, required — Y-coordinate for positioning the radio option in the document. - `checked` boolean, required — Indicates whether this radio option was selected by the Signer. - `recipient_stage_index` integer, required — Position of the Signer in the signing flow. Signers with the same index are notified simultaneously. - `approvers` ApproverEmbedded[], required — Array containing all Approvers of the Signature Request. - `id` string, uuid, required — Unique identifier of the Approver. - `status` 'initiated' | 'notified' | 'approved' | 'rejected', required — Current status of the Approver in the Signature Request process. - `recipient_stage_index` integer, required — Position of the Approver in the approval flow. Approvers with the same index are notified simultaneously. - `labels` Label[], required — Array containing all Labels associated with the Signature Request. - `id` string, uuid, required — Unique identifier of the Label. - `name` string, required — Name of the Label. - `documents` DocumentEmbedded[], required — Array containing all Documents in the Signature Request. - `id` string, uuid, required — Unique identifier of the Document. - `nature` 'signable_document' | 'attachment', required — Specify if the document is a Signable Document or an Attachment. - `custom_properties` CustomProperty[], required — Array containing all Custom Properties associated with the Signature Request. - `id` string, uuid, required — ID of the Custom Property. - `name` string, required — Name of the Custom Property. - `type` 'text' | 'list', required — Type of the Custom Property. - `value` string, required — Text value for text properties. - `value_ids` string[], required — Array of option ids for list properties. - `values` string[], required — Array of option values for list properties. ## Other responses - `400` — Bad request - `401` — Access unauthorized - `403` — Access forbidden - `404` — Resource not found - `405` — This method is not allowed - `415` — UnsupportedMediaType - `429` — Too Many Requests, please try again later. - `500` — Internal Server Error --- [API](https://skmtc.net/yousign/apis/public-api-v3.md) · [All operations](https://skmtc.net/yousign/apis/public-api-v3/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/yousign/public-api-v3/versions/8d258c0b45d6/schema)