After initialising the Yoti Identity Client, the next step is to configure your backend application to create a Share session. The Yoti SDKs enable integrators to dynamically create these sessions by defining a session configuration. A unique session would also include a share policy, which is a set of requested attributes or schemes for the sharing process.
First, we will describe which attributes are available so you know what policy you would like to build:
Good to know
Different ID documents have different attributes, bear this in mind when requesting attributes. e.g. A Nationality attribute is common for a Passport.
There is a small explanation of each attribute and what the content type is:
Name | Content Type | Explanation | Example |
|---|
remember_me_id | STRING | Unique identifier generated per user per application. Each time a user shares with a different application, they get a new identifier. This allows an application to recognise a returning user. | String Ic3NCB/dWVB1k4QPOD98IpDJ8ut04 lPHPSNV0RWikAc+szH2NrZFK1 nG+cZgaXe8 |
parent_remember_me_id | STRING | Unique identifier per user per organisation. It remains the same across all applications belonging to an organisation. This allows an organisation to recognise a returning user. | <UUID> |
Photo | JPEG | Photograph of user, encoded as a JPEG image. | N/A |
full_name | STRING | The user's full name. If family_name/given_names are present, this will be equal to the string ${given_names} + " " + ${family)_name}. | "Jon Jim Fred Foo" |
given_names | STRING | Corresponds to secondary names on a passport, and first/middle names in English. | "Jon Jim Fred" |
family_names | STRING | FamilyName is the family name. Not all documents provide split given names and family name | "Foo" |
phone_number | STRING | The user's phone number, as verified during registration. This will be a number in E.164 format | "+447777123456" |
email_address | STRING | The user's verified email address. | "test@test.com" |
date_of_birth | DATE | Date of birth of the user in the form yyyy-mm-dd, or yyyy-mm or yyyy. | "2000-12-01" |
age_over:[1-999] | STRING | Whether the user is over the specified age, as calculated from their date of birth. Either "true" or "false". | "TRUE", "FALSE" |
postal_address | STRING | Full address | "6th Floor, 107 Leadenhall St, London, EC3A 4AF" |
structured_postal_address | JSON | 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. | N/A |
gender | STRING | Corresponds to the gender in the registered document. | "MALE", "FEMALE", "TRANSGENDER" or "OTHER" |
nationality | STRING | Corresponds to the nationality on the passport. ISO-3166-1 alpha-3 code with ICAO9303 (passport) extensions. See Wikipedia page for ISO-3166-1 alpha-3 codes, and see ICAO 9303 part 3 (section 5 part A) for the extended list of codes. | "GBR" |
selfie_authentication | BOOLEAN | This is to prompt the user to take a selfie of themselves live via the Digital ID app as extra level of security. |
|
document_details | STRING | TYPE = [PASSPORT | DRIVING_LICENCE | NATIONAL_ID | PASS_CARD]
ISSUING_COUNTRY = alpha-3 country code, e.g. “GBR“ (see nationality above).
DOCUMENT_NUMBER = arbitrary document number
EXPIRATION_DATE = optional date in RFC3339 form (YYYY-MM-DD), e.g. “2016-03-21“ (21st March 2016). If the document does not expire, this field will not be present.
ISSUING_AUTHORITY = optional can either be a country code for a state or the name of the issuing authority.
|
|
document_images | MULTI_VALUE | Contains a jpeg image of the document. |
|
Unique IDs
When a user completes a share with you, Yoti generates two unique IDs.
A Remember me ID (service level)
A Parent remember me ID (organisation/account level)
One is for the specific application being used, and one is at an organisation level (parent). This means the user does not have to share their personal details every time, as you can just ask for your Remember Me ID instead.
For example, if you have two services:
Service 1 offered by Company ABC
Service 2 is offered by the same Company ABC That share will contain the same Company ABC ID and a different ID for application 2. Yoti has no access to these IDs. This approach is in line with Yoti’s data minimisation principle, meaning users should only share the details relevant to what you are doing.
Good to know
If a user deletes the Digital ID app without taking a backup, it will generate a new remember me ID when their Digital ID account is set-up.
Address attributes
Yoti has two options to show users' addresses:
Full address:- the address as a string.
Structured address:- a broken-down version of an address.
There is a small explanation of each attribute and what the content type is.
Name | Expected content type | Explanation |
|---|
building_number | STRING | The number of the building. |
building_name | STRING | The name of the building. |
sub_building_name | STRING | The subtitle of the building. |
address_line_1 | STRING | The first line of the address. |
address_line_2 | STRING | The second line of the address. |
address_line_3 | STRING | The third line of the address. |
town | STRING | The town of the address. |
country | STRING | The country of the address. |
postal_code | STRING | The postcode for the address. |
postal_address | STRING | The full address. |
structured_postal_address | JSON | The full address in both machine readable form and human readable form |
The below defines the fields of a JSON structure that can be used to define any address. 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.
We have four formats shown below:
Field | Format 1 (UK) | Format 2 (INDIA) | Format 3 (USA) | Format 4 (ROW) |
|---|
udprn | Optional |
|
|
|
care_of |
| Optional |
|
|
sub_building | Optional |
|
|
|
building_number | Optional |
|
|
|
building | Optional | Optional |
|
|
street |
| Optional |
|
|
landmart |
| Optional |
|
|
address_line_1 | Present |
| Present | Present |
address_line_2 | Optional |
| Optional | Optional |
address_line_3 | Optional |
|
| Optional |
address_line_4 |
|
|
| Optional |
address_line_n* |
|
|
| Optional |
locality | Present | Optional | Present |
|
town_city | Present | Optional | Present |
|
subdistrict |
| Optional |
|
|
district |
| Optional |
|
|
state | Optional | Optional | Present | Optional |
postal_code | Present | Present | Present |
|
post_office |
| Optional |
|
|
country_iso | Present | Present | Present | Present |
country | Present | Present | Present | Present |
formatted_address | Present | Present | Present | Present |
*The letter "n" represents a numerical figure. Yoti supports up to 6 lines of addresses.
Address Format 1
The UK address format is as shown below, with an example:
{
"address_format": 1,
"building_number": "15a",
"address_line1": "15a North Street",
"town_city": "CARSHALTON",
"postal_code": "SM5 2HW",
"country_iso": "GBR"
"country": "UK",
"formatted_address": "15a North Street\nCARSHALTON\nSM5 2HW\nUK"
}
Address Format 2
The Indian address format is as shown below, with an example:
{
"address_format": 2,
"care_of": "S/O: Vipen Kumar Aggarwal",
"building": "House No.86-A",
"street": "Rajguru Nagar",
"town_city": "Rajguru Nagar",
"subdistrict": "Ludhiana",
"district": "Ludhiana",
"state": "Punjab",
"postal_code": "141012",
"post_office": "Rajguru Nagar",
"country_iso": "IND",
"country": "India",
"formatted_address": "S/O: Vipen Kumar Aggarwal\nHouse No.86-A\nRajguru Nagar\nLudhiana\nPunjab\n141012\nIndia"
}
Address Format 3
The US address format is as shown below, with an example:
{
"address_format": 3,
"address_line1": "1512 Ferry Street",
"town_city": "Anniston",
"state": "AL",
"postal_code": "36201",
"country_iso": "USA",
"country": "USA",
"formatted_address": "1512 Ferry Street\nAnniston AL 36201\nUSA"
}
Build a policy
A policy is used to define what attributes are requested from the user. You can use the policy builder to define what attributes are needed.
const {
DigitalIdentityBuilders: {
PolicyBuilder
}
} = require('yoti');
const policy = new PolicyBuilder()
// using a predefined method to add an attribute
.withFullName()
.withEmail()
// if you wish the user to prove it's them by taking a selfie on share
.withSelfieAuthentication()
.build();
Policy policy = Policy.builder()
// using a predefined method to add an attribute
.withFullName()
.withEmail()
// if you wish the user to prove it's them by taking a selfie on share
.withSelfieAuthentication(true)
.build();
<?php
use Yoti\Identity\Policy\PolicyBuilder;
$policy = (new PolicyBuilder())
// using a predefined method to add an attribute
->withFullName()
->withEmail()
// if you wish the user to prove it's them by taking a selfie on share
->withSelfieAuthentication()
->build();
YotiPolicy policy = new PolicyBuilder()
// using a predefined method to add an attribute
.withFullName()
.withEmail()
// if you wish the user to prove it's them by taking a selfie on share
.withSelfieAuthentication()
.Build();
policy := (&digitalidentity.PolicyBuilder{})
// using a predefined method to add an attribute
.WithFullName()
.WithEmail()
// if you wish the user to prove it's them by taking a selfie on share
.WithSelfieAuth()
.Build()
There are several type of attributes that can be stored on a user's Digital ID app. Yoti provides the ability to request these attributes by specifying a share policy.
The attributes are independent of each other, so they can be requested separately. In order to request the required attributes using our SDKs, see the following examples:
const {
DigitalIdentityBuilders: {
PolicyBuilder
}
} = require('yoti');
const policy = new PolicyBuilder()
// using predefined methods to request attributes
.withFullName()
.withEmail()
.withPhoneNumber()
.withPostalAddress()
.withSelfie()
.withAgeOver(18)
.withDateOfBirth()
.withNationality()
.withGender()
.withStructuredPostalAddress()
.withDocumentDetails()
.withDocumentImages()
.withWantedRememberMe()
// using attributes specified by name
.withWantedAttributeByName("given_names")
.withWantedAttributeByName("family_name")
// if you wish the user to prove it's them by taking a selfie on share
.withSelfieAuthentication()
.build();
Policy policy = Policy.builder()
// using predefined methods to request attributes
.withFullName()
.withEmail()
.withPhoneNumber()
.withPostalAddress()
.withSelfie()
.withAgeOver(18)
.withDateOfBirth()
.withNationality()
.withGender()
.withStructuredPostalAddress()
.withWantedRememberMe(true)
// using attributes specified by name
.withWantedAttribute(true,"given_names")
.withWantedAttribute(true,"family_name")
// if you wish the user to prove it's them by taking a selfie on share
.withSelfieAuthentication(true)
.build();
<?php
use Yoti\Identity\Policy\PolicyBuilder;
$policy = (new PolicyBuilder())
// using predefined methods to request attributes
->withFullName()
->withEmail()
->withPhoneNumber()
->withPostalAddress()
->withSelfie()
->withAgeOver(18)
->withDateOfBirth()
->withNationality()
->withGender()
->withStructuredPostalAddress()
->withDocumentDetails()
->withDocumentImages()
->withWantedRememberMe(true)
// using attributes specified by name
->withWantedAttributeByName("given_names")
->withWantedAttributeByName("family_name")
//if you wish the user to prove it's them by taking a selfie on share
->withSelfieAuthentication()
->build();
YotiPolicy policy = new PolicyBuilder()
// using predefined methods to request attributes
.withFullName()
.withEmail()
.WithPhoneNumber()
.WithPostalAddress()
.WithSelfie()
.WithAgeOver(18)
.WithDateOfBirth()
.WithNationality()
.WithGender()
.WithStructuredPostalAddress()
.WithDocumentDetails()
.WithDocumentImages()
.WithRememberMeId(true)
// using attributes specified by name
.WithWantedAttributeByName("given_names")
.WithWantedAttributeByName("family_name")
// if you wish the user to prove it's them by taking a selfie on share
.withSelfieAuthentication()
.Build();
policy := (&digitalidentity.PolicyBuilder{})
// using a predefined method to add an attribute
.WithFullName()
.WithEmail()
.WithPhoneNumber()
.WithPostalAddress()
.WithSelfie()
.WithAgeOver(18)
.WithDateOfBirth()
.WithNationality()
.WithGender()
.WithStructuredPostalAddress()
.WithDocumentDetails()
.WithDocumentImages()
.WithWantedRememberMe()
// using attributes specified by name
.withWantedAttributeByName("given_names")
.withWantedAttributeByName("family_name")
// if you wish the user to prove it's them by taking a selfie on share
.WithSelfieAuth()
.Build()
Specify the Session configuration
The Session configuration is built using:
The policy.
The redirect URI for share completion. This is where the user will be redirected to after the share is completed. A receiptId query parameter will be added to the URL. You can use this to retrieve the user profile from the share.
A subject Id (optional).
A notification webhook (optional).
Any extensions.
const {
DigitalIdentityBuilders: {
ShareSessionNotificationBuilder,
ShareSessionConfigurationBuilder
}
} = require('yoti');
const notification = new ShareSessionNotificationBuilder()
.withUrl("your-webhook-url")
.withMethod("POST")
.withHeader("Authorization", "<Bearer_token>") // Optional
.withVerifiedTls(true) // Optional
.build();
const subject = {
subject_id: 'some_subject_id_string',
};
const shareSessionConfig = new ShareSessionConfigurationBuilder()
.withRedirectUri("/your-callback-url")
.withPolicy(policy)
.withSubject(subject)
.withNotification(notification)
.build();
ShareSessionNotification notification = ShareSessionNotification.builder("your-webhook-url")
.withMethod("POST")
.withHeader("Authorization", "<Bearer_token>") // Optional
.withVerifyTls(true) // Optional
.build();
Map<String, Object> subject = new HashMap<>();
subject.put("subject_id", "some_subject_id_string");
ShareSessionRequest shareSessionConfig = ShareSessionRequest.builder()
.withRedirectUri("/your-callback-url")
.withPolicy(policy)
.withSubject(subject)
.withNotification(notification)
.build();
<?php
use Yoti\Identity\ShareSessionRequestBuilder;
$notification = (new ShareSessionNotificationBuilder())
->withUrl("your-webhook-url")
->withMethod("POST")
->withHeader("Authorization", "<Bearer_token>") // Optional
->withVerifyTls(true) // Optional
->build();
$subject = (object)[
'subject_id' => 'some_subject_id_string'
];
$shareSessionConfig = (new ShareSessionRequestBuilder())
->withRedirectUri("your-callback-url")
->withPolicy($policy)
->withSubject($subject)
->withNotification($notification)
->build();
var notification = new NotificationBuilder()
.WithUrl("https://example.com/webhook")
.WithMethod("POST")
.WithVerifyTls(true)
.Build();
var subject = new
{
subject_id = "some_subject_id_string"
};
ShareSessionConfiguration shareSessionConfig = new ShareSessionRequestBuilder()
.WithRedirectUri("/your-callback-url")
.WithPolicy(policy)
.WithSubject(subject)
.WithNotification(notification)
.Build();
headers := []byte(`{
"Authorization": "<Bearer_token>"
}`)
notification := (&digitalidentity.ShareSessionNotification{})
.WithUrl("your-webhook-url")
.WithMethod("POST")
.WithHeaders(headers) // Optional
.WithVerifyTls(true) // Optional
.Build()
subject := []byte(`{
"subject_id": "my_subject_id"
}`)
shareSessionConfig := (&digitalidentity.ShareSessionBuilder{})
.WithRedirectUri("/your-callback-url")
.WithPolicy(policy)
.WithSubject(subject)
.WithNotification(notification)
.Build()
Create a Share session
Using the session configuration defined above, you can request the creation of a Share session that will be used by the Yoti Webshare script to generate a Yoti QR.
yotiClient.createShareSession(shareSessionConfig)
.then((shareSessionResult) => {
const shareSession = shareSessionResult;
const shareSessionId = shareSession.getId();
}).catch((error) => {
console.error(error.message);
});
try {
ShareSession shareSession = client.createShareSession(shareSessionConfig);
String shareSessionId = shareSession.getId();
} catch (DigitalIdentityException e) {
LOG.error(e.getMessage());
}
<?php
use Yoti\Exception\DigitalIdentityException;
try {
$shareSession = $client->createShareSession($shareSessionConfig);
$shareSessionId = $shareSession->getId();
} catch (DigitalIdentityException e) {
throw new DigitalIdentityException($e->getMessage());
}
ShareSession shareSession = yotiClient.CreateShareSession(shareSessionConfig);
var shareSessionId = shareSession.Id;
shareSession, err := client.CreateShareSession(shareSessionConfig)
shareSessionId := shareSession.Id
Error codes
Error code | Description |
|---|
400 | Invalid request payload sent |
400 | One or more of the specified attributes are not known |
403 | Service is disabled |
403 | Service does not belong to an organisation |
403 | Organisation status must be PENDING or VERIFIED to perform shares |
403 | Service isn’t allowed to request the specified 3rd party attribute |
403 | Service isn’t allowed to issue the specified 3rd party attribute |
