Guides
Status PageRoadmapTestimonies

Notifications managed by yourself

Suggest Edits

Manage notifications by yourself if signers are not ordered

To request a signature with notifications managed by yourself, in case you have not ordered signers, you have to follow the steps:

  1. Initiate the Signature Requests
  2. Upload the document to sign
  3. Add a Signer
  4. Activate the Signature Request
  5. Deliver the signature link to the Signer

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.

Manage notifications by yourself with ordered signer

Each signer must be notified sequentially, when a signer signs then the next must be notified until there are no more signers to sign. To do this, the recommended way is by using webhooks.

📘

  • In delivery mode "email", the signer status "notified" implies that this signer has been notified by Yousign.
  • In delivery mode "none", the signer status "notified" implies that this signer is ready to be notified.

Find the next signer to notify from a webhook

When the delivery mode "none" is used, the signature link of the next ordered signer can be retrieved using webhooks.

1116

Find the next signer's signature link for a Signature Request with delivery mode "none" with ordered signers

Step 1: Create a webhook subscription

To detect when a signer needs to be notified, you have to create a webhook subscription listening to the event signer.notified (see Configure a new webhook).

Step 2: Activate a Signature Request

When a signature request is created with a delivery_mode set to "none" and ordered_signers set to "true", the signature request activation (see Activate a signature request) will trigger the event signer.notified for the first ordered signer.

Step 3: Receive the webhook payload

Once the signature request is created and activated, a request is sent to the webhook subscription that listens for the signer.notified event. This request contains the information of the first signer who needs to be notified.

Here is an example of the payload associated with this request:

{
  "event_id": "4d6305e0-a69a-4653-84e7-701c562b8f25",
  "event_name": "signer.notified",
  "event_time": "1669733581",
  "subscription_id": "d89a0f7b-bd3f-494d-ab61-71b69f24a3e1",
  "subscription_description": "App webhook",
  "sandbox": false,
  "data": {
    "signature_request": {
      "id": "b9bf5521-00eb-4044-adf5-da4ea31a48e0",
      "status": "ongoing",
      "name": "My new request",
      "delivery_mode": "none",
      "created_at": "2022-11-29T14:52:39+00:00",
      "timezone": "Europe/Paris",
      "email_custom_note": null,
      "expiration_date": "2023-05-29T21:59:00+00:00",
      "source": "app",
      "ordered_signers": true,
      "external_id": null,
      "signers": [
        {
          "id": "395375bb-93d9-4762-8e11-5caa4734afc1",
          "answers": [],
          "status": "notified"
        }
      ],
      "approvers": [],
      "sender": {
        "id": "3409ab3f-9295-4a69-9923-e9d32d9533d6",
        "email": "[email protected]"
      },
      "documents": [
        {
          "id": "5dcae863-2a1b-4f93-92a7-73f6b7409474",
          "nature": "signable_document"
        }
      ],
      "reminder_settings": {
        "interval_in_days": 7,
        "max_occurrences": 5
      }
    },
    "signer": {
      "id": "395375bb-93d9-4762-8e11-5caa4734afc1",
      "info": {
        "first_name": "John",
        "last_name": "Doe",
        "email": "[email protected]",
        "phone_number":"+33700000000",
        "locale": "en"
      },
      "answers": [],
      "status": "notified",
      "signature_level": "electronic_signature",
      "signature_authentication_mode": "sms"
    }
  }
}

Step 4: Fetch the Signer's signature link

The signer ID can be found in the payload (here it's 395375bb-93d9-4762-8e11-5caa4734afc1), and the signature link can be retrieved by requesting the API. In this example, the request would be as follows:

GET /signature_requests/b9bf5521-00eb-4044-adf5-da4ea31a48e0/signers/395375bb-93d9-4762-8e11-5caa4734afc1

{
    "id": "395375bb-93d9-4762-8e11-5caa4734afc1",
    "info": {
        "first_name": "John",
        "last_name": "Doe",
        "email": "[email protected]",
        "phone_number": "+33700000000",
        "locale": "en"
    },
    "status": "notified",
    "signature_link": "https://yousign.app/signatures/70852b46-d0b1-4901-8178-9aefafae6cf6?s=d364cf2b709f33cc54ad2de28c61fb556bfa9b50d8fca088866d28afafd8e6c1472ebd5e5cbd4f0edf7ddf04525d70142b32d1d181d1ea97e45c863d92311dcb&r=7dcae4cc66676747516cce62a4af3404&source=email&lang=fr&magic_link_id=305b933d-899a-4d3b-b4c0-13bc859ec82b&domain_id=1b242e08f4&k=gaWNhPwxgARPJ7sDGGT9zms47HueiSz5",
    "signature_link_expiration_date": "2023-05-05T09:28:57+00:00",
    "signature_image_preview": "https://yousign.app/signature_requests/70852b46-d0b1-4901-8178-9aefafae6cf6/recipients/c591d3c1-bc02-4cbd-a941-206aa7c6a406/preview.8c1e958b7a4b98845d6cc1cf81c45341c2312161.svg",
    "fields": [
        {
            "id": "6364a7c2-34b6-4bbe-bb60-d07724400a67",
            "document_id": "22b93593-8631-45e9-b4ac-2a3a820d6034",
            "x": 56,
            "y": 231,
            "page": 1,
            "type": "signature",
            "height": 100,
            "width": 200
        },
        {
            "id": "fc5b59a5-4cc0-4e3b-a959-7ec7f3aada27",
            "document_id": "22b93593-8631-45e9-b4ac-2a3a820d6034",
            "x": 56,
            "y": 343,
            "page": 1,
            "type": "signature",
            "height": 102,
            "width": 101
        }
    ],
    "signature_level": "electronic_signature",
    "signature_authentication_mode": "otp_sms",
    "redirect_urls": {
        "success": null,
        "error": null
    },
    "custom_text": {
        "request_subject": null,
        "request_body": null,
        "reminder_subject": null,
        "reminder_body": null
    }
}

Step 5: Notify the signer

You can now use the signature_link value to send an invitation to sign to this signer.

📘

Repeat the process until no signer is left to sign.

Updated 2 days ago