API Documentation — BioVerify - AML/CFT biometric identity verification

BioVerify API

BioVerify offers an API that allows clients to initiate both biometric and non-biometric identity verifications and have the results of those verifications delivered via email in the form of an encrypted PDF or via a callback to the initiating client's systems.

Below you will find sample verification requests and a sample callback data package.

Verifications

Verification requests are made via a POST to https://api.bioverify.app/v1/verify with a header containing your api key:

x-api-key <the api key we provide you with>

Biometric - sample request

Request body:

{
    "verificationType": "NZ_STANDARD_BIOMETRIC",
    "individual" : {
        "firstName": "Frodo",
        "lastName": "Baggins"
    },
    "clientName": "Whatever Ltd",
    "clientReference": "ABC123",
    "resultDeliveryMethod": "PDF_VIA_EMAIL",
    "resultDeliveryEmailAddress": "test@mailinator.com",
    "pdfPassword": "SuperSecret1234$$"
}

Yields a response like

{
    "requestId": "37qJfAuFnkb2kYYHHMAK",
    "link": "https://bioverify.app/client/start/gsd2PybOc0JIM7dZkXn9"
}

You would send the link to your customer via SMS, email or some other messaging service or, if the customer is already on a mobile device you could simply forward them to the link URL.

If you want BioVerify to send the invitation message, include a mobile number or email address with the individual details, e.g.

{
    "verificationType": "NZ_STANDARD_BIOMETRIC",
    "individual" : {
        "firstName": "Frodo",
        "lastName": "Baggins"
        "mobile" : "+64 27 898800"
    },
    ...
}

In the example above, to minimise integration the caller chose to have the results delivered via email as an encrypted PDF attachment.

To have the verification results delivered via a callback, specify the appropriate resultDeliveryMethod, e.g.

"resultDeliveryMethod": "PDF_AND_SOURCES_DATA_VIA_CALLBACK"

If you specify result delivery via callback, you should record the requestId in your system so that you can match it to the corresponding results - see below.

Passing in your own data provider

We can use your existing Centrix or GreenID/GBG accounts. If you have a single account, you can provide us with the details and we'll configure everything for you. However, if you use multiple accounts on behalf of your clients, you can pass the appropriate details with each verification request.

Here's an example of passing in a Centrix account

{
  "verificationType": "NZ_STANDARD_BIOMETRIC",
  .....
  "dataProviderDetails": [
    {
      "dataProvider": "centrix",
      "parameters": [
        {
          "key": "CentrixSubscriberID",
          "value": "<your subscriber ID>"
        },
        {
          "key": "CentrixUserID",
          "value": "<your user ID>"
        },
        {
          "key": "CentrixUserKey",
          "value": "<your user key>"
        }
      ],
      "approvals": [
        {
          "key": "DIA",
          "value": true
        }
      ]
    }
  ]
}

Note that for us to check passports against DIA you must indicate that your client has DIA approval.

Non-biometric - sample request

Request body:

{
    "verificationType": "NZ_STANDARD_SOURCES",
    "individual" : {
        "firstName": "Frodo",
        "middleNames": "I",
        "lastName": "Baggins",
        "dateOfBirth": {
            "day": 23,
            "month": 8,
            "year": 1985
        },
        "residentialAddress": {
            "streetNumber": "12",
            "streetName": "Epuni",
            "streetType": "ST",
            "suburb": "Te Aro",
            "city": "Wellington",
            "postcode": "6011",
            "country": "NZ"
        },
        "id": "111999",
    },
    "idDocument": {
        "documentType": "DRIVERS_LICENCE.NZ",
        "documentNumber": "GF873009",
        "secondaryDocumentNumber": "521",
        "documentExpiryDate":{
            "day": 29,
            "month": 6,
            "year": 2025
        },
    },
    "clientName": "Whatever Ltd",
    "clientReference": "ABC123",
    "resultDeliveryMethod": "PDF_VIA_EMAIL",
    "resultDeliveryEmailAddress": "test@mailinator.com",
    "pdfPassword": "SuperSecret1234$$"
}

Yields a response like

{
    "requestId": "37qJfAuFnkb2kYYHHMAK",
}

As non-biometric checks don’t need the presence of the customer, there is no link and the verification is run almost immediately.

Detailed request documentation

Detailed documentation on how to construct a valid verification request can be found at https://bioverify.app/assets/docs/api.html.

Result delivery via callback

You can provide us with a callback URL to which we deliver the results.

Authentication

If you are able to provide a non-expiring token or key for authentication, we can simply use that. Alternatively, you can provide an OAUTH2 token-issuing URL together with a consumer key, consumer secret and password and we can call the issuing URL to obtain an access token to authenticate our POST to your endpoint.

Sample callback body

The callback data consists of

the overall verification status, being VERIFIED, PENDING or FAILED
the individual
the ID document
data source check results
watch-list check results
the encrypted PDF report, which is based 64 encoded.

For example:

{
  "requestId": "37qJfAuFnkb2kYYHHMAK",
  "verificationStatus": "PENDING",
  "individual": {
    "firstName": "FRODO",
    "middleNames": "DROGO",
    "lastName": "BAGGINS",
    "dateOfBirth": {
      "day": 22,
      "month": 9,
      "year": 1985
    },
    "residentialAddress": {
      "streetNumber": "42",
      "streetName": "JUBILEE",
      "streetType": "RD",
      "suburb": "KHANDALLAH",
      "city": "WELLINGTON",
      "country": "NZ",
      "postcode": "6035"
    }
  },
  "idDocument": {
    "documentType": "DRIVERS_LICENCE.NZ",
    "documentNumber": "AG273109",
    "secondaryDocumentNumber": "222",
    "documentExpiryDate": {
      "day": 29,
      "month": 6,
      "year": 2025
    }
  },
  "dataSourceChecks": [{
      "name": "Land Information New Zealand",
      "state": "MATCH",
      "matchingFields": [
          "address",
          "lastName",
          "firstName"
      ]
    }, {
        "name": "New Zealand Business Data",
        "state": "NO_MATCH",
        "matchingFields": []
  }],
  "watchListChecks": [{
      "name": "INTERPOL - Wanted Persons List",
      "state": "NO_MATCH"
    }, {
      "name": "Politically Exposed Persons Watchlist",
      "state": "MATCH"
  }],
  "pdfReport": "JVBERi0xLjcKJb/3ov4KMSAwIG9iago8PCAvRXh0ZW5zaW9ucyA8PCAvQURCRSA8PCAvQmFzZVZlcnNpb24gLzEuNyAvRXh0ZW5zaW9uTGV2ZWwgOCA+PiA+PiAvUGFnZXMgMyAwIFIgL1R5cGUgL0NhdGFsb2cgPj4KZW5kb2JqCjIgMCBvYmoKPDwgL0NyZWF0aW9uRGF0ZSA8YjAzMmE3NzcwODc5MmE3NDljNDc2Zjk5ZWVkNjAyMzI1MDk2NWNmNzAwOTQyNDRjMDliYWUzZDQyYTAzZWQzNDFhZGQ1OWVhOWY4MzMyMjBiODA4MjRhM2RkZmJlYjM2PiAvQ3JlYXRvciA8ZjFlN2NmNWU4MzMwNTVmNmZkMzkxOTBhMGNjZTBkZTU5MzE2ZjQ3ZjllMzI1ZmFmZmUyMThiNzhjNmZiYmExZj4gL01vZERhdGUgPDA5NGZiZTE3MDYxMjNlMTczNzQwNzdjYjQ4ZDI2NjMyNWNmZmYwNDQ4MmU2NzI5MjcxMTU4N2ZjNjgzODRmZWQ2MTg0YWUxYTY4ZjgzNjczYzVhNjFlYWU0OWQzYzQ1Mz4gL1Byb2R1Y2VyIDxkYjIxMGNiMTY4NDc4YTg1MjI1Y2Y4MmNkZDcwZGI4ODEwNWNkN2VmMjVhNzdjNmMxYjFmZDg2ZDQ2ZWQ5NGNhPiA+PgplbmRvYmoKMyAwIG9iago8PCAvQ291bnQgNCAvS2lkcyBbIDQgMCBSIDUgMCBSIDYgMCBSIDcgMCBSIF0gL1R5cGUgL1BhZ2VzID4+CmVuZG9iago0IDAgb2JqCjw8IC9Db250ZW50cy.....A4IDAgUiAvTWVkaWFCb3ggWyAwIDAgNTk0Ljk1OTk2IDg0MS45MTk5OCBdIC9QYXJlbnQgMyAwIFIgL1Jlc291cmNlcyA8PCAvRXh0R1N0YXRlIDw8IC9HMTYgOSAwIFIgL0cxOCAxMQzMCAwMDAwMCBuIAowMDAwNTQ2NjYxIDAwMDAwIG4gCjAwMDA1NDY5MTQgMDAwMDAgbiAKMDAwMDU0NzE2MSAwMDAwMCBuIAowMDAwNTQ3NDAzIDAwMDAwIG4gCjAwMDA1NDc3MzEgMDAwMDAgbiAKMDAwMDU0Nzk4NCAwMDAwMCBuIAowMDAwNTYxOTI5IDAwMDAwIG4gCjAwMDA1ODc5MDYgMDAwMDAgbiAKMDAwMDYxNTE0NyAwMDAwMCBuIAowMDAwNjM0NDY4IDAwMDAwIG4gCnRyYWlsZXIgPDwgL0luZm8gMiAwIFIgL1Jvb3QgMSAwIFIgL1NpemUgNzUgL0lEIFs8ZDQyMjZiZDM0ODhlMzlkZTM4ZjBjYjk5YzFiZjYxNjg+PGQ0MjI2YmQzNDg4ZTM5ZGUzOGYwY2I5OWMxYmY2MTY4Pl0gL0VuY3J5cHQgNzQgMCBSID4+CnN0YXJ0eHJlZgo2MzUwMTkKJSVFT0YK"
}

Note that the requestId matches the one returned from the original call to initiate the verification.

Also note that we do encrypt the PDF as many systems provide a download function and we need to guard against PDFs that contain full identity data sitting unprotected on desktops. The password protection has the additional benefit of making the report immutable.

Detailed callback documentation

Detailed documentation on the structure of the callback payload can be found at https://bioverify.app/assets/docs/callback.html

Callback failure handling

If when our system makes the callback, we do not receive a response indicating success, we automatically retry after 30 seconds, then again after waiting a further 60, 120, 240 and 480 seconds. If the callback still fails we will work with you to resolve the issue. If using a web-based flow, we can restart the process and deliver any missed callbacks once the issues have been resolved.