API Integration of MobileMatch
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".
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.
For instructions on how to test this workflow (including real user data), please visit: Testing MobileMatch Only
Updated 5 months ago