Open in your browser for best results

Inside Facebook, number lists sometimes don’t load. Tap continue to open Proxnum in Chrome or Safari — one tap, no copying links.

API Reference

Developer API Reference

This comprehensive API documentation provides developers and integrators with everything needed to implement SMS verification services. All responses are in JSON format.

Note: This reference is written for API users (developers and integrators). Each endpoint includes explanations, authentication requirements, sample requests, and example responses.
Authentication Bearer token setup Virtual Numbers One-time SMS verification Rental numbers Keep a number for days and receive every SMS

Authentication

All endpoints require a Bearer token in the Authorization header.

How to Get Your API Key
  1. Sign in to your Proxnum account and navigate to your Profile page
  2. Scroll to the "API Keys management" section
  3. Click "Create API key" to generate a new key
  4. Copy the displayed API token

Include your API token in every request:

Authorization: Bearer YOUR_API_TOKEN_HERE
Accept: application/json
Content-Type: application/json

Quick links:

Common Response Format

Errors use a normalized structure so your integration can switch on code reliably. All error responses follow this pattern:

{
  "success": false,
  "code": "no_numbers",
  "message": "No numbers available for the selected service and country"
}

Endpoints

GET /api/v1/resell/price?service=&country=

Get base and sell price for a given service and country. Use this to estimate cost before placing a chargeable order.

Parameters (query): service (string), country (int)

Example request:

curl -s -X GET "https://proxnum.com/api/v1/resell/price?service=ig&country=6" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Accept: application/json"

Success response:

{
  "country": "6",
  "service": "ig",
  "base_price": 0.0334,
  "sell_price": 0.1114892
}

GET /api/v1/prices

Get comprehensive pricing for all available services and countries. This endpoint returns base prices and your reseller sell prices for all combinations.

Parameters (query, optional):

  • service service (string) - Filter by specific service code (e.g., ig, wa, tg)
  • country country (int) - Filter by specific country code

Example request (all prices):

curl -s -X GET "https://proxnum.com/api/v1/prices" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Accept: application/json"

Example request (filtered by country):

curl -s -X GET "https://proxnum.com/api/v1/prices?country=6" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Accept: application/json"

Success response (filtered by country):

{
  "success": true,
  "prices": {
    "6": {
      "ig": {
        "base_price": 0.0334,
        "sell_price": 0.1114892,
        "available": 245
      },
      "wa": {
        "base_price": 0.0389,
        "sell_price": 0.1298737,
        "available": 189
      },
      "tg": {
        "base_price": 0.0223,
        "sell_price": 0.0744551,
        "available": 521
      },
      "go": {
        "base_price": 0.0278,
        "sell_price": 0.0928206,
        "available": 312
      }
    }
  }
}

Note: The response structure is a nested object where the first level keys are country codes, and the second level keys are service codes. Each service contains base_price (your cost), sell_price (your reseller price), and available (number of available numbers, or null if unknown).

POST /api/v1/resell/virtual/buy

Buy a temporary (virtual) number. The call will attempt to allocate a number and charge your account.

Body (JSON): {"service":"ig","country":6}

Example request:

curl -s -X POST "https://proxnum.com/api/v1/resell/virtual/buy" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"service":"ig","country":6}'

Success response (normalized):

{
  "success": true,
  "activation": {
    "id": 737,
    "phone": "62895406203932",
    "activation_id": "4390520873",
    "msg": "Waiting Sms",
    "date_created": "2025-11-08 21:50:34",
    "amount_paid": 0.111489,
    "status": 1
  }
}

Common error codes:

{
  "success": false,
  "code": "no_numbers",
  "message": "No numbers available for this service in the selected country"
}

{
  "success": false,
  "code": "insufficient_balance",
  "message": "Not enough balance to place the order"
}

GET /api/v1/resell/virtual/{id}/status

Check the status of an activation. {id} accepts activation id string returned by purchase.

Example request:

curl -s -X GET "https://proxnum.com/api/v1/resell/virtual/4390520873/status" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Accept: application/json"

Success (when a code is available):

{
  "success": true,
  "status": "completed",
  "code": "1234",
  "activation": { "id": 737, "phone": "628...", "activation_id": "4390520873" }
}

POST /api/v1/resell/virtual/resend

Request a resend/reactivation for an activation. Use the activation id string in the body.

Body: {"activation_id":"4390520873"}

curl -s -X POST "https://proxnum.com/api/v1/resell/virtual/resend" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"activation_id":"4390520873"}'

Response (accepted):

{
  "success": true,
  "message": "Resend requested; new activation created",
  "activation": { "id": 738, "activation_id": "4390520874", "phone": "628..." }
}

POST /api/v1/resell/virtual/cancel

Request cancellation and refund for an activation. Our server evaluates whether the activation is refundable and returns a normalized result.

Body: {"activation_id":"4390520873"}

curl -s -X POST "https://proxnum.com/api/v1/resell/virtual/cancel" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"activation_id":"4390520873"}'

Accepted:

{
  "success": true,
  "code": "cancel_accepted",
  "message": "Cancellation accepted, refund processed"
}

Rejected:

{
  "success": false,
  "code": "cancel_rejected",
  "message": "Cancellation rejected — activation already completed or not refundable"
}

GET /api/v1/resell/activations

List activations for the authenticated user (paginated). Supports page and per_page query parameters.

curl -s -X GET "https://proxnum.com/api/v1/resell/activations?page=1&per_page=25" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Accept: application/json"

Rental numbers

Rental numbers stay assigned to your account for the period you buy and receive every SMS sent to them. Use these endpoints to show your customers the available periods and prices, rent numbers, read incoming SMS, cancel within the allowed window and extend active rentals.

All rental endpoints are also available without the /resell prefix (for example /api/v1/rental/catalog). The public catalog at /api/v1/rental/catalog does not require a token.

Rental responses contain "ok" (true or false), an "error" code when something fails and a human-readable "message" in the language of your account. The HTTP status code reflects the result (200 success, 202 accepted and pending, 4xx request problem, 503 temporarily unavailable).

Rental statuses

  • active — The number is yours and receives SMS until expires_at.
  • cancelling — A cancellation was requested and is waiting for confirmation. No refund has been made yet.
  • cancelled — The cancellation was confirmed and amount_paid was returned to your balance.
  • expired — The rental period ended.

GET /api/v1/resell/rental/catalog?country=&hours=

Returns the rental periods currently offered, the countries and the services with your price and stock for one country and period. The list of periods comes live from our number supply, so always read it from durations[] instead of hard-coding values.

Query parameters: country (optional, numeric country id, see the country codes page) and hours (optional, one of durations[].hours). Invalid or missing values fall back to the defaults returned in the response.

Example request:

curl -s "https://proxnum.com/api/v1/resell/rental/catalog?country=187&hours=168" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Accept: application/json"
{
  "ok": true,
  "country": "187",
  "hours": 168,
  "durations": [
    { "hours": 24, "label": "1 day" },
    { "hours": 72, "label": "3 days" },
    { "hours": 168, "label": "1 week" },
    { "hours": 720, "label": "30 days" }
  ],
  "countries": [ { "id": "187", "name": "USA" }, { "id": "16", "name": "United Kingdom" } ],
  "services": [
    { "code": "wa", "name": "WhatsApp", "icon": "...", "price": 4.2, "stock": 35 }
  ],
  "cancel_window_seconds": 120
}

POST /api/v1/resell/rental/buy

Rents a number and charges your balance. hours must be one of the durations[].hours values from the catalog. Optionally send max_price: if the current price is higher, nothing is charged and you receive error price_changed with the new price.

Body (JSON): {"service":"wa","country":187,"hours":168,"max_price":4.20}

curl -s -X POST "https://proxnum.com/api/v1/resell/rental/buy" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json" \
  -d '{"service":"wa","country":187,"hours":168,"max_price":4.20}'
{
  "ok": true,
  "error": null,
  "message": "Your rental number is ready.",
  "price": 4.2,
  "balance": 25.8,
  "rental": {
    "id": 512,
    "phone": "14155550123",
    "service": "wa",
    "service_name": "WhatsApp",
    "country": "187",
    "country_name": "USA",
    "status": "active",
    "amount_paid": 4.2,
    "hours": 168,
    "purchased_at": "2026-10-03T12:00:00+03:00",
    "expires_at": "2026-10-10T12:00:00+03:00",
    "cancel_until": "2026-10-03T12:02:00+03:00",
    "can_cancel": true,
    "cancel_pending": false,
    "can_extend": true
  }
}

Common errors: invalid_period (422), no_numbers (409), price_changed (409), insufficient_funds (402), option_unavailable (422), unavailable or provider_unreachable (503, you were not charged).

GET /api/v1/resell/rental/{id}/status

Returns the rental with its received SMS (newest first). Each message includes the text and, when one is detected, the code. Poll every 5 to 10 seconds while you wait for a message. id can be our rental id or the activation id returned on purchase.

curl -s "https://proxnum.com/api/v1/resell/rental/512/status" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Accept: application/json"
{
  "ok": true,
  "rental": {
    "id": 512,
    "phone": "14155550123",
    "status": "active",
    "expires_at": "2026-10-10T12:00:00+03:00",
    "can_cancel": false,
    "can_extend": true,
    "messages": [
      { "id": 9001, "sender": "WhatsApp", "text": "Your WhatsApp code: 123-456", "code": "123456", "date": "2026-10-03T12:05:10+03:00" }
    ]
  }
}

POST /api/v1/resell/rental/cancel

A rental can be cancelled only within 2 minutes of purchase, if it has not received any SMS and has not been extended. The cancellation is confirmed with the number supplier, which can take a few minutes.

Body: {"id":512}

curl -s -X POST "https://proxnum.com/api/v1/resell/rental/cancel" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json" \
  -d '{"id":512}'
HTTP/1.1 202 Accepted
{
  "ok": true,
  "pending": true,
  "refunded": 0,
  "message": "Cancellation requested. Your refund will be added once the cancellation is confirmed, usually within a few minutes.",
  "rental": { "id": 512, "status": "cancelling", "cancel_pending": true }
}

HTTP/1.1 200 OK
{
  "ok": true,
  "pending": false,
  "refunded": 4.2,
  "balance": 30,
  "rental": { "id": 512, "status": "cancelled" }
}

HTTP/1.1 409 Conflict
{
  "ok": false,
  "error": "sms_received",
  "message": "This number has already received an SMS, so it cannot be cancelled."
}
HTTP 202 with "pending": true means the request was accepted but the refund has not been made yet. Poll the status endpoint: status becomes cancelled when amount_paid has been refunded, or returns to active if the cancellation was refused (for example because an SMS arrived in the meantime). A refund is never made before confirmation, and never twice.

Common errors: window_closed, sms_received, extended, cancel_pending (a request is already in progress), not_active (all 409).

GET /api/v1/resell/rental/{id}/extend-options

Lists the renewal periods and prices available for one active rental. Prices are read live for that specific number.

curl -s "https://proxnum.com/api/v1/resell/rental/512/extend-options" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Accept: application/json"

{
  "ok": true,
  "options": [
    { "hours": 24, "label": "1 day", "price": 1.1 },
    { "hours": 168, "label": "1 week", "price": 5.0 }
  ]
}

POST /api/v1/resell/rental/{id}/extend

Extends an active rental by one of the periods returned by extension options and charges your balance. Send max_price to make sure you are never charged more than the price you showed your customer. Extended rentals can no longer be cancelled.

Body (JSON): {"hours":168,"max_price":5.00}

curl -s -X POST "https://proxnum.com/api/v1/resell/rental/512/extend" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json" \
  -d '{"hours":168,"max_price":5.00}'

{
  "ok": true,
  "message": "Rental extended by 1 week.",
  "price": 5,
  "balance": 25,
  "rental": { "id": 512, "status": "active", "expires_at": "2026-10-17T12:00:00+03:00", "can_cancel": false }
}

Common errors: invalid_period (422), price_changed (409), insufficient_funds (402), not_active (409), unavailable (503).

GET /api/v1/resell/rentals

Paginated list of your rentals, newest first. Query parameters: page and per_page (1 to 100).

curl -s "https://proxnum.com/api/v1/resell/rentals?page=1&per_page=25" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Accept: application/json"

{ "ok": true, "total": 3, "page": 1, "per_page": 25, "data": [ { "id": 512, "phone": "14155550123", "status": "active", "...": "..." } ] }

Implementation Notes

  • All charging operations are idempotent per-order where possible; check the returned order or transaction fields for canonical identifiers.
  • Use the price endpoint to dry-run costs before placing chargeable requests.
  • Normalized error codes you may see include: no_numbers, insufficient_balance, service_unavailable, cancel_rejected.
Best Practices:
  • Always handle both success and error responses in your integration
  • Implement proper error handling for network timeouts
  • Cache country and service lists to reduce API calls
  • Use webhooks where available for real-time status updates

Last updated: January 26, 2026 — You may request improvements to our API documentation, or report issues within the api by sending email to [email protected].

chat us