OpenAPI 3.1 · v1.0.0

API reference

Provision verification numbers, stream one-time codes, manage credits and API keys. All monetary values are strings in USD; all timestamps are ISO 8601 (UTC).

Download bot schema OpenAPI spec (REST API)Get API key

Bot integration (gmxgen)

For clients that speak the custom SMS-provider format — plain GET /getPhone, /getCode, /cancel, /health — point the bot at the endpoint below and import the schema. This is separate from the REST API and does not affect it.

Base URLhttps://smsmonkey.org/api/gmxgen

Your API key

Custom schema

gmxgen-schema.json

{
  "authHeaderName": "authorization",
  "authHeaderPrefix": "Bearer ",
  "getPhone": {
    "route": "/getPhone",
    "method": "GET",
    "requestFormat": "query",
    "requestKeys": {
      "country": "country",
      "site": "site",
      "maxPrice": "maxPrice"
    },
    "responseKeys": {
      "id": "id",
      "phone": "number"
    },
    "serviceMap": {
      "Wonder": "wonder",
      "GMX": "gmx",
      "Ticketmaster": "ticketmaster"
    },
    "countryMap": {}
  },
  "getStatus": {
    "route": "/getCode",
    "method": "GET",
    "requestFormat": "query",
    "requestKeys": {
      "id": "id"
    },
    "responseKeys": {
      "status": "status",
      "code": "code"
    },
    "statusMap": {
      "pending": "pending",
      "success": "success",
      "failed": "failed"
    }
  },
  "cancel": {
    "route": "/cancel",
    "method": "GET",
    "requestFormat": "query",
    "requestKeys": {
      "id": "id"
    }
  },
  "health": {
    "route": "/health",
    "method": "GET"
  }
}

Available sites: Wonder, GMX, Ticketmaster. Sign in and your downloaded schema will include your base URL and API key, ready to use.

Introduction

The SMS Monkey API is a small, predictable REST API. Requests and responses are JSON; monetary amounts are decimal strings in USD; timestamps are ISO 8601 in UTC. Every response for a failed request uses the same error envelope.

Base URLhttps://smsmonkey.org

Quick start

curl

# 1 · Public catalog — no auth needed
curl "https://smsmonkey.org/api/v1/prices"

# 2 · An authenticated call
curl "https://smsmonkey.org/api/v1/me" \
  -H "Authorization: Bearer wnd_your_key"

# 3 · Order a number, then poll it for the code
curl -X POST "https://smsmonkey.org/api/v1/orders" \
  -H "Authorization: Bearer wnd_your_key" \
  -H "Content-Type: application/json" \
  -d '{"service":"wonder"}'

Authentication

Authenticate every request (except the public catalog) with an API key sent as a bearer token. Create and revoke keys from the API keys page after signing in with Discord.

Authorization header

Authorization: Bearer wnd_your_api_key

Missing or invalid credentials

401 Unauthorized

{
  "error": "Unauthorized"
}

Errors & status

Errors return a JSON object with a single error string and the matching HTTP status code.

Error envelope

{
  "error": "Insufficient balance"
}

Status codes

Status	Meaning
400	Bad request — the body or parameters failed validation.
401	Unauthorized — the API key or session is missing or invalid.
402	Payment required — insufficient credit balance for the action.
404	Not found — the resource does not exist or isn't yours.
409	Conflict — the resource can no longer transition (e.g. code already received).
500	Internal server error — something went wrong on our side.
503	Service unavailable — no numbers are available right now; retry shortly.

Order status values

Status	Meaning
pending	Order created; a number is being assigned.
waiting	Number assigned; waiting for the one-time code.
received	A code arrived. `code` and `fullMessage` are populated.
cancelled	Cancelled before a code arrived; the charge was refunded.
expired	The window elapsed with no code; the charge was refunded.
failed	A number could not be provisioned; the charge was refunded.

Account

GET/api/v1/me🔒 Requires API key

Get the authenticated account

Returns the identity behind the API key or session used for the request.

Request

GET /api/v1/me

curl -X GET "https://smsmonkey.org/api/v1/me" \
  -H "Authorization: Bearer wnd_your_key"

Responses

200The authenticated account.

200 response

{
  "id": "3f1c2b90-6d2a-4a7e-9b8c-2b1d0e4f5a6b",
  "discordId": "1461464020530892933",
  "username": "rx7nerd",
  "isAdmin": false
}

401Missing or invalid credentials.

401 response

{
  "error": "Unauthorized"
}

GET/api/v1/balance🔒 Requires API key

Get credit balance

Returns the account's spendable credit balance, derived from the immutable ledger.

Request

GET /api/v1/balance

curl -X GET "https://smsmonkey.org/api/v1/balance" \
  -H "Authorization: Bearer wnd_your_key"

Responses

200Current balance.

200 response

{
  "balance": "12.40",
  "currency": "USD"
}

401Missing or invalid credentials.

401 response

{
  "error": "Unauthorized"
}

Catalog

GET/api/v1/prices● Public

List services and prices

Returns the available services and their per-number price. This endpoint is public and needs no authentication.

Request

GET /api/v1/prices

curl -X GET "https://smsmonkey.org/api/v1/prices"

Responses

200Available services.

200 response

{
  "services": [
    {
      "service": "wonder",
      "name": "Wonder",
      "price": "0.30",
      "currency": "USD"
    },
    {
      "service": "gmx",
      "name": "GMX",
      "price": "0.10",
      "currency": "USD"
    },
    {
      "service": "ticketmaster",
      "name": "Ticketmaster",
      "price": "0.15",
      "currency": "USD"
    }
  ]
}

Orders

GET/api/v1/orders🔒 Requires API key

List orders

Returns your most recent orders, newest first (up to 50).

Request

GET /api/v1/orders

curl -X GET "https://smsmonkey.org/api/v1/orders" \
  -H "Authorization: Bearer wnd_your_key"

Responses

200A list of orders.

200 response

{
  "orders": [
    {
      "id": "ord_a1b2c3d4",
      "service": "wonder",
      "number": "+15551234567",
      "status": "received",
      "price": "0.30",
      "code": "481902",
      "fullMessage": "Your verification code is 481902",
      "expiresAt": "2026-08-16T20:20:00.000Z",
      "createdAt": "2026-08-16T20:00:00.000Z"
    },
    {
      "id": "ord_a1b2c3d4",
      "service": "wonder",
      "number": "+15551234567",
      "status": "waiting",
      "price": "0.30",
      "code": null,
      "fullMessage": null,
      "expiresAt": "2026-08-16T20:20:00.000Z",
      "createdAt": "2026-08-16T20:00:00.000Z"
    }
  ]
}

401Missing or invalid credentials.

401 response

{
  "error": "Unauthorized"
}

POST/api/v1/orders🔒 Requires API key

Order a verification number

Provisions a fresh number and debits your balance by the service price. Poll the order (or `GET /orders`) until `status` becomes `received` to read the code.

You are charged immediately. If a number can't be provisioned, the charge is refunded automatically.

Cancel before a code arrives to get a full refund — see the cancel endpoint.

Body parameters

Field	Type	Required	Description
service	string	optional	Service to order. One of `wonder`, `gmx`, `ticketmaster`. Defaults to `wonder`. See GET /prices for names and prices. · e.g. "wonder"

Request

POST /api/v1/orders

curl -X POST "https://smsmonkey.org/api/v1/orders" \
  -H "Authorization: Bearer wnd_your_key" \
  -H "Content-Type: application/json" \
  -d '{"service":"wonder"}'

Responses

201Order created; a number was assigned.

201 response

{
  "id": "ord_a1b2c3d4",
  "service": "wonder",
  "number": "+15551234567",
  "status": "waiting",
  "price": "0.30",
  "code": null,
  "fullMessage": null,
  "expiresAt": "2026-08-16T20:20:00.000Z",
  "createdAt": "2026-08-16T20:00:00.000Z"
}

400Unsupported service.

400 response

{
  "error": "Unsupported service"
}

402Insufficient credit balance.

402 response

{
  "error": "Insufficient balance"
}

401Missing or invalid credentials.

401 response

{
  "error": "Unauthorized"
}

503No numbers are available right now.

503 response

{
  "error": "No numbers are available for this service right now"
}

GET/api/v1/orders/{id}🔒 Requires API key

Retrieve an order

Fetches a single order by its public id. Use this to poll for the incoming code.

Path parameters

Field	Type	Required	Description
id	string	required	The public order id. · e.g. "ord_a1b2c3d4"

Request

GET /api/v1/orders/{id}

curl -X GET "https://smsmonkey.org/api/v1/orders/ord_a1b2c3d4" \
  -H "Authorization: Bearer wnd_your_key"

Responses

200The order.

200 response

{
  "id": "ord_a1b2c3d4",
  "service": "wonder",
  "number": "+15551234567",
  "status": "received",
  "price": "0.30",
  "code": "481902",
  "fullMessage": "Your verification code is 481902",
  "expiresAt": "2026-08-16T20:20:00.000Z",
  "createdAt": "2026-08-16T20:00:00.000Z"
}

401Missing or invalid credentials.

401 response

{
  "error": "Unauthorized"
}

404No such order for this account.

404 response

{
  "error": "Order not found"
}

POST/api/v1/orders/{id}/cancel🔒 Requires API key

Cancel an order

Cancels an order that has not yet received a code and refunds the charge.

Path parameters

Field	Type	Required	Description
id	string	required	The public order id. · e.g. "ord_a1b2c3d4"

Request

POST /api/v1/orders/{id}/cancel

curl -X POST "https://smsmonkey.org/api/v1/orders/ord_a1b2c3d4/cancel" \
  -H "Authorization: Bearer wnd_your_key"

Responses

200The cancelled, refunded order.

200 response

{
  "id": "ord_a1b2c3d4",
  "service": "wonder",
  "number": "+15551234567",
  "status": "cancelled",
  "price": "0.30",
  "code": null,
  "fullMessage": null,
  "expiresAt": null,
  "createdAt": "2026-08-16T20:00:00.000Z"
}

401Missing or invalid credentials.

401 response

{
  "error": "Unauthorized"
}

404No such order for this account.

404 response

{
  "error": "Order not found"
}

409A code already arrived; the order can't be refunded.

409 response

{
  "error": "This order already received a code and cannot be refunded"
}

API keys

GET/api/v1/api-keys🔒 Requires API key

List API keys

Lists your active API keys. Only a non-sensitive prefix is returned — never the full key.

Request

GET /api/v1/api-keys

curl -X GET "https://smsmonkey.org/api/v1/api-keys" \
  -H "Authorization: Bearer wnd_your_key"

Responses

200Active API keys.

200 response

{
  "apiKeys": [
    {
      "id": "b7f0…",
      "name": "Production",
      "prefix": "wnd_EdcOHmGD",
      "lastUsedAt": "2026-08-16T19:55:00.000Z",
      "createdAt": "2026-08-01T10:00:00.000Z"
    }
  ]
}

401Missing or invalid credentials.

401 response

{
  "error": "Unauthorized"
}

POST/api/v1/api-keys🔒 Requires API key

Create an API key

Creates a new API key. The full secret is returned once, in this response only.

Treat `key` like a password. If leaked, revoke it and create a new one.

Body parameters

Field	Type	Required	Description
name	string	optional	A label for the key (1–80 chars). Defaults to `API key`. · e.g. "Production"

Request

POST /api/v1/api-keys

curl -X POST "https://smsmonkey.org/api/v1/api-keys" \
  -H "Authorization: Bearer wnd_your_key" \
  -H "Content-Type: application/json" \
  -d '{"name":"Production"}'

Responses

201The created key. Store `key` now — it is never shown again.

201 response

{
  "id": "b7f0…",
  "name": "Production",
  "key": "wnd_9f3a1c…full-secret",
  "prefix": "wnd_9f3a1c"
}

401Missing or invalid credentials.

401 response

{
  "error": "Unauthorized"
}

DELETE/api/v1/api-keys/{id}🔒 Requires API key

Revoke an API key

Permanently revokes an API key. Requests using it will start returning 401.

Path parameters

Field	Type	Required	Description
id	string	required	The API key id (not the secret). · e.g. "b7f0e2a1-…"

Request

DELETE /api/v1/api-keys/{id}

curl -X DELETE "https://smsmonkey.org/api/v1/api-keys/b7f0e2a1-…" \
  -H "Authorization: Bearer wnd_your_key"

Responses

200The key was revoked.

200 response

{
  "revoked": true
}

401Missing or invalid credentials.

401 response

{
  "error": "Unauthorized"
}

404No such key for this account.

404 response

{
  "error": "API key not found"
}

Top-ups

GET/api/v1/top-ups🔒 Requires API key

List top-ups

Lists your recent crypto top-up payments, newest first (up to 25).

Request

GET /api/v1/top-ups

curl -X GET "https://smsmonkey.org/api/v1/top-ups" \
  -H "Authorization: Bearer wnd_your_key"

Responses

200Recent payments.

200 response

{
  "payments": [
    {
      "id": "pay_ZpcN53Vc",
      "amount": "25.00",
      "status": "finished",
      "checkoutUrl": "https://nowpayments.io/payment/…",
      "createdAt": "2026-08-16T18:00:00.000Z"
    }
  ]
}

401Missing or invalid credentials.

401 response

{
  "error": "Unauthorized"
}

POST/api/v1/top-ups🔒 Requires API key

Create a top-up invoice

Creates a crypto payment invoice via NOWPayments. Send the user to `checkoutUrl`; credits are added automatically once the payment is confirmed on-chain.

Body parameters

Field	Type	Required	Description
amount	number	required	USD amount to add. Minimum 5, maximum 1000. · e.g. 25
promoCode	string	optional	Optional first-deposit promo code. · e.g. "PROMO_CODE"

Request

POST /api/v1/top-ups

curl -X POST "https://smsmonkey.org/api/v1/top-ups" \
  -H "Authorization: Bearer wnd_your_key" \
  -H "Content-Type: application/json" \
  -d '{"amount":25,"promoCode":"PROMO_CODE"}'

Responses

201Invoice created.

201 response

{
  "id": "pay_ZpcN53Vc",
  "amount": "25.00",
  "checkoutUrl": "https://nowpayments.io/payment/…"
}

400Amount out of range or invalid promo code.

400 response

{
  "error": "Minimum top-up is $5.00"
}

401Missing or invalid credentials.

401 response

{
  "error": "Unauthorized"
}