Guides
Status PageRoadmapTestimonies

Request a signature with notifications managed by yourself

Suggest Edits

To request a signature with notifications managed by yourself, 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

5) Deliver the signature link to the Signer

📘

Choose your 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: none assures you that notifications are managed by yourself. When setting the delivery_mode: none, Approvers and Followers are not notified either. More details about the delivery_mode: none can be found here.

POST /signature_requests

application/json

{
    "name": "The name of your Signature Request",
    "delivery_mode": "none",
    "custom_experience_id": "{{customexperienceId}}",
    "external_id": "{{externalId}}"
}

curl --location --request POST '{baseUrl}/signature_requests' \
--header 'Authorization: Bearer {apiKey}' \
--header 'Content-Type: application/json' \
--data-raw '{
  "name": "The name of your Signature Request",
  "delivery_mode": "none",
  "timezone": "Europe/Paris"
}'

{
    "id": "b061af63-b25d-4ae7-aaef-b46178617129",
    "source": "public_api",
    "status": "draft",
    "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",
    "delivery_mode": "email",
    "documents": [],
    "signers": [],
    "external_id": null,
    "branding_id": null,
    "sender": null
}
  • 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) on which you want to request a signature.

To place the visual signature field 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 fields positions: you will give absolute coordinates of the signature (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.

🚧

Most of the time you should not set the Content-Type manually to multipart/form-data, it will be managed directly by your HTTP client and include the correct boundary for your form.

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.

{
    "info": {
        "first_name": "John",
        "last_name": "Doe",
        "email": "[email protected]",
        "phone_number": "+33700000000",
        "locale": "fr"
    },
    "signature_level": "electronic_signature",
    "signature_authentication_mode": "otp_email",
    "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": "otp_email"
}

Step 4: Activate the Signature Request

You activate the Signature Request to get the signature_link to send to the Signer.

POST /signature_requests/{id}/activate

The response body contain the signature_link that allow to sign the document.

❗️

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?

{
    "id": "ee1d9413-ce72-4c25-a294-fcf20cf34a26",
    "status": "ongoing",
    "name": "The name of your Signature Request",
    "created_at": "2023-01-03T10:40:00+00:00",
    "email_custom_note": "",
    "ordered_signers": false,
    "timezone": "Europe/Paris",
    "reminder_settings": null,
    "expiration_date": "2023-07-03T21:59:00+00:00",
    "signers": [
        {
            "id": "50c35490-bc04-493c-98da-7a0ac493744a",
            "status": "notified",
            "signature_link": "https://yousign.app/signatures/ee1d9413-ce72-4c25-a294-fcf20cf34a26?s=846991a748d97f86dd77az99ac23def97f8197ca0d93c2395b7&r=e8abd212f99bde967e37bb7deb4a3fdf&source=email&lang=fr&magic_link_id=b192a9f2-1071-4829-b2bc-d2a964402ec0&domain_id=c9cb0951a3&k=rnEV1JFOpbIWCtQ3gRcOAxXCkTMFxPfn",
            "signature_link_expiration_date": "2023-05-05T09:28:57+00:00"
        }
    ],
    "approvers": [],
    "documents": [
        {
            "id": "b9a7e6f1-c633-4305-b5b9-c36a592c0cb0",
            "nature": "signable_document"
        }
    ],
    "delivery_mode": "none",
    "external_id": null,
    "custom_experience_id": null,
    "sender": null
}

Step 5: Deliver the signature_link to the Signer

You will have to share the signature_link with the Signers and notify them that they are requested to sign.

More information about this option, with ordered Signers on this page.

If you need to generate a new magic link when it is expired:

  1. To get the signature link, do a GET /Signer
  2. In the payload you will always have the link and its expiration date
  3. If the expiration date has passed when you make this request, then a new link will be generated with a new expiration date.

Updated 7 months ago