Before You Begin

Installation Free Version

Installation not your thing? Read Add identity verification and KYC to your digital onboarding process in 10 minutes to get EmbedID up and running without installing anything.

This guide assumes you have already created an EmbedID experience, if not:
  • Navigate to EmbedID
  • Click Create New Experience.
  • Enter a name for your Experience, e.g. ‘My First Experience’.
  • Select one of the options from the list (if you're not sure which one, select Identity Verification).
How Does It Work?EmbedID is a low code front end tool that allows you to quickly add Identity Verification and ID Document Verification to your digital onboarding process. EmbedID works as follows:
  • A <script> tag is added to your front end; essentially the area of your website where you want EmbedID to be generated.
  • The script makes a call to your server to get an Access Token.
    • This Access Token is retrieved via an API call to Trulioo.
    • This needs to be a server side call, authenticated with a secret API Key to ensure you are the only one who can generate these Access Tokens.
  • Once EmbedID has this Access Token, the rest of your calls to Trulioo will be handled by EmbedID.
KeysWhen you are editing your EmbedID Experience you will see a section in the left panel called Keys. You will also notice there are 3 types of keys.Let's look at each one.
Trial Key (FE)The Trial Key is for Trial transactions and is used for testing. This is your public key for the Client Side (note: FE = FrontEnd). It will be passed to EmbedID and is used to get your configuration.
Live Key (FE)The Live Key is for Live transactions and will replace your Trial Key for production. Note: To have access to the Live Key you first need to Upgrade your account from Trial to Live.
API Key (BE)This is your Server's secret key (BE = BackEnd). It will be used to generate an access token for each EmbedID instance.
screenshot of keys
1. Generate Your Access Token (Server Side)
To ensure it's you making the requests, you'll need to generate an Access Token securely from your backend. This will validate the form you place in your frontend is making requests on your behalf.

A POST route should be configured `/trulioo-api/embedids/tokens/:publicKey` (for example - http://localhost:8080/trulioo-api/embedids/tokens/:publicKey) to generate the access token in the backend.

The following is the call your server needs to make:

cURL
curl -X POST 
  https://api-gateway-admin.trulioo.com/embedids/tokens 
  -H 'cache-control: no-cache' 
  -H 'content-type: application/json' 
  -H 'x-trulioo-api-key: YOUR_API_KEY_(BE)_GOES_HERE' 
  -d '{
    "publicKey": "YOUR_TRIAL_KEY_(FE)_GOES_HERE"
  }'

If successful, you will see the following response:

cURL Response
{"accessToken":"ACCESS_TOKEN"}
SDKs to Generate You Access TokenIf you are using Node js in your backend, Trulioo has built a middleware package (trulioo-middleware SDK) that you can use instead.
cmd/terminal
npm install trulioo-embedid-middleware
cmd/terminal
npm install express

Why install express? The trulioo-middleware SDK is an express middleware so depends on express.

You can then add the following js to your backend to invoke the middleware and generate an Access Token.

backend.js
const truliooMiddleware = require('trulioo-embedid-middleware')({ 
apiKey: “YOUR_API_KEY_(BE)_GOES_HERE” });  
const express = require('express'); 
const app = express(); 
const port = 8080; 
                
app.use(truliooMiddleware) 
app.listen(port, () => console.log('Example app listening on port ${port}!')); 

When this backend.js is running it will be listening on Port 8080 for EmbedID to make a request, which we will see in the next step.

2. Include Your EmbedID In Your Site (Client Side)
Once your server is running, you can then add your client side code to embed your Experience in your frontend/website. You will need to add the following snippet to the area of your site where you want the form to be generated.
HTML
<div id="trulioo-embedid"></div>

<!-- This script renders the form for the div above --> 
<script type="text/javascript" src="https://js.trulioo.com/latest/main.js"></script>

<!-- Initialize your form here with your Frontend (FE) key -->
<script> 
  // Handle the response of EmbedID after form submits
  function handleResponse(e) { 
    console.log('handleResponse', e); 
  } 
  
  const publicKey = 'Trial Key (FE)_OR_Live Key (FE)'; // Public Key
  // const accessTokenURL = 'http://localhost:8080';
  new TruliooClient({ 
    publicKey, 
    // accessTokenURL,
    handleResponse 
  });
</script>
      
Key things to note:
  • <div id="trulioo-embedid"></div> This is the div where your experience will be generated, i.e. where you put this is where your Experience will be displayed on the frontend.
  • <script type="text/javascript" src="https://js.trulioo.com/latest/main.js"></script> This generates your experience at the div above.
  • new TruliooClient This initializes your experience. You'll notice it takes a few props:
fieldRequired?Description
publicKeyYesThis is the key you want to use for rendering your form.
Trial Key (FE)
Use for trial requests (eg during development). These are only test data requests so you won’t be charged. Try verifying as a test entity to see it in action.
Live Key (FE)
Use for your production requests. You will be charged for these transactions, see our pricing page for more details.
accessTokenURLNoEmbedID assumes you are running your Frontend code (Step 1) and Backend Code (Step 2) on the same port.

If you are running them separately, for example you are testing on localhost, use accessTokenURL to specify where your Backend is running. It should just be the baseurl as our script will automatically append `/trulioo-api/embedids/tokens/:publicKey` to accessTokenURL.

accessTokenURL = '${location of server}' for example 'http://localhost:8080'
handleResponseNoThis is the callback for where the result of a verification will be posted.

See Section Understanding A Verify Response for how to process this response
Still seeing issues?
  • Is your server definitely running?
  • Have you added your “API key (BE)” to this server SDK?
  • Have you added your “Trial Key (FE) or Live Key (FE)” to the client side?
3. Knowing When Your Form Has Finished Rendering
If you supply the EmbedID client with the optional onInitialRenderComplete function, it will be called by the client when all the elements on the initial screen have finished rendering. The call to onInitialRenderComplete includes a status and statusText, depending on whether the render was successful or not.

This means that you can override the default loading behavior, and the page that is displayed when an error occurs.

The following is an example of the function in use. The next code block displays a loading message over the EmbedID client.
Loading Overlay (HTML)
<div id="loading-overlay" style="
  background-color: white;
  height: 100vh; 
  width: 100vw;
  display: block;
  position: absolute;
  z-index: 2">Loading...</div>
<div id="trulioo-embedid" style="z-index: 1"></div>

We can hide the loading message when onInitialRenderComplete has been called, and log the error if an error is found.
onInitialRenderComplete (Javascript)
function onInitialRenderComplete(e) {
  document.getElementById('loading-overlay').style.visibility = "hidden";
  if (e.status !== 200 || e.statusText !== "Success") {
    console.log('@onInitialRenderComplete', e);
  }
}
Status Text and Codes Passed Into onInitialRenderComplete
Status CodeStatus TextVariables passed into TruliooClient
200SuccessValid publicKey with valid accessToken or accessTokenURL
401ErrorInvalid publicKey, accessToken or accessTokenURL
4. Run Your First Verification

Now that your Experience is up and running you should test it out! We provide Test Entities specifically for this.

Identity VerificationWe have a full set of Test Entities for you to try out. Here's a couple for the US to mimic some user behavior.

Individual with Match result:

Justin Mark Williams

000568791

8/4/1988

0812319884104

802-660-9697

18 - 420 9th Avenue,
New York, NY
10001

Individual with NoMatch result:

Lucia J. Ronning

309-23-0000

10/11/1981

0922870874358

812-472-7518

2649 Lucy Lane,
Fredericksburg, IN
47120

Individual with Watchlist Hit:

Justin Williams

000568791

8/4/1988

0812319884104

221-214-4456

1111 West Kagy Boulevard,
Bozeman, MN
90010

ID Document Verification

Scan the QR code on your mobile device to launch document capture in sandbox mode. Follow the instructions on screen to capture an image of any document.

This will show you how the capture process will work for your Users. When you're instructed to, come back to your desktop and click ‘Next’.

Note: We won't send your image captures; only a fake/placeholder image instead.

5. Understanding the Verification Response
Now that you've had an opportunity to try out a couple of the Test Entities, are you wondering: How do I know if my customer has been verified?

When an end user (i.e. your customer) verifies themselves through EmbedID, an Experience Transaction ID is output to the handleResponse callback. You can use this Experience Transaction ID to get both the data that was entered by the user, as well as their verification result for every part of the verification that took place. The data entered by the user will only be available for 72 hours after the form submission.

Note: All user entered data is permanently deleted from Trulioo's servers after 72 hours.

The handleResponse Callback should pass the Experience Transaction ID to your backend so you can securely make the call.

Note: The handleResponse Callback will have status code "200" and status text "ok", if the transaction is a success. In the case of an error, an appropriate status code and text will be returned and experienceTransactionID will be undefined.

Simple ResultsCall GET https://gateway.trulioo.com/experienceTransaction/{experienceTransactionId} to get a simple overview of the results of the verification.
Request
curl -X GET 
https://gateway.trulioo.com/experienceTransaction/{experienceTransactionId} 
-H 'cache-control: no-cache' 
-H 'content-type: application/json' 
-H 'x-trulioo-api-key: YOUR_API_KEY_(BE)_GOES_HERE'
Response
{
  experienceTransactionId: '...',
  timestamp: 1234567,
  transactionResult: 'match',
  steps: [{
    name: 'IDVStep',
    result: 'match',
    inputData: {...}
  }]
}
Detailed Results

Call GET https://gateway.trulioo.com/experienceTransaction/{experienceTransactionId}/detailedResult to get all available data for the result of the verification.

Request
curl -X GET 
https://gateway.trulioo.com/experienceTransaction/{experienceTransactionId}/detailedResult 
-H 'cache-control: no-cache' 
-H 'content-type: application/json' 
-H 'x-trulioo-api-key: YOUR_API_KEY_(BE)_GOES_HERE'
Response
{
  "experienceTransactionId": "...",
  "status": "complete",
  "transactionResult": "match",
  "steps": [
    {
      "stepName": "IDVStep_OR_DocVStep",
      "result": "match",
      "transactionRecordId": "...",
      "transactionId": "...",
      "timestamp": 1234567,
      "inputFields": [...],
      "errors": [],
      "rule": {
        "RuleName": "RuleName",
        "Note": "The rule that defines whether result is match or nomatch"
      },
      "datasourceResults": [
        {
          "DatasourceName": "DatasourceName",
          "DatasourceFields": [],
          "AppendedFields": [],
          "Errors": [],
          "FieldGroups": []
        }
      ]
    }
  ]
}

© Copyright 2010-2024, Trulioo.