SMS API

Send and receive text messages, list your numbers, and manage group texting from your server. Unlike the other APIs, the SMS API is served by sms.bodek.us directly — not the dev gateway. You create and manage keys here on SMS API keys.

Base   https://sms.bodek.us/api/v1
Auth   Authorization: Bearer bs_live_…
EndpointScopePurpose
GET /v1/health
—Service check
GET /v1/numbers
numbers:readYour usable numbers
GET /v1/numbers/{id}
numbers:readIs one number live?
POST /v1/numbers/status
numbers:readCheck several at once
POST /v1/messages
messages:sendSend to one or more numbers
GET /v1/messages
messages:readList messages
GET /v1/messages/{id}
messages:readOne message
DELETE /v1/messages/{id}
messages:sendCancel a queued message
GET /v1/media/{token}
messages:readDownload an attachment
GET /v1/groups
groups:readList groups
POST /v1/groups/{id}/messages
messages:sendBroadcast to a group
GET /v1/webhooks
webhooks:readWebhook endpoints
GET /v1/opt-outs
optouts:readWho asked you to stop
GET /v1/flows
flows:readFlows (full CRUD)
GET /v1/calls/flows
voice:readCall flows — what a caller hears

Three companion references cover the parts that are big enough to need their own page: SMS Webhooks (inbound events, opt-outs, every delivery status, signature verification), SMS Flows API (build and manage text conversations entirely over the API) and SMS Call Flows (what a caller hears: spoken menus, forwarding, voicemail and recordings).

Authentication

Send your key as a bearer token. Keys are server-side credentials — never ship one in a browser or mobile app. A revoked key, or an account whose plan no longer includes SMS, stops working immediately (401 invalid_key / 402 subscription_inactive).

Authorization: Bearer bs_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
Content-Type: application/json

A key can be bound to one number. A bound key can only send from — and only sees messages on — that number.

Revoking and deleting a key

Keys go in two stages on SMS API keys. Revoke stops a key working immediately — the next request gets 401 invalid_key — and keeps it listed so you can see what used to exist while you fix whatever was using it. Delete is then offered on a revoked key and erases it for good: the secret, the name, the permissions and the number binding, along with its idempotency records.

Deleting a key does not delete the messages it sent. Delivery history, the opt-out record and your billing records are the account's, not the key's, so they stay intact and the key's id stays resolvable if support ever has to trace old traffic. There is no API route for either action — a leaked key cannot revoke or delete itself, or erase its own trail.

Requests & responses

  • All requests and responses are JSON.
  • Every response is an envelope: {"ok": true, …} on success or {"ok": false, "error": {"code": "…", "message": "…"}} on failure.
  • Each response carries an X-Request-Id header — quote it in support requests.
  • Phone numbers are E.164 (+15551234567); US 10-digit input is accepted and normalised. A message body is up to 1,600 characters (~10 segments).
  • A send returns 202 with the queued messages. Get delivery status by webhook (recommended) or by polling GET /v1/messages/{id}.

Message ids

Every message has an opaque, unguessable id — msg_ plus 32 hex characters from a CSPRNG:

"id":  "msg_af6d1cbbb042d08e5ddeef055306fd5a"   // the secure id — use this everywhere
"seq": 48125                                     // the row number, for since_id / before_id paging

That id is what every response and every webhook payload carries, and what /v1/messages/{id} takes. It can be logged, passed between systems or quoted in a support ticket without revealing how much traffic anyone sends, and nobody can walk your history by counting. Paging cursors still use seq, because they need an ordered value. /v1/messages/{id} accepts either form, so code written against the old numeric ids keeps working.

Other ids follow the same pattern: webhook endpoints are wh_…, webhook events evt_…, API keys bs_live_… and webhook secrets whsec_…. Flows, groups and numbers keep small integer ids — they are account-scoped objects you create, not records that accumulate.

⚠ Opt-out policy

Bodek SMS will not stop sending messages because a recipient sent an opt-out message. A reply of STOP, UNSUBSCRIBE, CANCEL or any other opt-out keyword is recorded and pushed to you as a message.opt_out webhook event. It does not suppress that recipient, cancel messages already queued to them, or send them any reply. Delivery stops only if and when Bodek administration decides to stop delivery.

The company integrating with Bodek SMS is responsible for receiving these webhooks and stopping delivery. Subscribe an endpoint to message.opt_out, add the recipient to your own suppression list as soon as the event arrives, and stop sending to them.

Violation of this rule can result in suspension of the Bodek SMS service.

Set this up before you send at scale: create a webhook endpoint, then read the full policy, the keyword lists and the reconciliation endpoint in SMS Webhooks → Opt-out policy.

GET /v1/opt-outs

Scope optouts:read. The record of everyone who asked you to stop — reconcile it against your suppression list on a schedule, so an event your server missed is still caught. It blocks nothing.

Rate limits

Each key has a per-minute request limit (default 30/min; set when you create the key). Over it you get 429 rate_limited with a Retry-After header. Each key also has a per-day message limit (rolling 24 hours); a send that would pass it gets 429 daily_key_limit.

Messages can be sent to US and Canada numbers only (premium-rate and Caribbean area codes excluded). Other numbers are refused with 400 unsupported_destination.

Separately, the account has a daily send allowance. Sends past it are rejected unless the account has pay-as-you-go enabled (then they're metered up to a spending cap). See Send a message for how rejections appear (rejected/reason, or a 402 daily_limit_reached when all recipients are rejected).

Health

GET /v1/health

No scope, but a valid key is required.

curl https://sms.bodek.us/api/v1/health -H "Authorization: Bearer bs_live_…"
{ "ok": true, "service": "sms", "version": "v1", "time": "2026-09-24T00:00:00+00:00" }

List numbers

GET /v1/numbers

Scope numbers:read. The numbers you can send from: the shared sending pool (available to every account with SMS access) plus any group-dedicated number assigned to your account. A key bound to one number returns just that number.

curl https://sms.bodek.us/api/v1/numbers -H "Authorization: Bearer bs_live_…"
{
  "ok": true,
  "numbers": [
    { "id": 12, "number": "+15551234567", "display": "(555) 123-4567", "label": "Front desk",
      "online": true, "shared": true, "group": false }
  ]
}

For one number, with the reason it isn't usable when it isn't, see Is a number live?

Is a number live?

GET /v1/numbers/{id-or-number}

Scope numbers:read. Answers one question: can this number carry traffic right now? GET /v1/numbers/{id}/status is the same endpoint under a longer name.

The path takes either the number's id or the phone number itself. Because a + is awkward in a URL, all four of these ask about the same number:

curl https://sms.bodek.us/api/v1/numbers/12          -H "Authorization: Bearer bs_live_…"
curl https://sms.bodek.us/api/v1/numbers/5551234567 -H "Authorization: Bearer bs_live_…"
curl https://sms.bodek.us/api/v1/numbers/15551234567 -H "Authorization: Bearer bs_live_…"
curl -g "https://sms.bodek.us/api/v1/numbers/+15551234567" -H "Authorization: Bearer bs_live_…"
{
  "ok": true,
  "number": {
    "id": 12,
    "number": "+15551234567",
    "display": "(555) 123-4567",
    "label": "Front desk",
    "online": true,
    "shared": false,
    "group": true,
    "live": true,
    "state": "live",
    "reason": "The number is checked in and can send and receive.",
    "last_seen_at": "2026-10-26T16:49:30+00:00",
    "seconds_since_seen": 14,
    "online_window_s": 90
  }
}
FieldDescription
liveThe answer. true only when the number is active, verified, and its phone has checked in inside the online window.
stateWhy, in one word: live, offline (nothing has checked in lately), unverified (the number isn't verified yet) or inactive (the number is turned off).
reasonThe same thing in a sentence you can show a user.
onlineChecked in recently. Same as the field in List numbers.
last_seen_atLast check-in (UTC, ISO 8601), or null if it has never checked in.
seconds_since_seenAge of that check-in in seconds, or null.
online_window_sHow recent a check-in has to be to count as online (90 seconds today). Read it rather than hard-coding it.
shared, groupshared: from the common sending pool. group: dedicated to your account for group texting.

Offline is not the same as broken. A message sent to an offline number is queued, not refused, and goes out when the number checks back in — so use live to decide whether to expect an immediate send, not whether to send at all.

A number that isn't yours returns 404 not_found, and so does one that never existed — the API doesn't say which. A key bound to a single number can only ask about that number.

Check several at once

POST /v1/numbers/status

Up to 100 ids or phone numbers in one call. The answers come back in the order you asked, each with the asked value echoed so you can line them up, and found: false for anything you can't use.

curl -X POST https://sms.bodek.us/api/v1/numbers/status \
  -H "Authorization: Bearer bs_live_…" -H "Content-Type: application/json" \
  -d '{"numbers": [12, "+15551234567", "5559999999"]}'
{
  "ok": true,
  "numbers": [
    { "asked": "12", "found": true, "id": 12, "number": "+15551234567", "live": true, "state": "live", … },
    { "asked": "+15551234567", "found": true, "id": 12, "live": true, "state": "live", … },
    { "asked": "5559999999", "found": false, "live": false, "state": "unknown",
      "reason": "No number you can use matches that id or phone number." }
  ]
}

Polling every 30 seconds is plenty: a phone checks in well inside the 90-second window, and the per-minute rate limit is shared with the rest of your calls.

Send a message

POST /v1/messages

Scope messages:send.

FieldDescription
torequiredA phone number, or a list of up to 100.
bodyrequiredMessage text (up to 1,600 characters). May be "" when media is sent.
mediaoptionalUp to 5 attachments, sent as one picture message (MMS): [{"content_type": "image/jpeg", "data": "<base64>", "name": "menu.jpg"}]. Images, video, audio and vCards; up to 10 MB each before encoding. Images are shrunk to fit an MMS; video/audio must be under 1 MB.
fromoptionalA number id or E.164 to send from — any number in the shared pool or your group-dedicated number. Defaults to the pool. Ignored (forced) for a bound key.
client_refoptionalYour own reference, echoed back (≤ 80 chars).
ttloptionalSeconds the message stays queued before it expires (60–604800).
idempotency_keyoptionalSee Idempotency (or send the Idempotency-Key header).
curl -X POST https://sms.bodek.us/api/v1/messages \
  -H "Authorization: Bearer bs_live_…" \
  -H "Content-Type: application/json" \
  -d '{
    "to": "+15551234567",
    "body": "Your table is ready!",
    "client_ref": "order-8412"
  }'

Returns 202:

{
  "ok": true,
  "messages": [
    { "id": 5567, "direction": "out", "phone": "+15551234567", "status": "queued",
      "segments": 1, "client_ref": "order-8412", "created_at": "2026-09-24T00:00:00+00:00" }
  ]
}

Sending to a list of to numbers queues one message per distinct number.

Billing limits. If the account is over its daily send allowance and pay-as-you-go is off, recipients are rejected. When some go through and some don't, the response is still 202 but adds rejected (a count), reason (limit_reached, metered_cap_reached, number_limit_reached or paused) and a human message. If every recipient is rejected, the call returns 402 daily_limit_reached with the reason — enable pay-as-you-go to send beyond the daily allowance.

Pictures & attachments

Messages carry a media list (empty for plain texts). Received pictures appear on incoming messages the same way.

"media": [
  { "id": 88, "type": "image/jpeg", "size": 184220, "width": 1280, "height": 960,
    "name": "menu.jpg", "url": "https://sms.bodek.us/api/v1/media/3f9c…" }
]
GET /v1/media/{token}

Scope messages:read. Downloads the file with the same Bearer key. Add ?download=1 to force a file download. Attachments are kept for 180 days.

Idempotency

To make a send safe to retry, set an Idempotency-Key header (or an idempotency_key field), up to 80 characters. A repeat within 24 hours with the same key returns the same messages instead of sending again — so a network timeout and retry never double-texts a customer.

curl -X POST https://sms.bodek.us/api/v1/messages \
  -H "Authorization: Bearer bs_live_…" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: order-8412-confirm" \
  -d '{ "to": "+15551234567", "body": "Your table is ready!" }'

List messages

GET /v1/messages

Scope messages:read. Query parameters: direction (in/out), status, phone, number_id, group_id, source, client_ref, purpose, read=1, created_after, created_before, sent_after, sent_before (ISO-8601 or unix seconds), since_id, before_id, limit (default 50, max 200).

Everything a platform needs to reconcile its traffic — both numbers, the text, the segment count, which key sent it and every timestamp — is on each message. See Pulling message details for the full field list and worked queries.

curl "https://sms.bodek.us/api/v1/messages?direction=in&limit=20" \
  -H "Authorization: Bearer bs_live_…"
{ "ok": true, "messages": [ … ], "next_before_id": 5540 }

Page backwards with before_id, or poll new messages with since_id. Both take the seq value, not the msg_… id.

Get a message

GET /v1/messages/{id}

Scope messages:read. Takes the msg_… id or the row id. Delivery goes queued → sending → sent → delivered, or ends in failed, expired or cancelled; read_at is filled in when the handset returns a read report (MMS/RCS only — plain SMS has none).

curl https://sms.bodek.us/api/v1/messages/msg_af6d1cbbb042d08e5ddeef055306fd5a   -H "Authorization: Bearer bs_live_…"
{ "ok": true, "message": {
  "id": "msg_af6d1cbbb042d08e5ddeef055306fd5a", "seq": 5567,
  "direction": "out", "from": "+15551230000", "to": "+15557654321", "number_id": 12,
  "body": "Your table is ready!", "status": "delivered", "source": "api",
  "segments": 1, "attempts": 1, "client_ref": "order-8412", "api_key_id": 31, "error": null,
  "created_at": "…", "sent_at": "…", "delivered_at": "…", "read_at": null, "expires_at": "…",
  "media": [],
  "delivery": { "state": "delivered", "terminal": true, "read": false, "bounced": false }
} }

Prefer webhooks to polling. Every one of these transitions — including bounced for a permanent rejection and read for a read receipt — is pushed to you as it happens; see Delivery status events.

GET /v1/messages/{id}/events

Scope webhooks:read. Every webhook event we raised about this message, to which endpoint, with the payload sent and the response we got — the delivery audit trail for one send.

Cancel a message

DELETE /v1/messages/{id}

Scope messages:send. Cancels a message that is still queued; once it's handed to a phone it can't be recalled (409 not_cancellable).

curl -X DELETE https://sms.bodek.us/api/v1/messages/5567 -H "Authorization: Bearer bs_live_…"

Webhooks & events

Instead of polling, let Bodek SMS push to you. An endpoint is a URL of yours plus a subscription list; every payload is signed with that endpoint's secret.

curl -X POST https://sms.bodek.us/api/v1/webhooks \
  -H "Authorization: Bearer bs_live_…" -H "Content-Type: application/json" \
  -d '{
    "name": "Production listener",
    "url": "https://your.app/hooks/bodek-sms",
    "events": ["message.received", "message.opt_out", "message.delivered", "message.bounced"]
  }'
FamilyEvents
Inboundmessage.received, message.opt_out, message.opt_in, message.help, message.keyword
Delivery statusmessage.queued, message.sending, message.sent, message.delivered, message.read, message.failed, message.bounced, message.expired, message.cancelled
Flowsflow.run.started, flow.run.step, flow.run.input, flow.run.completed, flow.run.expired, flow.run.stopped, flow.run.error, flow.updated

Subscribe to exact names or to a family (message.*, flow.*, *) — so an endpoint can receive opt-outs only and nothing else. Each endpoint can also replace the opt-out / opt-in / help keyword lists with its own. GET /v1/webhooks/events returns the catalogue at run time.

Everything else — the payload envelope, signature verification in PHP/Node/Python, per-endpoint keyword lists, the retry schedule, the delivery log and the full opt-out policy — is in SMS Webhooks. Manage endpoints in the console at SMS webhooks.

Groups

A group lives on one number; a text from a member is forwarded to the others. Read your groups with groups:read, broadcast with messages:send, and (optionally) manage them with groups:write.

Groups need a dedicated number. Unlike one-off sends (which use the shared pool), a group must be hosted on a number specifically assigned to your account. Creating a group on a shared/pool number is rejected — request a dedicated number first.

GET /v1/groups
GET /v1/groups/{id}
POST /v1/groups/{id}/messages
# One message to everyone in the group:
curl -X POST https://sms.bodek.us/api/v1/groups/7/messages \
  -H "Authorization: Bearer bs_live_…" \
  -H "Content-Type: application/json" \
  -d '{ "body": "Practice is cancelled tonight." }'

With groups:write you can also create groups and manage members:

POST /v1/groups
POST /v1/groups/{id}/members
DELETE /v1/groups/{id}/members/{member_id}
curl -X POST https://sms.bodek.us/api/v1/groups \
  -H "Authorization: Bearer bs_live_…" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "U12 Team",
    "number_id": 12,
    "members": [ { "name": "Coach", "phone": "+15551230001", "admin": true } ]
  }'

Calls

Each number is a real phone. When someone calls it, the phone applies your call rules (set on sms.bodek.us → Calls): let it ring, forward it to your number, send it to voicemail, or hang up — by caller and time of day. Any of these can also text back by starting your missed-call flow. The phone can't talk or listen on a call; menus happen by text.

GET /v1/calls

Query: number_id, limit (≤ 200), before_id (paging). Needs calls:read.

{"ok": true, "calls": [{
  "id": 81, "number_id": 12, "number": "+15551230000", "direction": "in",
  "caller": "+15557654321", "hidden": false,
  "outcome": "declined",          // missed | declined (forwarded / voicemail) | hung_up | answered | silenced | placed | failed
  "action": "decline", "rule_id": "r_3f9a01bc", "text_back": true, "duration_s": 0,
  "flow_session_id": 431,         // the text-back run, if one started
  "started_at": "2026-09-25T14:03:11+00:00", "ended_at": "2026-09-25T14:03:11+00:00"
}]}

Flows (text menus)

A flow is a text conversation on one of your numbers: menus, questions, API calls mid-chat, branches, staff alerts. It starts on a missed call, a keyword, any text, or from the API, and it can be built and managed entirely over the API — same format and same validator as the editor on sms.bodek.us. Flows need a number dedicated to your account.

GET /v1/flows
POST /v1/flows
GET /v1/flows/{id}
PATCH /v1/flows/{id}
POST /v1/flows/{id}/activate
POST /v1/flows/{id}/start
GET /v1/flows/runs/{id}
# Text a flow to someone now (e.g. an appointment confirmation menu):
curl -X POST https://sms.bodek.us/api/v1/flows/5/start \
  -H "Authorization: Bearer bs_live_…" \
  -H "Content-Type: application/json" \
  -d '{ "to": "+15557654321", "vars": { "name": "Ann", "appt": "Tue 3pm" } }'

→ 202 {"ok": true, "run": {"id": 431, "flow_id": 5, "to": "+15557654321", "status": "active"}}

# Later: where is the conversation and what did they answer?
curl https://sms.bodek.us/api/v1/flows/runs/431 -H "Authorization: Bearer bs_live_…"
→ {"ok": true, "run": {"id": 431, "status": "done", "waiting_on_step": null,
    "vars": {"name": "Ann", "appt": "Tue 3pm", "confirm": "yes"}, …}}

vars become {{name}} values in the flow's messages. Run status: active (waiting for a reply), done, expired, stopped, error. Needs flows:read / flows:run, and flows:write to build or change one. Flow texts count toward your daily message allowance like any send.

The full reference — the definition format, every step type, validation, activation rules, runs, API steps and limits — is in SMS Flows API.

No keyword is reserved for opt-outs, and a flow does not stop for anyone who replies STOP: see the opt-out policy.

Flows are text conversations. To control what a caller hears — answer the call, speak a keypad menu, forward it, take a voicemail — see SMS Call Flows. Every answered call there opens with a recording announcement that cannot be switched off.

System send (Bodek internal)

Bodek's own apps send 2FA codes and account notices through a separate, internal path (POST /v1/system/send) authenticated by a shared server secret, not an API key. It isn't available to customer keys. In-process callers use the Bodek\Sms\Internal class instead. This is documented for completeness only.

Scopes

messages:sendSend messages and cancel queued ones.
messages:readRead messages and delivery status.
numbers:readList your numbers and check whether one is live.
groups:readRead groups and members.
groups:writeCreate and change groups.
calls:readRead the call log.
flows:readList flows and read their runs.
flows:runStart a flow for a number.
flows:writeCreate, change, activate and delete flows; stop runs.
webhooks:readList webhook endpoints and their delivery log, and read a message's events.
webhooks:writeCreate, change and delete webhook endpoints; send tests and retry deliveries.
optouts:readRead the opt-out record for your numbers.

Choose scopes when you create a key. A call without the needed scope fails with 403 insufficient_scope.

Permissions can be changed after a key exists. Open Change permissions on the key at SMS API keys, tick what it should be allowed to do, and save. The secret itself never changes — the same bs_live_… token keeps working, so widening or narrowing an integration doesn't mean issuing a new key and redeploying. The new permissions apply from that key's next request; nothing is cached. (The key is still only ever shown once, at creation — that part can't be undone.) A revoked key can't be re-permissioned; create a new one.

This is deliberately console-only: there is no API route for changing permissions, so a key that leaks can never widen what it is allowed to do.

Errors

Every error is {"ok": false, "error": {"code": "…", "message": "…"}}.

StatusCodeMeaning
400invalid_number, invalid_body, invalid_vars, invalid_media, unsupported_destination, bad_requestThe request didn't validate (unsupported_destination: only US/Canada numbers can be texted).
401unauthorized, invalid_keyMissing, wrong, or revoked key.
402subscription_inactive, daily_limit_reachedPlan doesn't include SMS, or all recipients were over the send allowance (with a reason).
403insufficient_scopeThe key lacks the required permission.
404not_foundNo such message, group, number, or route. A number you can't use is also 404.
409not_cancellable, no_number, group_inactive, flow_inactive, flow_not_activatable, run_not_active, group_member, too_many_webhooks, not_retryableValid request, wrong state.
400invalid_url, invalid_eventsA webhook endpoint's URL is not an https address we will connect to, or its event list is empty/unknown. See Webhooks → Security.
429rate_limited, daily_key_limitPer-minute request limit or the key's per-day message limit; see Retry-After.