Loading...
Integrate into your application using our REST API
https://gsim.io
Include your API key in every request as a Bearer token:
Authorization: Bearer 2s_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
Manage your API keys at /dashboard/api-keys.
/api/v1/balanceGet your current account balance.
Response
{
"balance": 5.51,
"currency": "USD"
}/api/v1/servicesList all available services with minimum prices.
Response
[
{ "id": "telegram", "name": "Telegram", "minPrice": 0.15, "count": 12500 },
{ "id": "whatsapp", "name": "WhatsApp", "minPrice": 0.12, "count": 8700 }
]/api/v1/countriesList countries. Optionally filter by service.
Query Parameters
| Parameter | Required | Description |
|---|---|---|
service | No | Service ID (e.g. telegram) |
Response
[
{ "id": "russia", "name": "Russia", "iso": "RU", "minPrice": 0.15, "count": 1200 }
]/api/v1/operatorsList operators for a specific service and country.
Query Parameters
| Parameter | Required | Description |
|---|---|---|
service | Yes | Service ID |
country | Yes | Country ID |
Response
[
{ "id": "any", "name": "Any", "price": 0.18, "count": 450 },
{ "id": "mts", "name": "MTS", "price": 0.16, "count": 200 }
]/api/v1/ordersList your orders with optional filtering and pagination.
Query Parameters
| Parameter | Required | Description |
|---|---|---|
page | No | Page number (default: 1) |
limit | No | Results per page, max 100 (default: 20) |
status | No | Filter by status: PENDING | RECEIVED | CANCELLED | BANNED | REFUNDED | EXPIRED |
Response
{
"orders": [
{
"id": "cma1b2c3...",
"service": "telegram",
"country": "russia",
"operator": "any",
"phoneNumber": "+79991234567",
"smsCode": null,
"status": "PENDING",
"price": 0.18,
"createdAt": "2024-03-15T10:00:00.000Z",
"expiresAt": "2024-03-15T10:20:00.000Z"
}
],
"total": 42,
"page": 1,
"limit": 20,
"totalPages": 3
}/api/v1/ordersPurchase a new SMS number.
Request Body
| Parameter | Required | Description |
|---|---|---|
service | Yes | Service ID (from /api/v1/services) |
country | Yes | Country ID (from /api/v1/countries) |
operator | No | Operator ID (from /api/v1/operators). Omit for any. |
Request Body
{
"service": "telegram",
"country": "russia",
"operator": "any"
}Response
{
"id": "cma1b2c3...",
"phoneNumber": "+79991234567",
"service": "telegram",
"country": "russia",
"operator": "any",
"status": "PENDING",
"price": 0.18,
"expiresAt": "2024-03-15T10:20:00.000Z"
}/api/v1/orders/:idGet order details including SMS code when received.
Response
{
"id": "cma1b2c3...",
"service": "telegram",
"phoneNumber": "+79991234567",
"smsCode": "123456",
"status": "RECEIVED",
"price": 0.18,
"createdAt": "2024-03-15T10:00:00.000Z",
"expiresAt": "2024-03-15T10:20:00.000Z"
}/api/v1/orders/:id/cancelCancel a PENDING order and get a full refund.
Response
{ "success": true, "refunded": 0.18 }/api/v1/orders/:id/banBan a number (not receiving SMS) and get a full refund.
Response
{ "success": true, "refunded": 0.18 }/api/v1/rentals/searchSearch available phone numbers for rental.
Query Parameters
| Parameter | Required | Description |
|---|---|---|
country | Yes | 2-letter ISO country code (e.g. US, GB) |
type | No | Local | Mobile | TollFree (default: Local) |
smsEnabled | No | Filter SMS-capable numbers (true/false) |
voiceEnabled | No | Filter voice-capable numbers (true/false) |
areaCode | No | Area code filter (e.g. 510) |
contains | No | Pattern match (e.g. 555) |
pageSize | No | Max results, 1-50 (default: 20) |
Response
{
"numbers": [
{
"friendlyName": "(510) 555-1234",
"phoneNumber": "+15105551234",
"locality": "Oakland",
"region": "CA",
"isoCountry": "US",
"capabilities": { "voice": true, "SMS": true, "MMS": true }
}
]
}/api/v1/rentalsList your rented virtual numbers.
Query Parameters
| Parameter | Required | Description |
|---|---|---|
page | No | Page number (default: 1) |
limit | No | Results per page, max 100 (default: 20) |
status | No | ACTIVE | PENDING_RENEWAL | EXPIRED | CANCELLED |
Response
{
"rentals": [
{
"id": "cma...",
"phoneNumber": "+15105551234",
"country": "US",
"numberType": "LOCAL",
"status": "ACTIVE",
"monthlyPrice": 1.50,
"autoRenew": true,
"renewsAt": "2024-04-15T00:00:00.000Z"
}
],
"total": 3,
"page": 1
}/api/v1/rentalsRent a virtual phone number. Deducts monthly fee from balance.
Request Body
| Parameter | Required | Description |
|---|---|---|
phoneNumber | Yes | E.164 format number from search results |
numberType | Yes | LOCAL | MOBILE | TOLL_FREE |
country | Yes | 2-letter ISO country code |
monthlyPrice | Yes | Base monthly price (before markup) |
Request Body
{
"phoneNumber": "+15105551234",
"numberType": "LOCAL",
"country": "US",
"monthlyPrice": 1.15
}Response
{
"id": "cma...",
"phoneNumber": "+15105551234",
"country": "US",
"numberType": "LOCAL",
"status": "ACTIVE",
"monthlyPrice": 1.50,
"renewsAt": "2024-04-15T00:00:00.000Z"
}/api/v1/rentals/:idGet rental details including recent messages and calls.
Response
{
"id": "cma...",
"phoneNumber": "+15105551234",
"status": "ACTIVE",
"messages": [...],
"calls": [...]
}/api/v1/rentals/:idUpdate rental settings (forwarding, auto-renew, voicemail).
Query Parameters
| Parameter | Required | Description |
|---|---|---|
autoRenew | No | true/false |
forwardingNumber | No | E.164 number or null to disable |
voicemailEnabled | No | true/false |
friendlyName | No | Display name (max 64 chars) |
Request Body
{
"autoRenew": true,
"forwardingNumber": "+905551234567"
}Response
{ "id": "cma...", "autoRenew": true, "forwardingNumber": "+905551234567" }/api/v1/rentals/:idRelease a rented number. The number is immediately freed and cannot be recovered.
Response
{ "success": true }/api/v1/rentals/:id/smsList SMS messages for a rental (paginated).
Query Parameters
| Parameter | Required | Description |
|---|---|---|
page | No | Page number (default: 1) |
limit | No | Max 100 (default: 50) |
Response
{
"messages": [
{
"id": "cma...",
"direction": "INBOUND",
"from": "+14155551234",
"to": "+15105551234",
"body": "Your verification code is 123456",
"status": "received",
"createdAt": "2024-03-15T10:05:00.000Z"
}
],
"total": 15
}/api/v1/rentals/:id/smsSend an SMS from your rented number. Charges per-SMS usage fee.
Request Body
| Parameter | Required | Description |
|---|---|---|
to | Yes | Recipient phone number in E.164 format |
body | Yes | Message text (1-1600 chars) |
Request Body
{
"to": "+14155551234",
"body": "Hello from my virtual number!"
}Response
{ "id": "cma...", "status": "queued", "twilioSid": "SM..." }/api/v1/rentals/:id/callsList call history for a rental (paginated).
Query Parameters
| Parameter | Required | Description |
|---|---|---|
page | No | Page number (default: 1) |
limit | No | Max 100 (default: 50) |
Response
{
"calls": [
{
"id": "cma...",
"direction": "INBOUND",
"from": "+14155551234",
"to": "+15105551234",
"status": "COMPLETED",
"duration": 45,
"createdAt": "2024-03-15T10:10:00.000Z"
}
],
"total": 5
}/api/v1/rentals/:id/callsInitiate an outbound call from your rented number.
Request Body
| Parameter | Required | Description |
|---|---|---|
to | Yes | Destination phone number in E.164 format |
Request Body
{ "to": "+14155551234" }Response
{ "id": "cma...", "status": "RINGING", "twilioSid": "CA..." }All errors return JSON: { "error": "...", "code": "..." }
| Code | Status | Meaning |
|---|---|---|
UNAUTHORIZED | 401 | Missing or invalid API key |
FORBIDDEN | 403 | API key has been revoked |
NOT_FOUND | 404 | Resource not found |
INSUFFICIENT_BALANCE | 402 | Insufficient balance to complete purchase |
RATE_LIMITED | 429 | Rate limit exceeded — retry after 60 seconds |
VALIDATION_ERROR | 400 | Invalid or missing request parameters |
PROVIDER_ERROR | 503 | SMS provider temporarily unavailable |
CONFLICT | 409 | Order is no longer in a cancellable state |
const API_KEY = "2s_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx";
const BASE = "https://gsim.io";
async function getCode(service, country) {
// 1. Purchase a number
const order = await fetch(`${BASE}/api/v1/orders`, {
method: "POST",
headers: {
"Authorization": `Bearer ${API_KEY}`,
"Content-Type": "application/json"
},
body: JSON.stringify({ service, country })
}).then(r => r.json());
console.log("Phone:", order.phoneNumber);
// 2. Poll until SMS received (max 5 min)
for (let i = 0; i < 30; i++) {
await new Promise(r => setTimeout(r, 10_000));
const detail = await fetch(`${BASE}/api/v1/orders/${order.id}`, {
headers: { "Authorization": `Bearer ${API_KEY}` }
}).then(r => r.json());
if (detail.smsCode) {
console.log("SMS Code:", detail.smsCode);
return detail.smsCode;
}
if (detail.status === "EXPIRED" || detail.status === "CANCELLED") break;
}
// 3. Ban number if no SMS received
await fetch(`${BASE}/api/v1/orders/${order.id}/ban`, {
method: "POST",
headers: { "Authorization": `Bearer ${API_KEY}` }
});
throw new Error("No SMS received");
}
getCode("telegram", "russia");Need help? Contact us at support@gsim.io