Guides
Start typing to search…

API Integration of BioGovID

Table of Contents

  1. Overview
  2. Redirect URL
  3. 1. Get Access Token
    • Request Schema
    • Response Schema
  4. 2. Get / Send Document Capture Link
    • /send-link Request Schema
    • /send-link Response Schema
    • /get-link Request Schema
    • /get-link Response Schema
  5. 3. Verify
    • Request Schema
    • Response Schema

Overview

This guide provides a step-by-step overview of how to use the AXN Verify API to verify an individual using BioGovID. It covers authentication, link delivery for document capture, and retrieving the final verification decision.

📘

Prerequisites

  • Deploy the BioGovID Workflow by following the instructions here.
  • Obtain workflow access keys here.
  • Download and use the BioGovID Postman Collection here.

Redirect URL

📘

After the user completes document capture, they must be redirected away from the BioGovID interface.

The page they return to is defined by your asyncUIRedirect parameter.

1. Get Access Token

(POST) https://api.preprod.iddataweb.com/v1/token
API Reference: https://docs.iddataweb.com/reference/token

The access token is required for authenticating all subsequent API requests. Include it in the Authorization header as a Bearer token.

📘

When using the BioGovID Postman Collection, make sure to use your BioGovID API Key if you are not performing Country Selection before verification.

Access Token Request Example

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

Access Token Response Schema

{
  "errorCode": "string",
  "errorDescription": "string",
  "access_token": "string",
  "expires_in": "integer",
  "token_type": "Bearer"
}

2. Get / Send Document Capture Link

(POST) /v1/async-ui/send-link
(POST) /v1/async-ui/get-link

API References:

Once you have a valid access token, you may either send a document capture link to a user or generate the link without delivering it.

👍

Tip

  • Use /send-link to automatically send the document capture link to the user.
  • Use /get-link to generate the link for manual delivery.

/send-link Request Example

var data = {
    "apikey": "Your API Key",
    "credential": "[email protected]",
    "appID": "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';

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

/get-link Request Example

var data = {
    "apikey": "Your API Key",
    "credential": "[email protected]",
    "appID": "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';

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

/send-link Response Schema

{
  "services": [
    {
      "apTransactionId": "string",
      "name": "Incode BioGovID Verification",
      "status": "delivered",
      "apSessionId": "string"
    }
  ],
  "asi": "string"
}

/get-link Response Schema

{
  "services": [
    {
      "apTransactionId": "string",
      "name": "Incode BioGovID Verification",
      "url": "string",
      "status": "initialized",
      "apSessionId": "string"
    }
  ],
  "asi": "string"
}

3. Verify

(POST) https://api.preprod.iddataweb.com/v1/slverify
API Reference: https://docs.iddataweb.com/reference/slverify

After the user finishes the verification flow, they are redirected back to the Redirect URL you configured. This redirect will include the ASI, which must be submitted to /slverify to obtain the policy decision.

🚧

Ensure your application exposes a GET endpoint to receive asi from the redirect callback.

Verification Request Example

const axios = require("axios");

app.get("/redirect", async (request, response) => {
    var asi = req.query.asi;

    var data = {
        "credential": "incode",
        "asi": asi,
        "appID": "",
        "userAttributes": [],
        "country": "US",
        "idpType": "optional idp type",
        "apikey": "Your API Key"
    }

    var token = 'YOUR_BEARER_TOKEN';

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

    var verification = await requestVerify();
    var policyDecision = verification.policyDecision;

    if (policyDecision === 'approve') {
        response.redirect(`https://www...com/approved`);
    }

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

Verification Response Schema

{
  "errorCode": "string",
  "errorDescription": "string",
  "transaction_id": "string",
  "userAttributes": null,
  "acquiredAttributes": [
    {
      "provider": "Incode",
      "serviceOffering": "Incode BioGovID Verification",
      "attributeType": "string",
      "dateCreated": "MM/DD/YYYY HH:mm:ss",
      "values": {}
    }
  ],
  "userAssertionList": null,
  "mbun": "string",
  "forwardApiKey": "",
  "policyObligation": false,
  "policyDecision": "approve | deny"
}

If the policyDecision is approve, the user has successfully passed verification.
For more detail on the slverify response, see:
https://docs.iddataweb.com/docs/slverify-output

Updated 4 days ago