HomeAPI ReferenceAPI StatusSupportChangelog

Embedded Signing

Suggest Edits

Integrate seamless in-app contract signing with Signeasy e-Signature API's Embedded Signing workflow. This API-driven approach bypasses traditional email invitations, letting you embed the signing experience directly within your web or mobile app (iFrame or pop-up/new tab). This guide explains how you can Initiate signature requests, generate signing links via API, and seamlessly collect e-signatures without ever leaving your app's user flow.

📘

Prerequisites

Signeasy developer account

To get started, you'll need a Signeasy Developer account to manage the OAuth applications and its associated data. This account will be also your central repository for your contracts. If you haven't created an account already, go ahead and create the developer account.

API access token

You will then need a bearer token to authenticate with Signeasy platform and make API requests. If you're exploring the e-Signature API, generate a test token. For production e-signature transactions, generate a live token.

1. 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 using the import a new document endpoint.

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

The create an envelope RS originals + templates API supports upto 20 documents(a combination of both originals and templates) to be sent out for signatures to 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.

2. Create a signature request for that document(s)

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

📘

Difference between Embedded and Non-Embedded signing

Setting the value of embedded_signing parameter in the envelope API request is to true or 1 will create an embedded signature request. For embedded signature requests, no emails will be sent from Signeasy to the recipients. In this embedded signing workflow, you'll have to generate signature links for each recipients.

Setting the embedded_signing parameter to false or 0, will create a non-embedded signature request, where Signeasy will notify the recipients via email.

You would have to add the email address of the signer(s) 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 purposes.

On successful request, the API responds with an id. This is the pending_file_id of the signature request you initiated and in the later steps, you'll be using this to generate the signing URL along with the recipient email address.

Using Templates

You can also send a combination of templates and originals by defining the type and id of each document types in the request.

Sample Envelope API Request

curl --location --request POST 'https://api.signeasy.com/v3/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/v3/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"]
}'

3. Get your signers to sign the document

For each signer to sign within your website, you will need a unique signing URL for them to sign the document. This signing URL will ideally be embedded on your website/app in an iframe or pop-up.

Get the signing URL using these APIs:

  1. Fetch signing link for envelopes created with fields
  2. Fetch signing link for envelopes created without fields

using the pending_file_id from Step #3 and the 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 termed as Identity Verified by 'Third Party'.

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.

4. 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 the 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.

5. 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.

Updated 4 months ago

What’s Next

Webhooks