Embedded Signing

Embedded Signing will enable your signers to sign documents within your website or mobile apps. You can embed the signing experience in an iFrame or in a pop-up/new tab.

This is a guide on building this embedded signing functionality on your app (web or mobile). You would need a master account that would be initiating signature requests. Instead of the signers receiving signing links in their email inbox, the signing links will be available to you via an API which can then be used to collect signatures from your signers when they are ready to sign.

1. Setup master account and API keys

Create an account you would use to manage all your signature requests. This will be your master account that will hold all of your data and documents. You can create a new account here.

You will then have to generate your API keys using the API Key Generator.

🚧

Not for use in production

The keys generated by the API key generator are strictly for development purposes and not intended for use in production. Developer API keys will expire in 30 days.

2. Import the document that needs to be signed

Once you have identified the document that you want to be signed, upload the document using the API key generated in the previous step. The API to be used for uploading/importing a new document is here.

Note the id in the response of the API. This will be needed in order to send this file for signature.

The envelope API supports upto 20 documents(a combination of both originals and templates) to be sent out for signatures for your signers. All the files that are to be sent out for signature should be added to the sources array which contains the list of documents.

3. Create a signature request for that document/documents

Create a signature request (with or without fields), using the id of the original document from Step #2.

📘

Important

Please ensure that the embedded_signing parameter in the envelope API request is set to true/1. This means that there'll be no email communication from Signeasy towards your signers.
If you would still like to leverage our email communication service and notify your signers, just send the embedded_signing parameter to be false/0.

You would have to add the email address of the signer in the recipients array, as part of the body parameters along with the other required parameters. Even though the signers will not receive any emails, email addresses are still required to generate the audit trail at the end and for regulatory reasons.

Note the id in the response. This will be the pending_file_id of the signature request you just initiated.

Using Templates

You can send a combination of templates and originals, just originals or just templates with our envelope API.

Sample Envelope API Request

curl --location --request POST 'https://api.signeasy.com/v2.1/rs/envelope/' \
--header 'Authorization: Bearer **{{access_token}}**' \
--header 'Content-Type: application/json' \
--data-raw '{
    "embedded_signing": true,
    "sources": [{
        "source_id": 1,
        "type": "original",
        "id": 55590502
    },{
        "source_id": 2,
        "type": "original",
        "id": 50004293
    }],
    "is_ordered": 0,
    "recipients": [{
        "first_name": "john",
        "last_name": "doe",
        "email": "[email protected]",
        "recipient_id": 1
    },{
        "first_name": "jacob",
        "last_name": "Doe",
        "email": "[email protected]",
        "recipient_id": 2
    }],
    "message": "Envelope API Demo with 2 Originals",
    "recipient_role_mapping": [{
        "role_id": 1,
        "recipient_id": 1,
        "source_id": 1
    },{
        "role_id": 2,
        "recipient_id": 2,
        "source_id": 1
    }],
    "fields_payload": [
        {
            "recipient_id": 1,
            "source_id": 1,
            "type": "signature",
            "required": true,
            "page_number": 1,

            "position": {
                "text": "signeasy",
                "height": 50,
                "width": 50,
                "mode": "referenceText"
            },
    "additional_info": {}
        },
         {
            "recipient_id": 2,
            "source_id": 2,
            "type": "signature",
            "required": true,
            "page_number": "all",

            "position": {
                "x": 200,
                "y": 300,
                "height": 50,
                "width": 50,
                "mode": "fixed"
            },
    "additional_info": {}
        }
    ],
    "signature_panel_types": ["draw"]
}'

curl --location --request POST 'https://api.signeasy.com/v2.1/rs/envelope/' \
--header 'Authorization: Bearer **{{access_token}}**' \
--header 'Content-Type: application/json' \
--data-raw '{
    "embedded_signing": true,
    "sources": [{
        "source_id": 1,
        "type": "template",
        "id": 4228166
    },{
        "source_id": 2,
        "type": "template",
        "id": 4238638
    }],
    "is_ordered": 0,
    "recipients": [{
        "first_name": "john",
        "last_name": "doe",
        "email": "[email protected]",
        "recipient_id": 1
    },{
        "first_name": "jacob",
        "last_name": "Doe",
        "email": "[email protected]",
        "recipient_id": 2
    }],
    "message": "Envelope API Demo with 2 Originals",
    "recipient_role_mapping": [{
        "role_id": 1,
        "recipient_id": 1,
        "source_id": 1
    },{
        "role_id": 2,
        "recipient_id": 2,
        "source_id": 1
    }],
     "merge_fields": [
        {
            "label": "mergeLabel1",
            "value": "John",
            "source_id": 1
        },
        {
            "label": "mergeLabel2",
            "value": "Jacob",
            "source_id": 2
        }
    ],
    "fields_payload": [
        {
            "recipient_id": 1,
            "source_id": 1,
            "type": "signature",
            "required": true,
            "page_number": 1,

            "position": {
                "text": "signeasy",
                "height": 50,
                "width": 50,
                "mode": "referenceText"
            },
    "additional_info": {}
        },
         {
            "recipient_id": 2,
            "source_id": 2,
            "type": "signature",
            "required": true,
            "page_number": "all",

            "position": {
                "x": 200,
                "y": 300,
                "height": 50,
                "width": 50,
                "mode": "fixed"
            },
    "additional_info": {}
        }
    ],
    "signature_panel_types": ["draw"]
}'

4. Get your signers to sign the document

For each signer who needs to now sign on your website, you will first need the signing URL which lets them sign the document. This signing URL can be embedded on your website/app as an iframe or pop-up.

Get the signing URL using these APIs:
Envelope API
[Without Fields] (https://docs.signeasy.com/reference/fetch-signing-link-2)

using the pending_file_id from Step #3 and email address of the signer who needs to sign.

The URL you receive in the response can now be used to have the document signed by your signers from within your application. You can also use a link shortener and send links via various messaging services like WhatsApp, Facebook etc.

📘

Signers need to be logged in or verified!

Ensure that your signers are logged in to their user accounts on your site/app before you let them sign the documents using the signing URL. This is to ensure that the identity of the signers is validated (using your application login) before they sign the document.

This is necessary if you want your signatures to be legally binding.

The audit trails generated will contain information on whether Signeasy has verified the identity of the signers. In case of documents signed via embedded signing, this would be false.

If there is ever a dispute raised by your customers on the veracity or identity of the signing parties, you will be required to provide proof for the same.

5. Be notified of the signing activity

Once the signers have signed the document, you would usually want to be notified so that you can kick off the next step in the workflow or update the status of the document on your dashboard.

You can be notified about document signing activity in a couple of ways - webhooks or redirect URL.

Redirect URL

You can redirect the signer to a URL of your choice once they have finished signing the document so that the control is passed back to you after Step #4.

Once a signer has finished signing, they will be redirected to the URL specified along with pending_file_id of the signature request they just signed. Use this pending file ID to fetch the latest status of the document and show an appropriate message or screen to the signer. The signers are redirected to your URL, even in cases where they decline the signature request.

Redirect URL can be set, when you call the embedded signing link using the redirect_url parameter.

Webhooks

Setup a webhook receiver on your backend, and we will ping you whenever there is any activity on your signature requests along with the details of the request. Read about all the different kinds of webhooks and how to use them here.

6. Download the signed document

Once all signers in a signature request have finished signing, you will be able to download the completed document from the signed_file_id using the signed file download APIs

Envelopes as Zip
Envelopes as individual pdfs
Without Fields
Using Templates

You can get the "signed_file_id" either from rs.completed webhook or Retrieve Signed File details using pending ID that you'd receive from Step #5.