Developers

API Reference

Integrate seamless virtual numbers and SMS verification into your platform using our powerful RESTful API.

Authentication

All API requests require a Bearer token. You can generate and manage your API keys directly from your Developer Dashboard.

Include your key in the Authorization header of every request.

Base URL
https://numvia.org/api 
# Authenticate your requests via cURL
curl -H "Authorization: Bearer sk_live_abc123..." \
  https://numvia.org/api/v1/numbers

List Available Numbers

Retrieve a paginated list of all virtual numbers currently available in the global pool.

GET /v1/numbers

Query Parameters

country string, optional

Filter the returned numbers by country name or ISO2 code (e.g. US, ID, UK).

# Request available US numbers
curl -X GET "https://numvia.org/api/v1/numbers?country=US" \
  -H "Authorization: Bearer YOUR_API_KEY"

# Example Response
{
  "ok": true,
  "data": [
    {
      "id": 1042,
      "number": "12025551234",
      "country_name": "US"
    }
  ]
}

Claim a Number

Assign a specific virtual number to your account to begin receiving OTP codes. Returns a unique claim_id.

POST /v1/numbers/{id}/claim

Path Parameters

id integer, required

The unique ID of the virtual number you wish to claim (retrieved from the List Numbers endpoint).

# Claim number ID 1042
curl -X POST "https://numvia.org/api/v1/numbers/1042/claim" \
  -H "Authorization: Bearer YOUR_API_KEY"

# Example Response
{
  "ok": true,
  "message": "Number claimed successfully",
  "data": {
    "id": 88, // This is your claim_id
    "number": "12025551234"
  }
}

Poll for Messages

Poll this endpoint every 5-10 seconds to retrieve incoming SMS messages and OTP codes for your claimed number.

GET /v1/numbers/{claim_id}/messages

Path Parameters

claim_id integer, required

The claim_id returned when you successfully claimed the number (e.g. 88).

# Fetch messages for claim ID 88
curl -X GET "https://numvia.org/api/v1/numbers/88/messages" \
  -H "Authorization: Bearer YOUR_API_KEY"

# Example Response
{
  "ok": true,
  "data": [
    {
      "id": 991,
      "verification_code": "478-736",
      "message": "Your WhatsApp code: 478-736",
      "received_at": "2026-08-24 10:00:00"
    }
  ]
}

Release Number

Release a claimed number back to the public pool once your verification is complete.

POST /v1/numbers/{claim_id}/release 
# Release claim ID 88
curl -X POST "https://numvia.org/api/v1/numbers/88/release" \
  -H "Authorization: Bearer YOUR_API_KEY"

# Example Response
{
  "ok": true,
  "message": "Number released successfully"
}