API Documentation

Download API docs (Markdown)

kartesim gives partners real phone numbers and mobile IPs through two services: long-term number and proxy rentals and per-use OTP sessions. Both are available via the HANDLER_API protocol and the Native REST API.

OTP sessionsper use

Request a temporary number, wait for an SMS, receive the OTP code — in one API call cycle. Billed per session, refunded if you cancel before the code arrives.

Number rentalsSIM cards

Rent a dedicated phone number for daily, weekly, or monthly periods. All SMS received on that number is forwarded to your account in real time.

Proxy rentalsMobile IPs

Rent an HTTP/SOCKS5 mobile proxy with a real carrier IP. Each proxy runs on a dedicated device (Android or 4G modem) with a live SIM card.

Rentals are provisioned by your account manager. Contact us to set up your rental — once active, your phone number and proxy credentials appear in the partner portal and can be queried via API. OTP sessions are self-serve via API — no setup required.

Authentication

All API requests require your partner API key. How you pass it depends on your protocol.

Handler API — query parameter

GET /api/stubs/handler_api.php
  ?api_key=YOUR_KEY
  &action=getBalance

Native REST API — HTTP header

curl https://www.kartesim.com/api/v1/otp/request \
  -H "x-api-key: YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{"service": "telegram"}'

Keep your API key secret. Your key is visible in the partner portal under API. Use the Regenerate Key button there to rotate it instantly.

Handler API Reference

Base URL: /api/stubs/handler_api.php — All requests use GET. All responses are plain text.

GET/api/stubs/handler_api.php?action=getBalance

Returns your current pre-paid balance in USD.

Parameters

Name	Type	Required	Description
api_key	string	required	Your API key
action	string	required	Must be "getBalance"

Responses

45.00Your balance in USD

999999Fixed sentinel returned for unlimited-balance accounts — not a real balance, and does not change with usage

BAD_KEYInvalid or revoked API key

Example request

curl 'https://www.kartesim.com/api/stubs/handler_api.php
  ?api_key=YOUR_KEY&action=getBalance'

Example response

45.00

GET/api/stubs/handler_api.php?action=getCountries

List supported countries with their numeric codes.

Parameters

Name	Type	Required	Description
api_key	string	required	Your API key
action	string	required	Must be "getCountries"

Responses

JSON array[{ "id": 7, "name": "Russia" }, ...]

Example request

curl 'https://www.kartesim.com/api/stubs/handler_api.php
  ?api_key=YOUR_KEY&action=getCountries'

Example response

[
  { "id": 7,   "name": "Russia" },
  { "id": 212, "name": "Morocco" }
]

GET/api/stubs/handler_api.php?action=getPrices

Get current pricing and available active stock per country and service.

Parameters

Name	Type	Required	Description
api_key	string	required	Your API key
action	string	required	Must be "getPrices"
country	number	optional	Filter by numeric country ID
hide_empty	integer	optional	Set to 1 to exclude countries with zero stock from the response

Responses

JSON object{ "countryId": { "serviceId": { "cost": 0.1, "count": 10 } } }

Example request

curl 'https://www.kartesim.com/api/stubs/handler_api.php
  ?api_key=YOUR_KEY&action=getPrices&hide_empty=1'

Example response

{
  "212": {
    "wa": { "cost": 0.15, "count": 12 },
    "tg": { "cost": 0.15, "count": 12 }
  }
}

GET/api/stubs/handler_api.php?action=getNumber

Request a temporary phone number for OTP verification. Returns a session ID and the assigned number. The session expires after 10 minutes if no SMS arrives.

Parameters

Name	Type	Required	Description
api_key	string	required	Your API key
action	string	required	Must be "getNumber"
service	string	optional	Service name (e.g. "telegram", "whatsapp") — informational only
country	integer	optional	Country calling code (e.g. 212 for Morocco). Omit or use 0 for any country.

Responses

ACCESS_NUMBER:id:numberSession created — id is used for getStatus/setStatus, number is the assigned phone number

NO_NUMBERSNo online ports available matching your request

NO_BALANCEInsufficient balance to cover the OTP fee

Example request

curl 'https://www.kartesim.com/api/stubs/handler_api.php
  ?api_key=YOUR_KEY&action=getNumber&service=telegram&country=212'

Example response

ACCESS_NUMBER:cma4x9k3b0000abc123:212661234567

GET/api/stubs/handler_api.php?action=getStatus

Poll for the OTP code on an active session. Poll every 5–10 seconds until you receive STATUS_OK or STATUS_CANCEL.

Parameters

Name	Type	Required	Description
api_key	string	required	Your API key
action	string	required	Must be "getStatus"
id	string	required	Session ID from ACCESS_NUMBER response

Responses

STATUS_WAIT_CODESession is active — SMS not yet received. Keep polling.

STATUS_OK:84729OTP received — the code follows the colon

STATUS_CANCELSession expired or was cancelled

Example request

curl 'https://www.kartesim.com/api/stubs/handler_api.php
  ?api_key=YOUR_KEY&action=getStatus&id=cma4x9k3b0000abc123'

Example response

STATUS_OK:84729

GET/api/stubs/handler_api.php?action=setStatus

Confirm receipt of the OTP (status=1) or cancel the session for a full refund (status=8). Only PENDING sessions can be cancelled.

Parameters

Name	Type	Required	Description
api_key	string	required	Your API key
action	string	required	Must be "setStatus"
id	string	required	Session ID to act on
status	integer	required	1 = confirm received, 8 = cancel and refund

Responses

ACCESS_READYConfirmed — session acknowledged

ACCESS_CANCELCancelled — balance refunded

BAD_ACTIONSession not found or already completed

Example request

# Cancel and refund
curl 'https://www.kartesim.com/api/stubs/handler_api.php
  ?api_key=YOUR_KEY&action=setStatus&id=cma4x9k3b0000abc123&status=8'

Example response

ACCESS_CANCEL

Native REST API

For modern integrations, use our Native REST API instead of the legacy Handler API. Pass your API key using the x-api-key HTTP header.

OTP sessions

per use

OTP sessions let you request a temporary phone number, receive a one-time code, and release the number — all via API. Each session is billed once on creation. If you cancel before the code arrives, the full fee is refunded.

POST/api/v1/otp/request

Request a temporary phone number for OTP verification. Returns a sessionId and the assigned number. Charges the OTP_PER_USE fee immediately.

Parameters

Name	Type	Required	Description
country	integer	optional	Country calling code to filter by (e.g. 212). Omit for any.
service	string	optional	Service name e.g. "telegram" — stored on the session for your reference
webhookUrl	string	optional	HTTPS URL to POST to when the OTP arrives (instead of polling)
expiresIn	integer	optional	Session TTL in seconds (60–1800, default 600)

Responses

200 OKSession created — body contains sessionId, number, and expiresAt

402 Payment RequiredInsufficient balance

503 Service UnavailableNo online numbers available

Example request

curl -X POST https://www.kartesim.com/api/v1/otp/request \
  -H "x-api-key: YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{"service": "telegram", "country": 212}'

Example response

{ "sessionId": "cma4x9k3b0000abc123", "number": "212661234567", "status": "PENDING", "expiresAt": "2026-06-01T00:20:00.000Z" }

GET/api/v1/otp/:sessionId

Poll for OTP session status and code. Returns the extracted OTP code once the SMS arrives. Poll every 5–10 seconds.

Responses

200 OK — PENDINGstatus: "PENDING", otp: null — still waiting

200 OK — RECEIVEDstatus: "RECEIVED", otp: "84729" — code ready

200 OK — EXPIREDstatus: "EXPIRED" — no SMS within the timeout window

200 OK — CANCELLEDstatus: "CANCELLED" — you cancelled the session

Example request

curl -H "x-api-key: YOUR_KEY" https://www.kartesim.com/api/v1/otp/cma4x9k3b0000abc123

Example response

{ "sessionId": "cma4x9k3b0000abc123", "status": "RECEIVED", "number": "212661234567", "otp": "84729", "smsBody": "Your code is 84729" }

POST/api/v1/otp/:sessionId/cancel

Cancel a PENDING session. Issues a full refund of the OTP fee. Sessions that already received an OTP cannot be cancelled.

Responses

200 OKstatus: "CANCELLED", refunded: 0.10 — balance credited

409 ConflictSession is not in PENDING state — cannot cancel

404 Not FoundSession not found or belongs to another account

Example request

curl -X POST -H "x-api-key: YOUR_KEY" https://www.kartesim.com/api/v1/otp/cma4x9k3b0000abc123/cancel

Example response

{ "sessionId": "cma4x9k3b0000abc123", "status": "CANCELLED", "refunded": "0.1000" }

POSTYour webhook URL (server push)

When an OTP arrives, we POST to the webhookUrl you provided on session creation. This is an alternative to polling — your server receives the OTP automatically without needing to call getStatus.

Payload

POST to your webhookUrl

{
  "event":      "otp.received",
  "sessionId":  "cma4x9k3b0000abc123",
  "status":     "RECEIVED",
  "number":     "212661234567",
  "otp":        "84729",
  "smsBody":    "Your Telegram code is 84729",
  "receivedAt": "2026-06-21T12:00:00.000Z"
}

Security

Your webhook URL must be HTTPS in production — HTTP URLs are rejected.
We send an X-Webhook-Signature: sha256=... header (HMAC-SHA256). Verify it to confirm the request is genuine.
We retry once on 5xx after 2 seconds. Your endpoint should return 200 quickly.
Your endpoint must be idempotent — duplicate delivery is possible on retry.

GET/api/partner/rentals

Fetch all active number rentals for your account.

Responses

200 OKJSON array of active number rentals

401 UnauthorizedInvalid or missing API key

Example request

curl -H "x-api-key: YOUR_KEY" https://www.kartesim.com/api/partner/rentals

Example response

[
  {
    "id": "cuid...",
    "phoneNumber": "1234567890",
    "countryCode": 1,
    "expiresAt": "2026-06-25T10:00:00.000Z",
    "daysRemaining": 26
  }
]

GET/api/partner/proxies

Fetch all active proxy rentals for your account, including their current IP address and credentials.

Responses

200 OKJSON array of active proxy rentals

401 UnauthorizedInvalid or missing API key

Example request

curl -H "x-api-key: YOUR_KEY" https://www.kartesim.com/api/partner/proxies

Example response

[
  {
    "id": "cuid...",
    "port": "Port A",
    "host": "192.168.1.10",
    "socks5Port": 1080,
    "username": "user",
    "password": "pwd",
    "expiresAt": "2026-06-25T10:00:00.000Z"
  }
]

GET/api/partner/sms?simNumber=1234567890

Fetch the latest SMS messages received by your rented numbers. Optionally filter by a specific simNumber.

Parameters

Name	Type	Required	Description
simNumber	string	optional	Filter SMS for a specific rented number

Responses

200 OKJSON array of recent SMS messages

401 UnauthorizedInvalid or missing API key

Example request

curl -H "x-api-key: YOUR_KEY" https://www.kartesim.com/api/partner/sms

Example response

[
  {
    "id": "cuid...",
    "simNumber": "1234567890",
    "fromNumber": "Twilio",
    "body": "Your verification code is 49201",
    "receivedAt": "2026-05-29T15:30:00.000Z"
  }
]

Number rentals

Number rentals give you exclusive use of a real SIM card for a fixed rental period. Every SMS received on that number is delivered to your account in real time. You can rent numbers directly via the API or the partner portal.

Period	Duration	Description
Daily	24 hours	Best for short-term verification campaigns
Weekly	7 days	Best for ongoing access to a stable number
Monthly	30 days	Best for long-term dedicated number access

How it works

Call GET /api/v1/numbers/available to browse available numbers (masked).
Choose a number and billing cycle, then call POST /api/v1/numbers/rent to rent it instantly.
Your balance is debited immediately. The full unmasked phone number is returned in the response.
All SMS received on your rented number appears under SMS Logs in real time.
At expiry the number is automatically released. No refund is issued for unused time.

GET/api/v1/numbers/available

Browse numbers available for rental. Numbers are masked (e.g. +212 6** *** **7) so you can see country and carrier before committing. Optionally filter by country code.

Parameters

Name	Type	Required	Description
country	number	optional	ITU country code (e.g. 212). Omit or use 0 for any country.

Responses

200 OKJSON with available numbers list and total count

401 UnauthorizedInvalid or missing API key

429 Too Many RequestsRate limit exceeded (30 req/min)

Example request

curl -H "x-api-key: YOUR_KEY" https://www.kartesim.com/api/v1/numbers/available?country=212

Example response

{
  "available": [
    {
      "phoneId":      "clx...",
      "maskedNumber": "+212 6** *** **7",
      "countryCode":  212,
      "country":      "Morocco",
      "carrier":      "Orange",
      "pricing": { "daily": null, "weekly": 2.50, "monthly": 8.00 }
    }
  ],
  "total": 1
}

POST/api/v1/numbers/rent

Self-rent a number. Atomically deducts your balance and creates an exclusive rental. Returns the full (unmasked) phone number on success.

Parameters

Name	Type	Required	Description
phoneId	string	required	Port ID from /api/v1/numbers/available
billingCycle	string	required	DAILY \| WEEKLY \| MONTHLY
cycles	number	optional	Number of billing cycles to pay upfront (1–12, default 1)
autoRenew	boolean	optional	Auto-renew on expiry (default false)

Responses

200 OKRental created — full phone number in response

402 Payment RequiredInsufficient balance or no pricing configured for that cycle

409 ConflictNumber was just rented by another partner — retry with a different number

401 UnauthorizedInvalid or missing API key

Example request

curl -X POST -H "x-api-key: YOUR_KEY" -H "Content-Type: application/json" \
  -d '{"phoneId":"clx...","billingCycle":"MONTHLY","cycles":1}' \
  https://www.kartesim.com/api/v1/numbers/rent

Example response

{
  "rentalId":     "cly...",
  "phoneNumber":  "+212661234567",
  "countryCode":  212,
  "carrier":      "Orange",
  "billingCycle": "MONTHLY",
  "pricePerCycle": 8.00,
  "cycles":        1,
  "totalCharged":  8.00,
  "autoRenew":     false,
  "startedAt":    "2026-06-21T20:00:00.000Z",
  "expiresAt":    "2026-07-21T20:00:00.000Z"
}

GET/api/partner/rentals

Fetch all active number rentals for your account.

Responses

200 OKJSON array of active number rentals

401 UnauthorizedInvalid or missing API key

Example request

curl -H "x-api-key: YOUR_KEY" https://www.kartesim.com/api/partner/rentals

Example response

[
  {
    "id": "cuid...",
    "phoneNumber": "+212661234567",
    "maskedNumber": "+212 6** *** **7",
    "countryCode": 212,
    "expiresAt": "2026-06-25T10:00:00.000Z",
    "daysRemaining": 26
  }
]

Numbers are dedicated to your account. The number is never shared or re-assigned during your rental period. The balance required for the full period is charged at time of rental. If a number you requested is taken between browse and rent, you will receive a 409 — retry with another number.

Proxy rentals

Each port in the fleet exposes an HTTP and SOCKS5 proxy over its mobile data connection. Partners can route traffic through these proxies to obtain a real mobile IP for a specific country.

Protocol	Default port	Notes
HTTP	device-specific	HTTP CONNECT proxy — port shown in partner portal and `/api/partner/proxies`
SOCKS5	1080	SOCKS5 proxy — supports TCP and UDP tunneling

HTTP proxy — curl

curl --proxy http://USER:PASS@PHONE_IP:8888 https://api.ipify.org

SOCKS5 proxy — curl

curl --proxy socks5://USER:PASS@PHONE_IP:1080 https://api.ipify.org

Proxy credentials and IP are provided by your account manager. The port IP updates automatically on every heartbeat — the partner portal always shows the latest IP. Proxy access requires authentication — unauthenticated connections are rejected.

Viewing your active proxies

Your active proxy subscriptions — including the current IP, port, and expiry — are visible in the partner portal under Proxies. The IP field is updated live as the port reports its address.

Supported countries

Use getCountries to get the current list. Common country codes:

Code	Country	Code	Country
0	Any (auto-assign)	7	Russia
212	Morocco	33	France
1	United States	44	United Kingdom
49	Germany	34	Spain
966	Saudi Arabia	971	United Arab Emirates
20	Egypt	216	Tunisia

Error reference

Response	Meaning
BAD_KEY	Invalid, revoked, or missing API key
BAD_ACTION	Unknown action or missing required parameters
TOO_MANY_REQUESTS	Rate limit exceeded — 120 requests per minute
NO_NUMBERS	No online ports available matching your OTP request
NO_BALANCE	Insufficient balance to create an OTP session
STATUS_WAIT_CODE	OTP not yet received — keep polling
STATUS_OK:code	OTP received — digit code follows the colon
STATUS_CANCEL	Session expired or was cancelled
ACCESS_NUMBER:id:num	OTP session created — session ID and phone number follow
ACCESS_CANCEL	Session cancelled, balance refunded
ACCESS_READY	Session acknowledged / confirmed

kartesim Partner Documentation — For API key requests or rental enquiries, contact your account manager.