Dialer

Send a pre-recorded message to a user's phone number and receive a result that will let you know if the message was delivered.

This service is asynchronous

This service includes two POST request:

  • Initial request - defines which message to send and to what phone number. This request will also return a template with a unique token that should be submitted in the status request.

  • Status Request - a request with the template and token from the initial request to retrieve the status of the call.

You must provide the audio file

Provide your Veratad representative with the audio file you want to be delivered. You can have as many audio files as necessary. Once you have provided the audio file then Veratad will provide you with that files unique name which you will send as part of the initial request in the message attribute.

Please see the section below called "What types of audio files are acceptable" for a full list of file types.

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

post
PhoneMatch5.0.Dialer (initial request)

https://production.idresponse.com/process/comprehensive/gateway
Initial request details
Request
Response
Request
Body Parameters
user
required
string
Your account's API username
pass
required
string
Your account's API password
service
required
string
The service name (IDMatch5.0)
reference
optional
string
A unique identifier for your customer
target
required
object
The individual being sent for verification
phone
required
string
The target's phone number
options
optional
object
The transaction options
outofband
optional
object
The dialer specific options
message
optional
string
The audio file name provided to you by Veratad after you have provided Veratad with the audio file. (see below for acceptable audio file types)
do_not_send_to_types
optional
array
A list of line types that the message will not be delivered. Possible values are:mobile landline voip
Response
200: OK
Transaction processed and result returned
{
"output": {
"outofband": {}
},
"meta": {
"confirmation": 66834975,
"reference": "Unique Identifier",
"service": "PhoneMatch5.0.Dialer",
"timestamp": "2019-07-09 09:57:45",
"company": "Company ABC, Inc",
},
"result": {
"action": "PENDING",
"detail": "MORE INFORMATION IS REQUIRED",
"issues": []
},
"continuations": {
"outofband": {
"url": "/process/continue",
"template": {
"dialer": {
"return": "status"
},
"token": "ssskwryi5u5t222kd3sqjey4axsnonl8"
},
"instructions": "A phone call has been placed. Please resubmit to determine the status of said call"
}
}
}

Sample Initial Request Body

{
"user": "[email protected]",
"pass": "PASSWORD",
"service": "PhoneMatch5.0.Dialer",
"reference": "12345",
"options": {
"outofband": {
"message": "test.message",
"do_not_send_to_types": ["voip", "mobile", "landline"]
}
},
"target": {
"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 message was sent to the user. You may now send a subsequent request to get the status.

post
PhoneMatch5.0.Dialer (message status request)

https://production.idresponse.com/process/continue
OTP validation request details
Request
Response
Request
Body Parameters
token
required
string
The token returned in the initial request response
dialer
required
object
An object that contains the return value
return
required
string
The value to return
Response
200: OK
OTP match completed and response returned
{
"continuations": {
"outofband": {
"instructions": "A phone call has been placed. Please resubmit to determine the status of said call",
"template": {
"dialer": {
"return": "status"
},
"token": "ej809ouee0ci516cspuauva5m8q3cy2o"
},
"url": "\/process\/continue"
}
},
"meta": {
"company": "Company ABC, Inc",
"confirmation": 96399016,
"reference": null,
"service": "PhoneMatch5.0.Dialer",
"timestamp": "2020-07-14 10:33:14",
},
"output": [],
"result": {
"action": "PENDING",
"detail": "MORE INFORMATION IS REQUIRED",
"issues": []
}
}

Sample OTP Validation Request Body

{
"dialer": {
"return": "status"
},
"token": "ssskwryi5u5t222kd3sqjey4axsnonl8"
}

Action and Detail Response Status Request

Action

Detail

Description

FAIL

MESSAGE COULD NOT BE DELIVERED

Something went wrong and the message was never delivered to the customer.

PENDING

MORE INFORMATION IS REQUIRED

The call is still in progress. Take the template returned and submit again.

PASS

ALL CHECKS PASSED

The number is valid, the line type was not found in the do_not_send_to_types array, the message was successfully sent and was delivered.

Rules

PhoneMatch+Dialer 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 array

  • The message was sent successfully

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 array

  • The message was sent

  • The transaction is waiting for you to check the status

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 array

  • The message was not sent successfully

What types of audio files are acceptable?

You must provide Veratad with the audio file that you want delivered. Once you have provided this file Veratad will supply you with the files name in the system for you to populate the message attribute in your initial request.

Here are all of the acceptable file types:

MIME type

Description

audio/mpeg

mpeg layer 3 audio

audio/wav

wav format audio

audio/wave

wav format audio

audio/x-wav

wav format audio

audio/aiff

audio interchange file format

audio/x-aifc

audio interchange file format

audio/x-aiff

audio interchange file format

audio/x-gsm

GSM audio format

audio/gsm

GSM audio format

audio/ulaw

u-law audio format