REST API v1.0

Developer API

Name: Copy SMS
Availability: InStock
Author: Copy SMS

Fetch virtual phone numbers and read incoming verification SMS codes programmatically using standard HTTP JSON requests.

Base API URL

https://copysms.com/api/v1 HTTPS

All responses are returned as standard JSON with HTTP status codes.

API Authentication

Authorization: Bearer <YOUR_API_TOKEN>

Generate and manage your secret API key inside your account profile tab.

Available Endpoints

GET /api/v1/countries Returns all available countries and active number counts

{
  "success": true,
  "countries": [
    {
      "id": 1,
      "name": "United States",
      "iso_code": "US",
      "phone_prefix": "+1",
      "active_numbers": 3
    }
  ]
}

GET /api/v1/numbers Returns available phone numbers (optional filter: ?country=US)

{
  "success": true,
  "numbers": [
    {
      "id": 1,
      "number": "+12025550143",
      "formatted_number": "+1 (202) 555-0143",
      "carrier": "T-Mobile US",
      "country": "United States",
      "status": "active"
    }
  ]
}

GET /api/v1/numbers/{id}/messages Fetch incoming SMS messages and parsed verification OTP codes

{
  "success": true,
  "messages": [
    {
      "id": 104,
      "sender": "WhatsApp",
      "masked_sender": "Wh••••pp",
      "raw_content": "Your WhatsApp code is: 829-410. Don't share it.",
      "extracted_otp": "829410",
      "received_at": "2026-10-05T02:00:00Z"
    }
  ]
}

GET /api/v1/user/profile Requires Token Fetch account details, real-time balance, and active line count

{
  "success": true,
  "user": {
    "id": 1,
    "name": "Alex Rivera",
    "email": "alex@company.io",
    "wallet_balance": 145.50,
    "active_rentals_count": 2
  }
}

GET /api/v1/user/rentals Requires Token List dedicated reserved SIM lines and live expiration timestamps

{
  "success": true,
  "data": [
    {
      "id": 12,
      "number": "+12025550199",
      "formatted_number": "+1 (202) 555-0199",
      "country": "United States",
      "status": "active",
      "duration": "monthly",
      "expires_at": "2026-11-05T00:00:00Z"
    }
  ]
}

Mobile App API

Used by the Copy SMS Android / iOS app

Sign in with email + password to receive a personal bearer token, then call the authenticated endpoints with Authorization: Bearer <token>. Each device gets its own token; logging out revokes only that device.

GET /api/v1/catalog/services Public Apps you can get a code for, with the cheapest price

{ "success": true, "order_minutes": 15, "services": [ { "slug": "whatsapp", "name": "WhatsApp", "qty": 5000, "from_usd": 0.6, "from_formatted": "$0.60" } ] }

GET /api/v1/catalog/countries/{service} Public Countries with stock for that app, cheapest first

{ "success": true, "countries": [ { "slug": "nigeria", "name": "Nigeria", "flag": "🇳🇬", "count": 50, "rate": 95, "price_usd": 0.7, "price_formatted": "$0.70" } ] }

POST /api/v1/user/activations Requires Token Buy a number (debits the wallet). 402 = top up first, 422 = no stock / price changed

// body: { "service": "whatsapp", "country": "nigeria", "price": 0.70 }
{ "success": true, "activation": { "id": 20, "status": "pending", "formatted_phone": "+2346783…", "seconds_left": 900 }, "wallet_balance": 4.3 }

GET /api/v1/user/activations/{id} Requires Token Poll the order; settles it (code → finished, expired → refunded)

{ "success": true, "activation": { "id": 20, "status": "finished", "sms_code": "332328", "sms_text": "Your WhatsApp code is 332-328", "refunded": false } }

POST /api/v1/user/activations/{id}/cancel Requires Token Cancel before a code arrives → refund. Also /report when the app rejects the number

{ "success": true, "activation": { "id": 20, "status": "cancelled", "refunded": true }, "wallet_balance": 5.0 }

GET /api/v1/user/activations Requires Token History (add ?open=1 for orders still waiting)

{ "success": true, "data": { "data": [ { "id": 20, "service_name": "WhatsApp", "country_name": "Nigeria", "sms_code": "332328", "status": "finished" } ] } }

GET /api/v1/config Public Branding, currencies, enabled payment gateways and limits — call before login

{
  "success": true,
  "app": { "name": "Copy SMS", "tagline": "Receive SMS online — copy the code for any app" },
  "currency": { "base": "USD", "display_code": "XAF", "xaf_rate": 600 },
  "wallet": { "min_recharge_usd": 1 },
  "gateways": [ { "key": "fapshi", "name": "Mobile Money (MTN MoMo / Orange Money)", "direct_pay": true } ]
}

POST /api/v1/auth/register Public Create an account and receive a bearer token

// body: { "name", "email", "password", "password_confirmation", "terms": true, "device_name" }
{ "success": true, "token": "csms_live_…", "user": { "id": 42, "wallet_balance": 0 } }

POST /api/v1/auth/login Public Exchange email + password for a bearer token

// body: { "email", "password", "device_name" }
{ "success": true, "token": "csms_live_…", "user": { "id": 42, "wallet_balance_formatted": "FCFA 3 000" } }

POST /api/v1/user/auth/logout Requires Token Revoke the current device token

{ "success": true }

GET /api/v1/user/me Requires Token Profile, balance, unread notifications

{ "success": true, "user": { "id": 42, "name": "…", "wallet_balance": 5.0, "unread_notifications": 1 } }

POST /api/v1/user/wallet/deposit Requires Token Start a Mobile Money top-up (Fapshi). method = direct (USSD prompt) or checkout (hosted page)

// body: { "amount": 5, "gateway": "fapshi", "method": "direct", "phone": "6XXXXXXXX", "medium": "mobile money" }
{ "success": true, "type": "direct", "reference": "DEP-AB12CD34EF56", "amount_usd": 5, "amount_xaf": 3000 }
// or, for method=checkout:
{ "success": true, "type": "redirect", "reference": "DEP-…", "url": "https://checkout.fapshi.com/payment/…" }

GET /api/v1/user/wallet/deposit/{reference} Requires Token Poll the top-up; settles the wallet as soon as Fapshi reports SUCCESSFUL

{ "success": true, "status": "completed", "wallet_balance": 5.0, "wallet_balance_formatted": "$5.00" }

GET /api/v1/user/wallet/transactions Requires Token Paginated wallet history

{ "success": true, "data": { "data": [ { "reference": "DEP-…", "type": "deposit", "amount": 5, "gateway": "fapshi", "status": "completed" } ] } }

GET /api/v1/user/numbers/catalog Requires Token Private numbers available to rent with daily / weekly / monthly prices

{ "success": true, "data": { "data": [ { "id": 7, "formatted_number": "+1 (415) 555-2671", "prices": { "daily": 1.5, "weekly": 6, "monthly": 15 } } ] } }

POST /api/v1/user/devices Requires Token Register a push-notification token (FCM / APNs)

// body: { "platform": "android", "push_token": "…", "device_name": "Pixel 8" }
{ "success": true }

Admin API

Requires Admin Token

Programmatic control-plane access for server owners: platform stats, user management, number pool, rentals, transactions, notifications and read-only settings. Admin tokens are issued from Admin → API Tokens and use the same Authorization: Bearer <TOKEN> header. Regular user/reseller tokens are rejected on these endpoints with 403.

Method	Endpoint	Description
GET	/api/v1/admin/stats	Users, rentals, revenue and today's message counts
GET	/api/v1/admin/users	Paginated users — filters: ?status=active\|suspended, ?search=
GET	/api/v1/admin/users/{id}	Single user detail
PATCH	/api/v1/admin/users/{id}	Update name / email / status (role never changeable via API)
GET	/api/v1/admin/numbers	Paginated number pool — filters: ?status=, ?country=ISO2
POST	/api/v1/admin/numbers	Register a number (same validation as admin panel)
PATCH	/api/v1/admin/numbers/{id}	Update a pooled number
DELETE	/api/v1/admin/numbers/{id}	Delete a number — refused (409) while an active rental holds it
GET	/api/v1/admin/rentals	Paginated rentals — filter: ?status=active\|expired\|cancelled
POST	/api/v1/admin/rentals/{id}/cancel	Cancel a rental — optional {"refund": true} credits the wallet
GET	/api/v1/admin/transactions	Paginated wallet ledger — filters: ?status=, ?type=
POST	/api/v1/admin/notifications	In-app notification — target "all", or "user" + user_id/email
GET	/api/v1/admin/settings	Read-only operational settings (secrets never exposed)

Example — suspend a user

curl -X PATCH "https://copysms.com/api/v1/admin/users/42" \
  -H "Authorization: Bearer YOUR_ADMIN_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"status": "suspended"}'

{
  "success": true,
  "message": "User updated successfully.",
  "user": { "id": 42, "status": "suspended", "..." : "..." }
}

All admin endpoints are rate-limited to 60 requests/minute. Validation failures return 422 with messages; error responses follow the {"success": false, "error": ..., "message": ...} envelope.