Primex — API Documentation

Overview

🌐 Base URL

All endpoints are relative to:
https://primex.ng/api/

📦 Request Format

GET endpoints use query parameters.
POST endpoints accept application/json body or multipart/form-data.

📤 Response Format

All responses return JSON. Every response includes a status field: "success" or "error".

💰 Pricing

API users get a dedicated charge tier set by admin — typically lower than standard user pricing.

Authentication

Every request must include your API key. Pass it as a request header or query parameter.

🔑 API Key — All Endpoints

Your API key is shown in your Primex profile under API Access. It is only available after your account has been upgraded to API access by an admin.

Option 1 — HTTP Header (recommended)

X-Api-Key: your_64_character_api_key_here

Option 2 — Query Parameter

GET https://primex.ng/api/balance?api_key=your_key_here

Never expose your API key in client-side code or public repositories. If compromised, reset it from your Primex profile page.

Error Handling

HTTP Code	status field	Meaning
`200`	`success`	Request completed successfully
`200`	`error`	Request failed — see `message` field for reason
`401`	`error`	Missing, invalid, or non-API key — check your key
`404`	`error`	Unknown endpoint
`405`	`error`	Wrong HTTP method
`500`	`error`	Server error — try again

All error responses include a human-readable message field. Example: {"status":"error","message":"Invalid API key."}

Account

GET /api/balance Get your wallet balance

API Key Required

Example Request

GET https://primex.ng/api/balance
X-Api-Key: your_key_here

Success Response

{
  "status": "success",
  "balance": 15420.50,
  "currency": "NGN"
}

Virtual Numbers

GET /api/vn/providers List all enabled VN providers

API Key Required

Always call this first. Use the returned id field in all subsequent calls — it stays consistent but the name only shows you the tier (e.g. USA (S1), All Countries (S2)) without exposing the underlying vendor.

Provider Tiers at a Glance

p1USA (S1)

p2USA (S2)

p3All Countries (S2)

p4All Countries (S3)

p5All Countries (S1)

p6USA (S3)

p7USA (S4)

p8All Countries (S3) — V2

Success Response

{
  "status": "success",
  "providers": [
    { "id": "p1", "name": "USA (S1)",               "type": "usa_only" },
    { "id": "p2", "name": "USA (S2)",               "type": "usa_only" },
    { "id": "p3", "name": "All Countries (S2)",     "type": "multi_country" },
    { "id": "p4", "name": "All Countries (S3)",     "type": "multi_country" },
    { "id": "p5", "name": "All Countries (S1)",     "type": "multi_country" },
    { "id": "p6", "name": "USA (S3)",               "type": "usa_only" },
    { "id": "p7", "name": "USA (S4)",               "type": "usa_only" },
    { "id": "p8", "name": "All Countries (S3) — V2", "type": "multi_country" }
  ]
}

Provider Types

type	Meaning	country param needed?
`usa_only`	USA numbers only (S1, S2, S3, S4) — no country selection	No
`multi_country`	Multiple countries available (S1, S2, S3) — select country from /vn/countries	Yes — use /vn/countries first

GET /api/vn/services List all services for a provider

API Key Required

Query Parameters

Param	Type	Required	Description
`provider`	string	required	Provider ID from /vn/providers (e.g. `p1` for USA S1)

Example Request

GET /api/vn/services?provider=p1
X-Api-Key: your_key_here

// For multi-country: ?provider=p4 or ?provider=p3

Success Response

{
  "status": "success",
  "provider": "p1", // provider ID as passed
  "services": [
    { "code": "wa",  "name": "WhatsApp"  },
    { "code": "tg",  "name": "Telegram"  },
    { "code": "ig",  "name": "Instagram" }
  ]
}

Use the code field as service when calling /vn/price or /vn/buy.

GET /api/vn/countries List countries for a multi-country provider

API Key Required

Only valid for multi_country providers: All Countries (S1), All Countries (S2), All Countries (S3). Calling this on a USA-only provider returns an error.

Query Parameters

Param	Type	Required	Description
`provider`	string	required	Multi-country provider ID

Example Request

GET /api/vn/countries?provider=p4
X-Api-Key: your_key_here

// Use the provider ID returned by /vn/providers

Success Response

{
  "status": "success",
  "provider": "p4",
  "countries": [
    { "code": "US", "name": "United States" },
    { "code": "RU", "name": "Russia" },
    { "code": "NG", "name": "Nigeria" }
  ]
}

Use the code field as country when calling /vn/price or /vn/buy.

GET /api/vn/price Check price and availability before buying

API Key Required

Always call this before buying. The price returned is your API tier price. If available: false or count: 0, do not attempt to buy.

Query Parameters

Param	Type	Required	Description
`provider`	string	required	Provider ID
`service`	string	required	Service code from /vn/services
`country`	string	optional	Country code (required for multi-country providers)

Example — USA provider

GET /api/vn/price?provider=p1&service=wa
X-Api-Key: your_key_here

Example — Multi-country provider

GET /api/vn/price?provider=p4&service=wa&country=US
X-Api-Key: your_key_here

Success Response — Available

{
  "status":    "success",
  "available": true,
  "count":     142,        // numbers in stock
  "price_ngn": 450.00,    // your API tier price in NGN
  "provider":  "p1",
  "service":   "wa",
  "country":   null
}

Response — Unavailable

{
  "status":    "unavailable",
  "message":  "Service not available or out of stock.",
  "price_ngn": 0
}

POST /api/vn/buy Buy a virtual number — wallet is debited immediately

API Key Required

GET /api/vn/providersFind available providers

GET /api/vn/services?provider=xGet service codes

GET /api/vn/price?provider=x&service=xConfirm price and stock

POST /api/vn/buyPlace order — receive phone number + activation_id

GET /api/vn/status?provider=x&activation_id=xPoll every 5–10s until OTP received

Request Body

Field	Type	Required	Description
`provider`	string	required	Provider ID
`service_code`	string	required	Service code from /vn/services
`service_name`	string	optional	Human-readable service name (defaults to service_code)
`country_code`	string	optional*	Country code — required for multi-country providers
`country_name`	string	optional	Country name for display purposes

Example — USA provider

POST /api/vn/buy
Content-Type: application/json
X-Api-Key: your_key_here

{
  "provider":     "p1",    // USA S1 — use id from /vn/providers
  "service_code": "wa",
  "service_name": "WhatsApp"
}

Example — Multi-country provider

POST /api/vn/buy
Content-Type: application/json
X-Api-Key: your_key_here

{
  "provider":     "p4",    // All Countries S3 — use id from /vn/providers
  "service_code": "wa",
  "service_name": "WhatsApp",
  "country_code": "US",
  "country_name": "United States"
}

Success Response

{
  "status":        "success",
  "phone_number":  "+15551234567",
  "activation_id": "84729301",   // save this — needed for status polling and cancel
  "price_ngn":     450.00,
  "provider":      "p1",
  "service":       "wa",
  "message":       "Number ordered successfully. Poll /api/vn/status to receive your OTP."
}

Wallet is debited immediately on success. If the number request fails at the provider level, your wallet is automatically refunded. Save the activation_id — you need it for status checks and cancellation.

GET /api/vn/status Check OTP status for an active number

API Key Required

Query Parameters

Param	Type	Required	Description
`provider`	string	required	Same provider used when buying
`activation_id`	string	required	activation_id from the buy response

Example Request

GET /api/vn/status?provider=p1&activation_id=84729301
X-Api-Key: your_key_here

Success Response

{
  "status":        "success",
  "order_status":  "received",   // waiting | received | cancelled | expired
  "otp_code":      "382910",    // null until OTP arrives
  "activation_id": "84729301",
  "provider":      "p1"
}

Order Status Values

order_status	Meaning	Action
`waiting`	Number active, no OTP yet	Poll again in 5–10 seconds
`received`	OTP received — check `otp_code`	Use the OTP and cancel the number
`cancelled`	Order was cancelled	No further action
`expired`	Number expired without OTP	No further action

Poll every 5–10 seconds. Most numbers expire after 20 minutes. Once status is received, call cancel to free the number and avoid further charges on some providers.

POST /api/vn/cancel Cancel an active number order and get refunded

API Key Required

Request Body

Field	Type	Required	Description
`provider`	string	required	Provider ID
`activation_id`	string	required	activation_id from the buy response

Example Request

POST /api/vn/cancel
Content-Type: application/json
X-Api-Key: your_key_here

{
  "provider":      "p1",
  "activation_id": "84729301"
}

Success Response

{
  "status":  "success",
  "message": "Order cancelled and wallet refunded."
}

Cancellation is only possible while the order is in waiting or live status. Wallet is refunded automatically.

GET /api/vn/orders List your virtual number order history

API Key Required

Query Parameters

Param	Type	Required	Default
`limit`	integer	optional	20 (max 100)
`offset`	integer	optional	0

Success Response

{
  "status": "success",
  "total":  48,
  "limit":  20,
  "offset": 0,
  "orders": [
    {
      "vnActivationId": "84729301",
      "vnProvider":      "p1",
      "vnPhoneNumber":   "+15551234567",
      "vnServiceCode":   "wa",
      "vnServiceName":   "WhatsApp",
      "vnOtpCode":       "382910",
      "vnStatus":        "completed",
      "vnPriceNgn":      450.00,
      "vnCreatedAt":     "2026-03-18 14:23:00"
    }
  ]
}

SMM Boosting

GET /api/boost/services List all available SMM services with pricing

API Key Required

Query Parameters

Param	Type	Required	Description
`category`	string	optional	Filter by category (e.g. `Instagram`, `TikTok`). Omit for all.

Example Request

GET /api/boost/services?category=Instagram
X-Api-Key: your_key_here

Success Response

{
  "status":   "success",
  "category": "Instagram",
  "count":    14,
  "services": [
    {
      "service_id":    101,
      "name":          "Instagram Followers — HQ",
      "category":      "Instagram",
      "price_per_unit": 0.85,   // NGN per 1 unit — your API tier price
      "min_quantity":   100,
      "max_quantity":   50000,
      "refill":         true,
      "cancel":         false
    }
  ]
}

Total cost = price_per_unit × quantity. Ensure your wallet balance covers this before placing an order.

POST /api/boost/order Place a boost order

API Key Required

Request Body

Field	Type	Required	Description
`service_id`	integer	required	service_id from /boost/services
`link`	string	required	Full URL of the post/profile to boost
`quantity`	integer	required	Must be between service min_quantity and max_quantity

Example Request

POST /api/boost/order
Content-Type: application/json
X-Api-Key: your_key_here

{
  "service_id": 101,
  "link":       "https://www.instagram.com/yourprofile",
  "quantity":   1000
}

Success Response

{
  "status":    "success",
  "order_id":  48291,      // API-side order ID
  "cost_ngn":  850.00,
  "reference": "RSM-A3F9B2",
  "message":   "Order placed successfully."
}

Wallet is debited immediately. Orders are submitted to the SMM provider's API in real time. Save the order_id to check order progress.

GET /api/boost/order Get status of a single boost order

API Key Required

Query Parameters

Param	Type	Required	Description
`id`	integer	required	order_id from the place order response

Example Request

GET /api/boost/order?id=48291
X-Api-Key: your_key_here

Success Response

{
  "status": "success",
  "order": {
    "id":           48291,
    "service_name": "Instagram Followers — HQ",
    "category":     "Instagram",
    "link":         "https://www.instagram.com/yourprofile",
    "quantity":     1000,
    "cost_ngn":     850.00,
    "api_order_id": 9920143,
    "order_status": "Pending",   // Pending | Processing | Completed | Partial | Cancelled
    "reference":    "RSM-A3F9B2",
    "created_at":   "2026-03-18 14:50:00"
  }
}

GET /api/boost/orders List your boost order history

API Key Required

Query Parameters

Param	Type	Required	Default
`limit`	integer	optional	20 (max 100)
`offset`	integer	optional	0

Success Response

{
  "status": "success",
  "count":  5,
  "orders": [ /* same structure as single order */ ]
}

Social Logs

GET /api/logs List available social media account logs

API Key Required

Credentials are not returned until after purchase. Only description, price, and platform are shown at this stage.

Query Parameters

Param	Type	Required	Description
`platform`	string	optional	Filter by platform (e.g. `instagram`, `tiktok`). Omit for all.
`limit`	integer	optional	Max results (default 20, max 100)

Example Request

GET /api/logs?platform=instagram&limit=10
X-Api-Key: your_key_here

Success Response

{
  "status":   "success",
  "platform": "instagram",
  "count":    3,
  "logs": [
    {
      "id":          12,
      "platform":    "instagram",
      "description": "2.4K followers • Nigerian account • Active 2026",
      "price_ngn":   3500.00,
      "status":      "available"
    }
  ]
}

POST /api/logs/buy Purchase a social log — credentials revealed on success

API Key Required

Request Body

Field	Type	Required	Description
`log_id`	integer	required	id from /api/logs

Example Request

POST /api/logs/buy
Content-Type: application/json
X-Api-Key: your_key_here

{ "log_id": 12 }

Success Response

{
  "status":  "success",
  "message": "Purchase successful.",
  "log": {
    "id":           12,
    "platform":    "instagram",
    "description": "2.4K followers • Nigerian account • Active 2026",
    "credentials": "username:password",  // revealed only after purchase
    "extra":       "Recovery email: [email protected]",
    "price_ngn":   3500.00,
    "purchased_at": "2026-03-18 15:02:00"
  }
}

Wallet is debited immediately. Purchases are final — no refunds for social logs once credentials have been delivered.

GET /api/logs/mine List all logs you have purchased

API Key Required

Example Request

GET /api/logs/mine
X-Api-Key: your_key_here

Success Response

{
  "status": "success",
  "count":  2,
  "logs":   [ /* same structure as buy response log object */ ]
}

Full credentials are always returned here — store them securely after purchase.

Primex API Documentation v1.0 · primex.ng Built by HalalTech