Title
Create new category
Edit page index title
Edit category
Edit link
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) | application/json |
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 |
Got a question? Contact us here.