Yoti envelope
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
POST https://demo.api.yotisign.com/v2/envelopesProduction
POST https://api.yotisign.com/v2/envelopesBelow is an example of the full request for creating an envelope.
{ "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" }}Example code
x
const rp = require("request-promise");const fs = require("fs");const options = {}; //options objectconst 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();Expected response
On success Yoti returns a 202 and a JSON object in the following format:
{ "envelope_id": "<envelopeId>"}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 |
Was this page helpful?