Initiate a new Signature Request

post

https://api-sandbox.yousign.app/v3/signature_requests

Creates a new Signature Request resource.

Recent Requests

Time	Status	User Agent
Retrieving recent requests…

Loading…

💡 First steps

This is the first step towards sending a Signature Request. You will then need to add at least one Document and one Signer before you can activate the Signature Request. Consult this step by step guide for more information.

Related guide: Signature Request

🔓 Endpoint access

Environments: production, sandbox
API key scopes: organization, workspace
Plans: plus, pro, scale
Add-ons (for production access): Signature or Advanced E-Signature or Qualified Electronic Signature

Ask AI

Having trouble with this endpoint?

Body Params

Create a new Signature Request from scratch

name

string

required

length between 1 and 128

Name of the signature request.
This property is a Safe String.

delivery_mode

string

enum

required

Delivery mode to notify Signers.

Allowed:

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

object | null

Enable automatic reminders for pending Signers.

timezone

string

Defaults to Europe/Paris

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 | null

deprecated

A custom note added to emails sent to signers.
This property is a Safe String allowing email and leading or trailing whitespaces.

expiration_date

date

^\d{4}-(0[1-9]|1[012])-(0[1-9]|[12][0-9]|3[01])$

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

uuid

Create a Signature Request from an existing template.

external_id

string | null

^[\w\-@.%+]+$

Store a custom id that will be added to webhooks & appended to redirect urls.

branding_id

uuid | null

deprecated

Use a specific branding to customize the signature experience.

custom_experience_id

uuid | null

Use a specific Custom Experience to customize the signature experience.

documents

array of uuids

length ≤ 5

deprecated

You can directly attach orphan Documents to the Signature Request.

documents

signers

array of objects

deprecated

Can only be used if you add documents at the same time.

signers

workspace_id

uuid | null

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

string | null

enum

Define the locale for the generated audit trail.

Allowed:

signers_allowed_to_decline

boolean

Defaults to false

Allowing signers to decline to sign.

email_notification

object | null

template_placeholders

object | null

When creating a signature request from a template, all substituting data for placeholders defined in the given template.

archiving

string | null

enum

Once the signature request completed, archive its documents in a secure digital safe

Allowed:

labels

array of uuids

length ≤ 50

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

labels

workflow_session_id

uuid | null

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

uuid | null

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.

Responses

💡 First steps

201OK

400Bad request

401Access unauthorized

403Access forbidden

404Resource not found

405This method is not allowed

415UnsupportedMediaType

429Too Many Requests, please try again later.

500Internal Server Error