Introduction Authentication Endpoints Error Codes Servers Countries

InstaOTP API Documentation

Complete reference for integrating with InstaOTP's virtual number service. Manage numbers, receive SMS, and check balances programmatically.

GET https://instaotp.in/api/v1/handler_api.php

Introduction

The InstaOTP API allows developers to programmatically access virtual phone numbers for OTP verification services. This RESTful API returns responses in plain text format for easy integration.

All API requests are made as HTTP GET requests to the base URL with required parameters. The API uses API key authentication passed as a query parameter.

Response Format

Successful API responses follow a specific format with a status prefix:

ACCESS_NUMBER:12345:+1234567890
ACCESS_BALANCE:54.00
STATUS_OK:54321

Error responses typically begin with "ERROR_" or "BAD_" prefixes.

Authentication

All API requests require authentication using your API key. The API key should be included as a query parameter in every request.

API Key Parameter

Parameter Type Required Description
api_key String Yes Your unique API key for authentication

Example Request

https://instaotp.in/api/v1/handler_api.php?api_key=YOUR_API_KEY&action=getBalance

API Endpoints

GET /?action=getBalance

Check Wallet Balance

Retrieve the current balance of your InstaOTP account.

Parameters

Parameter Type Required Description
api_key String Yes Your API key

Response

Returns your current balance in the format: ACCESS_BALANCE:XX.XX

Example Request
Example Response
https://instaotp.in/api/v1/handler_api.php?api_key=abc123def456&action=getBalance
ACCESS_BALANCE:54.00
GET /?action=getService

Get Available Services

Retrieve a list of available services with their prices and availability.

Parameters

Parameter Type Required Description
api_key String Yes Your API key
server String No Filter by server
country String No Filter by country

Response

Returns a JSON object with available services and their details.

Example Request
Example Response
https://instaotp.in/api/v1/handler_api.php?api_key=abc123def456&action=getService&country=22
{
  "1": [
    {
      "id": "vk",
      "service": "Вконтакте/VKConnect",
      "price": "3.12",
      "qty": "1052",
      "country": "22",
      "provider": "1"
    }
  ]
}
GET /?action=getNumber

Get a Virtual Number

Request a virtual number for a specific service.

Parameters

Parameter Type Required Description
api_key String Yes Your API key
service String Yes The service ID (e.g., "wa, tg, am")
country String Yes The country code (e.g., "22" for India)
server String Yes The server identifier

Response

Returns the order ID and phone number in the format: ACCESS_NUMBER:ORDER_ID:PHONE_NUMBER

Example Request
Example Response
https://instaotp.in/api/v1/handler_api.php?api_key=abc123def456&action=getNumber&service=vk&country=22&server=1
ACCESS_NUMBER:12345:+1234567890
GET /?action=setStatus

Change Order Status (cancel / finish)

Use this endpoint to either finish an order (mark as completed) or cancel/ban an order. The API forwards the request to the provider and maps provider messages to standardized status responses.

Parameters

Parameter Type Required Description
api_key String Yes Your API key
id String Yes Order ID returned when the number was allocated
status String Yes Either cancel or finish

Behavior

If status=finish the API attempts to finish the order; if status=cancel it attempts to cancel/ban and may refund depending on provider response. Invalid or missing params will return parameter errors.

Mapped Responses

The provider message is mapped to the following standardized responses:

  • ACCESS_READY — Numbers readiness confirmed.
  • ACCESS_RETRY_GET — Waiting for a new SMS.
  • ACCESS_ACTIVATION — The service has been successfully activated.
  • ACCESS_CANCEL — Order cancelled / banned (or refunded) successfully.
  • EARLY_CANCEL_DENIED — It is not allowed to ban a number within the first 2 minutes.
  • ERROR_SQL — Database server error.
  • NO_ACTIVATION — Order ID does not exist / activation not found.
  • ALREADY_CANCEL — Order already banned.
  • BAD_SERVICE — Incorrect service name.
  • BAD_STATUS — Incorrect status value provided.
  • BAD_KEY — Invalid API key.
  • BAD_ACTION — Incorrect action specified.
Example Request
Example Response
https://instaotp.in/api/v1/handler_api.php?api_key=abc123def456&action=setStatus&id=12345&status=finish
ACCESS_ACTIVATION
EARLY_CANCEL_DENIED
ACCESS_CANCEL
ERROR_SQL
NO_ACTIVATION
ALREADY_CANCEL
BAD_SERVICE
BAD_STATUS
BAD_KEY
BAD_ACTION

Error Codes

Authentication Errors

Code Description
NO_API_KEY API key is missing in the request
BAD_KEY Invalid API key provided

Parameter Errors

Code Description
BAD_PARAMS Required parameters are missing
BAD_ACTION Incorrect action specified
BAD_SERVICE Incorrect service name provided
BAD_STATUS Invalid status value provided
INVALID_STATUS Status must be either 'cancel' or 'finish'

Service Errors

Code Description
NO_SERVICES No services available or failed to fetch services
NO_ACTIVATION Activation not found or invalid order ID
ALREADY_CANCEL Order has already been cancelled
EARLY_CANCEL_DENIED Cannot cancel number within first 2 minutes
ERROR_SQL Database server error occurred

Status Responses

Code Description
STATUS_WAIT_CODE Waiting for SMS code
ACCESS_RETRY_GET Waiting for new SMS
ACCESS_READY Numbers readiness confirmed
ACCESS_ACTIVATION Service activated successfully
ACCESS_CANCEL Order cancelled/banned successfully

Available Servers

Server 1

id: 1

Active
Server 2

id: 2

Active
Server 3

id: 3

Active
Server 4

id: 4

Active
Server 5

id: 5

Active
Server 6

id: 6

Active
Server 7

id: 7

Active
Server 8

id: 8

Active
Server 9

id: 9

Active
Server 10

id: 10

Inactive

Available Countries