# Dialer
## 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.
{% hint style="info" %}
As part of this process you are also validating the number the user provided since the service will not send to invalid phone lines.
{% endhint %}
## PhoneMatch5.0.Dialer (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 |
| phone\* | string | The target's phone number |
| options | object | The transaction options |
| outofband | object | The dialer specific options |
| message | 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 | array | A list of line types that the message will not be delivered. Possible values are:mobile
landline
voip
|
{% tabs %}
{% tab title="200 Transaction processed and result returned" %}
```javascript
{
"output": {
"outofband": {}
},
"meta": {
"confirmation": 66834975,
"reference": "Unique Identifier",
"service": "PhoneMatch5.0.Dialer",
"timestamp": "2019-07-09 09:57:45",
"company": "Company ABC, Inc",
"user": "user@company.com"
},
"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"
}
}
}
```
{% endtab %}
{% endtabs %}
## Sample Initial Request Body
```javascript
{
"user": "user@company.com",
"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. |
## PhoneMatch5.0.Dialer (message status 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 |
| dialer | object | An object that contains the return value |
| return | string | The value to return |
{% tabs %}
{% tab title="200 OTP match completed and response returned" %}
```javascript
{
"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",
"user": "user@company.com"
},
"output": [],
"result": {
"action": "PENDING",
"detail": "MORE INFORMATION IS REQUIRED",
"issues": []
}
}
```
{% endtab %}
{% endtabs %}
## Sample OTP Validation Request Body
```javascript
{
"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:
{% hint style="success" %}
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
{% endhint %}
{% hint style="warning" %}
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
{% endhint %}
{% hint style="danger" %}
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
{% endhint %}
## 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 |