Customer Letter
Here we will show you how to generate the Post Office in branch verification customer letter which contains;
- Applicant information
- List of documents
- Branch address
- Further information.
- A QR code that the person in branch will be required to scan.
Fetch session config
This endpoint will retrieve the session configuration, and also provide the requirement ID to be used for the instructions. This will be in a UUID format per document requested, and can be found in the required_resources array per document.
GET https://api.yoti.com/idverify/v1/sessions/{sessionId}/configurationSDK Example:
x
const { RequestBuilder} = require("yoti");const request = new RequestBuilder() .withBaseUrl("https://api.yoti.com/idverify/v1") .withPemFilePath("<YOTI_KEY_FILE_PATH>") // file path to PEM file .withEndpoint("/sessions/<sessionId>/configuration") .withMethod("GET") .withQueryParam("sdkId", "<YOTI_CLIENT_SDK_ID>") .build();// get Yoti responseconst response = await request.execute();Example Response
{ "session_id": "c02daa68-ec36-4687-9d4f-090a54b575cc", "client_session_token_ttl": 2100341, "requested_checks": [], "applicant_profile": {}, "capture": {}, "sdk_config": {}, "track_ip_address": true}Error Response
// 400 response{ "code": "MALFORMED_REQUEST", "errors": [ { "property": "header.X-Yoti-Auth-Token", "message": "must not be null or empty" } ]}| Error code | Description |
|---|---|
| 400 | malformed request |
| 401 | unauthorised request, wrong key used |
| 404 | no session found matching the sessionId provided |
| 409 | cannot begin this session until integrator provides all required resources |
| 503 | service is unavailable |
Generate Customer Letter
This endpoint will generate the letter that the applicant needs to complete the IBV session.
PUT https://api.yoti.com/idverify/v1/sessions/{sessionId}/instructionsSDK Example
const { RequestBuilder} = require("yoti");const request = new RequestBuilder() .withBaseUrl("https://api.yoti.com/idverify/v1") .withPemFilePath("<YOTI_KEY_FILE_PATH>") // file path to PEM file .withEndpoint("/sessions/<sessionId>/instructions") .withPayload(new Payload(INSTRUCTIONS_OBJ)) .withMethod("PUT") .withQueryParam("sdkId", "<YOTI_CLIENT_SDK_ID>") .build();// get Yoti responseconst response = await request.execute();Example
See below for a complete payload. This will just return a null body.
{ "contact_profile": { "first_name": "John", "last_name": "Doe", "email": "john.doe@gmail.com" }, "documents": [ { "requirement_id": "someIdDocumentRequirementId", "document": { "type": "ID_DOCUMENT", "country_code": "GBR", "document_type": "PASSPORT" } }, { "requirement_id": "someSupplementaryDocumentRequirementId", "document": { "type": "SUPPLEMENTARY_DOCUMENT", "country_code": "GBR", "document_type": "UTILITY_BILL" } } ], "branch": { "type": "UK_POST_OFFICE", "fad_code": "12345678" }}Error Response
//400 response{ "code": "PAYLOAD_VALIDATION", "message": "There were errors validating the payload", "errors": [ { "property": "The JSON property name", "message": "The error message associated with the property" } ]}| Error code | Description |
|---|---|
| 400 | payload validation error |
| 401 | unauthorised request, wrong key used |
| 404 | the referenced application does not exist |
| 409 | the session has expired |
| 500 | internal server error |
| 503 | service is unavailable |
Retrieving Customer Letter
This endpoint is used to pull the generated letter in a PDF format, which you can then send to the applicant.
GET https://api.yoti.com/idverify/v1/sessions/{sessionId}/instructions/pdfSDK Example
const fs = require('fs');const { RequestBuilder } = require("yoti");const request = new RequestBuilder() .withBaseUrl("https://api.yoti.com/idverify/v1") .withPemFilePath("<YOTI_KEY_FILE_PATH>") // file path to PEM file .withEndpoint("/sessions/<sessionId>/instructions/pdf") .withMethod("GET") .withQueryParam("sdkId", "<YOTI_CLIENT_SDK_ID>") .build();// get Yoti response, buffer set to true for executeconst response = await request.execute(true);// get parsed responseconst instructions = response.getParsedResponse();// Decode instructions octet stream to base64const base64 = instructions.toString('base64');// Convert base64 to pdf bufferconst pdf = Buffer.from(base64, 'base64');// Write pdf buffer to fileconst fileName = 'instructions.pdf';fs.writeFile(fileName, pdf, (error) => { if (error) throw error; console.log(`PDF saved to ${fileName}`);});PDF Example
Important - The use of the Post Office branded customer letter is mandatory for the In-Branch Verification service.
Error Response
//400 response{ "code": "PAYLOAD_VALIDATION", "message": "There were errors validating the payload", "errors": [ { "property": "The JSON property name", "message": "The error message associated with the property" } ]}| Error code | Description |
|---|---|
| 400 | payload validation error |
| 401 | unauthorised request, wrong key used |
| 404 | the referenced application does not exist |
| 409 | the session has expired |
| 500 | internal server error |
| 503 | service is unavailable |
Was this page helpful?