Create a Share session

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:

There is a small explanation of each attribute and what the content type is:

Unique IDs

When a user completes a share with you, Yoti generates two unique IDs.

1. A Remember me ID (service level)
2. 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:

1. Service 1 offered by Company ABC
2. 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.

Address attributes

Yoti has two options to show users' addresses:

1) Full address:- the address as a string.

2) Structured address:- a broken-down version of an address.

There is a small explanation of each attribute and what the content type is.

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:

*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();

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();

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();

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);

  });

Error codes