Used to initiate Text-to-Speech (TTS) reverse PIN verification request.

Base URL

All requests to PhonesVerification must be submitted to the base URL. PhonesVerification provides you with an option of a response as a JSON object, or an XML string - you get to choose which response by selecting the appropriate base URL for your request.

JSON end point

XML end point

HTTP Methods

All requests are submitted through the HTTP POST method using UTF-8 encoding and URL encoded values.

Expected "Content-Type" for POST is "application/x-www-form-urlencoded", however we also support "application/json", "application/jsonrequest", "application/x-javascript", "text/json", "text/javascript", "text/x-javascript", "text/x-json" when posting parameters as a JSON object.


All requests require your API credentials (apikey & apisecret), which you can find under "API" tab in "Settings" in PhonesVerification Dashboard.

Parameter Description
apikey Required. Your API Key. Ex: apikey=qd4cr4gd
apisecret Required. Your API Secret. Ex: apisecret=87548754
number Required. Mobile number of the recipient in international format, and one recipient per request. Ex: number=148485454545
pin Required. PIN that will be announced to the listener. Limited to 8 digits. Since customer will be dialing the PIN code in their mobile device, the PIN code should consist of numbers only. Ex: pin=12345
callbackurl Optional. PhonesVerification sends information (such as status, price etc) regarding this request on this URL. Ex:
callbackurltype Optional. Expected response is "http" or "https" . Ex: callbackurltype=https
brand Optional. Adds brand name to the message played to the user. Limited to 20 characters. Ex: brand=phonesverification

Sample URL

JSON Response (Success)

  "Response": {
    "id": 458521,
    "PhoneNumber": "148485454545",
    "Price": 0.015,
    "Created": "2016-06-06T08:02:17.1",
    "VerificationType": "PhoneReversePinVerification"
  "ErrorMessage": "",
  "Status": 0

XML Response (Success)

<PhonesVerification xmlns:i="">

JSON Response (Failure)

  "Response": null,
  "ErrorMessage": "Unable to authenticate user. Please try with valid ApiKey/ApiSecret.",
  "Status": 3

XML Response (Failure)

<PhonesVerification xmlns:i="">
    <ErrorMessage>Unable to authenticate user. Please try with valid ApiKey/ApiSecret.</ErrorMessage>
    <Response i:nil="true" />

Callback Response Parameters

If you set callback in your request or your account, we will send following return parameters to your callback URL. Return Parameters are sent using a GET request.

Parameter Description
requestid int - Request ID generated for this particular request. For example: '12345'
recipient string - Phone number of the recipient. For example: '18482332008'
cost decimal - The total cost charged to your account for this request. For example: '0.01'
datetime string - Date & time on which the request was initiated. For example: 'Jun 9 2020 9:03AM'
status string - Current status of the request. Status can be one of the following: 'Sent', 'Delivered', 'Failed', 'Insufficient Balance', 'Stopped', 'Delivered - PIN Verified', 'Delivered - PIN Unverified', 'Machine Hangup'
matched bool - This parameter is specific to this call only. It will show either 'true' or 'false' based on whether user has successfully entered correct PIN code or not.

Example callback URL: - PIN Verified&requestid=12345&recipient=18482332008&datetime=Jun 9 2020 9:03AM&cost=0.01&matched=true

Respond Codes

Code Meaning
0 Request is successful
1 Request has failed.
2 Parameters are missing.
3 Credentials are invalid.
4 Parameters are invalid.
5 Result has returned empty.
6 Status is invalid.
7 Keyword is invalid.
8 Command is invalid.