Embedded envelope
To see the flow of a standard envelope request please try out our demo here, switch our toggle on for embedded signing. We break down each section throughout the documentation so do continue reading.
Having an embedded flow means you can have your own branding and white label our solution.
The steps are:
- Generate envelope.
- Launch the envelope.
- Complete signing request.
- Redirect the user once the envelope is signed.
These endpoints allows you to create an envelope request by sending one or more documents:
Sandbox
POST https://demo.api.yotisign.com/v2/embedded-envelopesProduction
POST https://api.yotisign.com/v2/embedded-envelopesBelow is an example of the full request for creating an envelope.
{ "name": "envelope name", "emails": { "invitation": { "body": { "message": "Please sign this document" } } }, "recipients": [ { "name": "User 1", "email": "user1@gtest.com", "role": "Signee", "auth_type": "no-auth", "sign_group": 1, "tags": [ { "page_number": 1, "x": 0.1, "y": 0.1, "type": "signature", "optional": false, "file_name": "myfile.pdf" } ], "event_notifications": ["signer_invitation", "envelope_completion"] } ], "notifications": { "destination": "https://mysite.com/events", "subscriptions": [ "envelope_completion" ] }, "branding": { "logo_options": { "logo_choice": "brand_powered_by_yoti", "logo_base64": "base64-encoded-PNG-image" }, "primary_color": "#000", "primary_color_hover": "#c0c0c0", "on_primary_color": "#fff", "secondary_color": "#00ffff", "secondary_color_hover": "#d2691e" }, "parent_redirect_urls":{ "success":"https://someurl.com/success", "failure":"https://someurl.com/failure" }}Event Notifications
Event notifications must be present for embedded envelopes. An empty array means an event notification will not be sent. Accepted notifications are "signer_invitation" or "envelope_completion". These are for the recipient, who will receive an email notification from these events.
Example code
const rp = require("request-promise");const fs = require("fs");const options = {}; //options objectconst createEnvelope = () => { const request = { method: "POST", uri: `<BASE_URL>/v2/embedded-envelopes`, formData: { file: fs.createReadStream("path/to.pdf"), options: JSON.stringify(options), }, headers: { authorization: "Bearer <API_KEY>", }, }; return rp(request) .then((body) => body) .catch((err) => err);};//send requestlet result = await createEnvelope();Expected response
On success Yoti returns a 200 and a JSON object in the following format:
{ "envelope_id": <uuid>, "recipients": [ { "token": <uuid>, "email": <string> } ]}This envelope ID will be used to view the envelope status and retrieve the completed signed document.
Launch envelope
To launch an embedded envelope, render it using one of the following URLs.
Production:https://www.yotisign.com/embedded/sign/{your_token}Sandbox:https://demo.www.yotisign.com/embedded/sign/{your_token}The example below demonstrates the use of an iframe:
<iframe style="border:none;" width="100%" height="750px" src="https://www.yotisign.com/embedded/sign/{your_token}" allowfullscreen></iframe>Error codes
| Error code | Description |
|---|---|
| 400 | Bad Request, example: id provided not a UUID |
| 401 | Unauthorised request, example: requesting the status on an envelope you are not authorised to view |
| 403 | Forbidden, requesting user did not create the envelope |
| 413 | The combined file sizes have exceeded the 20MB limit |
| 422 | The request body did not pass validation |