AtlasSIM API documentation

Introduction

The AtlasSIM API is a REST API that uses the JSON format for all requests and responses. It lets you automate the purchase of virtual numbers, track received SMS, and manage your balance from your own systems.

All requests must be sent over HTTPS to the following base URL:

https://api.atlas-sim.org/v1

Every response contains a JSON object with a status field and the requested data. Errors are returned with an appropriate HTTP code and an explicit message.

Authentication

The API uses Bearer token authentication. Your API key must be passed in the Authorization HTTP header of every request.

Example header to include in all your requests:

Authorization: Bearer sk_live_51H8x...........

Never share your API key publicly (Git repo, front-end code, etc.). Any request without a valid header will return a 401 error.

API key management

From your account area, under the "API" section, you can create, view, and revoke your API keys at any time.

Endpoints

Here is the complete list of endpoints available to interact with the AtlasSIM platform.

curl -X GET "https://api.atlas-sim.org/v1/balance" \
  -H "Authorization: Bearer sk_live_51H8x..."

{
  "status": "success",
  "data": {
    "balance": 42.85,
    "currency": "USD"
  }
}

curl -X GET "https://api.atlas-sim.org/v1/countries?search=fr" \
  -H "Authorization: Bearer sk_live_51H8x..."

{
  "status": "success",
  "data": [
    { "code": "fr", "name": "France", "in_stock": 1245 },
    { "code": "ci", "name": "Côte d'Ivoire", "in_stock": 830 }
  ]
}

curl -X GET "https://api.atlas-sim.org/v1/services?country=fr" \
  -H "Authorization: Bearer sk_live_51H8x..."

{
  "status": "success",
  "data": [
    { "id": "whatsapp", "name": "WhatsApp", "price": 0.18, "available": true },
    { "id": "telegram", "name": "Telegram", "price": 0.15, "available": true }
  ]
}

curl -X POST "https://api.atlas-sim.org/v1/orders" \
  -H "Authorization: Bearer sk_live_51H8x..." \
  -H "Content-Type: application/json" \
  -d '{
    "country": "fr",
    "service": "whatsapp",
    "max_price": 0.25
  }'

{
  "status": "success",
  "data": {
    "id": "ord_9f83k2la",
    "phone_number": "+33612345678",
    "service": "whatsapp",
    "country": "fr",
    "price": 0.18,
    "status": "pending",
    "expires_at": "2024-06-01T12:34:56Z"
  }
}

curl -X GET "https://api.atlas-sim.org/v1/orders/ord_9f83k2la" \
  -H "Authorization: Bearer sk_live_51H8x..."

{
  "status": "success",
  "data": {
    "id": "ord_9f83k2la",
    "status": "completed",
    "phone_number": "+33612345678",
    "sms_code": "482913",
    "sms_text": "Votre code WhatsApp est 482913",
    "received_at": "2024-06-01T12:31:02Z"
  }
}

curl -X POST "https://api.atlas-sim.org/v1/orders/ord_9f83k2la/cancel" \
  -H "Authorization: Bearer sk_live_51H8x..."

{
  "status": "success",
  "data": {
    "id": "ord_9f83k2la",
    "status": "cancelled",
    "refunded_amount": 0.18
  }
}

curl -X GET "https://api.atlas-sim.org/v1/orders?status=completed&page=1&limit=20" \
  -H "Authorization: Bearer sk_live_51H8x..."

{
  "status": "success",
  "data": {
    "page": 1,
    "total": 132,
    "orders": [
      { "id": "ord_9f83k2la", "service": "whatsapp", "country": "fr", "status": "completed", "price": 0.18 },
      { "id": "ord_7d21m4xz", "service": "telegram", "country": "us", "status": "expired", "price": 0.15 }
    ]
  }
}

Webhooks

Configure a webhook URL from your account area to receive order-related events in real time, instead of continuously polling the API.

Available events

• order.createdA new order was created and a number was assigned.
• sms.receivedAn SMS code was received for an ongoing order.
• order.expiredAn order expired without receiving any SMS; the balance was refunded.
• balance.lowThe account balance dropped below the configured alert threshold.

Payload security

Every webhook request is signed with HMAC-SHA256 using your webhook secret key. The signature is provided in the X-AtlasSIM-Signature header and must be verified server-side before any processing.

X-AtlasSIM-Signature: sha256=7f1c3d9e0a4b2f8e6c5d1a9b3e7f0c2d

{
  "event": "sms.received",
  "data": {
    "order_id": "ord_9f83k2la",
    "sms_code": "482913",
    "sms_text": "Votre code WhatsApp est 482913",
    "received_at": "2024-06-01T12:31:02Z"
  }
}

Retries

If your endpoint does not respond with a 2xx status code, AtlasSIM performs up to 5 retries with exponential backoff, over a 24-hour period.

Response codes and errors

The API uses standard HTTP status codes to indicate the success or failure of a request.

Rate limits

Each API key is subject to a requests-per-minute limit depending on your plan.

Exceeding the limit returns a 429 status code with a Retry-After header indicating the delay before the next allowed attempt.

SDK examples

Here is how to call the number purchase endpoint from different environments.

curl -X POST "https://api.atlas-sim.org/v1/orders" \
  -H "Authorization: Bearer sk_live_51H8x..." \
  -H "Content-Type: application/json" \
  -d '{"country": "fr", "service": "whatsapp"}'

Best practices and support

• Always cache the list of countries and services: it rarely changes and this reduces the number of requests.
• Use webhooks rather than polling to track incoming SMS in real time.
• Handle 429 errors with exponential backoff to respect rate limits.
• Never hard-code your API keys: use secure environment variables.
• Test your integrations with small amounts before deploying to production.