To request a signature with notifications managed by Yousign, you have to follow the steps:

1) Initiate the Signature Request

2) Upload the document to sign

3) Add a Signer

4) Activate the Signature Request

📘

Choose the right environment

In the following requests, you should prefix all the endpoints with the correct Base URL according to the environment you want to use. If you are on trial you can only use the Sandbox.

Sandbox Base URL: https://api-sandbox.yousign.app/v3
Production Base URL: https://api.yousign.app/v3

Step 1: Initiate a Signature Request

First, you have to initiate a Signature Request and specify the Signers.
The delivery_mode: email assures you that notifications are managed by Yousign.

POST /signature_requests

application/json

{
    "name": "The name of your Signature Request",
    "delivery_mode": "email",
    "timezone": "Europe/Paris",
    "custom_experience_id": "{{customexperienceId}}",
    "external_id": "{{externalId}}",
    "workspace_id": "{{workspaceId}}"
}

• Replace {{customexperienceId}} if you want to customize the Custom Experience or delete this optional attribute
• Replace {{externalId}} if you want to set your own id or delete this optional attribute

Step 2: Upload a Document

Then, you prepare the document (PDF) you want to request a signature on.

To place the Signature Request field visual on the document you have two solutions:

• using Smart Anchors: you will place text placeholders like {{s1|signature|200|100}} directly in the source documents and will automatically detect the position and size of the signature. You can use this sample document: test.pdf

• using manual field positions: you will give absolute coordinates of the signature field (page, position in the page, width and height). You can use this tool to find the coordinates: Field Position

To sign the document, you need to add at least one signature_field.

You can now proceed to the document upload.

POST /signature_requests/{signatureRequestId}/documents

multipart/form-data

curl --location --request POST '{baseUrl}/signature_requests/{signatureRequestId}/documents' \
--header 'Authorization: Bearer {apiKey}' \
--form 'file=@"/Users/user/test.pdf"' \
--form 'nature="signable_document"'

curl --location --request POST '{baseUrl}/signature_requests/{signatureRequestId}/documents' \
--header 'Authorization: Bearer {apiKey}' \
--form 'file=@"/Users/user/test.pdf"' \
--form 'nature="signable_document"' \
--form 'parse_anchors="true"'

{
    "id": "1bfddb98-91f5-4120-87a9-068be05da257",
    "filename": "test.pdf",
    "nature": "signable_document",
    "content_type": "application/pdf",
    "sha256": "3df79d34abbca99308e79cb94461c1893582604d68329a41fd4bec1885e6adb4",
    "is_protected": false,
    "is_signed": false,
    "created_at": "2021-09-15T12:52:39+00:00",
    "total_pages": 1,
    "is_locked": false,
    "initials": null
}

When you upload your document, you can choose the alignment and position of the area that will contain the initials on the document. If you add several signers, they will each have their initials written on the document. You can choose their alignment and position on the document when uploading your document.

🚧

Do not forget to replace {baseUrl} and {apiKey} with the proper value.
The API Key should be created with the same "Environment" as the Base URL you use.

🚧

You should set the Content-Type to multipart/form-data when you call document upload endpoint. You can refer to the code examples to learn how you can achieve that.

Step 3: Add a Signer

Then, you have to add a *Signer's to your Signature Request.
A Signer must have at least one Signature Field. The signature Field represents the place on the document where the Signer will apply his signature. A Signature Field must be associated with a document. You can learn more about Fields creation here.

POST /signature_requests/{signatureRequestId}/signers

application/json

{
    "info": {
        "first_name": "John",
        "last_name": "Doe",
        "email": "[email protected]",
        "phone_number": "+33700000000",
        "locale": "fr"
    },
    "signature_level": "electronic_signature",
    "signature_authentication_mode": "no_otp",
    "fields": [
        {
            "document_id": "{{documentId}}",
            "type": "signature",
            "page": 1,
            "width": 180,
            "x": 400,
            "y": 650
        }
    ]
}

{
    "info": {
        "first_name": "John",
        "last_name": "Doe",
        "email": "[email protected]",
        "phone_number": "+33700000000",
        "locale": "fr"
    },
    "signature_level": "electronic_signature",
    "signature_authentication_mode": "no_otp"
}

• Add information about the Signer: first_name, last_name, email, phone_number
• Add information about the signature field: document_id, type, page, width, coordinates
• Signer locale can be one of: fr, en, it, de, es, nl, or pl

Step 4: Activate the Signature Request

Finally, you activate the Signature Request to notify the Signers by email.

📘

As long as the Signature Request is not activated it is considered as a draft and can be freely edited or deleted

POST /signature_requests/{signatureRequestId}/activate

curl --location --request POST '{baseUrl}/signature_requests/{signatureRequestId}/activate' \
--header 'Authorization: Bearer {apiKey}'

{
    "id": "b061af63-b25d-4ae7-aaef-b46178617129",
    "status": "ongoing",
    "name": "The name of your Signature Request",
    "created_at": "2022-01-12T11:07:33+00:00",
    "email_custom_note": "a custom note added to the email sent to signers",
    "ordered_signers": false,
    "timezone": "Europe/Paris",
    "reminder_settings": null,
    "expiration_date": "2022-07-12T21:59:00+00:00",
    "signers": [
        {
            "id": "ea99491d-c598-4624-8a9d-c1e4661cf300",
            "signature_link": "https://www.yousign.app/signatures/...",
            "signature_link_expiration_date": "2023-05-05T09:28:57+00:00",
            "status": "initiated"
        }
    ],
    "documents": [
        {
            "id": "efa464de-e3a5-45f1-a45b-88fe17457bb6",
            "nature": "signable_document"
        }
    ],
    "delivery_mode": "email",
    "external_id": null,
    "branding_id": null,
    "sender": null
}

The Signer will receive an email requesting to sign.

❗️

The signature_link is sensitive information and should be treated like a user credential (password for example). Its validity is limited to ensure its security. How long is this magic link valid?

Email content