REST API

API Reference

One key. One endpoint. Both servers. Every call returns {"s1": ..., "s2": ...} — filter what you need.

Balancehttps://socialsexpert.com/api/balance

v1https://socialsexpert.com/api/v1

Get API Key Examples

Authentication

Pass your API key as X-API-Key header. Generate keys from your dashboard.

Security: Never expose your API key in client-side code.

Rate Limit: 60 req/min per key. Returns 429 when exceeded.

bash

curl -H "X-API-Key: YOUR_KEY" \
  https://socialsexpert.com/api/balance

Balance

GET/balance

getBalance

Returns wallet balance linked to your API key. One shared balance across both servers.

curl

curl -H "X-API-Key: YOUR_KEY" "https://socialsexpert.com/api/balance"

response

{
  "success": true,
  "balance": 142.50,
  "currency": "USD"
}

Products

GET/products

getProducts

Returns all available products from both servers in a single call. Filter by response.s1 (sessions/Instagram) or response.s2 (Telegram numbers).

Param	Type	Req	Description
`type`	string	No	Filter: telegram or instagram

curl

curl -H "X-API-Key: YOUR_KEY" "https://socialsexpert.com/api/v1/products"

response

{
  "s1": {
    "success": true,
    "data": [
      { "type": "telegram", "total_stock": 56,
        "pools": [{ "country": "IN", "stock": 32, "price": 12.00 }] },
      { "type": "instagram", "total_stock": 24,
        "pools": [{ "year": 2018, "stock": 12, "price": 25.00 }] }
    ]
  },
  "s2": {
    "success": true,
    "type": "telegram-numbers",
    "total_stock": 9681,
    "pools": [{ "country": "UZ", "stock": 6450, "price": 1.20 }]
  }
}

Instagram Accounts

GET/instagram/stock

getInstagramStock

Instagram stock grouped by creation year.

Param	Type	Req	Description
`account_age`	int	No	Filter by year, e.g. 2018
`sort_by`	string	No	stock, price, or year

curl

curl -H "X-API-Key: YOUR_KEY" "https://socialsexpert.com/api/v1/instagram/stock"

response

{
  "success": true,
  "total_stock": 24,
  "pools": [
    { "year": 2018, "stock": 12, "price": 25.00 },
    { "year": 2020, "stock": 4, "price": 22.00 }
  ]
}

POST/instagram/buy

buyInstagram

Purchase one Instagram account. Returns full login credentials instantly.

Param	Type	Req	Description
`account_age`	int	No	Filter by year

Body

json

{ "account_age": 2018 }

curl

curl -X POST -H "X-API-Key: YOUR_KEY" -H "Content-Type: application/json" -d '{ "account_age": 2018 }' https://socialsexpert.com/api/v1/instagram/buy

response

{
  "success": true,
  "order_id": "uuid-here",
  "account": {
    "username": "cool_user",
    "password": "p@ssw0rd",
    "email": "user@mail.com",
    "account_age": 2018
  },
  "price": 25.00,
  "balance_after": 117.50
}

Telegram Sessions

GET/telegram/stock

getTelegramStock

Telegram stock pool. Use the server parameter to switch between S1 (Sessions) and S2 (Number codes).

Param	Type	Req	Description
`country`	string	No	ISO code, e.g. US, IN
`server`	string	No	s1 (default, sessions) or s2 (numbers)
`sort_by`	string	No	stock, price, or country

curl

curl -H "X-API-Key: YOUR_KEY" "https://socialsexpert.com/api/v1/telegram/stock"

response

{
  "success": true,
  "service": "telegram-aged-accounts",
  "total_stock": 56,
  "pools": [
    { "country": "IN", "stock": 32, "price": 12.00 },
    { "country": "US", "stock": 24, "price": 25.00 }
  ]
}

POST/telegram/buy

buyTelegram

Purchase a Telegram account. Pass server='s2' to buy a direct number code. Provide a webhook_url to instantly receive the code without polling requestOtp.

Param	Type	Req	Description
`country`	string	No	ISO code, e.g. US (Required for S2)
`server`	string	No	s1 (default) or s2
`webhook_url`	string	No	Instant callback URL (Hyper-fast delivery)

Body

json

{ "country": "US", "server": "s2", "webhook_url": "https://yourapi.com/tg-webhook" }

curl

curl -X POST -H "X-API-Key: YOUR_KEY" -H "Content-Type: application/json" -d '{ "country": "US", "server": "s2", "webhook_url": "https:' https://socialsexpert.com/api/v1/telegram/buy

response

{
  "success": true,
  "order_id": "abc-123-def",
  "delivery_type": "webhook",
  "account": {
    "phone_number": "+12025551234",
    "country": "US",
    "year_created": 2018
  },
  "price": 25.00,
  "balance_after": 117.50
}

POST/telegram/request-otp

requestOtp

Read the login OTP for a purchased Telegram account. The system automatically detects whether the order_id belongs to S1 or S2 and routes seamlessly. ⏱️ Note: OTP fetching is time-restricted to 10 minutes (S1) or 5 minutes (S2) after purchase.

Param	Type	Req	Description
`order_id`	string	Yes	From buyTelegram response

Body

json

{ "order_id": "abc-123-def" }

curl

curl -X POST -H "X-API-Key: YOUR_KEY" -H "Content-Type: application/json" -d '{ "order_id": "abc-123-def" }' https://socialsexpert.com/api/v1/telegram/request-otp

response

{
  "success": true,
  "order_id": "abc-123-def",
  "delivery_type": "number_otp",
  "phone_number": "+12025551234",
  "country": "US",
  "year_created": 2018,
  "two_fa": "mypassword123",
  "otp_code": "54821",
  "otp_found": true
}

Webhook Integration

For hyper-fast Telegram OTP delivery, pass a webhook_url in your /telegram/buy request. As soon as the OTP arrives across our distributed servers, we'll actively `POST` the credentials to your URL instantly.

Using webhooks eliminates the need to aggressively poll the requestOtp endpoint and ensures you get the code the absolute millisecond it's received. Both S1 native accounts and S2 ephemeral numbers fully support webhooks.

Webhook Payload (POST)

json

{
  "success": true,
  "order_id": "8e31a-4c22-b2d9",
  "phone_number": "+12025551234",
  "otp_code": "54821",
  "two_fa": "mypassword123",
  "otp_found": true
}

Error Codes

Code	HTTP	Description
`INVALID_API_KEY`	401	Missing or invalid API key
`INACTIVE_API_KEY`	403	Key revoked
`INSUFFICIENT_BALANCE`	402	Not enough balance
`INVALID_PARAM`	400	Invalid parameter
`OUT_OF_STOCK`	404	No stock available
`ORDER_NOT_FOUND`	404	Order not found
`OTP_NOT_AVAILABLE`	400	OTP fetch window expired (5-10m) or session unavailable
`RATE_LIMITED`	429	Too many requests
`PROVIDER_ERROR`	502	Upstream provider down
`CODE_NOT_READY`	409	Code not yet available

error

{
  "success": false,
  "error": {
    "code": "INSUFFICIENT_BALANCE",
    "message": "Required: $15.00, Available: $3.50"
  }
}

Code Examples

Python

python

import requests

KEY = "YOUR_API_KEY"
H = {"X-API-Key": KEY}
V1 = "https://socialsexpert.com/api/v1"

# Buy a Telegram account (Server 1 Native)
order1 = requests.post(f"{V1}/telegram/buy", headers=H,
    json={"country": "US", "server": "s1"}).json()

creds1 = requests.post(f"{V1}/telegram/request-otp", headers=H,
    json={"order_id": order1["order_id"]}).json()

# Buy a Telegram account (Server 2 Number)
order2 = requests.post(f"{V1}/telegram/buy", headers=H,
    json={"country": "UZ", "server": "s2"}).json()

# Use the exact same endpoint for OTP retrieval!
creds2 = requests.post(f"{V1}/telegram/request-otp", headers=H,
    json={"order_id": order2["order_id"]}).json()

JavaScript

javascript

const KEY = "YOUR_API_KEY";
const headers = { "X-API-Key": KEY, "Content-Type": "application/json" };
const V1 = "https://socialsexpert.com/api/v1";

// Buy Telegram account (Server 1 Native)
const order1 = await fetch(`${V1}/telegram/buy`, {
  method: "POST", headers,
  body: JSON.stringify({ country: "US", server: "s1" })
}).then(r => r.json());

const creds1 = await fetch(`${V1}/telegram/request-otp`, {
  method: "POST", headers,
  body: JSON.stringify({ order_id: order1.order_id })
}).then(r => r.json());

// Buy Telegram account (Server 2 Number)
const order2 = await fetch(`${V1}/telegram/buy`, {
  method: "POST", headers,
  body: JSON.stringify({ country: "UZ", server: "s2" })
}).then(r => r.json());

// Exact same endpoint for OTP retrieval from S2!
const creds2 = await fetch(`${V1}/telegram/request-otp`, {
  method: "POST", headers,
  body: JSON.stringify({ order_id: order2.order_id })
}).then(r => r.json());