Login Register
Developer Resources

API Documentation

Integrate CodeBypass SMS verification services seamlessly into your applications. Our comprehensive API provides real USA non-VoIP numbers with enterprise-grade reliability.

99.9%
Uptime
<200ms
Response Time
24/7
Support
Get Started Get API Key
Request SMS Verification
POST https://www.codebypass.app/api_command.php
"cmd": "request"
"service": "Google"
"api_key": "your_api_key"

Code Bypass API Command Reference

API command reference

The API endpoint URL for scripted requests is

https://www.codebypass.app/api_command.php

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

One-time MDNs

Quick jump: Long-term MDN Rentals | Balance & Other Info | Proxy Rentals | HTTP Callback

1. Request an MDN

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 be seen on View Services web 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 3-digit area code. Takes precedence over "state" patameter. If "mdn" parameter is passed, the "areacode" parameter is ignored. N
state A 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 "Premium 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 callback URL, you will receive an event of "premium_request" type if your bid has won.

After 30 minutes an unfulfilled request with "Awaiting MDN" status will be automatically deleted.		 N

Returned data is a JSON array with the following data:

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-tergeted requests), "markup", "price", "carrier" and "till_expiration" (in seconds).

Example request

Request URL 
https://www.codebypass.app/api_command.php?cmd=request&user=test&api_key=0123456789&service=Amazon

Example output:

JSON Response 
{
"status":"error",
"message":"Invalid service name Goooooogle"
}
{
"status":"error",
"message":"No numbers available, retry later"
}

or, in the case a request was successful:

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

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

JSON Response 
{
"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

Request URL 
https://www.codebypass.app/api_command.php?cmd=request&user=test&api_key=0123456789&service=Amazon&mdn=12345678901

Example output:

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

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

Returned data is a JSON array with the following data:

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-tergeted requests), "markup", "carrier" and "till_expiration" (in seconds).

Example request

Request URL 
https://www.codebypass.app/api_command.php?cmd=request_status&user=test&api_key=0123456789&id=10000001

Example output:

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

or, in the case a request was successful:

JSON Response 
{
"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
  }
]
}

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 premium 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

Returned data is a JSON array with the following data:

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 timed out successfully.

Example request

Request URL 
https://www.codebypass.app/api_command.php?cmd=reject&user=test&api_key=0123456789&id=10000001

Example output:

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

or, in the case a request was successful:

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

4. Read SMSes

Get messages received to a one-time or long-term rented MDN.

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
ltr_id ID of a long-term rental, as obtained with "ltr_rent" command. If passed, "mdn" parameter is ignored.
If you're renting an MDN for "Unlimited" service, you may pass the "service" parameter to filter data by a specific service.		 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.

If you're renting an unlimited number with "ltr_rent" command, you can either omit this parameter and parse incoming messages on your end, or put the service name as it would be detected by us (i.e. Unknown or Google). Do not set this parameter to "Unlimited".		 N

Returned data is a JSON array with the following data:

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:

Request URL 
https://www.codebypass.app/api_command.php?cmd=read_sms&user=test&api_key=0123456789&service=Google

Example output:

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

or

JSON Response 
{
"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"
  }
]
}

5. Reply to an SMS

You can send outgoing SMSes to numbers where you earlier received messages from for a flat fee of 0.10. The following criteria should be met:

  1. You have received an incoming message from that external number to that MDN no earlier than 30 minutes ago.
  2. This MDN is still available. For best results it's adviced to send a reply within 2 minutes after getting an incoming message.
  3. Maximum SMS length is 160 bytes (not unicode characters).

You will be charged if the SMS was accepted for delivery. Delivery cannot be guaranteed. This function works for both one-time numbers and long-term rentals.

Parameter Value Required
cmd "send_sms" Y
user Your user name or email Y
api_key Your API key Y
mdn An MDN where you earlier received a message to. Y
to A destination phone number. Y
sms Message text Y

Returned data is a JSON array with the following data:

Parameter Value
status "ok" or "error"
message If "status" field equals to "error" this field will contain the explanation of the error.

Example request

Request URL 
https://www.codebypass.app/api_command.php?cmd=send_sms&user=test&api_key=0123456789&mdn=12345678901&to=555&sms=Hello

Example output:

JSON Response 
{
"status":"error",
"message":"No incoming messages within past 30 minutes"
}

If you're getting the error below, and this is a long-term rental, you can activate the number and bring it back online. With one-time numbers this is not possible.

JSON Response 
{
"status":"error",
"message":"MDN is offline"
}

Long-term MDN Rentals

Quick jump: One-time MDNs | Balance & Other Info | Proxy Rentals | HTTP Callback

1. Rent an MDN

Parameter Value Required
cmd "ltr_rent" Y
user Your user name or email Y
api_key Your API key Y
service One service name (as returned by "list_services" command or seen on View Services web page) Y
duration Rental duration, in days. Can equal to 3 or 30 days. If omitted a default value of 30 days will be used. Please note that not all MDNs may support 3-day rentals. N
mdn If this parameter is passed, we will try to provide this specific requested MDN.

This command can also be used to renew an MDN if it is (or was) rented by you. If a particular MDN is still available, a new rental of a specified duration will be added.

The script will return an error if this number is not available anymore or if it's rented by another user.		 N
areacode A 3-digit area code. Takes precedence over "state" patameter. If "mdn" parameter is passed, the "areacode" parameter is ignored. N
state A 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
reserve This parameter can only be used with "Unlimited" service. If passed and set to "true", it will create a reservation and the next available MDN will be assigned to this rental's ID. You can check the status of the reservation with "ltr_status" command. Please note that the full price of the rental will be debited from your balance plus a flat fee of $5. N
autorenew If passed and set to "true", your number will be auto renewed after expiration, if your balance allows that. This parameter can be toggled on and off at Long Term MDN Rentals page N

Returned data is a JSON array with the following data:

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 these variables: "id", "mdn", "service", "price", "expires" and "carrier".

Example request

Request URL 
https://www.codebypass.app/api_command.php?cmd=ltr_rent&user=test&pass=test&service=Amazon&duration=30&mdn=12345678901&autorenew=true

Example output:

JSON Response 
{
"status":"error",
"message":"Insufficient funds. Your balance is $1.00"
}

or, in the case a request was successful:

JSON Response 
{
"status": "ok",
"message":
  {
    "id": 1,
    "mdn": "12345678901",
    "service": "Amazon",
    "price": 15.5,
    "expires": "2100-12-31 23:59:59",
    "carrier": "Verizon"
  }
}

In the SMS message log you will see an entry with the sender "Billing" which will contain the price of your subscription.

2. Change auto renew status for rented MDN

Parameter Value Required
cmd "ltr_autorenew" Y
user Your user name or email Y
api_key Your API key Y
ltr_id ID of the long term rental as returned by "ltr_rent" command. If not passed, "service" and "mdn" parameters are required N
service A service name (as returned by "list_services" command or seen on View Services web page). Ignored if "ltr_id" parameter is passed. Y
mdn An MDN that is currently being rented and not expired. Ignored if "ltr_id" parameter is passed. Y
autorenew "true" or "false". If this parameter is omitted, the current renewal status will be returned in the "message" field N

Returned data is a JSON array with the following data:

Parameter Value
status "ok" or "error"
message If "status" field equals to "error" this field will contain the explanation of the error.

Example request

Request URL 
https://www.codebypass.app/api_command.php?cmd=ltr_autorenew&user=test&api_key=0123456789&service=Amazon&mdn=12345678901&autorenew=true

Example output:

JSON Response 
{
"status":"error",
"message":"Unable to change auto renew status"
}

or, in the case a request was successful:

JSON Response 
{
"status":"ok",
"message":"Auto renew status updated"
}

To check the current autorenew status

Request URL 
https://www.codebypass.app/api_command.php?cmd=ltr_autorenew&user=test&api_key=0123456789&service=Amazon&mdn=12345678901

Example output:

JSON Response 
{
"status":"ok",
"message":true
}

Note: Additional long-term rental endpoints (ltr_status, ltr_activate, ltr_release, ltr_report, ltr_reported_status, ltr_switch_service, ltr_forward) follow the same documentation pattern with their complete parameter tables and examples as provided in your content.

Balance & Other Info

Quick jump: One-time MDNs | Long-term MDN Rentals | Proxy Rentals | HTTP Callback

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 View Services web page), separated by comma.

If this parameter is omitted, all available services will be listed.		 N

Returned data is a JSON array with the following data:

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", "available", "ltr_available", "recommended_markup".

Example request

Request URL 
https://www.codebypass.app/api_command.php?cmd=list_services&user=test&api_key=0123456789&service=Google

Example output:

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

or, in the case a request was successful:

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

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

Returned data is a JSON array with the following data:

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

Request URL 
https://www.codebypass.app/api_command.php?cmd=balance&user=test&api_key=0123456789

Example output:

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

Proxy Rentals

Quick jump: One-time MDNs | Long-term MDN Rentals | Balance & Other Info | HTTP Callback

1. List available proxy ports

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

Returned data is a JSON array with the following data:

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 these variables:
"port": a unique port ID
"location"
"carrier"
"redial_interval": how often will the IP be changed, in minutes
"leases": how many times a certain port is leased by other users
"services": a string containing the list of services the porrt is currently leased for
"services": a string containing the list of services the porrt is currently leased for
"is_exclusive": whether a port can be rented exclusively. A boolen variable, can be true or false
"renting_possible": if a port can be rented (i.e. not full). A boolen variable, can be true or false

Example request

Request URL 
https://www.codebypass.app/api_command.php?cmd=proxy_list&user=test&api_key=0123456789

Example output:

JSON Response 
{
"status":"ok",
"message":
  {
    "port": "50001",
    "location": "NJ",
    "carrier": "Verizon",
    "redial_interval": "15",
    "leases": "0",
    "services": null,
    "is_exclusive": true
  },
  {
    "port": "50002",
    "location": "NJ",
    "carrier": "T-Mobile",
    "redial_interval": "15",
    "leases": "2",
    "services": "Ebay, Uber",
    "is_exclusive": false
  }
}

Please note that the above command will list ALL ports that are currently available, including those that are already being rented by you.

2. Rent a proxy port

Parameter Value Required
cmd "proxy_rent" Y
user Your user name or email Y
api_key Your API key Y
port Port ID, as obtained with "proxy_list" command. If omitted, a random port will be used N
service A name of the service that you intend to use this proxy with (will be shown to other users) Y
duration Lease duration, in minutes. The discount will be applied automatically once the duration exceeds a corresponding threshold. The minimum value is 60 minutes. Y
exclusive When passed and set to "true", the port will be rented exclusively to you.

You should ensure that the current number of leases returned by "proxy_list" command equals to zero for a desired port.

Once rented successfully, other users won't be able to access this port, and the IP won't be changed automatically. You will have to use the "proxy_redial" command to change the IP address.

Please note that the pricing for exclusive rental is different from shared one.		 N

Returned data is a JSON array with the following data:

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", the following variables will be returned:
"Id": Id of the rental (can be used in proxy_redial or proxy_swap commands)
"port": Id of the proxy port (as obtained with "proxy_list" command)
"proxy_carrier": Carrier & location for the proxy port you selected
"proxy_user": Your proxy user
"proxy_pass": Password for a proxy user
"proxy_ip": Server IP
"proxy_socks_port": Server port for SOCKS5 proxy
"proxy_http_port": Server port for HTTP proxy
"proxy_auth": Proxy authentication data in HTML format
"price": The price with all the discounts factored in

Example request

Request URL 
https://www.codebypass.app/api_command.php?cmd=proxy_rent&service=Uber&port=50001&duration=120&exclusive=true&user=test&api_key=0123456789

Example output:

JSON Response 
{
"status":"error",
"message":"Unable to rent the port exclusively"
}

or in a case of a success

JSON Response 
{
"status": "ok",
"message": {
    "id": "1",
    "port": "50001",
    "proxy_carrier": "Verizon / TX",
    "proxy_user": "test_50001",
    "proxy_pass": "rfSPSfeNJU059VA",
    "proxy_ip": "127.0.0.1",
    "proxy_socks_port": 50000,
    "proxy_http_port": 49999,
    "proxy_auth": "IP: 127.0.0.1
SOCKS5 Port: 50000 / HTTPS Port: 49999
User: test_50001
Pass: rfSPSfeNJU059VA",
    "price": "10.00"
}
}

Please note that it may take a minute or two for your login credentials to start working..

3. Swap a proxy port to a new one

Parameter Value Required
cmd "proxy_swap" Y
user Your user name or email Y
api_key Your API key Y
id Id of your existing proxy rental, as obtained by "proxy_rent" command. N
port New port ID, as obtained with "proxy_list" command. If omitted, a random port will be used N

Returned data is a JSON array with the following data:

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", the following variables will be returned:
"port": Id of the proxy port (as obtained with "proxy_list" command)
"proxy_carrier": Carrier & location for the proxy port you selected
"proxy_user": Your proxy user
"proxy_pass": Password for a proxy user
"proxy_ip": Server IP
"proxy_socks_port": Server port for SOCKS5 proxy
"proxy_http_port": Server port for HTTP proxy
"proxy_auth": Proxy authentication data in HTML format

Example request

Request URL 
https://www.codebypass.app/api_command.php?cmd=proxy_swap&user=test&api_key=0123456789&port=50002&proxy_user=test_50001
https://www.codebypass.app/api_command.php?cmd=proxy_swap&user=test&api_key=0123456789&id=1

Example output:

JSON Response 
{
"status": "ok",
"message": {
    "id": "1",
    "port": "50002",
    "proxy_carrier": "AT&T / CA",
    "proxy_user": "test_50002",
    "proxy_pass": "fXJixSimV9U5JQx",
    "proxy_ip": "127.0.0.1",
    "proxy_socks_port": 50000,
    "proxy_http_port": 49999,
    "proxy_auth": "IP: 127.0.0.1
SOCKS5 Port: 50000 / HTTPS Port: 49999
User: test_50002
Pass: fXJixSimV9U5JQx"
}
}

Please note that it may take a minute or two for your new login credentials to start working..

4. Redial a proxy port when rented exclusively

Parameter Value Required
cmd "proxy_redial" Y
user Your user name or email Y
api_key Your API key Y
id Id of your existing proxy rental. If not passed, "proxy_user" variable is required N
proxy_user Old proxy user name, contained in "proxy_user" variable obtained earlier with "proxy_rent" command N

Returned data is a JSON array with the following data:

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 port redial command has been accepted.

Example request

Request URL 
https://www.codebypass.app/api_command.php?cmd=proxy_redial&user=test&api_key=0123456789&proxy_user=test_5https://www.codebypass.app/api_command.php?cmd=proxy_redial&user=test&api_key=0123456789&proxy_user=test_50001
https://www.codebypass.app/api_command.php?cmd=proxy_redial&user=test&api_key=0123456789&id=1

Example output:

JSON Response 
{
"status":"error",
"message":"No exclusive port rental"
}

or, in the case a request was successful:

JSON Response 
{
"status": "ok",
"message": "Redial requested"
}

HTTP Callback

Quick jump: One-time MDNs | Long-term MDN Rentals | Balance & Other Info | Proxy Rentals

1. How to set up a callback URL

In your account profile, You can set up a HTTP callback 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. For long-term rentals two other fields will be passed instead: "ltr_id" with the id of your current rental, and "first_ltr_id" which will contain the id of your first rental for this MDN and service.
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, as it was detected. If you're renting an unlimited number with "ltr_rent" command, this field will contain the actual service that the message was received for.
reply contents of the received SMS
pin a PIN code, when it was successfully recognized
price price of the received message

3. Automatic renewals of long-term rentals

When your long-term rental has been set to auto renew, and was renewed successfully, the following HTTP POST request will be sent to your callback URL.

Field Value
event "ltr_renewal"
status "ok"
new_ltr_id New Id of the long term rental after renewal.
previous_ltr_id Previous Id of the long term rental that has expired.
mdn MDN
service Service name
price The price of the subscription
expires The expiration time of a new rental in human-readable format

In case of an unsuccessful renewal another type of message will be sent

Field Value
event "ltr_renewal"
status "error"
message A description of an error (e.g. "Low balance").
previous_ltr_id Previous Id of the long term rental that has expired.
mdn MDN
service Service name

4. Winning of a premium request

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

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

Ready to Get Started?

Join thousands of developers who trust CodeBypass for their SMS verification needs. Get your API key today and start integrating our reliable non-VoIP numbers into your applications.

Get Your API Key