v1.0.0 · REST API · Production Ready

PVALines SMS API

Get OTP codes on real phone numbers across 200+ countries. Simple REST API, JWT auth, and webhooks.

200+

Countries

Endpoints

250/min

Rate Limit

1 hr

Token TTL

🔑

1. Get Token

POST your credentials to /oauth/token to get a JWT

🔍

2. Find Service

Browse /api/services and pick one with stock > 0

📱

3. Buy Number

POST to /api/buyNumbers with your service ID

⚡

4. Receive OTP

Poll /getNumber/:id or set a webhook for push

Base URL

https://api.pvalines.com

Authentication

Every protected endpoint requires a Bearer JWT in the x-token header. Here's how it works:

🔐

Send this header with every request:
x-token: Bearer <your_token>

Tokens are valid for 1 hour (3600s). When you request a new token, the old one is immediately invalidated — so only one token is active per account at a time.

bash

curl -X POST https://api.pvalines.com/oauth/token \
  -H "Content-Type: application/json" \
  -d '{"clientId":"usr_xxx","clientSecret":"sk_live_xxx"}'
# → { "token": "eyJ...", "type": "Bearer", "expiresIn": 3600 }

# Use the token in all subsequent requests:
curl https://api.pvalines.com/api/services \
  -H "x-token: Bearer eyJ..."

Rate Limiting

You can make up to 250 requests per 60 seconds per account (sliding window). If you exceed this, you'll get a 429 Too Many Requests response. The response headers tell you exactly where you stand:

Response Header	What it means
X-RateLimit-Limit	Max requests per window (250)
X-RateLimit-Remaining	How many requests you have left right now
X-RateLimit-Reset	Unix timestamp when your limit resets
Retry-After	Seconds to wait before retrying (only sent on 429)

Error Codes

All errors return a consistent JSON shape — no surprises:

{ "success": false, "message": "Human-readable description of the error", "status": 400 }

200Everything worked fine

400Bad Request — check your input fields

401Unauthorized — missing or expired token

402Payment Required — top up your balance

404Not Found — order or resource doesn't exist

429Too Many Requests — slow down

500Internal Server Error — something went wrong on our end

OAuth

Get an Access Token

Exchange your credentials for a signed JWT. You'll need this token for every other API call. The token expires after 1 hour, and getting a new one invalidates the previous one.

POST /oauth/token No auth required

Request Body

Field	Type	Required	Description
clientId	string	required	Your client ID from the developer dashboard
clientSecret	string	required	Your secret key — never expose this in client-side code

Code Examples

Returns: { "token": "eyJ...", "type": "Bearer", "expiresIn": 3600 }

curl -X POST https://api.pvalines.com/oauth/token \
  -H "Content-Type: application/json" \
  -d '{
    "clientId": "usr_9f3a2c1b4d7e",
    "clientSecret": "sk_live_4xT9mKpQ2rNzWvYcL8jHbA"
  }'

import requests

r = requests.post(
    "https://api.pvalines.com/oauth/token",
    json={
        "clientId": "usr_9f3a2c1b4d7e",
        "clientSecret": "sk_live_4xT9mKpQ2rNzWvYcL8jHbA",
    },
)
token = r.json()["token"]  # save this for other calls

const res = await fetch("https://api.pvalines.com/oauth/token", {
  method: "POST",
  headers: { "Content-Type": "application/json" },
  body: JSON.stringify({
    clientId: "usr_9f3a2c1b4d7e",
    clientSecret: "sk_live_4xT9mKpQ2rNzWvYcL8jHbA",
  }),
});
const { token } = await res.json(); // use this in x-token header

body, _ := json.Marshal(map[string]string{
    "clientId":     "usr_9f3a2c1b4d7e",
    "clientSecret": "sk_live_4xT9mKpQ2rNzWvYcL8jHbA",
})
resp, _ := http.Post(
    "https://api.pvalines.com/oauth/token",
    "application/json", bytes.NewBuffer(body),
)
var out map[string]any
json.NewDecoder(resp.Body).Decode(&out)
fmt.Println(out["token"])

var body = """
    {"clientId":"usr_9f3a2c1b4d7e",
     "clientSecret":"sk_live_4xT9mKpQ2rNzWvYcL8jHbA"}""";
var req = HttpRequest.newBuilder()
    .uri(URI.create("https://api.pvalines.com/oauth/token"))
    .header("Content-Type","application/json")
    .POST(HttpRequest.BodyPublishers.ofString(body)).build();
var resp = HttpClient.newHttpClient()
    .send(req, HttpResponse.BodyHandlers.ofString());

using var client = new HttpClient();
var res = await client.PostAsJsonAsync(
    "https://api.pvalines.com/oauth/token",
    new { clientId="usr_9f3a2c1b4d7e",
          clientSecret="sk_live_4xT9mKpQ2rNzWvYcL8jHbA" });

200Token generated successfully 400Missing clientId or clientSecret 401Wrong credentials

Orders

Buy SMS Numbers

Purchase one or more Non VoIP numbers in a single request. Numbers are activated immediately. Call GET /api/services first to get a valid websiteId — make sure stock > 0 before buying.

POST /api/buyNumbers

Request Body — services[ ] array

Field	Type	Required	Description
websiteId	string	required	The service ID from GET /api/services
quantity	integer	required	How many numbers to buy (min: 1)
biddingPercentage	number	optional	Bid % above base price for auction-based services
webhookUrl	string	optional	We'll POST the SMS here instead of you polling
number	string	optional	Request a specific phone number
regionInfo	object	optional	Filter by region/country

Code Examples

curl -X POST https://api.pvalines.com/api/buyNumbers \
  -H "Content-Type: application/json" \
  -H "x-token: Bearer YOUR_TOKEN" \
  -d '{
    "services": [{
      "websiteId": "69a13a4ef133cd20b4a7c082",
      "quantity": 1,
      "webhookUrl": "https://yourapp.com/webhook/sms"
    }]
  }'

r = requests.post(
    "https://api.pvalines.com/api/buyNumbers",
    headers={"x-token": f"Bearer {TOKEN}"},
    json={"services": [{
        "websiteId": "69a13a4ef133cd20b4a7c082",
        "quantity": 1,
        "webhookUrl": "https://yourapp.com/webhook/sms",
    }]},
)
batch_id = r.json()["data"]  # use this to poll /getNumber/:id

const res = await fetch("https://api.pvalines.com/api/buyNumbers", {
  method: "POST",
  headers: {
    "Content-Type": "application/json",
    "x-token": `Bearer ${TOKEN}`,
  },
  body: JSON.stringify({
    services: [{
      websiteId: "69a13a4ef133cd20b4a7c082",
      quantity: 1,
      webhookUrl: "https://yourapp.com/webhook/sms",
    }],
  }),
});
const { data: batchId } = await res.json();

payload := map[string]any{"services": []map[string]any{{
    "websiteId":  "69a13a4ef133cd20b4a7c082",
    "quantity":   1,
    "webhookUrl": "https://yourapp.com/webhook/sms",
}}}
body, _ := json.Marshal(payload)
req, _ := http.NewRequest("POST",
    "https://api.pvalines.com/api/buyNumbers",
    bytes.NewBuffer(body))
req.Header.Set("Content-Type","application/json")
req.Header.Set("x-token","Bearer "+token)
http.DefaultClient.Do(req)

var body = """
    {"services":[{"websiteId":"69a13a4ef133cd20b4a7c082",
      "quantity":1,
      "webhookUrl":"https://yourapp.com/webhook/sms"}]}""";
var req = HttpRequest.newBuilder()
    .uri(URI.create("https://api.pvalines.com/api/buyNumbers"))
    .header("Content-Type","application/json")
    .header("x-token","Bearer "+token)
    .POST(HttpRequest.BodyPublishers.ofString(body)).build();

client.DefaultRequestHeaders.Add("x-token",$"Bearer {token}");
await client.PostAsJsonAsync(
    "https://api.pvalines.com/api/buyNumbers",
    new { services = new[] {
        new { websiteId="69a13a4ef133cd20b4a7c082",
              quantity=1,
              webhookUrl="https://yourapp.com/webhook/sms" }
    }});

200Returns a batch order ID 400Invalid websiteId or missing fields 401Unauthorized 402Insufficient balance

Orders

Get Order Details

Check the status of a specific order and retrieve the SMS/OTP once it arrives. Poll every 5–10 seconds until status === "COMPLETED", or skip polling entirely by setting a webhookUrl when buying.

GET /api/getNumber/:id

Order Statuses

PENDINGWaiting for SMS to arrive

COMPLETEDSMS received successfully

EXPIREDTime window closed, no SMS came

FLAGGEDReported as broken/non-working

Code Examples

curl https://api.pvalines.com/api/getNumber/ORDER_ID \
  -H "x-token: Bearer YOUR_TOKEN"

import requests, time

ORDER_ID = "69d4b90edb480636c33e23b9"
headers = {"x-token": f"Bearer {TOKEN}"}

while True:
    r = requests.get(
        f"https://api.pvalines.com/api/getNumber/{ORDER_ID}",
        headers=headers,
    ).json()
    status = r["data"]["status"]
    if status == "COMPLETED":
        print("OTP received!", r["data"]["sms"])
        break
    elif status in ("EXPIRED", "FLAGGED"):
        print("Order failed:", status)
        break
    time.sleep(5)

async function pollOrder(orderId, token) {
  while (true) {
    const { data } = await fetch(
      `https://api.pvalines.com/api/getNumber/${orderId}`,
      { headers: { "x-token": `Bearer ${token}` } }
    ).then(r => r.json());
    if (data.status === "COMPLETED") return data;
    if (["EXPIRED","FLAGGED"].includes(data.status)) throw new Error(data.status);
    await new Promise(r => setTimeout(r, 5000)); // wait 5s
  }
}

for {
    req, _ := http.NewRequest("GET",
        "https://api.pvalines.com/api/getNumber/"+orderID, nil)
    req.Header.Set("x-token","Bearer "+token)
    resp, _ := http.DefaultClient.Do(req)
    var out map[string]any
    json.NewDecoder(resp.Body).Decode(&out)
    resp.Body.Close()
    if out["data"].(map[string]any)["status"] == "COMPLETED" {
        break
    }
    time.Sleep(5 * time.Second)
}

var req = HttpRequest.newBuilder()
    .uri(URI.create(
        "https://api.pvalines.com/api/getNumber/"+orderId))
    .header("x-token","Bearer "+token)
    .GET().build();
var resp = HttpClient.newHttpClient()
    .send(req, HttpResponse.BodyHandlers.ofString());

client.DefaultRequestHeaders.Add("x-token",$"Bearer {token}");
var res = await client.GetAsync(
    $"https://api.pvalines.com/api/getNumber/{orderId}");

Orders

List All Purchased Numbers

Retrieve your full order history with cursor-based pagination. To get the next page, pass the pageInfo.endCursor value as the cursor param. Keep going until hasNextPage is false.

GET /api/getNumbers

Query Param	Type	Description
limit	integer	Results per page. Default: 20, Max: 100
cursor	string	Pagination cursor from previous response's pageInfo.endCursor
filter	JSON string	Filter by: country, duration, type, status, number
order	JSON string	Sort by createdAt: "1" = oldest first, "-1" = newest first

Fetch All Pages — Node.js

async function getAllNumbers(token) {
  const all = [];
  let cursor = null;
  do {
    const params = new URLSearchParams({ limit: 100 });
    if (cursor) params.set("cursor", cursor);
    const { data } = await fetch(
      `https://api.pvalines.com/api/getNumbers?${params}`,
      { headers: { "x-token": `Bearer ${token}` } }
    ).then(r => r.json());
    all.push(...data.edges);
    cursor = data.pageInfo.hasNextPage ? data.pageInfo.endCursor : null;
  } while (cursor);
  return all;
}

Orders

Reuse a Number

Request another OTP on the same number — useful if you need multiple codes from the same service. Only works while the order is still active. Check expireAt first to make sure the window hasn't closed.

POST /api/reuseNumber/:id

curl -X POST https://api.pvalines.com/api/reuseNumber/ORDER_ID \
  -H "x-token: Bearer YOUR_TOKEN"

r = requests.post(
    f"https://api.pvalines.com/api/reuseNumber/{order_id}",
    headers={"x-token": f"Bearer {TOKEN}"},
)

const res = await fetch(
  `https://api.pvalines.com/api/reuseNumber/${orderId}`,
  { method:"POST", headers:{"x-token":`Bearer ${token}`} }
);

req, _ := http.NewRequest("POST",
    "https://api.pvalines.com/api/reuseNumber/"+orderID, nil)
req.Header.Set("x-token","Bearer "+token)
http.DefaultClient.Do(req)

var req = HttpRequest.newBuilder()
    .uri(URI.create(
        "https://api.pvalines.com/api/reuseNumber/"+orderId))
    .header("x-token","Bearer "+token)
    .POST(HttpRequest.BodyPublishers.noBody()).build();

await client.PostAsync(
    $"https://api.pvalines.com/api/reuseNumber/{orderId}",null);

200Number reused, waiting for new SMS 400Order expired or not eligible 404Order not found

Orders

Flag a Problem Number

Report a number that isn't receiving SMS or was already used before purchase. Our team reviews flags for replacement or refund. Each number can only be flagged once.

POST /api/flagNumber/:id

curl -X POST https://api.pvalines.com/api/flagNumber/ORDER_ID \
  -H "x-token: Bearer YOUR_TOKEN"

r = requests.post(
    f"https://api.pvalines.com/api/flagNumber/{order_id}",
    headers={"x-token": f"Bearer {TOKEN}"},
)

const res = await fetch(
  `https://api.pvalines.com/api/flagNumber/${orderId}`,
  { method:"POST", headers:{"x-token":`Bearer ${token}`} }
);

req, _ := http.NewRequest("POST",
    "https://api.pvalines.com/api/flagNumber/"+orderID, nil)
req.Header.Set("x-token","Bearer "+token)
http.DefaultClient.Do(req)

var req = HttpRequest.newBuilder()
    .uri(URI.create(
        "https://api.pvalines.com/api/flagNumber/"+orderId))
    .header("x-token","Bearer "+token)
    .POST(HttpRequest.BodyPublishers.noBody()).build();

await client.PostAsync(
    $"https://api.pvalines.com/api/flagNumber/{orderId}",null);

200Number flagged for review 400Already flagged or window expired

Orders

Toggle Auto-Renewal (LTR)

Enable or disable automatic renewal for a long-term rental number. This is a toggle — calling it once enables renewal, calling it again disables it. Only works on orders with type: LTR.

PUT /api/renewLTRNumber/:id

curl -X PUT https://api.pvalines.com/api/renewLTRNumber/ORDER_ID \
  -H "x-token: Bearer YOUR_TOKEN"

r = requests.put(
    f"https://api.pvalines.com/api/renewLTRNumber/{order_id}",
    headers={"x-token": f"Bearer {TOKEN}"},
)
print(r.json()["message"])  # "Auto-renewal enabled" or "disabled"

const res = await fetch(
  `https://api.pvalines.com/api/renewLTRNumber/${orderId}`,
  { method:"PUT", headers:{"x-token":`Bearer ${token}`} }
);
const { message } = await res.json();

req, _ := http.NewRequest("PUT",
    "https://api.pvalines.com/api/renewLTRNumber/"+orderID, nil)
req.Header.Set("x-token","Bearer "+token)
http.DefaultClient.Do(req)

var req = HttpRequest.newBuilder()
    .uri(URI.create(
        "https://api.pvalines.com/api/renewLTRNumber/"+orderId))
    .header("x-token","Bearer "+token)
    .PUT(HttpRequest.BodyPublishers.noBody()).build();

await client.PutAsync(
    $"https://api.pvalines.com/api/renewLTRNumber/{orderId}",null);

200Renewal toggled 400Not an LTR order

Catalog

Browse Available Services

Search for available SMS verification services — see what's in stock, pricing, and which countries are available. The websiteId from here is what you pass to /buyNumbers. No auth needed.

GET /api/services No auth required

Query Param	Description	Example
filter	Filter by: country (iso2), duration, type, isFavorite	{"country":"US"}
order	Sort by name: "1" A→Z, "-1" Z→A	{"name":"1"}
limit	Results per page. Default: 20, Max: 100	50
cursor	Pagination cursor from previous pageInfo.endCursor	eyJ...

Code Examples

curl "https://api.pvalines.com/api/services?filter=%7B%22country%22%3A%22US%22%7D&limit=20"

import requests, json

def find_service(name, country="US"):
    cursor = None
    while True:
        params = {"limit":100, "filter": json.dumps({"country":country})}
        if cursor: params["cursor"] = cursor
        r = requests.get(
            "https://api.pvalines.com/api/services", params=params
        ).json()
        for s in r["data"]["edges"]:
            if s["name"].lower()==name.lower() and s["stock"]>0:
                return s["websiteId"]
        if not r["data"]["pageInfo"]["hasNextPage"]: return None
        cursor = r["data"]["pageInfo"]["endCursor"]

website_id = find_service("Telegram")

async function findService(name, country = "US") {
  let cursor = null;
  while (true) {
    const params = new URLSearchParams({
      limit: 100,
      filter: JSON.stringify({ country }),
      ...(cursor && { cursor }),
    });
    const { data } = await fetch(
      `https://api.pvalines.com/api/services?${params}`
    ).then(r => r.json());
    const match = data.edges.find(
      s => s.name.toLowerCase() === name.toLowerCase() && s.stock > 0
    );
    if (match) return match.websiteId;
    if (!data.pageInfo.hasNextPage) return null;
    cursor = data.pageInfo.endCursor;
  }
}

import "net/url"
filter := url.QueryEscape(`{"country":"US"}`)
resp, _ := http.Get(
    "https://api.pvalines.com/api/services?filter="+filter)

var filter = URLEncoder.encode("{\"country\":\"US\"}", "UTF-8");
var req = HttpRequest.newBuilder()
    .uri(URI.create(
        "https://api.pvalines.com/api/services?filter="+filter))
    .GET().build();

var filter = Uri.EscapeDataString("{\"country\":\"US\"}");
var res = await client.GetAsync(
    $"https://api.pvalines.com/api/services?filter={filter}");

Catalog

List Supported Countries

Returns up to 200 countries in one call — no pagination needed. Use the iso2 code from this response as the country filter in /api/services. No auth needed.

GET /api/countries No auth required

curl https://api.pvalines.com/api/countries

countries = requests.get(
    "https://api.pvalines.com/api/countries"
).json()["data"]["edges"]
us = next(c for c in countries if c["iso2"] == "US")
print(us["name"], us["cc"])

const { data } = await fetch(
  "https://api.pvalines.com/api/countries"
).then(r => r.json());
console.log(`${data.edges.length} countries available`);

resp, _ := http.Get("https://api.pvalines.com/api/countries")
defer resp.Body.Close()
var out map[string]any
json.NewDecoder(resp.Body).Decode(&out)

var req = HttpRequest.newBuilder()
    .uri(URI.create("https://api.pvalines.com/api/countries"))
    .GET().build();

var res = await client.GetAsync(
    "https://api.pvalines.com/api/countries");

⚡ PVALines

support@pvalines.com · API v1.0.0 · pvalines.com