API Documentation

You read the catalog, buy a number, then poll for the code. Three calls in the happy path, and no list-orders endpoint: store the id the create call returns.

Copy the ids exactly as you receive them. Country, service and carrier values are opaque. One can be a string (whatsapp) or a number (1012), they are not shared between catalogs, and they change or disappear as stock moves. Take each one from the catalog response and pass it straight back. Never guess one, and never reuse a value you cached earlier. Re-read the catalog before you order.

Quick start

Send your key in the X-API-Key header on every request.

BASE=https://api.socialcheap.net/v1
KEY=SCKEY_your_api_key
 
# Every id below is an example. Read each one from the catalog and copy it exactly.
PROVIDER=global            # GET /sim/providers
COUNTRY=afghanistan        # GET /sim/providers/$PROVIDER/countries
SERVICE=linkedin           # GET /sim/providers/$PROVIDER/countries/$COUNTRY/services
CARRIER=virtual4           # GET /sim/providers/$PROVIDER/countries/$COUNTRY/services/$SERVICE/pricing
 
# Price the service, then buy with the carrier you were just quoted
curl -s "$BASE/sim/providers/$PROVIDER/countries/$COUNTRY/services/$SERVICE/pricing" \
  -H "X-API-Key: $KEY"
 
curl -s -X POST "$BASE/sim/orders" \
  -H "X-API-Key: $KEY" \
  -H "Content-Type: application/json" \
  -d "{\"provider\":\"$PROVIDER\",\"country\":\"$COUNTRY\",\"service\":\"$SERVICE\",\"carrier\":\"$CARRIER\"}"
 
# Read the code, using the id the create call returned
curl -s "$BASE/sim/orders/SCG-NLQXAZLSEW" \
  -H "X-API-Key: $KEY"

const base = "https://api.socialcheap.net/v1";
const headers = {
  "X-API-Key": process.env.SOCIALCHEAP_API_KEY,
  "Content-Type": "application/json",
};
 
const order = await fetch(`${base}/sim/orders`, {
  method: "POST",
  headers,
  // Each id is an example. Read them from the catalog and copy them exactly.
  body: JSON.stringify({
    provider: "global", // GET /sim/providers
    country: "afghanistan", // GET .../countries
    service: "linkedin", // GET .../services
    carrier: "virtual4", // GET .../pricing
  }),
}).then((r) => r.json());
 
// Poll until the code arrives
while (true) {
  const { data } = await fetch(`${base}/sim/orders/${order.data.id}`, {
    headers,
  }).then((r) => r.json());
 
  if (data.code) {
    console.log(data.code);
    break;
  }
  await new Promise((r) => setTimeout(r, 3000));
}

import os, time, requests
 
base = "https://api.socialcheap.net/v1"
headers = {"X-API-Key": os.environ["SOCIALCHEAP_API_KEY"]}
 
# Each id is an example. Read them from the catalog and copy them exactly.
order = requests.post(f"{base}/sim/orders", headers=headers, json={
    "provider": "global",       # GET /sim/providers
    "country": "afghanistan",   # GET .../countries
    "service": "linkedin",      # GET .../services
    "carrier": "virtual4",      # GET .../pricing
}).json()
 
# Poll until the code arrives
while True:
    data = requests.get(f"{base}/sim/orders/{order['data']['id']}",
                        headers=headers).json()["data"]
    if data["code"]:
        print(data["code"])
        break
    time.sleep(3)

Store the id from the create response; it is how you read the order afterwards. Poll every 3 to 5 seconds while status is active, and stop once code is set.

Authentication

Keys are issued per account from the dashboard. One key is live at a time: issuing a new one revokes the previous key immediately.

X-API-Key: SCKEY_your_api_key
Accept: application/json

Authenticated account

GET /v1/me returns the account the key belongs to.

{
  "msg": "Authenticated",
  "data": {
    "id": "USR-8f14e45f",
    "username": "ada",
    "email": "ada@example.com",
    "balance": 15250.0
  }
}

No path parameter and no account id: the key identifies the account. As a GET, it spends read budget.

Responses

Success and failure share one envelope.

{
  "msg": "Countries",
  "data": [{ "code": "usa", "name": "USA", "iso": "us" }]
}

Every answer is msg plus exactly one payload key. The key is the signal: a failure never arrives as "data": null:

{
  "msg": "Invalid API key",
  "errors": []
}

Action endpoints return "data": [] on success. Branch on the HTTP status; msg is a human-readable label.

A 400 is not always a complaint about your request. The catalog can refuse the action (This catalog does not support ban), or the number can go out of stock between pricing and purchase. Re-read pricing and try again later.

Validation errors (422)

Field-keyed, so each message pins to the input it came from:

{
  "msg": "Unprocessable entity",
  "errors": {
    "carrier": ["Field required"]
  }
}

• errors maps a field to one or more messages, and the key is the field name.
• A problem that belongs to the whole body is keyed body; a nested field uses a dotted path (params.count).
• More than one field can fail at once. Ordering premium without a country and a carrier names both.

Prices and balances are naira in major units: 1500.0 is ₦1,500, directly comparable to the balance from /me.

Rate limits

Limits apply per key and per IP address, and the lower of the two applies.

Services that call from the same address share that IP budget. A heavy integration should arrive from its own egress IP.

These are returned with every limited response, including 429. On a 429, wait out Retry-After and back off exponentially if it repeats.

Catalog

The catalog is a tree: catalog, country, service, then carrier pricing. One tree per provider, and the ids are not shared between them: usa is global's, 1 is ultra's.

Values are opaque: a string or a number, and subject to change. Read each one, use it, then read it again before you order.

Every service list is country-scoped. There is no catalog-wide one. Walk a country at a time and pick from the services it has stock for.

GET /sim/providers
GET /sim/providers/{provider}/countries
GET /sim/providers/{provider}/countries/{country}/services
GET /sim/providers/{provider}/countries/{country}/services/{service_id}/pricing
GET /sim/providers/{provider}/areacodes

{
  "msg": "Providers",
  "data": [
    {
      "id": "global",
      "name": "Global",
      "actions": ["cancel", "ban", "finish"]
    },
    { "id": "premium", "name": "Premium", "actions": [] },
    { "id": "ultra", "name": "Ultra", "actions": ["cancel"] }
  ]
}

{
  "msg": "Countries",
  "data": [{ "code": "usa", "name": "USA", "iso": "us" }]
}

{
  "msg": "Services",
  "data": [{ "code": "whatsapp", "name": "WhatsApp" }]
}

{
  "msg": "Pricing",
  "data": [{ "carrier": "virtual4", "name": "virtual4", "price": 459.85 }]
}

{
  "msg": "Area codes",
  "data": [{ "code": "212", "region": "New York" }]
}

Orders

{
  "provider": "global",
  "country": "afghanistan",
  "service": "linkedin",
  "carrier": "virtual4"
}

{
  "msg": "Order created",
  "data": {
    "id": "SCG-NLQXAZLSEW",
    "number": "+93788503317",
    "service": "linkedin",
    "country": "afghanistan",
    "status": "active",
    "code": null,
    "message": null,
    "expires_at": "2026-10-15T09:38:53.484428Z",
    "cost": 459.85,
    "provider": "global"
  }
}

{
  "msg": "Order",
  "data": {
    "id": "SCG-NLQXAZLSEW",
    "number": "+93788503317",
    "service": "linkedin",
    "country": "afghanistan",
    "status": "active",
    "code": "428462",
    "message": "[LinkedIn] 428462 is your verification code, valid for 5 minutes.",
    "expires_at": "2026-10-15T09:38:53.484428Z",
    "cost": 459.85,
    "provider": "global"
  }
}

POST /sim/orders/{id}/cancel   cancel and, where eligible, refund
POST /sim/orders/{id}/ban      block the number from reuse