Call
Validate a user's number and send a one time password via call 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.
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.
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.Call (initial request)
POST
https://production.idresponse.com/process/comprehensive/gateway
Initial request details
Request Body
user
string
Your account's API username
pass
string
Your account's API password
service
string
The service name (PhoneMatch5.0.Call)
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
do_not_send_to_types
array
A list of line types that the message will not be delivered. Possible values are:mobile landline voip
Sample Initial Request Body
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.Call (OTP validation request)
POST
https://production.idresponse.com/process/continue
OTP validation request details
Request Body
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
Sample OTP Validation Request Body
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:
The base ruleset will return a PASS when:
The phone number is valid
The phone line type is not found in the
do_not_send_to_types
arrayThe OTP was sent successfully
The user OTP entry matched the OTP sent
The base ruleset will return a PENDING when:
The phone number is valid
The phone line type is not found in the
do_not_send_to_types
arrayThe OTP was sent successfully
The transaction is waiting for submission of the user's OTP entry
The base ruleset will return a FAIL when:
The phone number is not valid
The phone line type is found in the
do_not_send_to_types
arrayThe OTP was not sent successfully
The user OTP entry did not match the OTP sent
Last updated