This section will show you how to:
Authentication
Create the session
Fetch the session
Authentication
Please use our Yoti SDKs to automatically build the relevant session for you. First you will need the following information about your application from Yoti Hub:
There are two ways in which generate a signed request:
Generate signed request
SDK request builder.
Generate signed request
You can create your own signed request using the below endpoint:
GET /sessions?sdkId=b88ad843-13cc-44ba-a3e0-053f71d89b1f&nonce=b88ad843-13cc-44ba-a3e0-053f71d89b1f×tamp=1480509893
POST /sessions?sdkId=b88ad843-13cc-44ba-a3e0-053f71d89b1f&nonce=b88ad843-13cc-44ba-a3e0-053f71d89b1f×tamp=1480509893&ew0KImlkIiA6IDEsDQoibmFtZSIgOiBpdGVtDQoNCn0=
Concatenate the:
HTTP method
The path
The query string (enriched with a timestamp and a nonce parameter)
The base64 encoded request body, if available, using the & character
Apply SHA256withRSA to the string generated from 1. Base64 encode the result from 2, so that it can be sent as a string for the X-Yoti-Auth-Digest header.
Parameter | Description |
|---|
SDK ID | 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.
// Get the Yoti PHP SDK library via a Composer package
composer require yoti/yoti-php-sdk
// If you are using Maven, add the following dependency:
<dependency>
<groupId>com.yoti</groupId>
<artifactId>yoti-sdk-impl</artifactId>
<version>2.6.0</version>
</dependency>
// If you are using Gradle, add the following dependency:
compile group: 'com.yoti', name: 'yoti-sdk-impl', version: '2.6.0'
// As of version 2.4.0, modules are used. This means it's not necessary to get a copy or fetch all dependencies
// as instructed below, as the Go toolchain will fetch them as necessary.
// You can simply add a `require github.com/getyoti/yoti-go-sdk/v2` to go.mod.
// To download and install the Yoti SDK and its dependencies, run the following command from your terminal:
go get "github.com/getyoti/yoti-go-sdk/v2"
// To install the Yoti NuGet package you will need to install NuGet.
// To import the latest Yoti SDK into your project, enter the following
// command from NuGet Package Manager Console in Visual Studio:
Install-Package Yoti
// For other installation methods, see https://www.nuget.org/packages/Yoti
gem install yoti
# The gem provides a configuration generator for Ruby on Rails:
rails generate yoti:install
const { 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 response
const response = await request.execute();
<?php
use Yoti\Http\RequestBuilder;
use Yoti\Http\Payload;
$request = (new RequestBuilder())
->withBaseUrl('https://api.yoti.com/idverify/v1')
->withPemFilePath('<YOTI_KEY_FILE_PATH>')
->withEndpoint('/sessions')
->withPayload(Payload::fromString(SESSION_JSON_STRING)) // * Version ^2: new Payload(SESSION_OBJ)
->withMethod('POST')
->withQueryParam('sdkId', '<YOTI_CLIENT_SDK_ID>')
->build()
//get Yoti Response
->execute();
// * For JSON data in Version >3 please use Payload::fromJsonData(SESSION_OBJ)
from yoti_python_sdk.http import SignedRequest, RequestHandler
import json
import requests
def execute(request):
response = requests.request(
url=request.url, data=request.data, headers=request.headers, method=request.method)
return response.content
def generate_session():
payload = {} # payload
payload_string = json.dumps(payload).encode()
signed_request = (
SignedRequest
.builder()
.with_pem_file("<YOTI_KEY_FILE_PATH>")
.with_base_url("https://api.yoti.com/idverify/v1")
.with_endpoint("/sessions")
.with_http_method("POST")
.with_param("sdkId", "<YOTI_CLIENT_SDK_ID>")
.with_payload(payload_string)
.build()
)
# get Yoti response
response = signed_request.execute()
response_payload = json.loads(response.text)
byte[] SESSION_OBJ = ...
try {
SignedRequest signedRequest = SignedRequestBuilder.newInstance()
.withKeyPair(<YOTI_KEY_FILE_PATH>)
.withBaseUrl("https://api.yoti.com/idverify/v1")
.withEndpoint("/sessions")
.withPayload(SESSION_OBJ)
.withHttpMethod("POST")
.withQueryParameter("sdkId", "<YOTI_CLIENT_SDK_ID>")
.build();
YourPojo yourPojo = signedRequest.execute(YourPojo.class);
} catch (GeneralSecurityException | URISyntaxException | IOException | ResourceException ex) {
ex.printStackTrace();
}
import (
"io/ioutil"
"net/http"
"github.com/getyoti/yoti-go-sdk/v2/requests"
)
key, _ := ioutil.ReadFile("<YOTI_KEY_FILE_PATH>")
// Create session
request, _ := requests.SignedRequest{
HTTPMethod: http.MethodPost,
BaseURL: "https://api.yoti.com/idverify/v1",
Endpoint: "/sessions",
Params: map[string]string{
"sdkId": "<YOTI_CLIENT_SDK_ID>"
},
Headers: map[string][]string{
"Content-Type": {"application/json"},
"Accept": {"application/json"}
},
Body: func(data []byte, _ error) []byte {
return data
}(json.Marshal(jsonobj{ data },
})),
}.WithPemFile(key).Request()
//get Yoti response
response, _ := http.DefaultClient.Do(request)
using System;
using System.IO;
using System.Net.Http;
using Microsoft.AspNetCore.Mvc;
using Yoti.Auth.Web;
class ExampleClass
{
private Uri _baseUrl = new UriBuilder("https", "api.yoti.com", 443, "idverify/v1").Uri;
public void ExampleFunction()
{
HttpClient httpClient = new HttpClient();
StreamReader privateKeyStream = System.IO.File.OpenText(_pemFilePath);
byte[] byteContent = ...; // JSON Request
string clientSdkId = Environment.GetEnvironmentVariable("YOTI_CLIENT_SDK_ID");
Yoti.Auth.Web.Request docScanRequest = new RequestBuilder()
.WithKeyPair(privateKeyStream)
.WithBaseUri(_baseUrl)
.WithEndpoint("/session")
.WithPayload(byteContent)
.WithHttpMethod(HttpMethod.Post)
.WithQueryParam("sdkId", clientSdkId)
.Build();
HttpResponseMessage response = docScanRequest.Execute(httpClient).Result;
}
}
Once you have added the Yoti SDK dependency to your project, you can use it to build and send your request. See the code snippets below for examples of how to construct the session.
Create session
You can use it to build and send your session as shown in the code snippet below. 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.
Hint remember to pass the X-Yoti-Auth-Digest as a header when making the requests
POST https://api.yoti.com/idverify/v1/sessions
Example
{
"session_deadline": "2024-09-03T23:59:59.000000+00:00",
"resources_ttl": "1209600",
"ibv_options": {
"support": "MANDATORY"
},
"user_tracking_id": "some_id",
"notifications": {
"endpoint": "https://some-domain.example",
"topics": [
"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 Address Line 1",
"town_city": "CityName",
"postal_code": "E14 3RN",
"country_iso": "GBR",
"country": "United Kingdom"
}
}
}
}
Name | Description | Optional |
|---|
resources_ttl | Retention period ("time to live") for uploaded documents/images in number of seconds. Default is one week (60_60_24*7=604800). This value must be at least 24 hours longer than the client_session_token_ttl. | ✅ |
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. | ✅ |
session_deadline | This is in a date format. The user has up until this date to complete the session. Note: we also have client_session_token_ttl (seconds) to set your session expiry. |
|
client_session_token_ttl | An alternative to the session_deadline. Allows a session timer to be specified in seconds, rather than a date time. |
|
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. |
SESSION_COMPLETION | Triggered when all tasks and all checks inside of a given session have been completed. |
Requested checks
The below represents the 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. |
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" |
given_names | String | GivenNames contains first and middle names. | "Jon Jim" |
first_name | String | FirstName is the first name only. | “Jon” |
middle_name | String | MiddleName contains the middle names only. | “Jim” |
family_name | String | The family name. | “Foo” |
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>"
}
Response | 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 |
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.
GET https://api.yoti.com/idverify/v1/sessions/{sessionId}/configuration
Example
{
"session_id": "c02daa68-ec36-4687-9d4f-090a54b575cc",
"client_session_token_ttl": 2100341,
"requested_checks": [
"IBV_VISUAL_REVIEW_CHECK",
"DOCUMENT_SCHEME_VALIDITY_CHECK",
"PROFILE_DOCUMENT_MATCH"
],
"applicant_profile": {
"media": {
"id": "c709d220-edd6-4ba6-8494-b9aac6685e19",
"type": "JSON",
"created": "2022-10-18T16:33:59Z",
"last_updated": "2022-10-18T16:33:59Z"
}
},
"capture": {
"required_resources": [
{
"type": "ID_DOCUMENT",
"id": "d430440c-5c6d-402c-9855-3aebc8145a94",
"state": "REQUIRED",
"allowed_sources": [
{
"type": "IBV"
}
],
"requested_tasks": [],
"ibv_client_assessments": [
{
"type": "IBV_VISUAL_REVIEW_CHECK",
"state": "REQUIRED"
},
{
"type": "DOCUMENT_SCHEME_VALIDITY_CHECK",
"state": "REQUIRED",
"scheme": "UK_DBS"
},
{
"type": "PROFILE_DOCUMENT_MATCH",
"state": "REQUIRED"
}
],
"supported_countries": [
{
"code": "GBR",
"supported_documents": [
{
"type": "PASSPORT"
}
]
}
],
"allowed_capture_methods": "CAMERA",
"attempts_remaining": {
"RECLASSIFICATION": 2,
"GENERIC": 2
}
},
{
"type": "ID_DOCUMENT",
"id": "d33f1c38-2f4a-4d10-a22b-971ac63132ce",
"state": "REQUIRED",
"allowed_sources": [
{
"type": "IBV"
}
],
"requested_tasks": [],
"ibv_client_assessments": [
{
"type": "IBV_VISUAL_REVIEW_CHECK",
"state": "REQUIRED"
},
{
"type": "DOCUMENT_SCHEME_VALIDITY_CHECK",
"state": "REQUIRED",
"scheme": "UK_DBS"
},
{
"type": "PROFILE_DOCUMENT_MATCH",
"state": "REQUIRED"
}
],
"supported_countries": [
{
"code": "GBR",
"supported_documents": [
{
"type": "DRIVING_LICENCE"
}
]
}
],
"allowed_capture_methods": "CAMERA",
"attempts_remaining": {
"RECLASSIFICATION": 2,
"GENERIC": 2
}
},
{
"type": "SUPPLEMENTARY_DOCUMENT",
"id": "b23048de-0927-4a42-bd38-762d904d9fd7",
"state": "REQUIRED",
"allowed_sources": [
{
"type": "IBV"
}
],
"requested_tasks": [],
"ibv_client_assessments": [
{
"type": "IBV_VISUAL_REVIEW_CHECK",
"state": "REQUIRED"
},
{
"type": "DOCUMENT_SCHEME_VALIDITY_CHECK",
"state": "REQUIRED",
"scheme": "UK_DBS"
},
{
"type": "PROFILE_DOCUMENT_MATCH",
"state": "REQUIRED"
}
],
"document_types": ["UTILITY_BILL"],
"country_codes": ["GBR"],
"objective": {
"type": "UK_DBS"
}
}
],
"biometric_consent": "NOT_REQUIRED"
},
"sdk_config": {
"primary_colour": "#D71440",
"locale": "en-GB",
"hide_logo": false,
"allow_handoff": false
},
"track_ip_address": true
}
