SMS

Validate a user's number and send a one time password via SMS to their phone to verify they have possession.

This service is asynchronous

The PhoneMatch OTP delivery services are asynchronous which means you will make an initial call to send the OTP and receive a response and a second call to validate the user's OTP entry against what was sent.

  1. Initial Request - Send the phone number with other options via the Initial Request Instructions below and when successful you will receive a response with a template that includes a token value.

  2. OTP Validation Request - Send the template returned in the initial request including the token and the user's OTP entry back to the system for final match result.

As part of this process you are also validating the number the user provided since the service will not send to invalid phone lines.

PhoneMatch5.0.SMS (initial request)

POST https://production.idresponse.com/process/comprehensive/gateway

Initial request details

Request Body

Name
Type
Description

user*

string

Your account's API username

pass*

string

Your account's API password

service*

string

The service name (IDMatch5.0)

reference

string

A unique identifier for your customer

target

object

The individual being sent for verification

fn*

string

The target's first name

ln*

object

The target's last name

phone*

string

The target's street address (line 1 and line 2)

options

object

the target's city

outofband

object

The target's state

message

string

The sms message content. Use {} to enter a target attribute and the OTP value i.e. Hello {fn}, your one-time password is {pin}

do_not_send_to_types

array

A list of line types that the message will not be delivered. Possible values are: mobile landline voip

{
  "output": {
    "outofband": {}
  },
  "meta": {
    "confirmation": 57984073,
    "reference": "12345",
    "service": "PhoneMatch5.0.SMS",
    "timestamp": "2019-01-07 12:35:09",
    "company": "Company ABC, Inc.",
    "user": "[email protected]"
  },
  "result": {
    "action": "PENDING",
    "detail": "MORE INFORMATION IS REQUIRED",
    "issues": []
  },
  "continuations": {
    "outofband": {
      "url": "/process/continue",
      "template": {
        "token": "o76m3nvz94jvaatfsmespzgx3qkzjjl1",
        "codematch": {
          "key": null
        }
      },
      "instructions": "A code has been delivered to the provided number.  Please resubmit the code to complete the transaction."
    }
  }
}

Sample Initial Request Body

{
	"user": "[email protected]",
	"pass": "PASSWORD",
	"service": "PhoneMatch5.0.SMS",
	"reference": "12345",
	"options": {
		"outofband": {
			"message": "Hello {fn}, your one-time password is {pin}",
			"do_not_send_to_types": ["voip", "mobile", "landline"],
			"country": {
				"blacklist": ["ISO2 Country Code"], //countries you do not want to send codes  
                		"whitelist": ["ISO2 Country Code"] //countries you only want to send codes
			}
		}
	},
	"target": {
		"fn": "John",
		"ln": "Smith",
		"phone": "2015106000"
	}
}

Action and Detail Responses Initial Request

The following are all values that will be returned in the result object of the response.

Action
Detail
Description

FAIL

SUPPRESSED SENDING CODE

The phone line type was detected as one of the line types passed in the options object in the do_not_send_to_types array

FAIL

FAILED TO SEND TO NUMBER

An issue occurred during password delivery and it never reached the user

FAIL

DATA CHECK FAILED

The phone number is invalid and the code could not be sent

PENDING

TRANSACTION REQUIRES FURTHER ATTENTION

The line type is not in the do_not_send_to_types array, the number is valid and the SMS was sent to the user. The transaction is now waiting for submission of the OTP for final matching

PhoneMatch5.0.SMS (OTP validation request)

POST https://production.idresponse.com/process/continue

OTP validation request details

Request Body

Name
Type
Description

token

string

The token returned in the initial request response

codematch

object

An object that contains the key with the user's OTP entry

key

string

The user's OTP entry

{
	"final": {
		"template": {
			"token": "1x6mvu6b4kuwonduqw8b1nsj7jpxgaza"
		},
		"url": "\/process\/status"
	},
	"meta": {
		"company": "Veratad Technologies, LLC",
		"confirmation": 96197373,
		"reference": null,
		"service": "PhoneMatch5.0.SMS",
		"timestamp": "2020-07-10 10:46:08",
		"user": "[email protected]"
	},
	"output": {
		"codematch": {
			"key_matched": true
		}
	},
	"result": {
		"action": "PASS",
		"detail": "ALL CHECKS PASSED",
		"issues": []
	}
}

Sample OTP Validation Request Body

{
	"token": "o76m3nvz94jvaatfsmespzgx3qkzjjl1",
	"codematch": {
		"key": "12345"
	}
}

Action and Detail Response OTP Validation Request

Action
Detail
Description

FAIL

FAILED OUT-OF-BAND CHECK

The number is valid, the line type was not found in the do_not_send_to_types array, the OTP was successfully sent, the user entered the OTP and the OTP entered DID NOT match the OTP sent.

PASS

ALL CHECKS PASSED

The number is valid, the line type was not found in the do_not_send_to_types array, the OTP was successfully sent, the user entered the OTP and the OTP entered matched the OTP sent.

Rules

PhoneMatch+SMS will process with the default base ruleset:

Last updated