API Integration of MobileMatch

Suggest Edits

Overview

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

📘

Prerequisites

  • Deploy the "MobileMatch" Workflow by following the directions here.
  • Obtain the access keys for your new workflow by following the directions here
  • Download and use the MobileMatch Postman Project to try it out

📘

An example MobileMatch application is also made available for you to download here

What you'll do:

  • Collect the Full Name, Home Address and Personal Mobile Phone Number of the end user.
  • Ensure that the full name and/or address are associated with the phone number (Step 2).
  • Ensure that the end user has possession of the device (Steps 3 and 4).

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

Then, to request an access token:

var axios = require('axios')

var user = 'Your Workflow API Key';
var password = 'Your Workflow Shared 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": "TjZK7NSjw45AxGK9UhOE9uJDaZT23gKYuUC-9GMTAgLU", // your access token
    "expires_in": "1800",
    "token_type": "Bearer"
}

1.1. Country Selection

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

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

Once you've received an access token, you'll need to check if the user is located in a country supported by our services.

Using the same API Key as before, prompt the user to select a country, and if the country is supported, your response will contain the API Key required to take the next step in MobileMatch verification.

Request

var data = {
    "apikey": "Your API Key",
    "credential": "e.g. : [email protected]",
    "appID":"Your App Name, (e.g. 'Employee Onboarding App')",
    "userAttributes": [
        {
            "attributeType": "Country",
            "values": {
                "country": "US" // accepted values: (country codes) e.g. "US", "MX", "AU" ....
            }
        }
    ]
}

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/slverify',
    method: 'post',
    data: data,
    headers: {
      'Content-Type': 'application/json',
      'Cache-Control': 'no-cache',
      Authorization: 'Bearer ' + token,
    }
  })
    console.log(response.data)
}
request();

Response

{
    "errorCode": "",
    "errorDescription": "",
    "transaction_id": "xxxxx-xxxx-xxxx-xxxx-xxxxx",
    "userAttributes": [
        {
            "attributeType": "Country",
            "dateCreated": "11/08/2022 17:26:36",
            "values": {
                "country": "US"
            }
        }
    ],
    "acquiredAttributes": null,
    "userAssertionList": [
        {
            "provider": "Threatmetrix",
            "serviceOffering": "Threatmetrix Session Query Low Location Accuracy",
            "dateAsserted": "11/08/2022 17:26:37",
            "assertions": {
                "blacklist.device": "unverified",
                "blacklist.ofacIP": "unverified",
                "test.gte3Credential1d": "unverified",
                "detect.browserAnomaly": "unverified",
                "test.gte5Credential1d": "unverified",
                "test.lte3ProxyToday": "unverified",
                "test.trustedDevice6mo": "unverified",
                "test.trustedDevice": "unverified",
                "detect.possibleVPNOrTunnel": "unverified",
                "test.lte3CredentialsDevice7d": "unverified",
                "test.gte5Device1d": "unverified",
                "link.timeZone_TrueGeo": "unverified",
                "test.gte5CredentialDevice1d": "unverified",
                "test.credentialLTE500mi1hr": "unverified",
                "detect.vpn": "unverified",
                "test.exactIDAgeGTE7d": "unverified",
                "test.trueIPLTE500miInputIP": "unverified",
                "detect.proxyAnonymous": "unverified",
                "test.apSessionIDNotReplay": "unverified",
                "detect.jailbreak": "unverified",
                "link.proxyOrg_TrueOrg": "unverified",
                "test.expectedLanguage": "unverified",
                "blacklist.ip": "unverified",
                "detect.malware": "unverified",
                "detect.torExitNode90d": "unverified",
                "test.gte10Credential1d": "unverified",
                "detect.mobileTethering": "unverified",
                "test.trustedDevice28days": "unverified",
                "test.gte20Credential1d": "unverified",
                "detect.aggregator": "unverified",
                "test.smartIDAgeGTE7d": "unverified",
                "detect.proxyOpenTransparent": "unverified",
                "detect.unusualActivity": "unverified",
                "detect.proxyHidden": "unverified",
                "link.proxyISP_TrueISP": "unverified",
                "detect.tor": "unverified",
                "detect.torNode": "unverified",
                "detect.knownVPNISP": "unverified",
                "link.proxyGeo_TrueGeo": "unverified",
                "test.gte2Credential1d": "unverified"
            }
        }
    ],
    "mbun": "xxxxxx-xxxx-xxxx-xxxx-xxxxxx",
    "forwardApiKey": "324e1d4975f40c5", // Your Next API Key
    "policyObligation": true,
    "policyDecision": "obligation"
}

📘

NOTE:

The output above includes additional information from our Device Profiling service.

Device Profiling is the process of screening the Device and User Activity of a new transaction (user session).

If a transaction is found to be high risk (fraud), you'll be alerted of any fraudulent activity found, and the transaction will be prevented from proceeding further. Device Profiling requires an embedded script to run. Without it, assertions will be marked "unverified".

For more information on Device Profiling

2. Collect Personal Information (PII)

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

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

/slverify collects the individual's Personal Information and Phone Number, and returns a policyDecision indicating how accurately this information matches.

  • If the individual's Full Name and Phone Number match active phone records, /slverify will return a policyDecision of obligation, and also allow them to receive an OTP (via SMS or voice).

  • If the individual's Full Name and Phone Number do not match, /slverify will return a policyDecision of deny, and the workflow will not continue.

👍

Each step has a designated API Key.

Each key is designed to return the API key required for the next step. This key is called your forwardApiKey.

In the response body of your last request, you'll find your next forwardApiKey.

Request

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

var data = {
    "apikey": "YOUR_MOBILEMATCH_PII_API_KEY", // -- obtained from step 1.1 --
     "credential": "USERNAME",
     "appID":"YOUR_APPLICATION_NAME",
         "asi": "xxxxx-xxxx-xxxx-xxxxx", // -- obtained from step 1.1 --
     "userAttributes": [
    {
        "attributeType": "FullName",
        "values": {
            "fname": "John",
            "mname": "",
            "lname": "Smith"
        }
    },
    {
        "attributeType": "InternationalAddress",
        "values": {
            "country": "US",
            "administrative_area_level_1": "VA",
            "locality": "Vienna",
            "postal_code": "23225",
            "route": "Liberty St",
            "street_number": "123"
        }
    },
    {
        "attributeType": "InternationalTelephone",
        "values": {
            "dialCode": "1",
            "telephone": "1234567890"
        }
    }
]
}

var request = 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
    }
  })
  console.log(response.data)
}
request();

Response

{
    "errorCode": "",
    "errorDescription": "",
    "transaction_id": "xxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxx",
    "userAttributes": [
        {
            "attributeType": "FullName",
            "dateCreated": "10/27/2022 13:50:14",
            "values": {
                "fname": "John",
                "lname": "Smith",
                "mname": "",
                "suffix": null
            }
        },
        {
            "attributeType": "InternationalAddress",
            "dateCreated": "10/27/2022 13:50:14",
            "values": {
                "country": "US",
                "sublocality": null,
                "locality": "Vienna",
                "subpremise": null,
                "sublocality_level_2": null,
                "route": "Liberty St",
                "administrative_area_level_2": null,
                "premise": null,
                "sublocality_level_5": null,
                "administrative_area_level_3": null,
                "sublocality_level_4": null,
                "sublocality_level_3": null,
                "administrative_area_level_1": "VA",
                "street_number": "123",
                "neighborhood": null,
                "postal_code": "23225"
            }
        },
        {
            "attributeType": "InternationalTelephone",
            "dateCreated": "10/27/2022 13:50:14",
            "values": {
                "dialCode": "1",
                "telephone": "1234567890"
            }
        }
    ],
    "acquiredAttributes": [
        {
            "provider": "Experian",
            "serviceOffering": "Experian Precise ID",
            "attributeType": "ExperianScore",
            "dateCreated": "10/27/2022 13:50:15",
            "values": {
                "experianScore": "488"
            }
        },
        {
            "provider": "Experian",
            "serviceOffering": "Experian Precise ID",
            "attributeType": "MostRecentAddress",
            "dateCreated": "10/27/2022 13:50:15",
            "values": {
                "country": null,
                "address": null,
                "route": null,
                "administrative_area_level_1": null,
                "street_number": null,
                "locality": null,
                "postal_code": null,
                "subpremise": null
            }
        }
    ],
    "userAssertionList": [
        {
            "provider": "Experian",
            "serviceOffering": "Experian Precise ID",
            "dateAsserted": "10/27/2022 13:50:15",
            "assertions": {
                "test.fraudulentActivityAddress": "pass",
                "link.fullName_address": "fail",
                "link.lastName_address": "fail",
                "test.noAddressConflicts": "pass",
                "test.address90DaysOld": "pass",
                "test.fileOneAddressMatch": "pass",
                "test.addressIsResidential": "fail",
                "link.lastName_phone": "fail",
                "link.phone_address": "fail",
                "link.fullName_phone": "fail"
            }
        },
        {
            "provider": "Boku",
            "serviceOffering": "Boku - International Mobile Carrier Reverse Lookup",
            "dateAsserted": "10/27/2022 13:50:15",
            "assertions": {
                "link.phone_zip": "unverified",
                "test.lastPortGT14days": "unverified",
                "test.phone_landline_mobile_personal": "unverified",
                "test.phoneActive": "unverified",
                "test.lastPortGT30days": "unverified",
                "link.lastName_phone": "unverified",
                "link.phone_address": "unverified",
                "link.phone_state": "unverified",
                "link.fullName_phone": "unverified"
            }
        }
    ],
    "mbun": "xxxxxx-xxxx-xxxx-xxxx-xxxxxx",
    "forwardApiKey": "YOUR_FORWARD_API_KEY", // If you've successfully verified PII, this will be your OTP API key. If not, the API key to verify PII will be returned so that you can try again.
    "policyObligation": true,
    "policyDecision": "obligation"
}

3. Send OTP

(GET) https://api.preprod.iddataweb.com/v1/otp

The endpoint /otp allows you to send a one-time-passcode to the user's device.

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

Tip:

  • In your UI, prompt users to select whether they prefer to receive their OTP by "SMS" or "voice". Then, in your request params, pass the value into 'type' to continue with that method.
  • The default timeout for one-time-passcodes is 15 minutes.

Request

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

var params = {
  type: "SMS", // accepted values: "voice", "SMS"
  dialCode: "1",
  telephone: "1234567890",
  apikey: "YOUR_MOBILEMATCH_OTP_API_KEY", // -- obtained from step 2 --
  credential: "USERNAME",
  appID: "YOUR_APPLICATION_NAME",
  asi: "YOUR_TRANSACTION_ID", // -- obtained from step 1.1 --
};

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

Response

{
  responseCode: '200',
  errorDescription: null,
  asi: 'xxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxx',
  status: 'SUCCESS'
}

4. Verify OTP

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

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

After receiving an OTP, prompt the individual to verify the PINCode using /slverify.

Request

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

var data = {
    "asi": "xxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxx", // -- obtained from step 1.1 --
    "apikey": "YOUR_MOBILEMATCH_OTP_API_KEY", // -- obtained from step 2 --
    "credential": "USERNAME",
    "appID":"YOUR_APPLICATION_NAME",
    "userAttributes": [
        {
            "attributeType": "PINCode",
            "values": {
                "pincode": "123456",
                "pinType": "SMS" // accepted values: "voice", "SMS"
            }
        },
        {
            "attributeType": "InternationalTelephone",
            "values": {
                "dialCode": "1",
                "telephone": "1234567890"
            }
        },
        {
            "attributeType": "PINDeliveryPreference",
            "values": {
                "pindeliverypreference": "SMS" // accepted values: "voice", "SMS"
            }
        }
]
}



var request = 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,
    },
  });
  console.log(response.data);
};
request();

Response

{
  errorCode: '',
  errorDescription: '',
  transaction_id: 'xxxxxx-xxxx-xxxx-xxxx-xxxxxx',
  userAttributes: [
    {
      attributeType: 'PINCode',
      dateCreated: '10/27/2022 17:24:33',
      values: [Object]
    },
    {
      attributeType: 'InternationalTelephone',
      dateCreated: '10/27/2022 17:24:33',
      values: [Object]
    },
    {
      attributeType: 'PINDeliveryPreference',
      dateCreated: '10/27/2022 17:24:33',
      values: [Object]
    }
  ],
  acquiredAttributes: [
    {
      provider: 'IDDataWeb',
      serviceOffering: 'Assertion Score Service',
      attributeType: 'AssertionScore',
      dateCreated: '10/27/2022 17:24:33',
      values: [Object]
    },
    {
      provider: 'IDDataWeb',
      serviceOffering: 'Assertion Score Service',
      attributeType: 'RawAssertionScore',
      dateCreated: '10/27/2022 17:24:33',
      values: [Object]
    },
    {
      provider: 'IDDataWeb',
      serviceOffering: 'IDDataWeb Trust Score Service',
      attributeType: 'IDWScore',
      dateCreated: '10/27/2022 17:24:33',
      values: [Object]
    }
  ],
  userAssertionList: [
    {
      provider: 'IDDataWeb',
      serviceOffering: 'IDDataWeb International Phone PIN Service',
      dateAsserted: '10/27/2022 17:24:33',
      assertions: [Object]
    }
  ],
  mbun: 'xxxxxx-xxxx-xxxx-xxxx-xxxxxx',
  forwardApiKey: '',
  policyObligation: false,
  policyDecision: 'approve' // expect values: "approve", "deny"
}

Result

If policyDecision = approve, the individual has been approved.

policyDecision is a standard output of /slverify, the endpoint used to verify user information. Additional information on the output of SLVerify can be found here.

For instructions on how to test this workflow (including real user data), please visit: Testing MobileMatch Only

Updated about 1 month ago