Skip to main content

Welcome to Vellosim API

The Vellosim API provides a comprehensive solution for integrating eSIM services into your application or website. Our API enables you to offer global connectivity solutions to your customers with ease.

Base URL

https://api.vellosim.com

Authentication

All API requests require authentication using an API Key in the X-API-Key header. Production:
X-API-Key: vls_live_YOUR_API_KEY
Testing/Sandbox:
X-API-Key: vls_test_YOUR_API_KEY
Use keys with vls_live_ prefix for production and vls_test_ prefix for testing/sandbox. The API automatically routes requests to the appropriate environment based on your key prefix.

Getting Your API Key

  1. Log in to your Vellosim dashboard
  2. Navigate to DeveloperAPI Keys
  3. Click Generate New API Key
  4. Copy and securely store your API key
Keep your API key secure! Never share it publicly or commit it to version control. The API key is shown only once during creation.

Request Format

Headers

Include these headers in all requests:
X-API-Key: YOUR_API_KEY
Content-Type: application/json
Accept: application/json

HTTP Methods

MethodUsage
GETRetrieve resources (regions, packages, orders)
POSTCreate resources (purchase eSIMs)
PUTUpdate resources
DELETEDelete resources

Response Format

All API responses are returned in JSON format with consistent structure.

Success Response

{
  "success": true,
  "data": {
    // Response data here
  },
  "message": "Request processed successfully"
}

Error Response

{
  "success": false,
  "error": {
    "code": "ERROR_CODE",
    "message": "Human-readable error message"
  },
  "statusCode": 400
}

Status Codes

CodeStatusDescription
200OKRequest successful
201CreatedResource created successfully
400Bad RequestInvalid parameters or business logic error
401UnauthorizedMissing or invalid API key
403ForbiddenValid key but insufficient permissions
404Not FoundResource not found
429Too Many RequestsRate limit exceeded
500Internal Server ErrorServer error occurred
503Service UnavailableService temporarily unavailable

Rate Limiting

API requests are rate-limited based on your plan:
PlanRate Limit
Standard100 requests/minute
Premium500 requests/minute
EnterpriseCustom limits
Rate limit information is included in response headers:
X-RateLimit-Limit: 100
X-RateLimit-Remaining: 95
X-RateLimit-Reset: 1699564800

Pagination

Endpoints that return lists support pagination:
GET /api/esim/my-esims?page=1&limit=20

Pagination Response

{
  "success": true,
  "data": {
    "items": [...],
    "pagination": {
      "currentPage": 1,
      "totalPages": 5,
      "totalItems": 100,
      "itemsPerPage": 20,
      "hasNextPage": true,
      "hasPrevPage": false
    }
  }
}

API Endpoints

Wallet

Get Balance

Retrieve your current wallet balance

eSIM

Purchase

Buy eSIM

Purchase an eSIM package

Orders

SDKs and Libraries

We’re working on official SDKs for popular languages. In the meantime, you can use standard HTTP clients like:
  • JavaScript/TypeScript: fetch, axios
  • Python: requests, httpx
  • PHP: cURL, Guzzle
  • Java/Kotlin: OkHttp, Retrofit
  • Swift: URLSession, Alamofire

Support

Need help integrating the API?
Start with the Quickstart Guide to make your first API call in minutes!