Create a session

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:

  • Yoti SDK ID
  • Your application key pair.

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:

HTTP
Copy

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.

ParameterDescription
SDK IDUUID generated when producing your Yoti keys
nonceNonces are UUID strings
TimestampUNIX 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.

Javascript
PHP
Python
Java
Go
C#
Ruby
Copy
Javascript
PHP
Python
Java
Go
C#
Ruby
Copy

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

HTTP
Copy

Example

JSON
Copy
NameDescriptionOptional
resources_ttlRetention 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__idAllows the relying business backend to track the same user across multiple sessions. Note: This should not contain any personal identifiable information
ibv_optionsOutlines that an IBV session is being generated.
session_deadlineThis 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_ttlAn 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.

NameDescription
NEW_PDF_SUPPLIEDYou can subscribe to be notified when the user has got the PDF. Only relevant when using the At home flow.
INSTRUCTIONS_EMAIL_REQUESTEDIf 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_REQUESTEDEnabling 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_COMPLETIONTriggered when all tasks and all checks inside of a given session have been completed.

Requested checks

The below represents the in-person checks.

CheckDescription
PROFILE_DOCUMENT_MATCHChecks the document the applicant brought with them matches the submitted applicant profile.
DOCUMENT__SCHEME__VALIDITY_CHECKChecks 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_CHECKA 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).

JSON
Copy
NameDescription
typeOutlines 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.

NameTypeDescriptionExample
full_nameStringFullName contains given names and family name.“Jon Jim Foo”
date_of_birthStringDateOfBirth is the date of birth in the form yyyy-mm-dd."2000-12-01"
given_namesStringGivenNames contains first and middle names."Jon Jim"
first_nameStringFirstName is the first name only.“Jon”
middle_nameStringMiddleName contains the middle names only.“Jim”
family_nameStringThe family name.“Foo”
structured_postal_addressObjectStructuredPostalAddress 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 nameTypeDescription
address_formatnumberAddressFormat 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.
udprnstringUdprn is the Unique Delivery Point Reference Number that identifies a property throughout its lifecycle.
care_ofstringCareOf identifies the owner of the premises.
sub_buildingstringSubBuilding is used when the building is divided into smaller units (e.g. a block of flats) to identify the sub unit.
building_numberstringBuildingNumber is the number of the building.
buildingstringBuilding is the name/number of the building.
streetstringStreet is the name/number of the street the building is on.
landmarkstringLandmark is a description used to describe the location of the building.
address_line1stringAddressLine1 is the first line of the address.
address_line2stringAddressLine2 is the second line of the address.
address_line3stringAddressLine3 is the third line of the address.
address_line4stringAddressLine4 is the fourth line of the address.
address_line5stringAddressLine5 is the fifth line of the address.
address_line6stringAddressLine6 is the sixth line of the address.
localitystringLocality is the area the building is in.
town_citystringTownCity is the town/city/village/hamlet/community/etc. that the building is in.
subdistrictstringSubdistrict is the sub-district the building is in.
districtstringDistrict is the district the building is in.
statestringState is the state/county the building is in.
postal_codestringPostalCode is a code used by the country's postal service to aid in sorting and delivering mail (e.g. postcode, zipcode, pincode).
post_officestringPostOffice is the post office that serves the area the building is in.
country_isostringCountryIso is the country the building is in. In ISO-3166-1 alpha-3 format.
countrystringCountry is the country the building is in. Localised.
formatted_addressstringFormattedAddress 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 formatGBR, JEY, IMNINDUSA, AUSAll other countries
address_format1234
udprnOptional
care_ofOptional
sub_buildingOptional*
building_numberOptional*
buildingOptional*Optional
streetOptional
landmarkOptional
address_line1MandatoryMandatoryMandatory
address_line2OptionalOptionalOptional
address_line3OptionalOptional
address_line4Optional
address_line5Optional
address_line6Optional
localityOptional
town_cityMandatoryOptionalMandatory
subdistrictOptional
districtOptional
stateOptionalOptionalMandatory
postal_codeMandatoryMandatoryMandatoryOptional
post_officeOptional
country_isoMandatoryMandatoryMandatoryMandatory
countryMandatoryMandatoryMandatoryMandatory
formatted_address**MandatoryMandatoryMandatoryMandatory

** 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:

JSON
Copy
ResponseDescription
client_session_token_ttlTime in seconds until the client session expires
client_session_tokenUsed to authenticate the session
session_idID 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.

HTTP
Copy

Example

JSON
Copy
Type to search, ESC to discard
Type to search, ESC to discard
Type to search, ESC to discard
  Last updated by Jason Martyres