Create your first Signature Request (SR)
You can create your first SR in three steps only.
To create your first Signature Request, you will need to follow these 4 steps:
- Initiate the Signature Request
- Upload the document to sign
- Add a signer
- 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 👏
Updated 6 months ago