Used to initiate Short Message Service (SMS) 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

Sample URL

JSON Response (Success)

  "Response": {
    "id": 458521,
    "PhoneNumber": "148485454545",
    "Price": 0.015,
    "Created": "2016-06-06T08:02:17.1",
    "VerificationType": "SmsPinVerification"
  "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
id int - Request ID generated for this particular request. For example: '12345'
text string - Message sent to the recipient. For example: 'Your verification code is 12345.'
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'

Example callback URL: verification code is 12345.&datetime=Jun  9 2020 9:03AM&cost=0.01

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.