QuickSim API Documentation

Integrate virtual phone numbers and SMS verification directly into your applications.

Getting Started

The QuickSim API provides programmatic access to virtual phone numbers and SMS verification services. All API requests are made over HTTPS to the base URL below.

Base URL
https://api.quicksim.app/api

All requests must include an authentication token in the Authorization header. Responses are returned in JSON format. Rate limiting is applied at 100 requests per minute per user.

Request Headers
Authorization: Bearer <your_access_token>
Content-Type: application/json

Authentication

QuickSim uses JWT-based authentication. Obtain an access token via Google OAuth or email/password login, then include it in all subsequent requests.

POST /api/auth/google

Authenticate using a Google OAuth credential token.

Request Body
{
  "credential": "eyJhbGciOiJSUzI1NiIsInR5cCI6..."
}
Response — 200 OK
{
  "access": "eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9...",
  "refresh": "eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9...",
  "user": {
    "id": 1842,
    "email": "user@example.com",
    "name": "Jane Developer"
  }
}
POST /api/users/login

Authenticate with email and password credentials.

Request Body
{
  "email": "user@example.com",
  "password": "your_password"
}
Response — 200 OK
{
  "access": "eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9...",
  "refresh": "eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9..."
}
Token Refresh

Access tokens expire after 24 hours. Use the refresh token to obtain a new access token by sending a POST request to /api/users/token/refresh with the refresh token in the body.

Countries

Retrieve the list of supported countries for virtual number activations.

GET /api/fivesim/countries

Returns a list of all available countries with their codes and names.

Response — 200 OK
{
  "countries": [
    {
      "name": "United States",
      "code": "usa",
      "prefix": "+1",
      "flag": "🇺🇸"
    },
    {
      "name": "United Kingdom",
      "code": "england",
      "prefix": "+44",
      "flag": "🇬🇧"
    },
    {
      "name": "Germany",
      "code": "germany",
      "prefix": "+49",
      "flag": "🇩🇪"
    }
  ]
}

Products / Services

Get a list of available services and their pricing for a specific country.

GET /api/fivesim/products?country=usa

Returns available services with pricing and number availability for the specified country.

Parameter Type Description
country string Country code (e.g., "usa", "england", "germany")
Response — 200 OK
{
  "products": [
    {
      "name": "whatsapp",
      "display_name": "WhatsApp",
      "price": 3500,
      "currency": "NGN",
      "available": 342
    },
    {
      "name": "google",
      "display_name": "Google",
      "price": 2500,
      "currency": "NGN",
      "available": 1205
    },
    {
      "name": "telegram",
      "display_name": "Telegram",
      "price": 2000,
      "currency": "NGN",
      "available": 891
    }
  ]
}

Activations

Purchase a virtual phone number for a specific country and service.

POST /api/fivesim/activation

Creates a new activation, deducts the cost from your wallet, and returns the assigned phone number.

Request Body
{
  "country": "usa",
  "product": "whatsapp"
}
Response — 201 Created
{
  "id": 48291037,
  "phone": "+13125550847",
  "product": "whatsapp",
  "country": "usa",
  "price": 3500,
  "status": "PENDING",
  "expires_at": "2026-02-27T15:30:00Z",
  "sms": null,
  "created_at": "2026-02-27T15:10:00Z"
}

Check SMS

Poll for incoming SMS messages on an active activation. Call this endpoint repeatedly until a message arrives or the activation expires.

GET /api/fivesim/check?activation_id=48291037

Checks for received SMS messages on the specified activation.

Parameter Type Description
activation_id integer The activation ID returned from the activation endpoint
Response — 200 OK (SMS received)
{
  "id": 48291037,
  "phone": "+13125550847",
  "status": "RECEIVED",
  "sms": [
    {
      "id": 9102847,
      "text": "Your WhatsApp verification code is: 847-291",
      "code": "847291",
      "received_at": "2026-02-27T15:10:08Z"
    }
  ]
}
Response — 200 OK (waiting)
{
  "id": 48291037,
  "phone": "+13125550847",
  "status": "PENDING",
  "sms": []
}

Finish / Cancel

Complete or cancel an active activation. Finishing confirms receipt. Cancelling releases the number and refunds your wallet.

POST /api/fivesim/finish

Mark an activation as complete after receiving the SMS code.

Request Body
{
  "activation_id": 48291037
}
Response — 200 OK
{
  "id": 48291037,
  "status": "FINISHED",
  "message": "Activation completed successfully"
}
POST /api/fivesim/cancel

Cancel an activation and receive a full refund to your wallet balance.

Request Body
{
  "activation_id": 48291037
}
Response — 200 OK
{
  "id": 48291037,
  "status": "CANCELED",
  "refunded": 3500,
  "message": "Activation canceled. ₦7,200 refunded to wallet."
}

Wallet

Manage your wallet balance and virtual accounts for funding.

GET /api/wallet/virtual-accounts

Retrieve your wallet balance and list of virtual accounts for funding.

Response — 200 OK
{
  "balance": 36750,
  "currency": "NGN",
  "virtual_accounts": [
    {
      "id": "va_8k2m9x",
      "bank_name": "Wema Bank",
      "account_number": "7821034561",
      "account_name": "QuickSim/Jane Developer",
      "created_at": "2026-01-15T10:30:00Z"
    }
  ]
}
POST /api/wallet/create-virtual-account

Create a new virtual bank account for depositing funds into your wallet.

Request Body
{
  "bank_code": "035"
}
Response — 201 Created
{
  "id": "va_9n3p2q",
  "bank_name": "Wema Bank",
  "account_number": "7821034892",
  "account_name": "QuickSim/Jane Developer",
  "message": "Virtual account created. Deposits will be credited automatically."
}

Error Handling

All errors follow a consistent JSON format. Use the HTTP status code and the error code field to handle errors programmatically.

Error Response Format
{
  "error": "insufficient_balance",
  "message": "Your wallet balance is too low for this activation.",
  "status": 402
}
Status Error Code Description
400 invalid_request Missing or malformed request parameters
401 unauthorized Invalid or expired access token
402 insufficient_balance Wallet balance too low for the requested activation
404 not_found Requested resource does not exist
409 activation_expired The activation has expired and can no longer be used
422 no_numbers_available No numbers currently available for the selected country and service
429 rate_limited Too many requests. Wait and retry after the cooldown period
500 internal_error Unexpected server error. Contact support if persistent