Embedded envelope

AI Tools

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.

Important Authentication is important. Please ensure that any user signing through the embedded version are authenticated. You can do this by validating the email address or doing an IDV check on the user.

These endpoints allows you to create an envelope request by sending one or more documents:

Sandbox

POST https://demo.api.yotisign.com/v2/embedded-envelopes

Production

POST https://api.yotisign.com/v2/embedded-envelopes

Below 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"]

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 object

const 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 request

let result = await createEnvelope();

package com.yoti.sign;

import java.io.File;

import java.io.IOException;

import java.net.URI;

import javax.json.Json;

import javax.json.JsonObject;

import javax.json.JsonReader;

import org.apache.http.HttpResponse;

import org.apache.http.client.methods.HttpPost;

import org.apache.http.entity.ContentType;

import org.apache.http.entity.mime.MultipartEntityBuilder;

import org.apache.http.impl.client.CloseableHttpClient;

import org.apache.http.impl.client.HttpClients;

public class Example {

private static final String YOTI_SIGN_AUTH_TOKEN = "<YOUR_AUTH_TOKEN>";

private static final String YOTI_SIGN_BASE_URL = "https://api.yotisign.com/v2";

public static void main(String[] args) {

// Create the client and HttpRequest

<?php

use GuzzleHttp\Client;

use GuzzleHttp\Psr7\MultipartStream;

use GuzzleHttp\Psr7\Request;

use function GuzzleHttp\Psr7\stream_for;

$options = [

'file_name' => 'example-document.pdf',

'name' => 'Sign your request for..',

'emails' => [

'invitation' => [

'body' => [

'message' => 'Please sign the example document',

'recipients' => [

[

'name' => 'John Smith',

'email' => 'example@example.com',

'role' => 'Signee',

'auth_type' => 'no-auth',

'sign_group' => 1,

'tags' => [

[

'page_number' => 1,

using (var pdfFileContent = new StreamContent(

new FileStream(

"test.pdf",

FileMode.Open,

FileAccess.Read)))

{

using (var optionsJsonContent = new StringContent(

optionsJson,

Encoding.UTF8))

{

MultipartFormDataContent multiPartContent = new MultipartFormDataContent

{

{ pdfFileContent, "file", "test.pdf" },

{ optionsJsonContent, "options" }

};

using (HttpRequestMessage request = new HttpRequestMessage

{

Method = HttpMethod.Post,

RequestUri = new Uri("https://api.yotisign.com/v2/embedded-envelopes"),

Content = multiPartContent

})

{

request.Headers.Add("Authorization", "Bearer " + yotiAuthenticationToken);

options := `{}`

payload := &bytes.Buffer{}

writer := multipart.NewWriter(payload)

_ = writer.WriteField("options", options)

file, err := os.Open("path/to.pdf")

defer file.Close()

formFile, err := writer.CreateFormFile("file",filepath.Base("path/to.pdf"))

_, err = io.Copy(formFile, file)

err = writer.Close()

req, err := http.NewRequest("POST", "<BASE_URL>/v2/embedded-envelopes", payload)

req.Header.Add("Authorization", "Bearer <API_KEY>")

req.Header.Add("Content-Type", "multipart/form-data")

req.Header.Set("Content-Type", writer.FormDataContentType())

client := &http.Client{}

response, err := client.Do(req)

if err != nil {

fmt.Println(err)

} else {

result, _ := ioutil.ReadAll(response.Body)

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:

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

Last updated on

Was this page helpful?