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

https://phonesverification.com/app/api/json

XML end point

https://phonesverification.com/app/api/xml

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.

Parameters

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: callbackurl=www.abc.com/getcallback.aspx
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

https://phonesverification.com/app/api/json/sms/pinverification?apikey=qd4cr4gd&apisecret=87548754&number=148485454545&pin=1234abc&brand=phonesverification

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="http://www.w3.org/2001/XMLSchema-instance">
    <ErrorMessage></ErrorMessage>
    <Response>
        <Created>2016-06-06T08:02:17.1</Created>
        <PhoneNumber>148485454545</PhoneNumber>
        <Price>0.015</Price>
        <VerificationType>SmsPinVerification</VerificationType>
        <id>458521</id>
    </Response>
    <Status>0</Status>
</PhonesVerification>

JSON Response (Failure)

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

XML Response (Failure)

<PhonesVerification xmlns:i="http://www.w3.org/2001/XMLSchema-instance">
    <ErrorMessage>Unable to authenticate user. Please try with valid ApiKey/ApiSecret.</ErrorMessage>
    <Response i:nil="true" />
    <Status>3</Status>
</PhonesVerification>

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:

https://example.com/PVCallback?id=12345&text=Your 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.