> For the complete documentation index, see [llms.txt](https://api.veratad.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://api.veratad.com/phone-verification-and-validation/one-time-passwords/sms-otp.md). # SMS ## 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. {% 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.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

| {% tabs %} {% tab title="200 Transaction processed and result returned" %} ```javascript { "output": { "outofband": {} }, "meta": { "confirmation": 57984073, "reference": "12345", "service": "PhoneMatch5.0.SMS", "timestamp": "2019-01-07 12:35:09", "company": "Company ABC, Inc.", "user": "user@company.com" }, "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." } } } ``` {% endtab %} {% endtabs %} ## Sample Initial Request Body ```javascript { "user": "user@company.com", "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 | {% tabs %} {% tab title="200 OTP match completed and response returned" %} ```javascript { "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": "root@veratad.com" }, "output": { "codematch": { "key_matched": true } }, "result": { "action": "PASS", "detail": "ALL CHECKS PASSED", "issues": [] } } ``` {% endtab %} {% endtabs %} ## Sample OTP Validation Request Body ```javascript { "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: {% 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 OTP was sent successfully * The user OTP entry matched the OTP sent {% 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 OTP was sent successfully * The transaction is waiting for submission of the user's OTP entry {% 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 OTP was not sent successfully * The user OTP entry did not match the OTP sent {% endhint %}