# Call ## 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.Call (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 (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 | {% tabs %} {% tab title="200 Transaction processed and result returned" %} ```javascript { "output": { "outofband": {} }, "meta": { "confirmation": 57984073, "reference": "12345", "service": "PhoneMatch5.0.Call", "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.Call", "reference": "12345", "options": { "outofband": { "do_not_send_to_types": ["voip", "mobile", "landline"], "country": { "blacklist": ["ISO2 Country Code"], //countires you do not want to send codes "whitelist": ["ISO2 Country Code"] //countires 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.Call (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 %} --- # Agent Instructions: Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter: ``` GET https://api.veratad.com/phone-verification-and-validation/one-time-passwords/call-otp.md?ask= ``` The question should be specific, self-contained, and written in natural language. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.