Embedded Signing (GET /v2.0/envelopes/{envelopeId}/generate_embedded_url/{signerEmail})
Embedded Signing enables users to view and sign the document directly on a web application using an iFrame.
Prerequisites
There are a few configurations required to enable Embedded Signing flow.
-
Generate signing URL using API request. Using an API endpoint user can create a signing URL; keep in mind that the signing URL expires after 600 seconds (10 minutes). You will need to generate a new signing URL when the older one gets expired.
-
View signing request in user interface. Once you received the signing URL, the next step is to load it into the user interface. To make the flow work, include the following code on your web application:
<script type="text/javascript" src="https://app.jsign.com/script/embeddedsignhandler.js"></script>
After adding the javascript, include the following code and specify all required options to display an iFrame:
embeddedjSign.open({
url: EMBEDDED_SIGNING_URL,
containerID: containerID,
events: {
loaded: function () {
console.log("loaded callback");
},
signed: function () {
console.log("signed Callback");
},
declined: function () {
console.log("declined Callback");
},
error: function () {
console.log("error Callback");
}
}
});
Parameter Details
| Parameter | Detail |
|---|---|
| URL | Embedded signing URL retrieved from API request. |
| containerID | ID of an element (such as div) where you want to place your iFrame. |
| events.loaded | This callback function triggers when the iFrame finishes loading. |
| events.signed | This callback function triggers when the document is signed. |
| events.declined | This callback function triggers if the document is declined. |
| events.error | This callback function triggers when an error occurs in the iFrame loading or signing process. |
Request Parameters
Request Headers
| Header | Value |
|---|---|
| Authorization | Bearer {access_token} |
| app_auth_type | jsign-oauth2 |
Request Parameters
| Field | Type | Required | Description |
|---|---|---|---|
| envelopeId | GUID | Yes | Envelope ID for which embedded signing URL is to be generated. |
| signerEmail | string | Yes | Email of signer for whom the embedded signing URL is to be generated. |
Response Parameters
Response Body Message Field
| Field | Value |
|---|---|
| message | The returned message |
Response Body Data Fields
| Field | Always Present? | Notes |
|---|---|---|
| embedded_sign_url | Yes | Embedded signing URL |
| expires_at | Yes | Expiration time (UNIX timestamp) |
Sample Success Response
REQUEST:
curl --location --request GET 'api/v2.0/envelopes/dc9f8e29-9519-4a1a-8983-626a54509398/generate_embedded_url/[email protected]' \
--header 'Authorization: Bearer eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9'
--header 'app_auth_type: jsign-oauth2' \
RESPONSE:
{
"message": "",
"data": {
"embedded_sign_url": ""https://example.com/envelope/embeddedSign?et=37485f78-7014-4181-a096-e7eb8247a8de",",
"expires_at": 1639051366
}
}
Sample Error Response
REQUEST:
curl --location --request GET 'api/v2.0/envelopes/dc9f8e29-9519-4a1a-8983-626a54509398/generate_embedded_url/jon.smithemail.com'' \
--header 'Authorization: Bearer eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9'
--header 'app_auth_type: jsign-oauth2' \
RESPONSE:
{
"errors": [
{
"error_code": "SIGNER_EMAIL_INVALID",
"developer_message": "Signer Email is invalid."
}
]
}
Note: View the full list of applicable error code for this method here.