Used to initiate Text-to-Speech (TTS) 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 characters. Ex: pin=1234abc
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
locale Optional. The language used to synthesize the message. Default is "en" for English. Ex: locale=en

Sample URL

JSON Response (Success)

  "Response": {
    "id": 458521,
    "PhoneNumber": "148485454545",
    "Price": 0.015,
    "Created": "2016-06-06T08:02:17.1",
    "VerificationType": "PhonePinVerification"
  "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" />

Response Parameters

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

Parameter Description
requestid Request ID generated for this particular request.
text Message announced to the listener.
recipient Phone number of the recipient.
cost The total cost charged to your account for this request.
date Date & time on which the request was initiated.
status Current status of the request.

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.