API reference

Developer Reference

The complete HTTP API for sending SMS, managing groups and looking up numbers. This page documents all 19 endpoints and 20 operations, with every parameter and every response field.

Version
3.2
OpenAPI
3.0.3
Base URL
https://sms.world-text.com/v2.0

Specification reviewed 2026-10-20. It is generated into this page at build time from the published OpenAPI document .

Contents

Introduction

The World Text REST API can query account and number information, manage groups, and send SMS text messages.

This document describes the v2.0 HTTP API served by wthttpgw. It was corrected against the gateway source rather than the prose documentation; see api/CHANGES.md for the full list of corrections, each with a file:line reference into wthttpgw.

Base URL

https://sms.world-text.com/v2.0/

Plain HTTP (http://) is accepted by the gateway for compatibility, but should not be used: credentials travel in the request, and browser and mobile clients increasingly block it.

Authentication

Every request must carry an API token in the request header:

Authorization: Bearer <token>

A token is an opaque string issued from the admin console or the customer portal, and is displayed once, at creation. It is verified server-side against a SHA-256 digest; the token itself is not stored anywhere.

Interfaces

A token names the interfaces it may be used on. It is not a list of operations: a credential that can reach an interface can use all of it, and can send messages, because that is what a token is issued for.

Interface Where the credential may be used
http this HTTP API
email email to SMS, one message per email
bulk the bulk email mailbox, one email for many messages

A token may carry more than one. A token presented at an interface it does not carry is rejected with 403, whatever the operation. Empty grants nothing.

There are no finer permissions by operation or by area. Reading is free and harmless, so there was nothing worth gating; the boundary that matters is where a credential can be spent. The one exception is worth stating plainly: the HLR lookups below are charged, and an http token can call them without ever sending a message. Issue separate tokens per system and revoke them individually if that matters.

New interfaces are added over time without changing the token format. An unknown name is rejected at creation rather than stored and ignored.

Rejections

A missing or malformed header is rejected with 400; an unknown, expired or revoked token with 401; a valid token that does not carry the interface it was presented at with 403. All three use the standard error envelope:

{"status":"1","error":"1000","desc":"[RFC6750] The access token is invalid or expired"}

These responses never disclose whether a given token identifier exists.

Transport

Send the header over HTTPS only. The token is a bearer credential: anyone who observes it can use it.

Response envelope

Every response is JSON (or XML/JSONP, see Response formats) with an HTTP status code that reflects the outcome.

  • Success responses carry "status": "0".
  • Error responses carry "status", "error" (numeric error code, as a string) and "desc" (human readable message).

status is a stringified integer: "0" success, "1" permanent failure, "2"/"3" temporary failure. Numeric fields such as credits, msgid counts and state are stringified for historical reasons; clients should parse them rather than compare them as numbers.

Response formats

  • &jsonp=<callback> wraps the JSON body as <callback>(...);
  • &xml=true returns <result>...</result> instead

These are supported for every operation but are not described per operation below.

HTTP method overloading

Every context reads a method query parameter and uses it in place of the HTTP verb when present, but whether the override is honoured depends on the context, and this differs between contexts in the same deployment. Observed on 2026-10-18 against sms2.world-text.com:

Request Result Override applied?
GET /group/contents?method=DELETE 1302 group not found yes
GET /sms/send?txt=x 1201 Unknown Command no
PUT /sms/send?txt=x 1200 Incorrect arguments n/a (verb matched)

Treat the override as unreliable: verify it per operation before relying on it. Where it does apply, a plain GET with method=DELETE will delete, which makes destructive operations reachable by link prefetchers and crawlers. Use real verbs.

Submission rate

Clients should submit no more than 10 messages per second. Accounts that exceed this may be throttled or suspended. There is currently no machine-readable rate-limit header, so avoid tight retry loops.

Simulation

&sim runs an operation without sending. In the v2 API, presence of the parameter is enough: sim=false still simulates. (The v3 JSON API checks the literal string "true".) Simulation is useful on sms/send, group/send, hlr/lookup and hlr/mnp.

Delivery receipts

Delivery receipts are POSTed to a URL configured on your account, when a message reaches a final state. They are not modelled as an OpenAPI callback because the URL is configured out of band; the fields are documented in components/schemas/DeliveryReceipt.

Receipt fields: msgid, error, state (ACCEPTD, DELIVRD, EXPIRED, REJECTD, UNDELIV), date (yymmddhhmm), plus clientref and e212 when enabled on the account.

Do not poll sms/query for delivery status: that operation is deprecated.

Not covered by this document

  • The v1 root API (/credits, /sendsms, /grouplist, ...).
  • The v3 JSON-body API under /v3.0/.
  • Inbound (MO) SMS and the email API (/v2.0/email).

Authentication schemes

Scheme Type Status Detail
bearerAuth http (bearer) Live

An opaque World Text API token, sent as Authorization: Bearer <token> over TLS. Tokens are issued from the admin console or the customer portal and are displayed once, at creation. A token carries one or more of four permissions: sms, groups, admin and hlr. They are independent: a token holding sms cannot reach a groups, admin or HLR operation. Each operation below names the permission it requires. An unknown, expired or revoked token is rejected with 401. A token that is valid but lacks the required permission is rejected with 403 and a WWW-Authenticate header describing the missing scope.

Admin

Account credits and liveness checks.

GET /admin/credits #getCredits

Credits on Account

Prepay accounts: credits currently available. Account customers: the number of credits used this period, expressed as a negative balance.

Responses

Status Description Body schema
200 Current credit balance. CreditsResponse
400 Incorrect arguments (`1200`). Error
401 Authentication failure (`1000`). The gateway does not send a `WWW-Authenticate` challenge header. Error
GET /admin/ping #ping

Ping SMSC

Check that the gateway is alive and the credentials are valid.

Responses

Status Description Body schema
200 Gateway reachable. StatusResponse
400 Incorrect arguments (`1200`). Error
401 Authentication failure (`1000`). The gateway does not send a `WWW-Authenticate` challenge header. Error
GET /admin/details #getDetails

Account details

The account the credential belongs to.

Useful where one customer has several accounts and needs to confirm which one a token was issued against. Costs nothing and sends nothing.

Responses

Status Description Body schema
200 Account details. AccountDetailsResponse
400 Incorrect arguments (`1200`). Error
401 Authentication failure (`1000`). The gateway does not send a `WWW-Authenticate` challenge header. Error

Lookup Services

HLR and mobile number portability lookups.

GET /hlr/lookup #lookupHlr

HLR Lookup

HLR (Home Location Register) lookup of a mobile number: validity, state, IMSI and, with extended, the network details the gateway already holds.

The account must be enabled for HLR lookups. Lookups are charged.

Parameters

Name In Type Required Description
msisdn query string Yes

Mobile number in E.164 format without the leading +, e.g. 447989123456.
sim query boolean No

Simulate. In v2, the mere presence of this parameter simulates; the value is ignored, so sim=false also simulates.
extended query boolean No

Include mcc, mnc, cc, country, network, prefix and ported in the response.

Responses

Status Description Body schema
200 HLR result, or an error envelope for lookup failures. HlrResult
400 Incorrect arguments (`1200`). Error
401 Authentication failure *and* billing/provisioning failures. The gateway reuses 401 for insufficient funds (`1100`) and service not provisioned (`1203`); inspect `error` to tell them apart. Error
GET /hlr/mnp #lookupMnp

MNP Lookup

Mobile Number Portability lookup: validity, home network, and whether the number is ported. Where a country does not permit portability data, prefix-derived network information is returned instead.

The account must be enabled for MNP lookups. Lookups are charged.

Parameters

Name In Type Required Description
msisdn query string Yes

Mobile number in E.164 format without the leading +, e.g. 447989123456.
sim query boolean No

Simulate. In v2, the mere presence of this parameter simulates; the value is ignored, so sim=false also simulates.

Responses

Status Description Body schema
200 MNP result, or an error envelope for lookup failures. MnpResult
400 Incorrect arguments (`1200`). Error
401 Authentication failure, insufficient funds (`1100`) or service not provisioned (`1203`). Error
GET /hlr/info #getNumberInfo

Number Information

Return information the gateway already holds for a number (country, network, mcc/mnc, credits). Does not perform an HLR query. Charged as an HLR lookup.

Parameters

Name In Type Required Description
msisdn query string Yes

Mobile number in E.164 format without the leading +, e.g. 447989123456.

Responses

Status Description Body schema
200 Number information, or error 1400 if nothing is known. NumberInfo
400 Incorrect arguments (`1200`). Error
401 Authentication failure or insufficient funds (`1100`). Error

SMS

Send and cost-check individual messages.

GET /sms/cost #getSmsCost

Cost To Send SMS

Credits a single message to this destination would cost. If the cost cannot be determined the gateway falls back to a fixed default.

Parameters

Name In Type Required Description
dstaddr query string Yes

Destination number in E.164 format without the leading +, e.g. 447989123456.

Responses

Status Description Body schema
200 Cost to send. CostResponse
400 Incorrect arguments (`1200`). Error
401 Authentication failure or service not provisioned (`1203`). Error
PUT /sms/send #sendSms

Send SMS

Submit one message to one destination. POST is accepted as an alias for PUT.

Text messages. Supply txt. Encoding defaults to GSM 7-bit; set enc to UCS2 or LATIN1 for other character sets, or to any other value to pass it through untouched.

Binary messages. Supply data (hex encoded) and dcs (data coding scheme, 2 for 8-bit binary) instead of txt.

The response always contains a message array, even for a single destination.

Parameters

Name In Type Required Description
dstaddr query string Yes

Destination number in E.164 format without the leading +, e.g. 447989123456.
txt query string No

Message text. Optional at the protocol level, but a message with neither txt nor data is rejected with 1200.
clientref query string No

Your reference, echoed in the delivery receipt. Maximum 32 characters.
sendid query string No

Your reporting reference, maximum 32 characters.
idempotency query string No

Deduplication key. Re-submitting the same sendid/idempotency key is rejected with 1205 (Duplicate Send ID used).
data query string No

Hex encoded binary payload. Takes the place of txt.
dcs query string No

Data Coding Scheme. 2 for 8-bit binary.
enc query string No

GSM, LATIN1 or UCS2. Any other value is passed through.
multipart query integer No

Maximum number of parts to concatenate, up to 9. If omitted, the account default is used (1 unless configured otherwise). Text beyond the limit is discarded without error.
delay query integer No

Delay before submission, in seconds. Maximum 60. Delayed messages do not survive an SMSC restart.
expiry query integer No

Validity period in seconds. Default is 48 hours. Do not exceed 7 days (604800).
srcaddr query string No

Source address: a number you hold (up to 16 digits), an alphanumeric sender (up to 11 characters, A-Z a-z 0-9), or a short code. Defaults to the account default.
callback query string (uri) No

Per-message delivery receipt URL. Overrides the account default.
pid query integer No

Protocol identifier.
esm query integer No

Élément SM (ESM) class. 64 typically indicates multipart.
silent query boolean No

Mark the message silent where the destination supports it.
cluster query string No

Force routing to a named cluster.
deviceid query string No

Device identifier for device-bound routing.
sim query boolean No

Simulate. In v2, the mere presence of this parameter simulates; the value is ignored, so sim=false also simulates.

Request body (optional)

application/x-www-form-urlencoded · schema SendSmsParameters

Parameters may be sent as a query string or as an application/x-www-form-urlencoded body; both are read.

Field Type Notes
dstaddr string
txt string
data string
dcs string
enc string
srcaddr string
clientref string
sendid string
multipart integer

Responses

Status Description Body schema
200 Submission accepted. Check each message's `state`. SendResponse
400 Missing destination (`1200`), unknown path (`1201`), or bad request (`1202`). Error
401 Authentication failure (`1000`). The gateway does not send a `WWW-Authenticate` challenge header. Error
403 Account disabled (`1025`), insufficient funds (`1100`), service not provisioned (`1203`), or destination outside the account's permitted profile (`1304`). Error
GET /sms/query Deprecated #querySmsStatus

Query SMS Status (deprecated)

Returns the gateway's internal delivery state for a message.

Deprecated. Delivery receipts should be consumed from the callback URL instead. The response is a raw state dump: state is a numeric SMSC status code (not the DELIVRD vocabulary used in receipts), and the date field is finaldate, not date.

Parameters

Name In Type Required Description
msgid query string Yes

Message ID returned by sendSms.

Responses

Status Description Body schema
200 Message state. SmsQueryResponse
400 Incorrect arguments (`1200`). Error
401 Authentication failure (`1000`). The gateway does not send a `WWW-Authenticate` challenge header. Error

SMS To Group

Create, populate and send to groups.

GET /group/cost #getGroupCost

Cost to Send SMS to a Group

Total credits to send one message to every number in the group. Only meaningful for groups whose members are in the same country; unknown routes are costed at a fixed default.

Parameters

Name In Type Required Description
grpid query integer (int64) Yes

Group identifier, as returned by createGroup.
multipart query integer No

Parts per message to cost for. Defaults to 1.
nosql query boolean No

Read or write groups from the NoSQL store instead of MySQL. Presence of the parameter enables it.

Responses

Status Description Body schema
200 Total cost and group size. GroupCostResponse
400 Incorrect arguments (`1200`). Error
401 Authentication failure or service not provisioned (`1203`). Error
PUT /group/create #createGroup

Create a Group

Create a group. POST is accepted as an alias for PUT. Group names must be 1–32 characters; a duplicate name returns 1300.

Parameters

Name In Type Required Description
name query string No

Group name, 1–32 characters. Must not contain spaces.
srcaddr query string No

Default source address for group sends. Optional; an empty value is stored.
pin query string No

PIN protecting the group (used for remote dispatch). Optional. String, because PINs may begin with zero.
nosql query boolean No

Read or write groups from the NoSQL store instead of MySQL. Presence of the parameter enables it.

Responses

Status Description Body schema
200 Group created. CreateGroupResponse
400 Missing name (`1200`), name length invalid (`1303`), group already exists (`1300`), or unknown error (`1900`). Error
401 Authentication failure (`1000`). The gateway does not send a `WWW-Authenticate` challenge header. Error
DELETE /group/destroy #deleteGroup

Destroy (remove) a Group

Remove an existing group. Returns 1302 if not found.

Parameters

Name In Type Required Description
grpid query integer (int64) Yes

Group identifier, as returned by createGroup.
nosql query boolean No

Read or write groups from the NoSQL store instead of MySQL. Presence of the parameter enables it.

Responses

Status Description Body schema
200 Group removed. StatusResponse
400 Missing argument (`1200`) or group not found (`1302`). Error
401 Authentication failure (`1000`). The gateway does not send a `WWW-Authenticate` challenge header. Error
PUT /group/entry #addGroupEntry

Add a single entry to a group

Parameters

Name In Type Required Description
grpid query integer (int64) Yes

Group identifier, as returned by createGroup.
dstaddr query string Yes

Destination number in E.164 format without the leading +, e.g. 447989123456.
name query string No

Display name for the entry. Optional.
nosql query boolean No

Read or write groups from the NoSQL store instead of MySQL. Presence of the parameter enables it.

Responses

Status Description Body schema
200 Entry added. StatusResponse
400 Missing argument (`1200`) or group not found (`1302`). Error
401 Authentication failure (`1000`). The gateway does not send a `WWW-Authenticate` challenge header. Error
DELETE /group/entry #deleteGroupEntry

Delete a single entry from a group

Parameters

Name In Type Required Description
grpid query integer (int64) Yes

Group identifier, as returned by createGroup.
dstaddr query string Yes

Destination number in E.164 format without the leading +, e.g. 447989123456.
nosql query boolean No

Read or write groups from the NoSQL store instead of MySQL. Presence of the parameter enables it.

Responses

Status Description Body schema
200 Entry removed. StatusResponse
400 Missing argument (`1200`) or group not found (`1302`). Error
401 Authentication failure (`1000`). The gateway does not send a `WWW-Authenticate` challenge header. Error
PUT /group/entries #addGroupEntries

Add entries to a group

Add several number:name pairs at once. The list is comma separated: 447989000001:Alice,447989000002:Bob. Entries that do not contain exactly one colon are silently skipped and counted as failed.

This encoding cannot represent names containing : or ,. Use one group/entry call per member if your names may contain those characters.

Parameters

Name In Type Required Description
grpid query integer (int64) Yes

Group identifier, as returned by createGroup.
members query string No

number:name,number:name,...
nosql query boolean No

Read or write groups from the NoSQL store instead of MySQL. Presence of the parameter enables it.

Responses

Status Description Body schema
200 Counts of entries added and failed. AddEntriesResponse
400 Missing argument (`1200`) or group not found (`1302`). Error
401 Authentication failure (`1000`). The gateway does not send a `WWW-Authenticate` challenge header. Error
GET /group/numbers #getGroupNumbers

Numbers in a group

Parameters

Name In Type Required Description
grpid query integer (int64) Yes

Group identifier, as returned by createGroup.
nosql query boolean No

Read or write groups from the NoSQL store instead of MySQL. Presence of the parameter enables it.

Responses

Status Description Body schema
200 Every number in the group. GroupNumbersResponse
400 Missing argument (`1200`) or group not found (`1302`). Error
401 Authentication failure (`1000`). The gateway does not send a `WWW-Authenticate` challenge header. Error
GET /group/details #getGroupDetails

Group details

Parameters

Name In Type Required Description
grpid query integer (int64) Yes

Group identifier, as returned by createGroup.
nosql query boolean No

Read or write groups from the NoSQL store instead of MySQL. Presence of the parameter enables it.

Responses

Status Description Body schema
200 Name, number and email for each member. GroupDetailsResponse
400 Missing argument (`1200`) or group not found (`1302`). Error
401 Authentication failure (`1000`). The gateway does not send a `WWW-Authenticate` challenge header. Error
GET /group/list #listGroups

List groups

Parameters

Name In Type Required Description
nosql query boolean No

Read or write groups from the NoSQL store instead of MySQL. Presence of the parameter enables it.

Responses

Status Description Body schema
200 All groups on the account. GroupListResponse
400 Incorrect arguments (`1200`). Error
401 Authentication failure (`1000`). The gateway does not send a `WWW-Authenticate` challenge header. Error
DELETE /group/contents #deleteGroupContents

Delete all entries in a group

Removes every member from the group but keeps the group.

Parameters

Name In Type Required Description
grpid query integer (int64) Yes

Group identifier, as returned by createGroup.
nosql query boolean No

Read or write groups from the NoSQL store instead of MySQL. Presence of the parameter enables it.

Responses

Status Description Body schema
200 Rows deleted. DeleteContentsResponse
400 Missing argument (`1200`) or group not found (`1302`). Error
401 Authentication failure (`1000`). The gateway does not send a `WWW-Authenticate` challenge header. Error
PUT /group/send #sendGroupSms

Send SMS to a group

Send one message to every member of a group. POST is accepted as an alias for PUT.

Supply txt, or template with the numeric id of a stored template. If both are given, the template wins. subs=true replaces {{time}} (GMT) and {{date}} (UK) in the text.

Response contains one message entry per recipient.

Parameters

Name In Type Required Description
grpid query integer (int64) Yes

Group identifier, as returned by createGroup.
txt query string No

Message text. Required unless template is given.
template query integer No

Numeric id of a stored template. When present, overrides txt.
subs query boolean No

Substitute {{time}} and {{date}} tags in the text.
srcaddr query string No

Source address. Defaults to the group's or account's.
clientref query string No

Your reference, echoed on every receipt. All messages in the send share it.
sendid query string No

Your reporting reference, maximum 32 characters.
enc query string No

GSM, LATIN1 or UCS2.
multipart query string No

Maximum parts per message. Accepts an integer, or the strings true (meaning 3) / false (meaning 1).
repeats query integer No

Schedule the send to repeat this many times after the first submission.
rdelay query integer No

Interval between repeats in seconds. Defaults to 20.
callback query string (uri) No

Per-send delivery receipt URL.
sim query boolean No

Simulate. In v2, the mere presence of this parameter simulates; the value is ignored, so sim=false also simulates.
nosql query boolean No

Read or write groups from the NoSQL store instead of MySQL. Presence of the parameter enables it.

Responses

Status Description Body schema
200 Submission accepted; one entry per recipient. SendResponse
400 Missing group, or neither `txt` nor `template` (`1200`). Error
401 Authentication failure (`1000`). The gateway does not send a `WWW-Authenticate` challenge header. Error
403 Account disabled (`1025`), insufficient funds (`1100`), service not provisioned (`1203`) or restricted profile (`1304`). Error

Shared parameters

These parameters are defined once in the specification and reused across operations. Any operation listing one by name uses this definition.

Name In Type Required Description
msisdn query string Yes

Mobile number in E.164 format without the leading +, e.g. 447989123456.
dstaddr query string Yes

Destination number in E.164 format without the leading +, e.g. 447989123456.
grpid query integer (int64) Yes

Group identifier, as returned by createGroup.
nosql query boolean No

Read or write groups from the NoSQL store instead of MySQL. Presence of the parameter enables it.
sim query boolean No

Simulate. In v2, the mere presence of this parameter simulates; the value is ignored, so sim=false also simulates.

Response schemas

The complete set of objects this API returns, generated from the specification's component schemas. Every field below is published, including nested objects.

Error

Error envelope returned for every non-2xx response.

Field Type Required Description
status string one of "0", "1", "2", "3" Yes

"1" permanent failure, "2" or "3" temporary failure (may be retried).
error string one of "1000", "1025", "1100", "1200", "1201", "1202", "1203", "1204", "1205", "1300", "1301", "1302", "1303", "1304", "1400", "1900" Yes

Numeric error code, as a string.

  • 1000 authorisation failure
  • 1025 account disabled / not activated
  • 1100 insufficient funds
  • 1200 incorrect arguments
  • 1201 unknown command
  • 1202 bad request
  • 1203 service not provisioned
  • 1204 not implemented
  • 1205 duplicate send id (idempotency)
  • 1300 group name already exists
  • 1301 group is empty
  • 1302 group does not exist
  • 1303 group name length invalid
  • 1304 delivery restricted to profile
  • 1400 no information for the MSISDN
  • 1900 unknown error
desc string Yes

StatusResponse

Bare success envelope.

Field Type Required Description
status StatusValue Yes

'0' on success.

CreditsResponse

Field Type Required Description
status StatusValue Yes

'0' on success.
credits string Yes

Credit balance (or negative usage for account customers).

CostResponse

Field Type Required Description
status StatusValue Yes

'0' on success.
credits string Yes

Credits required to send to this destination.

AccountDetailsResponse

Field Type Required Description
status StatusValue Yes

'0' on success.
accountid string Yes

The account the credential belongs to. Returned as a string, like every other number in this API, so it survives a JSON round trip without being coerced to a float.

SendResponse

Submission result. message is always present on success, even for a single destination. A failed submission returns an Error envelope instead.

Field Type Required Description
status StatusValue Yes

'0' on success.
message array of SentMessage Yes
message.state string Yes

SMSC submission status as a stringified integer. "0" is accepted.
message.dstaddr string Yes
message.msgid string Yes
message.credits string Yes

Credits charged (may be decimal).

SentMessage

Field Type Required Description
state string Yes

SMSC submission status as a stringified integer. "0" is accepted.
dstaddr string Yes
msgid string Yes
credits string Yes

Credits charged (may be decimal).

SmsQueryResponse

Field Type Required Description
status StatusValue Yes

'0' on success.
state string Yes

Numeric SMSC status code as a string: 2 delivered, 3 expired, 5 undeliverable, 8 rejected, 9 pending/unknown.
error string Yes
finaldate string Yes

Final-state timestamp. yymmddhhmm format.

GroupCostResponse

Field Type Required Description
status StatusValue Yes

'0' on success.
credits string Yes

Total credits to send once to the whole group.
entries string Yes

Number of members in the group.

CreateGroupResponse

Field Type Required Description
status StatusValue Yes

'0' on success.
groupid string Yes

AddEntriesResponse

Field Type Required Description
status StatusValue Yes

'0' on success.
added string Yes

Entries added.
failed string Yes

Entries rejected (duplicate, or malformed).

DeleteContentsResponse

Field Type Required Description
status StatusValue Yes

'0' on success.
rows string Yes

Number of entries deleted.

GroupListResponse

Field Type Required Description
status StatusValue Yes

'0' on success.
group array of GroupSummary Yes
group.id string Yes

Group id as a string. Note grpid is sent as an integer, so the round trip requires a cast.
group.name string Yes

GroupSummary

Field Type Required Description
id string Yes

Group id as a string. Note grpid is sent as an integer, so the round trip requires a cast.
name string Yes

GroupNumbersResponse

Field Type Required Description
status StatusValue Yes

'0' on success.
entry array of object Yes
entry.number string Yes

GroupDetailsResponse

Field Type Required Description
status StatusValue Yes

'0' on success.
entry array of GroupEntry Yes
entry.name string Yes
entry.number string Yes
entry.email string Yes

Member email, empty when not set.

GroupEntry

Field Type Required Description
name string Yes
number string Yes
email string Yes

Member email, empty when not set.

HlrResult

HLR lookup succeeded. A lookup that could not complete returns an Error envelope with status 200 instead.

Field Type Required Description
status StatusValue Yes

'0' on success.
msisdn string Yes
state string Yes

HLR state. FAIL means the lookup itself did not complete.

OK, ABSENT_SUBSCRIBER, BLOCKED, CALL_BARRED, DATA_MISSING, FAIL, HLR_ABORT, HLR_CANCEL, HLR_REJECT, HLR_TIMEOUT, NOT_SUPPORTED, THROTTLED, SYSTEM_FAILURE, UNKNOWN, UNKNOWN_SUBSCRIBER.
imsi string Yes

IMSI; at minimum the MCC/MNC when known.
location string Yes

Country code of the current location.
mcc string No

Present only when extended was set.
mnc string No

Present only when extended was set.
cc string No

Present only when extended was set.
country string No

Present only when extended was set.
network string No

Present only when extended was set.
prefix string No

Present only when extended was set.
ported string No

"true"/"false"; present only when extended was set and the IMSI prefix disagrees with the routed network.

MnpResult

MNP lookup succeeded. A lookup that could not complete returns an Error envelope with status 200 instead.

Field Type Required Description
status StatusValue Yes

'0' on success.
msisdn string Yes
state string Yes

Same vocabulary as HlrResult.state, with FAIL when the lookup did not complete.
imsi string Yes
location string Yes

NumberInfo

Field Type Required Description
status StatusValue Yes

'0' on success.
mcc string Yes
mnc string Yes
cc string Yes
country string Yes
network string Yes
credits string Yes

DeliveryReceipt

Payload of the delivery-receipt callback POST. Not an OpenAPI callbacks entry because the URL is configured out of band.

Field Type Required Description
msgid string Yes
error string Yes

SMSC error code, "0" on success.
state string one of "ACCEPTD", "DELIVRD", "EXPIRED", "REJECTD", "UNDELIV" Yes
date string Yes

Time the message reached its final state, yymmddhhmm, in UK local time (no timezone is conveyed).
clientref string No

Present if supplied on send.
e212 string No

MCC/MNC of the destination network, if receipt e212 reporting is enabled. 000000 when unknown.

StatusValue

'0' on success.

string one of "0"

SendSmsParameters

Documentation-only projection of the form-encoded body accepted by sendSms; every field mirrors the query parameters of the same name.

Field Type Required Description
dstaddr string No
txt string No
data string No
dcs string No
enc string No
srcaddr string No
clientref string No
sendid string No
multipart integer No

Error codes

Every non-success response returns this envelope. The error value identifies the failure; status says whether it is worth retrying.

Field Type Required Description
status string one of "0", "1", "2", "3" Yes

"1" permanent failure, "2" or "3" temporary failure (may be retried).
error string one of "1000", "1025", "1100", "1200", "1201", "1202", "1203", "1204", "1205", "1300", "1301", "1302", "1303", "1304", "1400", "1900" Yes

Numeric error code, as a string.

  • 1000 authorisation failure
  • 1025 account disabled / not activated
  • 1100 insufficient funds
  • 1200 incorrect arguments
  • 1201 unknown command
  • 1202 bad request
  • 1203 service not provisioned
  • 1204 not implemented
  • 1205 duplicate send id (idempotency)
  • 1300 group name already exists
  • 1301 group is empty
  • 1302 group does not exist
  • 1303 group name length invalid
  • 1304 delivery restricted to profile
  • 1400 no information for the MSISDN
  • 1900 unknown error
desc string Yes

Using the specification directly

This reference is generated from our OpenAPI document, which is published and free to use. Point a client generator, a mock server or an IDE plugin at it:

/openapi/spec.yaml : OpenAPI 3.0.3, 3.2.

Need a key, or an endpoint that is not listed?

Grab your API key from the API tab of your account, or talk to us about what you are building. Everything here is supported by the same team that runs the network.

Create an account Developer APIs Contact us