Developers / API reference

BitSMS Public API v1.0.0

BitSMS is an SMS gateway operated by BitCommerz. One API, multiple upstream providers; BitSMS chooses the route, retries, fails over and reports delivery.

Authentication

Scope	Allows
`messages:send`	`POST /messages`, `POST /messages/bulk`
`messages:read`	`GET /messages`, `GET /messages/{id}`
`otp`	`POST /otp`, `POST /otp/{otp_id}/verify`
`balance:read`	`GET /balance`
`senders:read`	`GET /sender-ids`
`webhooks:write`	`/webhooks*`

bsk_test_… keys use the sandbox: nothing is delivered or charged, and the sandbox behaves deterministically by the last two digits of the number (see the developer guide).

Asynchronous sending

Idempotency

Rate limits

Numbers

Message parts and price

Money

Errors

Stability

Base URL: https://api.[DOMAIN]/v1 — Production

Base URL: http://localhost:8080/v1 — Local development (docker-compose)

Download the OpenAPI 3.1 file to generate a client or import into Postman.

Messages

get/messages

List messages

Newest first, cursor-paginated. Requires messages:read. Searches within the last 13 months.

Parameters

Name	In	Type	Description
status	query	MessageStatus
to	query	string	Destination in any accepted form.
client_ref	query	string
batch_id	query	string (uuid)
sender_id	query	string
created_from	query	string (date-time)
created_to	query	string (date-time)
limit	query	integer
cursor	query	string

Responses

200A page of messages. — object
400Malformed request (invalid JSON, missing field, bad type). — Error
401Missing, invalid, revoked or expired API key. — Error
403Key lacks a scope, IP not allowed, account not verified / suspended / closed, or sender not allowed. — Error
429Rate limit exceeded. — Error

post/messages

Send a single SMS

Validates, prices and debits the message, then queues it. Requires scope messages:send. The default class is transactional.

Parameters

Name	In	Type	Description
Idempotency-Key*	header	string	Unique per logical send. Same key + same body within 7 days returns the original result.

Request body

application/json: SendMessageRequest

Responses

202Accepted and queued. — Message
400Malformed request (invalid JSON, missing field, bad type). — Error
401Missing, invalid, revoked or expired API key. — Error
402Balance does not cover the cost (`insufficient_credit`). — Error
403Key lacks a scope, IP not allowed, account not verified / suspended / closed, or sender not allowed. — Error
409Idempotency key reused with a different body, or the same key is in flight. — Error
422Semantically invalid (bad number, text too long, unknown sender). — Error
429Rate limit exceeded. — Error
503Temporarily unable to accept (`backpressure`, `internal_unavailable`). Nothing was charged. — Error

post/messages/bulk

Send one text to many numbers

Up to 10 000 recipients per request. Valid recipients are accepted and debited in one transaction; invalid ones are listed in rejected and not charged. If the balance cannot cover all valid recipients the whole request fails with 402 insufficient_credit (nothing is sent). Default class bulk. May return 503 backpressure when the bulk queue is saturated; retry after Retry-After.

Parameters

Name	In	Type	Description
Idempotency-Key*	header	string	Unique per logical send. Same key + same body within 7 days returns the original result.

Request body

application/json: SendBulkRequest

Responses

202Batch accepted. — BulkResult
400Malformed request (invalid JSON, missing field, bad type). — Error
401Missing, invalid, revoked or expired API key. — Error
402Balance does not cover the cost (`insufficient_credit`). — Error
403Key lacks a scope, IP not allowed, account not verified / suspended / closed, or sender not allowed. — Error
409Idempotency key reused with a different body, or the same key is in flight. — Error
422Semantically invalid (bad number, text too long, unknown sender). — Error
429Rate limit exceeded. — Error
503Temporarily unable to accept (`backpressure`, `internal_unavailable`). Nothing was charged. — Error

get/messages/{id}

Get a message and its delivery status

Requires messages:read. ?include=events adds the status history.

Parameters

Name	In	Type	Description
id*	path	string (uuid)
include	query	string

Responses

200The message. — Message
401Missing, invalid, revoked or expired API key. — Error
403Key lacks a scope, IP not allowed, account not verified / suspended / closed, or sender not allowed. — Error
404Not found (or belongs to another account). — Error
429Rate limit exceeded. — Error

OTP

post/otp

Generate and send a one-time password

BitSMS generates the code, sends it with class otp (highest priority), stores only a hash, and returns an otp_id to verify against. The code is never returned. Requires scope otp.

The template must contain {{code}} once; default "Your {{app_name}} code is {{code}}. Valid for {{ttl_minutes}} minutes.".

Limits: 3 OTPs per number per 10 minutes, 10 per number per day (per tenant).

Parameters

Name	In	Type	Description
Idempotency-Key*	header	string	Unique per logical send. Same key + same body within 7 days returns the original result.

Request body

application/json: SendOtpRequest

Responses

202OTP sent (queued). — Otp
400Malformed request (invalid JSON, missing field, bad type). — Error
401Missing, invalid, revoked or expired API key. — Error
402Balance does not cover the cost (`insufficient_credit`). — Error
403Key lacks a scope, IP not allowed, account not verified / suspended / closed, or sender not allowed. — Error
409Idempotency key reused with a different body, or the same key is in flight. — Error
422Semantically invalid (bad number, text too long, unknown sender). — Error
429Rate limit exceeded. — Error

post/otp/{otp_id}/verify

Verify a code

Returns 200 {"verified": true} on success. A wrong code returns 200 with verified: false and attempts_remaining. After 5 wrong codes, or after expiry, returns 410 with otp_exhausted / otp_expired. A verified OTP cannot be verified again (410 otp_already_verified).

Parameters

Name	In	Type	Description
otp_id*	path	string (uuid)

Request body

application/json: object

Field	Type	Description
code*	string

Responses

200Verification result. — OtpVerifyResult
401Missing, invalid, revoked or expired API key. — Error
403Key lacks a scope, IP not allowed, account not verified / suspended / closed, or sender not allowed. — Error
404Not found (or belongs to another account). — Error
410OTP expired, exhausted, or already verified. — Error
429Rate limit exceeded. — Error

Account

get/balance

Current credit balance and prices

Requires balance:read.

Responses

200Balance. — Balance
401Missing, invalid, revoked or expired API key. — Error
403Key lacks a scope, IP not allowed, account not verified / suspended / closed, or sender not allowed. — Error
429Rate limit exceeded. — Error

get/sender-ids

Sender IDs this account may use

Approved masking sender IDs and the default non-masking sender. Requires senders:read. Requests for new masking IDs are made in the dashboard (documents required).

Responses

200Sender IDs. — object
401Missing, invalid, revoked or expired API key. — Error
403Key lacks a scope, IP not allowed, account not verified / suspended / closed, or sender not allowed. — Error

Webhooks

get/webhooks

List webhook endpoints

Responses

200Endpoints. — object
401Missing, invalid, revoked or expired API key. — Error
403Key lacks a scope, IP not allowed, account not verified / suspended / closed, or sender not allowed. — Error

post/webhooks

Max 5 endpoints per account. URL must be https:// and publicly resolvable (private/loopback addresses are refused). The signing secret is returned once in this response.

Request body

application/json: WebhookCreate

Responses

201Created. — WebhookWithSecret
400Malformed request (invalid JSON, missing field, bad type). — Error
401Missing, invalid, revoked or expired API key. — Error
403Key lacks a scope, IP not allowed, account not verified / suspended / closed, or sender not allowed. — Error
422Semantically invalid (bad number, text too long, unknown sender). — Error

get/webhooks/{webhook_id}

Get a webhook endpoint

Parameters

Name	In	Type	Description
webhook_id*	path	string (uuid)

Responses

200Endpoint. — Webhook
401Missing, invalid, revoked or expired API key. — Error
404Not found (or belongs to another account). — Error

patch/webhooks/{webhook_id}

Update URL, events, or re-enable

Parameters

Name	In	Type	Description
webhook_id*	path	string (uuid)

Request body

application/json: WebhookUpdate

Responses

200Updated. — Webhook
400Malformed request (invalid JSON, missing field, bad type). — Error
401Missing, invalid, revoked or expired API key. — Error
404Not found (or belongs to another account). — Error
422Semantically invalid (bad number, text too long, unknown sender). — Error

delete/webhooks/{webhook_id}

Delete an endpoint

Parameters

Name	In	Type	Description
webhook_id*	path	string (uuid)

Responses

204Deleted.
401Missing, invalid, revoked or expired API key. — Error
404Not found (or belongs to another account). — Error

post/webhooks/{webhook_id}/rotate-secret

Rotate the signing secret

The old secret stays valid for 24 hours; during that time deliveries carry two signatures.

Parameters

Name	In	Type	Description
webhook_id*	path	string (uuid)

Responses

200New secret (shown once). — WebhookWithSecret
401Missing, invalid, revoked or expired API key. — Error
404Not found (or belongs to another account). — Error

post/webhooks/{webhook_id}/test

Send a test event now

Sends a signed sample message.delivered event (event_id test_<uuid>, message_id all zeros) to the endpoint right away and returns the result. Nothing is stored or retried.

Parameters

Name	In	Type	Description
webhook_id*	path	string (uuid)

Responses

200Result of the test delivery. — WebhookDeliveryAttempt
401Missing, invalid, revoked or expired API key. — Error
404Not found (or belongs to another account). — Error
429Rate limit exceeded. — Error

post/webhooks/{webhook_id}/replay

Re-deliver events from a time range

Queues re-delivery of events created in [from, to) (max 72 hours, within the last 30 days). Events keep their original event_id.

Parameters

Name	In	Type	Description
webhook_id*	path	string (uuid)

Request body

application/json: object

Field	Type	Description
from*	string (date-time)
to*	string (date-time)
only_failed	boolean	default true

Responses

202Replay queued. — object
400Malformed request (invalid JSON, missing field, bad type). — Error
401Missing, invalid, revoked or expired API key. — Error
404Not found (or belongs to another account). — Error

Tools

post/tools/sms-count

Count characters and parts for a text

Same counting the send endpoints use. No authentication required; rate-limited per IP (60/minute). Texts over 10 parts are counted, not rejected; the send endpoints reject them with text_too_long.

No authentication.

Request body

application/json: object

Field	Type	Description
text*	string	max length 1530

Responses

200Count. — SmsCount
400Malformed request (invalid JSON, missing field, bad type). — Error
429Rate limit exceeded. — Error

Schemas

Money

Field	Type	Description
amount*	integer (int64)	Minor units (paisa).
currency*	string

MessageClass

Priority class. otp > transactional > bulk. Affects queue priority and retry policy only, not price.

One of: otptransactionalbulk

MessageStatus

Public view of the internal state machine: internal accepted/queued → queued; processing/retry_wait → sending. queued → sending → sent → delivered, or a terminal failure. Terminal: delivered, failed, failed_unknown, expired, rejected. Extensible: clients must handle unknown values as non-terminal.

One of: queuedsendingsentdeliveredfailedfailed_unknownexpiredrejected

SendMessageRequest

Field	Type	Description
to*	string	Bangladesh mobile number: 01XXXXXXXXX, 8801XXXXXXXXX or +8801XXXXXXXXX.
text*	string	Up to 10 parts (1530 GSM-7 chars / 670 Unicode). max length 1530
sender_id	string	Approved masking sender name. Omit for the default non-masking sender. max length 11
class	MessageClass
client_ref	string	Your reference; searchable and echoed in webhooks. max length 128
validity_seconds	integer	Give up if not handed to a provider within this time. default 3600 · min 60 · max 86400
metadata	object	Echoed in webhooks. Max 2 KB serialized.

SendBulkRequest

Field	Type	Description
to*	array of string	Duplicates are sent once. max 10000 items
text*	string	max length 1530
sender_id	string	max length 11
class	MessageClass
client_ref	string	max length 128
validity_seconds	integer	default 3600 · min 60 · max 86400

Message

Field	Type	Description
id*	string (uuid)
batch_id	string \| null (uuid)
to*	string
sender_id*	string
sender_type*	string	one of: "masking", "non_masking"
class*	MessageClass
text	string	Present on GET only.
status*	MessageStatus
status_reason	string \| null	Stable reason code for failures, e.g. `all_providers_failed`, `invalid_number`, `no_dlr`.
encoding*	string	one of: "gsm7", "ucs2"
characters	integer
parts*	integer	min 1 · max 10
cost*	Money
refunded	boolean
client_ref	string \| null
metadata	object \| null
provider	string \| null	Display name of the provider that carried the message.
created_at*	string (date-time)
sent_at	string \| null (date-time)
delivered_at	string \| null (date-time)
expires_at	string (date-time)
events	array of object	Only with `include=events`.

BulkResult

Field	Type	Description
batch_id*	string (uuid)
parts_per_message	integer
encoding	string	one of: "gsm7", "ucs2"
total_cost*	Money
accepted*	array of object
rejected*	array of object

SendOtpRequest

Field	Type	Description
to*	string
length	integer	default 6 · min 4 · max 8
ttl_seconds	integer	default 300 · min 60 · max 600
template	string	Must contain `{{code}}`. May use `{{app_name}}`, `{{ttl_minutes}}`. max length 300
app_name	string	max length 30
sender_id	string	max length 11
client_ref	string	max length 128

Otp

Field	Type	Description
otp_id*	string (uuid)
message_id*	string (uuid)
to*	string
expires_at*	string (date-time)
cost	Money

OtpVerifyResult

Field	Type	Description
verified*	boolean
attempts_remaining	integer

Balance

Field	Type	Description
balance*	Money
low_balance_threshold*	Money
account_status	string	one of: "trial", "active", "suspended", "closed"
prices*	object
estimated_parts_remaining	object

SenderId

Field	Type	Description
name*	string
type*	string	one of: "masking", "non_masking"
is_default*	boolean
approved_at	string \| null (date-time)

WebhookEventType

One of: message.sentmessage.deliveredmessage.failedmessage.expiredmessage.rejectedotp.verified

WebhookCreate

Field	Type	Description
url*	string (uri)
events*	array of WebhookEventType
description	string	max length 100

WebhookUpdate

Field	Type	Description
url	string (uri)
events	array of WebhookEventType
description	string	max length 100
enabled	boolean

Webhook

Field	Type	Description
id*	string (uuid)
url*	string
events*	array of WebhookEventType
description	string \| null
status*	string	one of: "active", "disabled_by_user", "disabled_failing"
secret_prefix*	string
consecutive_failures	integer
created_at*	string (date-time)

WebhookWithSecret

Includes Webhook

Field	Type	Description
secret*	string	Shown once.

WebhookDeliveryAttempt

Field	Type	Description
delivered*	boolean
http_status	integer \| null
duration_ms	integer
error	string \| null

WebhookEvent

Field	Type	Description
event_id*	string	Stable: `<message_id>:<status>`. Dedupe on it.
type*	WebhookEventType
created_at*	string (date-time)
data*	object

SmsCount

Field	Type	Description
encoding*	string	one of: "gsm7", "ucs2"
characters*	integer	GSM-7 septets (extension chars count 2) or UTF-16 code units.
parts*	integer
per_part*	integer	one of: 160, 153, 70, 67
remaining_in_part*	integer
non_gsm_characters	array of string	First characters that forced Unicode (max 10).

ErrorCode

Stable machine-readable codes. Extensible — new codes may be added.

Code	HTTP	Meaning
`invalid_request`	400	Malformed JSON / missing or wrong-typed field (`details` lists fields)
`idempotency_key_missing`	400	Send endpoint called without `Idempotency-Key`
`unauthorized`	401	Missing or invalid API key
`api_key_revoked`	401	Key revoked or expired
`insufficient_credit`	402	Balance below cost (`details.required`, `details.balance`)
`scope_missing`	403	Key lacks the scope (`details.required_scope`)
`ip_not_allowed`	403	Caller IP not in key allowlist
`account_not_verified`	403	Sign-up not completed
`account_suspended`	403	Account suspended
`account_closed`	403	Account closed
`sender_not_allowed`	403	Sender ID unknown, not approved, or disabled for this account
`not_found`	404	Resource not found
`idempotency_key_reused`	409	Same key, different body
`idempotency_in_progress`	409	Same key still being processed; retry shortly
`otp_expired`	410	OTP expired
`otp_exhausted`	410	Too many wrong codes
`otp_already_verified`	410	Already verified
`invalid_destination`	422	Not a valid Bangladesh mobile number
`recipient_opted_out`	422	Number opted out of your bulk messages
`text_too_long`	422	More than 10 parts
`text_empty`	422	Empty text
`invalid_template`	422	OTP template missing `{{code}}`
`too_many_recipients`	422	Bulk over 10 000
`webhook_url_invalid`	422	Not https or resolves to a private address
`webhook_limit_reached`	422	Max 5 endpoints
`rate_limited`	429	Key rate limit exceeded
`otp_rate_limited`	429	Too many OTPs to this number
`backpressure`	503	Bulk queue saturated; retry after `Retry-After`
`internal_unavailable`	503	Temporary internal failure; nothing charged
`internal_error`	500	Unexpected error; nothing charged unless a message id was returned

One of: invalid_requestidempotency_key_missingunauthorizedapi_key_revokedinsufficient_creditscope_missingip_not_allowedaccount_not_verifiedaccount_suspendedaccount_closedsender_not_allowednot_foundidempotency_key_reusedidempotency_in_progressotp_expiredotp_exhaustedotp_already_verifiedinvalid_destinationrecipient_opted_outtext_too_longtext_emptyinvalid_templatetoo_many_recipientswebhook_url_invalidwebhook_limit_reachedrate_limitedotp_rate_limitedbackpressureinternal_unavailableinternal_error

Error

Field	Type	Description
error*	object