Guest Links¶
This feature allows a user to generate an invitation link that can be sent to someone who does not have a TrustID Cloud account. This allows the recipient (the guest) to submit one application under the link creator’s account. This is useful for systems that request a third party to perform a one-off scan but do not want to give them an account.
An example might be a landlord who wants a new tenant to upload their ID document for validation as part of a “Right to Rent” check.
The link allows only for uploading of the scan. The guest user themselves will never be able to see the result of the scan.
When you create a guest link you must :
Specify the email address that the invitation will be sent to. This information will be attached to the application when it is submitted by the guest, for future reference.
Specify the name of the guest you are sending the invitation to. This information will be attached to the application when it is submitted by the guest, for future reference.
Specify any mandatory application-level custom field values.
When you create a guest link you will probably want to:
Specify the branch the scan will be assigned to. If you do not specify a branch the scan is assigned to the branch of the account you use to create the guest link.
Specify values for any optional application-level custom fields.
Note
Please contact TrustID if you need additional application-level custom fields or branches added to your account.
Creating a Guest Link¶
Create a guest link as shown below:
Request
POST {{server}}/VPE/guestLink/createGuestLink/
Content-Type: application/json
{
"SessionId": "...",
"DeviceId": "device-id",
"Email": "guest@domain.co.uk",
"Name": "Guest Name",
"BranchId": "..."
}
For endpoint details, see /guestLink/createGuestLink/.
var api = new TVS.Api();
api.login('username', 'password').then(function(loginInfo) {
// get all branches available
return api.getBranchesX();
}).then(function(branches) {
//Use first branch in list as example.
var branchId = branches[0].Id;
//Now create the guest link
return api.createGuestLink('guest@domain.co.uk', 'Guest Name', branchId);
});
For endpoint details, see Api.createGuestLink.
An email will be sent to the guest containing a link for them to use to submit their application. Optionally, you can specify that you do not want this email to be sent by the system. In this case the guest link URL is returned to you and it is your responsibility to pass it on to the guest.
See also
Raw API - CreateGuestLinkRequest.SendEmail.
Javascript API - the sendEmail parameter of createGuestLink().
Note
Retrieving Branches shows how to use the API to retrieve a list of possible branch Ids.
Using Application-level Custom Fields¶
When you create a guest link, you must specify custom fields at application-level.
For information on how to obtain a list of custom fields at application-level and how to construct data to send, see Application-level Custom Fields. The final request should look something like this:
Request
POST {{server}}/VPE/guestLink/createGuestLink/
Content-Type: application/json
{
"SessionId": "...",
"DeviceId": "...",
"Email": "guest@domain.co.uk",
"Name": "Guest Name",
"BranchId": "..."
"ApplicationFlexibleFieldValues": [
{
"FlexibleFieldVersionId": "...",
"FieldValueString": "Software Development and IT Department"
}
]
}
For endpoint details, see /guestLink/createGuestLink/.
var api = new TVS.Api();
api.login('username', 'password').then(function(loginInfo) {
// get all available branches
return api.getBranchesX();
}).then(function(branches) {
//Use first branch in list as example.
var branchId = branches[0].Id;
// get application-level custom fields available in the system for required branch
return api.getApplicationFlexibleFieldsForBranch(branchId);
}).then(function(flexibleFields) {
// create a new (empty) container with application-level custom fields attached,
// assuming a field with the name 'ApplicantId' exists
var customFields = Container.createCustomFields(flexibleFields, {
'ApplicantId': '123456'
})
//Now create the guest link
return api.createGuestLink('guest@domain.co.uk', 'Guest Name', branchId, customFields);
});
For endpoint details, see Api.createGuestLink.
Using Callback Properties Creating a Guest Link¶
When you create a guest link, you can specify callback properties to be able to receive callback at certain event within a guest link workflow.
You can specify ContainerEventCallbackUrl to link guest link with callback url and you can specify ContainerEventCallbackHeaders used by callback, request should look something like this:
Request
POST http://localhost:8000/VPE/guestLink/createGuestLink/
Content-Type: application/json
{
"SessionId": "...",
"DeviceId": "...",
"Email": "guest@domain.co.uk",
"Name": "Guest Name",
"BranchId": "..."
"ApplicationFlexibleFieldValues": [
{
"FlexibleFieldVersionId": "...",
"FieldValueString": "Software Development and IT Department"
}
],
"ContainerEventCallbackUrl": "https://www.my-company.co.uk/web-hooks/container-event-callback/",
"ContainerEventCallbackHeaders"::[
{
"Header":"Authorization",
"Value":"..."
}
],
"ClientApplicationReference": "MyReference"
}
For endpoint details, see /guestLink/createGuestLink/.
var api = new TVS.Api();
api.login('username', 'password').then(function(loginInfo) {
// get all available branches
return api.getBranchesX();
}).then(function(branches) {
//Use first branch in list as example.
var branchId = branches[0].Id;
// get application-level custom fields available in the system for required branch
return api.getApplicationFlexibleFieldsForBranch(branchId);
}).then(function(flexibleFields) {
// create a new (empty) container with application-level custom fields attached,
// assuming a field with the name 'ApplicantId' exists
var customFields = Container.createCustomFields(flexibleFields, {
'ApplicantId': '123456'
})
//Now create the guest link
return api.createGuestLink('guest@domain.co.uk', 'Guest Name', branchId, customFields, null, null, true, 0, 'MyReference', 0, 'https://www.my-company.co.uk/web-hooks/container-event-callback/');
});
Using Digital Identity Property¶
When you create a guest link, you can specify digital identity scheme property.
You can specify DigitalIdentityScheme property to achieve identity profile, request should look something like this:
Request
POST http://localhost:8000/VPE/guestLink/createGuestLink/
Content-Type: application/json
{
"SessionId": "...",
"DeviceId": "...",
"Email": "guest@domain.co.uk",
"Name": "Guest Name",
"BranchId": "..."
"ApplicationFlexibleFieldValues": [
{
"FlexibleFieldVersionId": "...",
"FieldValueString": "Software Development and IT Department"
}
],
"ContainerEventCallbackUrl": "https://www.my-company.co.uk/web-hooks/container-event-callback/",
"ContainerEventCallbackHeaders"::[
{
"Header":"Authorization",
"Value":"..."
}
],
"ClientApplicationReference": "MyReference",
"DigitalIdentityScheme": 2
}
For endpoint details, see /guestLink/createGuestLink/.
var api = new TVS.Api();
api.login('username', 'password').then(function(loginInfo) {
// get all available branches
return api.getBranchesX();
}).then(function(branches) {
//Use first branch in list as example.
var branchId = branches[0].Id;
// get application-level custom fields available in the system for required branch
return api.getApplicationFlexibleFieldsForBranch(branchId);
}).then(function(flexibleFields) {
// create a new (empty) container with application-level custom fields attached,
// assuming a field with the name 'ApplicantId' exists
var customFields = Container.createCustomFields(flexibleFields, {
'ApplicantId': '123456'
})
//Now create the guest link
return api.createGuestLink('guest@domain.co.uk', 'Guest Name', branchId, customFields, null, null, true, 0, 'MyReference', 2, 'https://www.my-company.co.uk/web-hooks/container-event-callback/');
});
For endpoint details, see Api.createGuestLink.