Create a session
This section will show you how to:
- Authenticate the request
- Create a session
Authentication
From here on, each endpoint requires an RSA-signed request for Authentication. This can either be constructed manually or via one of our backend SDKs. The Yoti SDK exposes a simple request builder class to support the authentication process, and the examples provide snippets of this usage in each endpoint code snippet. You will need your Yoti SDK ID and application key pair for either process.
The method is detailed below if you prefer to authenticate without the SDK.
Generate signed request
Yoti API endpoints are authenticated through signed requests, and the current approach for building signed requests consists of passing the following HTTP Header:
- X-Yoti-Auth-Digest
Here's how to compute it:
- Concatenate the HTTP method, the path, the query string (enriched with a timestamp and a nonce parameter) and the base64 encoded request body, if available, using the & character.
Example GET request:
GET GET&/sessions?sdkId=b88ad843-13cc-44ba-a3e0-053f71d89b1f&nonce=b88ad843-13cc-44ba-a3e0-053f71d89b1f×tamp=1480509893Example POST request:
POST POST&/sessions?sdkId=b88ad843-13cc-44ba-a3e0-053f71d89b1f&nonce=b88ad843-13cc-44ba-a3e0-053f71d89b1f×tamp=1480509893&ew0KImlkIiA6IDEsDQoibmFtZSIgOiBpdGVtDQoNCn0=- Apply SHA256withRSA to the string generated from step 1, using your PEM private key generated from the Yoti Hub.
- Base64 encode the result from 2, so that it can be sent as a string header.
The API Base URL is https://api.yoti.com/idverify/v1
| Parameter | Description |
|---|---|
| sdkId | UUID generated when producing your Yoti keys |
| nonce | Nonces are UUID strings |
| timestamp | UNIX timestamps (number of elapsed seconds since Jan 1st 1970) |
SDK request builder
Please use our Yoti SDKs to automatically build the relevant request. The Yoti SDKs are available via popular dependency management systems.
npm install -S -E yoticonst { RequestBuilder, Payload } = 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") .withPayload(new Payload(SESSION_OBJ)) .withMethod("POST") .withQueryParam("sdkId", "<YOTI_CLIENT_SDK_ID>") .build();//get Yoti responseconst response = await request.execute();Create session
You can use it to build and send your session as shown in the code snippet below. For the claimed ID version you will need to ensure you have captured applicant details including:
- Applicant information: Name, DOB and Address.
- Which three documents they will be bringing to the branch.
- A branch look up service.
This information is needed at a minimum to fulfil the DBS requirements.
POST https://api.yoti.com/idverify/v1/sessionsExample Payloads
{ "session_deadline": "2023-10-15T22:00:00Z", "resources_ttl": "604800", "ibv_options": { "support": "MANDATORY" }, "user_tracking_id": "optional_string", "notifications": { "endpoint": "https://some-domain.example", "topics": [ "INSTRUCTIONS_EMAIL_REQUESTED", "THANK_YOU_EMAIL_REQUESTED", "SESSION_COMPLETION" ] }, "requested_checks": [ { "type": "IBV_VISUAL_REVIEW_CHECK", "config": { "manual_check": "IBV" } }, { "type": "PROFILE_DOCUMENT_MATCH", "config": { "manual_check": "IBV" } }, { "type": "DOCUMENT_SCHEME_VALIDITY_CHECK", "config": { "manual_check": "IBV", "scheme": "UK_DBS" } } ], "required_documents": [ { "type": "ID_DOCUMENT", "filter": { "type": "DOCUMENT_RESTRICTIONS", "inclusion": "WHITELIST", "documents": [ { "country_codes": ["GBR"], "document_types": ["PASSPORT"] } ] } }, { "type": "ID_DOCUMENT", "filter": { "type": "DOCUMENT_RESTRICTIONS", "inclusion": "WHITELIST", "documents": [ { "country_codes": ["GBR"], "document_types": ["DRIVING_LICENCE"] } ] } }, { "type": "SUPPLEMENTARY_DOCUMENT", "document_types": ["UTILITY_BILL"], "country_codes": ["GBR"], "objective": { "type": "UK_DBS" } } ], "resources": { "applicant_profile": { "full_name": "John James Doe", "date_of_birth": "1988-11-02", "structured_postal_address": { "address_format": 1, "building_number": "74", "address_line1": "74 First Address Line", "town_city": "London", "postal_code": "E14 3RN", "country_iso": "GBR", "country": "United Kingdom" } } }}| Name | Description | Optional |
|---|---|---|
| session_deadline | This is in a datetime format. The user has up until this date and time to complete the session. The customer letter will only show the date, not the time, and therefore we recommend setting the time to 22:00 to ensure a candidate has the entire day to enter a Post Office branch. This must be a minimum of 7 days. | |
| resources_ttl | This sets the retention time for images, document data and the applicant profile data in the session. This timer must be configured to be at least 24 hours longer than your session_deadline. It starts from the first media upload. | |
| user_tracking_id | Allows the relying business backend to track the same user across multiple sessions. Note: This should not contain any personal identifiable information | ✅ |
| ibv_options | Outlines that an IBV session is being generated. |
Notifications
This service optionally posts an update notification every time the session state changes, based on the selected subscription topics.
| Name | Description |
|---|---|
| NEW_PDF_SUPPLIED | You can subscribe to be notified when the user has got the PDF. Only relevant when using the At home flow. |
| INSTRUCTIONS_EMAIL_REQUESTED | If you do not enable this notification an email will automatically be sent to the user with their instructions. If you do enable this notification the email service will be revoked and you will need to configure this set up yourself. Yoti will send an async notification to prompt you to retrieve the PDF from Yoti and send it to the customer. |
| THANK_YOU_EMAIL_REQUESTED | Enabling this notification suppresses the final email a user receives after completing their journey in the branch. You may want to enable this if planning to send your own completion email. |
| FIRST_BRANCH_VISIT | This notification is triggered when an applicant has had their customer letter QR code scanned in a Post Office branch for the first time. The notification could be used to assess whether a customer has visited a branch location, but been turned away due to no follow up session completion. |
| SESSION_COMPLETION | Triggered when all tasks and all checks inside of a given session have been completed. |
Requested In Person Checks
| Check | Description |
|---|---|
| PROFILE_DOCUMENT_MATCH | Checks the document the applicant brought with them matches the submitted applicant profile. |
| DOCUMENT_SCHEME_VALIDITY_CHECK | Checks the documents themselves fit within the rule of that scheme. E.g. DBS have rules of bills and expiry e.g. valid for the last 3 months or issued within X time. |
| IBV_VISUAL_REVIEW_CHECK | A visual review of the document by the postmaster. |
Additional Optional Checks
This service is highly configurable, if you would like assistance in using any of the checks below please get in touch with our client support team through support.yoti.com.
| Check | Description |
|---|---|
| Document authenticity | A request to assess the characteristics of a document, to determine the validity of the ID document. Yoti will perform multiple checks on a ID document. |
| Text extraction | A request to obtain the data printed visually on a document, in sta ructured form. |
| Supporting documents | Yoti offers the ability to request additional documents to enhance the verification of the user. |
| Document comparison | If you request your users to upload more than one document we offer the ability to cross check the data |
| Face match check | A request to assess whether the user's face matches the face on the ID document. |
| Address check | This check will facilitate an extra verification of a user by searching a person’s details against a collated database from various sources worldwide. |
| AML check | Extend the Identity verification integration by requesting an watchlist, PEPs and sanctions check as part of a session. |
Required documents
Please check out the overview page for which documents we support. In the example below and above, three documents are being set for the applicant (each document is one object in the list).
"required_documents": [ { "type": "ID_DOCUMENT", "filter": { "type": "DOCUMENT_RESTRICTIONS", "inclusion": "WHITELIST", "documents": [ { "country_codes": [ "GBR" ], "document_types": [ "PASSPORT" ] } ] } }, { "type": "ID_DOCUMENT", "filter": { "type": "DOCUMENT_RESTRICTIONS", "inclusion": "WHITELIST", "documents": [ { "country_codes": [ "GBR" ], "document_types": [ "DRIVING_LICENCE" ] } ] } }, { "type": "SUPPLEMENTARY_DOCUMENT", "document_types": [ "UTILITY_BILL" ], "country_codes": [ "GBR" ], "objective": { "type": "UK_DBS" } } ],| Name | Description |
|---|---|
| type | Outlines the type of documents required. Either an ID document or supplementary document. |
Applicant Profile
This is the customer information you will collect before generating the session.
| Name | Type | Description | Example |
|---|---|---|---|
| full_name | String | FullName contains given names and family name. | “Jon Jim Foo” |
| date_of_birth | String | DateOfBirth is the date of birth in the form yyyy-mm-dd. | "2000-12-01" |
| structured_postal_address | Object | StructuredPostalAddress is the postal address with the breakdown in address lines, post code and so on as well as the formatted address all in one line. See details for structured_postal_address JSON properties below. | See below |
Structured Postal Address
| Field name | Type | Description |
|---|---|---|
| address_format | number | AddressFormat is used to identify which fields may be present in the JSON object. See table below that defines what format is used for each country. |
| udprn | string | Udprn is the Unique Delivery Point Reference Number that identifies a property throughout its lifecycle. |
| care_of | string | CareOf identifies the owner of the premises. |
| sub_building | string | SubBuilding is used when the building is divided into smaller units (e.g. a block of flats) to identify the sub unit. |
| building_number | string | BuildingNumber is the number of the building. |
| building | string | Building is the name/number of the building. |
| street | string | Street is the name/number of the street the building is on. |
| landmark | string | Landmark is a description used to describe the location of the building. |
| address_line1 | string | AddressLine1 is the first line of the address. |
| address_line2 | string | AddressLine2 is the second line of the address. |
| address_line3 | string | AddressLine3 is the third line of the address. |
| address_line4 | string | AddressLine4 is the fourth line of the address. |
| address_line5 | string | AddressLine5 is the fifth line of the address. |
| address_line6 | string | AddressLine6 is the sixth line of the address. |
| locality | string | Locality is the area the building is in. |
| town_city | string | TownCity is the town/city/village/hamlet/community/etc. that the building is in. |
| subdistrict | string | Subdistrict is the sub-district the building is in. |
| district | string | District is the district the building is in. |
| state | string | State is the state/county the building is in. |
| postal_code | string | PostalCode is a code used by the country's postal service to aid in sorting and delivering mail (e.g. postcode, zipcode, pincode). |
| post_office | string | PostOffice is the post office that serves the area the building is in. |
| country_iso | string | CountryIso is the country the building is in. In ISO-3166-1 alpha-3 format. |
| country | string | Country is the country the building is in. Localised. |
| formatted_address | string | FormattedAddress is the full address in a single human readable string in a format that is suitable for printing onto an envelope. This field is not required when providing address information. |
The below defines the fields of the JSON structure used for all addresses. A subset of fields will be present in each case and address_format can be used to ascertain which ones for any given address. The country iso should not be used for this purpose.
Four address formats are available and detailed below:
| Countries that use this format | GBR, JEY, IMN | IND | USA, AUS | All other countries |
| address_format | 1 | 2 | 3 | 4 |
| udprn | Optional | |||
| care_of | Optional | |||
| sub_building | Optional* | |||
| building_number | Optional* | |||
| building | Optional* | Optional | ||
| street | Optional | |||
| landmark | Optional | |||
| address_line1 | Mandatory | Mandatory | Mandatory | |
| address_line2 | Optional | Optional | Optional | |
| address_line3 | Optional | Optional | ||
| address_line4 | Optional | |||
| address_line5 | Optional | |||
| address_line6 | Optional | |||
| locality | Optional | |||
| town_city | Mandatory | Optional | Mandatory | |
| subdistrict | Optional | |||
| district | Optional | |||
| state | Optional | Optional | Mandatory | |
| postal_code | Mandatory | Mandatory | Mandatory | Optional |
| post_office | Optional | |||
| country_iso | Mandatory | Mandatory | Mandatory | Mandatory |
| country | Mandatory | Mandatory | Mandatory | Mandatory |
| formatted_address** | Mandatory | Mandatory | Mandatory | Mandatory |
** At least one must be present
*** Will always be returned in the data extraction, but is not mandatory when configuring an applicant profile
Example response
If the request is successful and a session is generated the API will send a response in the form:
{ "client_session_token_ttl": 599, "client_session_token": "<uuid>", "session_id": "<uuid>"}| Name | Description |
|---|---|
| client_session_token_ttl | Time in seconds until the client session expires |
| client_session_token | Used to authenticate the session |
| session_id | ID of the session |
Error Responses
If the request is unsuccessful you will receive one of the below error responses in the form:
// 400 response{ "code": "PAYLOAD_VALIDATION", "errors": [ { "property": "requested_checks", "message": "must not be empty" } ]}| Error code | Description |
|---|---|
| 400 | payload validation error |
| 401 | unauthorised request, wrong key used |
| 403 | application is disabled or no associated organisation id |
| 404 | the application for provided sdk id does not exist |
| 503 | service is unavailable |