API documentation

REST API for batch / automated access to jiema.my. Use this to integrate SMS verification into your own services. All endpoints return JSON.

Contents

Authentication
Errors & rate limits
GET /v1/account
GET /v1/services
GET /v1/countries
GET /v1/prices
POST /v1/orders
GET /v1/orders/:id
POST /v1/orders/:id/cancel
POST /v1/orders/:id/next-sms
GET /v1/orders
Typical workflow

Authentication

Every request must include your API key:

Authorization: Bearer jm_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

Alternative header form: X-API-Key: jm_xxx…

Create and revoke keys at /account/api-keys. Each user can hold up to 10 active keys. The full token is shown only once on creation — store it securely.

Errors & rate limits

All errors return JSON:

{ "ok": false, "code": "RATE_LIMITED", "message": "..." }

HTTP	code	meaning
401	AUTH_MISSING / AUTH_INVALID	No key or revoked
403	FORBIDDEN	Banned or no access
400	BAD_REQUEST / INSUFFICIENT / NO_NUMBERS / …	Validation or business error
404	NOT_FOUND	Order doesn't exist (or not yours)
429	RATE_LIMITED	Per-key throttling
500	INTERNAL	Server error (auto-reported)

Rate limits: Per key, sliding 60s window. Write endpoints (orders, cancel, next-sms) 10 req/min; read endpoints (account, services, prices, list) 60 req/min.

GET /v1/account

Get your current balance and basic profile.

curl https://jiema.my/api/v1/account \
  -H "Authorization: Bearer jm_xxx"

# 200 OK
{ "ok": true, "data": {
  "id": "clxxxxxxxxxxx",
  "balanceCents": "1200",       // string to preserve precision; $12.00
  "referralCode": "abc123",
  "displayName": "Alice",
  "lang": "en"
}}

GET /v1/services

List services with stock. Cached server-side ~5 min.

curl https://jiema.my/api/v1/services -H "Authorization: Bearer jm_xxx"

{ "ok": true, "data": { "items": [
  { "code": "tg", "slug": "telegram", "name": "Telegram",
    "minCostUsd": 0.18, "totalCount": 1234, "countryCount": 24 },
  ...
] }}

Use code (or the friendly slug) as the service field when creating an order.

GET /v1/countries

curl https://jiema.my/api/v1/countries -H "Authorization: Bearer jm_xxx"

{ "ok": true, "data": { "items": [
  { "id": 7, "slug": "my", "name": "Malaysia" },
  ...
] }}

id is the upstream numeric country id; slug is the SEO short code (e.g. "my" / "us"). Either form works as the country field.

GET /v1/prices?service=tg

Per-country price and stock for a given service. Prices already include the markup/discount configured by ops.

curl "https://jiema.my/api/v1/prices?service=tg" -H "Authorization: Bearer jm_xxx"

{ "ok": true, "data": {
  "service": "tg",
  "items": [
    { "countryId": 7, "countrySlug": "my", "priceCents": "32", "count": 540 },
    ...
  ]
}}

POST /v1/orders

Create an SMS verification order. The system reserves a phone number from the upstream and deducts the charged amount from your balance.

curl -X POST https://jiema.my/api/v1/orders \
  -H "Authorization: Bearer jm_xxx" \
  -H "content-type: application/json" \
  -d '{ "service": "tg", "country": 7 }'

{ "ok": true, "data": {
  "id": "ckxxxxx",
  "status": "WAITING",
  "service": "tg",
  "country": "7",
  "phone": "+60123456789",
  "expiresAt": "2026-05-22T08:30:00.000Z",
  "chargedCents": "32"
}}

No optional fields beyond service / country.

Common error codes: INSUFFICIENT (top up needed), NO_NUMBERS, BAD_SERVICE, BAD_COUNTRY.

GET /v1/orders/:id

Poll until status becomes RECEIVED and smsBody is non-null.

curl https://jiema.my/api/v1/orders/ckxxxxx -H "Authorization: Bearer jm_xxx"

{ "ok": true, "data": {
  "id": "ckxxxxx",
  "status": "RECEIVED",
  "phone": "+60123456789",
  "smsBody": "Your verification code is 123456",
  "smsHistory": [
    { "body": "Your verification code is 123456", "receivedAt": "..." }
  ],
  "smsReceivedAt": "2026-05-22T08:12:34.000Z",
  ...
}}

Statuses: WAITING (number active, waiting for SMS) · RECEIVED (code arrived) · COMPLETED / FAILED / CANCELLED are terminal.

Suggested polling: every 3–5 seconds. Upstream sync runs inside this endpoint so polling it drives state forward even if the background worker is busy.

POST /v1/orders/:id/cancel

Cancel an order that hasn't received a code yet. Full refund to your balance.

curl -X POST https://jiema.my/api/v1/orders/ckxxxxx/cancel \
  -H "Authorization: Bearer jm_xxx"

{ "ok": true, "data": { "id": "ckxxxxx", "status": "CANCELLED" }}

Rejected with CODE_RECEIVED if the number already received any SMS, or ALREADY_CHANGED if status changed concurrently.

POST /v1/orders/:id/next-sms

After RECEIVED, request the upstream to keep the number active and wait for another SMS (no extra charge within the active window).

curl -X POST https://jiema.my/api/v1/orders/ckxxxxx/next-sms \
  -H "Authorization: Bearer jm_xxx"

{ "ok": true, "data": { "id": "ckxxxxx", "status": "WAITING" }}

GET /v1/orders

Cursor-paginated list of your recent orders.

curl "https://jiema.my/api/v1/orders?limit=20" -H "Authorization: Bearer jm_xxx"

{ "ok": true, "data": {
  "items": [ { "id": "ck...", "status": "RECEIVED", "service": "tg", ... }, ... ],
  "nextCursor": "ck..." | null
}}

Optional query: status · limit 1–100 (default 20) · cursor = previous page's nextCursor.

Typical workflow

Top up via the web UI → GET /v1/account to confirm balance.
Pick a service: GET /v1/services and GET /v1/prices?service=tg.
Create an order: POST /v1/orders with service + country.
Read data.phone and trigger the upstream SMS from your client (e.g. paste into Telegram registration).
Poll GET /v1/orders/:id every 3–5s. When status === "RECEIVED", read smsBody.
If wrong SMS or want a second code: POST /v1/orders/:id/next-sms → back to WAITING.
Done. If you cancel before any SMS arrives: POST /v1/orders/:id/cancel for full refund.

jiema.my