Get envelope
This endpoint allows you to query the Yoti Sign API for the current state of an envelope request:
Sandbox:GET https://demo.api.yotisign.com/v2/envelopes/<envelopeId>Production: GET https://api.yotisign.com/v2/envelopes/<envelopeId>Header explained
The following elements are needed:
| Header | Description |
|---|---|
| Authorization (header) | API Key to call the Yoti Sign API. This should be sent as a bearer token. |
| Content-Type (header) | multipart/form-data |
Response
On success, we return a 200 with a JSON body matching the following schema. The response seen whilst the files are being processed and the envelope is being sealed is shown below:
{ "envelope_id": "<envelopeId>", "status": "QUEUED"}Click the tabs for different status responses:
{ "envelope_id": "<envelopeId>", "status": "ACTIVE", "details": { "recipients": [ { "id": "uuid", "sign_status": "UNSIGNED", "name": "name1", "email": "email1@email.com", "auth_type": "sign-auth", "role": "Signee" } ] }}For a completed envelope, and extra details which are included in the response will appear as 'tags' in the response body.
Status
This is the status of the envelope.
| Status | Description |
|---|---|
| QUEUED | The envelope is being processed, before being sent to the recipients. |
| ACTIVE | The envelope has been successfully sent to recipients. |
| ARCHIVED | The envelope has been archived. |
| COMPLETE | The envelope has been signed by all the recipients. |
| ERRORED | There has been an error in the creation of the envelope |
Details
This will contain all the relevant details for the envelope including recipients or errors.
Sign_Status
This is the status of the envelope.
| Status | Description |
|---|---|
| SIGNED | The envelope has been signed.
|
| UNSIGNED | The envelope has not been signed. |
Additional
These fields will appear in certain scenarios:
| Attribute | Description |
|---|---|
| errors | If an error occurs then you will be provided with the file name causing the error if applicable and an error message (see below for a list of error messages) |
| signed_at | UTC Timestamp for when the recipient has signed the document |
| archived_at | UTC Timestamp for when the envelope has been Archived |
Example code
const rp = require("request-promise");const getEnvelope = () => { const request = { method: "GET", uri: "https://api.yotisign.com/v2/envelopes/<envelopeId>", headers: { authorization: "Bearer <API_KEY>", }, }; return rp(request) .then((body) => body) .catch((err) => err);};//send requestlet result = await getEnvelope();Error codes
If the request is unsuccessful a response code and a message will be sent:
| Response | Description |
|---|---|
| 400 | Bad Request, example: id provided not a UUID |
| 401 | Unauthorised request, example: requesting the status on an envelope you are not authorized to view |
| 403 | Forbidden, requesting user did not create the envelope |
| 404 | The envelope ID couldn’t be found |