To create your first Signature Request, you will need to follow these 4 steps:

1. Initiate the Signature Request
2. Upload the document to sign
3. Add a signer
4. Activate the Signature Request

ℹ️

Watch out for the environment you use

Be careful, if you are in the Sandbox environment, don't forget to create your API key for this environment 🙂

In the following requests, you must modify all the endpoints with the correct Base URL, according to the environment you want to use. If you are in the trial period, you can only use the Sandbox.

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

💡

How to test Yousign API in a minute with Postman?

For developers wishing to test the first API calls from Postman, we're making available a ready-to-use Postman Collection. You can fork the Collection with a single click. Enjoy it!

Step 1: Initiate the Signature Request

You will now initiate the Signature Request and specify the Signers.

POST /signature_requests

application/json

{
    "name": "The name of your Signature Request",
    "delivery_mode": "email",
    "timezone": "Europe/Paris"
}

Step 2: Upload the document

The first step is to prepare the document (PDF) that will be signed.

You need to have at least one signature field.
To place the visual signature field on the document, you need to use manual field positions : you will give absolute coordinates for the signature (page, position within the page, width and height). You can use this tool to find the coordinates.

The other option is to use Smart Anchors.

You can now proceed to upload your document.

POST /signature_requests/{signatureRequestId}/documents

multipart/form-data

curl --location --request POST '{baseUrl}/signature_requests/{signatureRequestId}/documents' \
--header 'Authorization: Bearer {apiKey}' \
--form 'file=@"/path/to/the/document/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
}

🚧

• Don't forget to replace {baseUrl} and {apiKey} with the proper values
• The type of your API Key (Sandbox or Production) should correspond to the Base URL you use (see above)
• The PDF document should not be sent as Base64

Step 3: Add a signer

Next, you have to add a Signer to your Signature Request.
A Signer must be linked to at least one Signature Field. The signature Field visually represents the place on the document where the Signer will apply this/her signature. A Signature Field must be linked to a document. Learn more about how to create Fields 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
        }
    ]
}

• Replace {{documentId}} with the ID obtained in the response of the previous request.
• For signer locale, select one of the following : fr, en, it, de, es

Step 4: Activate the Signature Request

In this final step, activate the Signature Request to notify the Signers by email.

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",
    "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/...",
            "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 inviting them to sign.

👍

Congratulations you just did your first Signature Request 👏