Yoti envelope

AI Tools

To see the flow of a standard envelope request please try out our demo here. We break down each section throughout the documentation so do continue reading.

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

Sandbox

HTTP
    
 
POST https://demo.api.yotisign.com/v2/envelopes
Copy

Production

HTTP
    
 
POST https://api.yotisign.com/v2/envelopes
Copy

Below is an example of the full request for creating an envelope.

JSON
    
 
{    "name": "envelope name",    "emails": {        "invitation": {            "body": {                "message": "Please sign this document"            }        },      "reminders": {          "frequency": 1      }    },    "sender": {        "event_notifications": ["envelope_completion"]    },    "has_envelope_otps": true,    "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"                }            ],            "iso_country_code": "GB",            "mobile_number": 7999999999,            "witness": {              "tags": [                ...              ]            }        }    ],    "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"    }}
Copy

Example code

Javascript
Java
PHP
C#
Go
    
​x
 
const rp = require("request-promise");const fs = require("fs");​const options = {}; //options object​const createEnvelope = () => {  const request = {    method: "POST",    uri: `<BASE_URL>/v2/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();
Copy

Expected response

On success Yoti returns a 202 and a JSON object in the following format:

JSON
    
 
{    "envelope_id": "<envelopeId>"}
Copy

This envelope ID will be used to view your the envelope status and retrieve the document.

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?