USPhoneVerify API Command Reference

API command reference

The API endpoint URL for scripted requests is

https://www.usphoneverify.com/api_command.php

To authorize for API requests, you should generate an API key on the Account -> Profile page. Please note that this action requires a confirmation by email.

One-time MDNs

Quick jump: Balance & Other Info | Webhook URL

1. Request an MDN

Note: each one-time MDN request can only receive a single SMS. If you need to receive another message for the same number and service, make a new request passing "mdn" parameter to reuse the same phone number.

Parameter	Value	Required
cmd	"request"	Y
user	Your user name or email	Y
api_key	Your API key	Y
service	Service name (as returned by "list_services" command or seen on Billing -> Services and Rates page).	Y
mdn	If this parameter is passed, we will try to provide this specific requested MDN. It can be either reused with the same service or used with another one. The script will return an error if this number is used in an open request or is not available anymore.	N
areacode	A valid 3-digit area code. Takes precedence over "state" parameter. If "mdn" parameter is passed, the "areacode" parameter is ignored.	N
state	A valid 2-character US state abbreviation. If this parameter is passed, we will try to provide a number from a specific state. If "mdn" or "areacode" parameters are passed, the "state" parameter is ignored.	N
markup	A numeric value, between 10 and 2000 for "priority requests" feature. If passed, and there are no MDNs available for a particular service, the request will be created with "Awaiting MDN" status and a lifetime of 30 minutes. If during that time an MDN becomes available, and there are several users that placed bids, it will be given to the one who placed the highest bid earlier than others. The status of the request will then change to "Reserved". You can monitor the status of the request using "request_status" command. Also, if you have configured a webhook URL, you will receive an event of "priority_request" type if your bid has won. After 30 minutes an unfulfilled request with "Awaiting MDN" status will be automatically deleted. Tip: use the "list_services" command with a single service name to get the "recommended_markup" value as a starting point for your bid.	N

A JSON array with the following fields will be returned:

Parameter	Value
status	"ok" or "error"
message	If "status" field equals to "error" this field will contain the explanation of the error. if "status" equals to "ok", a JSON array will be returned with each entry containing these variables: "id", "mdn", "service", "status", "state" (for geo-targeted requests), "markup", "price", "carrier" and "till_expiration" (in seconds).

Example request:

https://www.usphoneverify.com/api_command.php?cmd=request&user=test&api_key=0123456789&service=Amazon

Example output:

Successful request:

{
  "status": "ok",
  "message": [
    {
      "id": "10000001",
      "mdn": "15302286946",
      "service": "Amazon",
      "status": "Reserved",
      "state": "",
      "markup": 0,
      "price": 0.50,
      "carrier": "TMobile",
      "till_expiration": 900
    }
  ]
}

Unsuccessful request:

{
  "status":"error",
  "message":"Invalid service name Goooooogle"
}

{
  "status":"error",
  "message":"No numbers available, retry later"
}

This is an example output when a priority request using "markup" parameter is made. The value of "mdn" parameter will be empty, and the status will be "Awaiting MDN".

{
  "status": "ok",
  "message": [
    {
      "id": "10000001",
      "mdn": "",
      "service": "Amazon",
      "status": "Awaiting MDN",
      "state": "CA",
      "markup": 25,
      "price": 0.60,
      "carrier": "",
      "till_expiration": 900
    }
  ]
}

To reuse the MDN you have used with a certain service, please add "mdn" parameter to the request. Keep in mind that the numbers are changed periodically, so it may not be available any more by the time you want to re-activate your account.

Example request:

https://www.usphoneverify.com/api_command.php?cmd=request&user=test&api_key=0123456789&service=Amazon&mdn=12345678901

Example output:

Unsuccessful request:

{
  "status":"error",
  "message":"The MDN is not available"
}

Requesting the same MDN for different services at once

It is possible to pass several service names to "request", command to be able to get an MDN that can be used for all listed services at the same time. In such a case, several priority requests will be created, and when a suitable phone number becomes available, it will be assigned to these requests.

For each of the services you pass a markup will be assigned automatically to ensure you are the highest bidder for all of them.

Note that using geo targeting may greatly limit the pool of available numbers.

Parameter	Value	Required
cmd	"request"	Y
user	Your user name or email	Y
api_key	Your API key	Y
service	Up to 5 service names, separated with commas (as returned by "list_services" command or seen on Billing -> Services and Rates page).	Y
areacode	A valid 3-digit area code. Takes precedence over "state" parameter.	N
state	A valid 2-character US state abbreviation. If this parameter is passed, we will try to provide a number from a specific state. If "areacode" parameter is passed, the "state" parameter is ignored.	N

Example request:

https://www.usphoneverify.com/api_command.php?cmd=request&user=test&api_key=0123456789&service=Yahoo,Google,Amazon

Example output:

{
  "status": "ok",
  "message": [
    {
      "id": "10000001",
      "mdn": "",
      "service": "Amazon",
      "status": "Awaiting MDN",
      "state": "",
      "markup": 10,
      "price": 0.30,
      "carrier": "",
      "till_expiration": 900
    },
    {
      "id": "10000002",
      "mdn": "",
      "service": "Google",
      "status": "Awaiting MDN",
      "state": "",
      "markup": 110,
      "price": 1.30,
      "carrier": "",
      "till_expiration": 900
    },
    {
      "id": "10000003",
      "mdn": "",
      "service": "Yahoo",
      "status": "Awaiting MDN",
      "state": "",
      "markup": 50,
      "price": 0.45,
      "carrier": "",
      "till_expiration": 900
    }
  ]
}

2. Get a status of the request

Get a current status of the request by its ID.

Parameter	Value	Required
cmd	"request_status"	Y
user	Your user name or email	Y
api_key	Your API key	Y
id	Request ID, as obtained with "Request" command.	Y

A JSON array with the following fields will be returned:

Parameter

Value

status

"ok" or "error"

message

If "status" field equals to "error" this field will contain the explanation of the error.

if "status" equals to "ok", a JSON array will be returned with each entry containing these variables: "id", "mdn", "service", "status", "state" (for geo-targeted requests), "markup", "carrier" and "till_expiration" (in seconds).

Possible values for the "status" field inside "message" array:
• Awaiting MDN — a priority bid has been placed; no number has been assigned yet. The "mdn" field will be empty.
• Reserved — a phone number has been assigned and is waiting for an incoming SMS. The "mdn" field will contain the assigned number.
• Completed — an SMS has been received. Use the "read_sms" command to retrieve the message.
• Rejected — the request was rejected by you (via the "reject" command) or no suitable number was available.
• Timed Out — no SMS arrived within the allowed time; the request has been automatically cancelled.

Polling note: when polling this command while waiting for a status change, it is recommended to wait at least 15 seconds between requests.

Example request:

https://www.usphoneverify.com/api_command.php?cmd=request_status&user=test&api_key=0123456789&id=10000001

Example output:

Successful request:

{
  "status": "ok",
  "message": [
    {
      "id": "10000001",
      "mdn": "",
      "service": "Amazon",
      "status": "Awaiting MDN",
      "state": "CA",
      "markup": 20,
      "carrier": "",
      "till_expiration": 300
    }
  ]
}

{
  "status": "ok",
  "message": [
    {
      "id": "10000001",
      "mdn": "12345678901",
      "service": "Amazon",
      "status": "Reserved",
      "state": "CA",
      "markup": 20,
      "carrier": "ATT",
      "till_expiration": 890
    }
  ]
}

Unsuccessful request:

{
  "status":"error",
  "message":"Invalid request ID"
}

3. Reject an MDN

Reject an MDN that has "Reserved" status. After rejection this number won't be offered to you anymore.

The command can also be used to cancel your bid if you're using priority requesting.

Parameter	Value	Required
cmd	"reject"	Y
user	Your user name or email	Y
api_key	Your API key	Y
id	Request ID, as obtained with "Request" command.	Y

A JSON array with the following fields will be returned:

Parameter	Value
status	"ok" or "error"
message	If "status" field equals to "error" this field will contain the explanation of the error. if "status" equals to "ok", this means the MDN has been rejected successfully.

Example request:

https://www.usphoneverify.com/api_command.php?cmd=reject&user=test&api_key=0123456789&id=10000001

Example output:

Successful request:

{
  "status": "ok",
  "message": "MDN has been rejected"
}

Unsuccessful request:

{
  "status":"error",
  "message":"Invalid request ID"
}

4. Read SMS

Get messages received to a one-time or long-term rented MDN. Kindly note that using this method is not recommended, since SMS polling may take a lot of resources.

Consider configuring a webhook URL (described below).

Note: when filtering by "id", this command only returns a result after the request status changes to "Completed" (i.e. an SMS has been received). Without the "id" filter, messages from previously completed requests may also be included in the response.

Parameter	Value	Required
cmd	"read_sms" The script will return a maximum of 3 latest messages received in the past 2 days, sorted by time of receipt, in descending order (newest messages first)	Y
user	Your user name or email	Y
api_key	Your API key	Y
id	ID of a one-time MDN rental, as obtained with "request" command. Once added to parameters list, will filter output by the request ID. If passed, "mdn" and "service" parameters are ignored.	N
mdn	Use MDN parameter to filter the command results only by that MDN.	N
service	One service name can be added to the request in order to filter the command results only by that service.	N

A JSON array with the following fields will be returned:

Parameter

Value

status

"ok" or "error"

message

If "status" field equals to "error" this field will contain the explanation of the error

if "status" equals to "ok", a JSON array will be returned with each entry containing the following variables:
"timestamp": UNIX timestamp of the time the message was received
"date_time" in human-readable format (server's time zone is America/New_York)
"from": the sending number
"to": the receiving number
"service": service name
"price": price
"reply": contents of the received SMS
"pin": a PIN code, when it was successfully recognized

Example request:

https://www.usphoneverify.com/api_command.php?cmd=read_sms&user=test&api_key=0123456789&service=Google

Example output:

Successful request:

{
  "status": "ok",
  "message": [
    {
      "timestamp": "1600108956",
      "date_time": "2020-09-14 14:42:36 EDT",
      "from": "22000",
      "to": "18503814729",
      "service": "Google",
      "price": 1.20,
      "reply": "G-804036 is your Google verification code.",
      "pin": "G-804036"
    },
    {
      "timestamp": "1600108852",
      "date_time": "2020-09-14 14:40:52 EDT",
      "from": "18339020112",
      "to": "15182193312",
      "service": "Google",
      "price": 1.20,
      "reply": "G-551858 is your Google verification code.",
      "pin": "G-551858"
    }
  ]
}

Unsuccessful request:

{
  "status": "error",
  "message":"No messages"
}

Balance & Other Info

Quick jump: One-time MDNs | Webhook URL

1. List services

Parameter	Value	Required
cmd	"list_services"	Y
user	Your user name or email	Y
api_key	Your API key	Y
service	One or many service names (as returned by "list_services" command or seen on Billing -> Services and Rates page), separated by comma. If this parameter is omitted, all available services will be listed.	N

A JSON array with the following fields will be returned:

Parameter	Value
status	"ok" or "error"
message	If "status" field equals to "error" this field will contain the explanation of the error. if "status" equals to "ok", a JSON array will be returned with each entry containing these variables: "name", "price", "ltr_price", "ltr_short_price", "otp_available", "ltr_available", "recommended_markup".

Example request:

https://www.usphoneverify.com/api_command.php?cmd=list_services&user=test&api_key=0123456789&service=Google

Example output:

Successful request:

{
  "status": "ok",
  "message": [
    {
      "name": "Google",
      "price": "1.00",
      "ltr_price": "20.00",
      "ltr_short_price": "5.00",
      "otp_available": "74",
      "ltr_available": "3",
      "recommended_markup": "10"
    }
  ]
}

Unsuccessful request:

{  "status": "error",
   "message":"Invalid service name DummyService"
}

The "recommended_markup" variable will only return a value when a "service" parameter is passed with a single value.

The availability data returned by this command is approximate, as it is not calculated in real time. Only when you make a request, you will know if there are any numbers available for a certain service.

2. View balance

Parameter	Value	Required
cmd	"balance"	Y
user	Your user name or email	Y
api_key	Your API key	Y

A JSON array with the following fields will be returned:

Parameter	Value
status	"ok" or "error"
message	If "status" equals to "ok", your current balance will be displayed, otherwise it will contain the explanation of the error.

Example request:

https://www.usphoneverify.com/api_command.php?cmd=balance&user=test&api_key=0123456789

Example output:

{
  "status": "ok",
  "message": "10.00"
}

Webhook URL

Quick jump: One-time MDNs | Balance & Other Info

1. How to set up a webhook URL

Please go to Account -> Profile in the members area and set up a webhook URL where all notifications from the script will be forwarded. Data will be sent as a POST request to your URL. Note that your URL must return HTTP 200 code and not use use redirects.

If your URL is unavailable when we send data to it (i.e., the response status is not HTTP 200), the script will attempt to notify your URL five more times at 10-minute intervals and then stop the attempts.

2. Incoming messages

The following fields will be passed:

Field	Value
event	"incoming_message"
id	request ID, as obtained with "request" API command.
timestamp	UNIX timestamp
date_time	date and time, in human-readable format (server's time zone is America/New_York)
from	the sending number
to	the receiving number
service	service name
reply	contents of the received SMS
pin	a PIN code, when it was successfully recognized
price	price of the received message

3. Winning of a priority request

When your priority request wins and you are successfully assigned a number, the following message will be sent.

Field	Value
event	"priority_request"
status	"ok"
id	Id of your request.
mdn	MDN
service	Service name
price	The price of the request