Overview

This guide will show you how to use the AXN Verify API to verify an individual via. BioGovID.

📘
Prerequisites

Deploy the "BioGovID" Workflow by following the directions here.

Obtain the access keys for your new workflow by following the directions here

Download and use the BioGovID Postman Collection to try it out

Redirect URL

📘
After completing document capture, your users will need to be properly redirected away from your BioGovID interface.
The redirect page they return to is specified by the field asyncUIRedirect.

1. Get Access Token

(POST) https://api.preprod.iddataweb.com/v1/token

API Reference: https://docs.iddataweb.com/reference/auth

This access token is used to authenticate your requests. Place this token in the header of each subsequent request. See the postman project above for examples.

Locate your workflow's access keys

📘
NOTE
When using our BioGovID postman collection, use your BioGovID API key to request an access token if you're not planning to perform Country Selection before the user begins verification.

Then, to request an access token:

var axios = require('axios')

var user = 'Your *BioGovID* API key';
var password = 'Your *BioGovID* API Secret';

var base64encodedData = Buffer.from(user + ':' + password).toString('base64');

var request = async () => {
  var response = await axios({
    url: 'https://api.preprod.iddataweb.com/v1/token',
    method: 'post',
    params: {
      grant_type: 'client_credentials'
    },
    headers: {
      'Content-Type': 'application/json',
      'Cache-Control': 'no-cache',
      Authorization: 'Basic ' + base64encodedData
    }
  })
  console.log(response.data);
}
request();

Response

{
    "errorCode": "",
    "errorDescription": "",
    "access_token": "TjZK7NSjw24AxGK9UhOE9uJDaZT23gKYuUC-9GMTAgLU", // your access token
    "expires_in": "1800",
    "token_type": "Bearer"
}

2. Get / Send Document Capture Link

(POST) https://api.preprod.iddataweb.com/v1/async-ui/send-link
& (POST) https://api.preprod.iddataweb.com/v1/async-ui/get-link

API Reference:

Once you've received an access token, you'll use it to send a Document Capture link to your end user.

👍
TIP:
You can optionally generate a link and not have it sent to your end user automatically. That way, you can control how this link is provided. See /get-link
To generate and deliver the link automatically, see /send-link

Request: /send-link

var data = {
    "apikey": "Your API Key",
    "credential": "e.g. : [email protected]",
    "appID":"Your App Name, (e.g. 'Employee Onboarding App')", 
    "country": "US",
    "userAttributes": [
      {
          "attributeType": "InternationalTelephone",
          "values": {
          	"dialCode": "1",
          	"telephone": "1234567890"
          }
      },
      {
            "attributeType": "FullName",
            "values": {
                "fname": "",
                "mname": "",
                "lname": ""
            }
      }
    ]
}

var axios = require('axios')
var token = 'YOUR_BEARER_TOKEN' // -- obtained from step 1 --

var request = async () => {
  var response = await axios({
    url: 'https://api.preprod.iddataweb.com/v1/async-ui/send-link',
    method: 'post',
    data: data,
    headers: {
      'Content-Type': 'application/json',
      'Cache-Control': 'no-cache',
      Authorization: 'Bearer ' + token,
    }
  })
	console.log(response.data)
}
request();

Request: /get-link

var data = {
    "apikey": "Your API Key",
    "credential": "e.g. : [email protected]",
    "appID":"Your App Name, (e.g. 'Employee Onboarding App')", 
    "country": "US",
     "userAttributes": [
      {
          "attributeType": "InternationalTelephone",
          "values": {
          	"dialCode": "1",
          	"telephone": "1234567890"
          }
      },
      {
            "attributeType": "FullName",
            "values": {
                "fname": "",
                "mname": "",
                "lname": ""
            }
      }
    ]
}

var axios = require('axios')
var token = 'YOUR_BEARER_TOKEN' // -- obtained from step 1 --

var request = async () => {
  var response = await axios({
    url: 'https://api.preprod.iddataweb.com/v1/async-ui/get-link',
    method: 'post',
    data: data,
    headers: {
      'Content-Type': 'application/json',
      'Cache-Control': 'no-cache',
      Authorization: 'Bearer ' + token,
    }
  })
	console.log(response.data)
}
request();

Response

/** Depending on the endpoint used  **/

// Response: to  /send-link
{ 
    "services": [
      {
            // InterviewID of the Incode session
            "apTransactionId": "687xxxxxxxxxxxxxxxxxxxxx",
            "name": "Incode BioGovID Verification",

             // Creates and delivers link.
            "status": "delivered",
            "apSessionId": "34523008-c5a3-4ca0-93452-2z5mbd10"
        }
    ],
    "asi": "4e234574e8-c706-45eb-b648-effdb90ff31a7"
}

// Response: to  /get-link
{
    "services": [
      {
            // InterviewID of the Incode session
            "apTransactionId": "687xxxxxxxxxxxxxxxxxxxxx",
            "name": "Incode BioGovID Verification",

            // Returns link instead of delivering it.
            "url": "https://stg.orchestration.incode.net?session_id=9qeZvvG&lang=en",
            "status": "initialized",
            "apSessionId": "c5af5e18-bbff-479f-b721-09b3ce06e754"
        }
    ],
    "asi": "3dc24510-c44b-4000-849d-cf7644685aad"
}

3. Verify

(POST) https://api.preprod.iddataweb.com/v1/slverify

API Reference: https://docs.iddataweb.com/reference/slverify

Lastly, you'll collect the asi (obtained from step 2) and submit it to the endpoint /slverify for a final policy decision.

🚧
IMPORTANT:
When your user completes verification, they will be redirected to the Redirect URL you have specified, along with the ASI for their completed user session.
Example: https://www.iddataweb.com/redirect/?asi=6cd23a78-cd52-28e7-sdae-009c3234bb
In your application, expose one /GET endpoint to receive and verify completed user sessions.

Request

const axios = require("axios"); // http-request library

app.get("/redirect", async (request, response) => {
    // Retrieve the ASI obtained from your redirect URL.
    var asi = req.query.asi

    // Slverify payload:
    var data = {
        "credential": "incode",
        "asi": "your_transaction_ID", // -- obtained from step 2 --
        "appID": "",
        "userAttributes": [], // if user attributes were not already collected (via. /send-link), include them here (e.g. full name, telephone).
        "country": "US",
        "idpType": "optional idp type",
        "apikey": "Your API Key"
    }

    var token = 'YOUR_BEARER_TOKEN'; // -- obtained from step 1 --

    var request = async () => {
        var response = await axios({
            url: "https://api.preprod.iddataweb.com/v1/slverify",
            method: "post",
            body: data,
            headers: {
                "Content-Type": "application/json",
                "Cache-Control": "no-cache",
                Authorization: "Bearer " + token,
            },
        });
        return response.data
    };

    // Lastly, call slverify to receive your user's policy decision.
    var policyDecision = await request().policyDecision;

    // Redirect your user depending on their result.
    if (policyDecision === 'approve') {
        // ... grant the user access
        response.redirect(`https://www...com/approved`)
    }

    if (policyDecision === 'deny') {
        // ... deny the user access
        response.redirect(`https://www...com/denied`)
    }
})

Response

{
    "errorCode": "",
    "errorDescription": "",
    "transaction_id": "76gjhbl9-842c-4d2f-8d43-13c5fb4eff23",
    "userAttributes": null,
    "acquiredAttributes": [
        {
            "provider": "Incode",
            "serviceOffering": "Incode BioGovID Verification",
            "attributeType": "SubmissionTimestamp",
            "dateCreated": "08/17/2023 18:22:41",
            "values": {
                "Timestamp": "17/08/2023 18:22:41"
            }
        },
        {
            "provider": "Incode",
            "serviceOffering": "Incode BioGovID Verification",
            "attributeType": "WorkflowTransactionStageAttempt",
            "dateCreated": "08/17/2023 18:22:41",
            "values": {
                "Count": "1"
            }
        },
        {
            "provider": "Incode",
            "serviceOffering": "Incode BioGovID Verification",
            "attributeType": "WorkflowTransactionStage",
            "dateCreated": "08/17/2023 18:22:41",
            "values": {
                "Stage": "1"
            }
        }
    ],
    "userAssertionList": null,
    "mbun": "jvsdahv87876-20a1-4bbc-925b-6ffeb7619ea3",
    "forwardApiKey": "",
    "policyObligation": false,
    "policyDecision": "approve"
}

If the policyDecision = approve , the user has been approved. Additional information on the SLVerify output(s) can be found here.