Introduction


Beephub provides SMS APIs for sending messages. The APIs also let your application check delivery status and track each message throughout its delivery lifecycle.

Two API versions are available:

Version
V2LATEST
API Style
JSON body, single or batch sending and status lookup
Authentication
Authorization: Bearer <token> header
Recommended Use
Default choice for all new integrations
Version
V1
API Style
Query-string or JSON body, single-message sending and status lookup
Authentication
apiKey query parameter
Recommended Use
Existing clients, simple HTTP clients, quick testing, or integrations that cannot send a request body

V2 is the right choice for new integrations. JSON payloads integrate cleanly with any HTTP client or SDK, Bearer token auth keeps credentials out of URLs and server logs, and structured error responses tell you exactly what went wrong. Batch sending lets you dispatch multiple messages in a single call, reducing both latency and round trips. The clientReference idempotency key protects retries from accidental duplicate sends.

V1 is a good fit for simple HTTP clients, quick testing with curl, clients that can only make simple URL calls with no request body, or existing integrations that work and have no reason to change.

Getting Started

Account Registration

Beephub API access is provisioned on request, there is no self-service sign-up. To register, submit the contact form on the Beephub website.

Our team will:

Keep your API key confidential. Do not include it in client-side code, public repositories, or any environment accessible to untrusted parties. Contact support immediately if you believe your key has been compromised.

Free Trial

Free Trial can be activated during account registration and lets you verify your full integration — authentication, message formatting, response handling, and delivery-status polling — without sending production traffic or incurring delivery costs.

  • Trial numbers: Trial numbers are recipient phone numbers configured for your account for testing. Free Trial messages can be sent only to configured trial numbers. Messages sent to any other destination are rejected. Each account supports up to 10 trial numbers.
  • Free quota: Each account includes 100 Free Trial messages. Learn how message usage is calculated here.

IP Whitelisting

When IP whitelisting is enabled, API requests can be sent only from IP addresses configured for your account. Requests from any other IP address are rejected with 403 Forbidden.

IP whitelisting can be configured during registration and modified at any time by contacting the Beephub support team.

Core Concepts

Phone Numbers

All APIs accept Georgian mobile numbers in multiple common formats. Accepted inputs are normalized internally before dispatch and returned in MSISDN format in API responses.

Accepted Number Formats

Example
995555123456
Accepted format
Georgian mobile number with country code
Normalized
995555123456
Example
555123456
Accepted format
Georgian mobile number without country code
Normalized
995555123456
Example
00995555123456
Accepted format
Georgian mobile number with international dialing prefix
Normalized
995555123456
Example
+995555123456
Accepted format
Georgian mobile number with leading +
Normalized
995555123456

Numbers that cannot be resolved to a valid destination are rejected with error code INVALID_PHONE_NUMBER.

Sender ID

You can only send messages using the Sender ID assigned to your account, which is configured during registration and can be changed per-request.

Formatting rules:

  • 1 to 11 characters
  • Alphanumeric only: letters A–Z, a–z, digits 0–9, spaces and dashes - between the characters.

Opting out

Under Georgia’s Law on Personal Data Protection, you must obtain recipient consent before sending direct-marketing SMS messages and provide a simple way to opt out.

If you send direct-marketing messages, you will receive a NO SMS number during registration. Include this number in every marketing message, for example:

SMS OFF 12345 or NO-12345 where 12345 refers to your NO SMS number.

When a recipient opts out using this number, Beephub automatically blocks future messages to that recipient from the same Sender ID. You do not need to maintain a separate blocklist.

Opt-outs apply per Sender ID, so messages from other Sender IDs remain unaffected.

Note: Opt-out instructions are not required for non-marketing messages, such as verification codes.

SMS Encoding and Fragments

SMS text length is measured in fragments. Encoding is determined automatically from the message text:

Encoding
GSM-7 (standard alphabet)
Single message limit
160 characters
Per-fragment limit (multipart)
153 characters
Maximum characters
1530 characters
Encoding
UCS-2 (Unicode / non-GSM characters)
Single message limit
70 characters
Per-fragment limit (multipart)
67 characters
Maximum characters
670 characters

Any character outside the GSM-7 character set (section 6.2.1 of GSM 03.38) forces UCS-2 encoding for the entire message. Text that fits within the single-message limit is sent as one fragment. Longer text becomes multipart, where each fragment holds up to 153 GSM-7 or 67 UCS-2 characters.

Message usage is calculated per fragment, not per API message. A single-part SMS uses one billable fragment, and a multipart SMS uses one billable fragment for each part.

Examples:

  • 160 GSM-7 characters = 1 fragment; 161 GSM-7 characters = 2 fragments.
  • 70 UCS-2 characters = 1 fragment; 71 UCS-2 characters = 2 fragments.

The maximum allowed fragment count is 10. Messages exceeding this limit are rejected before dispatch.

Date-time format and time zone

All date/time fields in API responses are returned as timezone-aware ISO 8601 strings in the UTC+04:00 time zone.

Format: yyyy-MM-dd'T'HH:mm:ss.SSSXXX

Example: 2026-05-12T13:37:48.011+04:00

Always parse the timezone from the value. Do not assume browser local time, server local time, or a fixed offset.

SMS APIV1

The V1 API provides SMS sending and delivery status lookup for existing integrations. It supports two submission styles: query-string GET requests and JSON POST requests. All endpoints share a single response envelope.

Beephub tries for 86400 seconds (24 hours) to deliver each accepted message to the carrier. If the carrier does not accept the message before this time elapses, the message expires with FAILED status.

Authentication: Pass your API key as the apiKey URL query parameter on every request.

Response structure: Successful requests return 200 OK with a data object. Errors return the appropriate HTTP status code with an error object. 429 Too Many Requests also includes a Retry-After header. The data and error fields are mutually exclusive.

Send SMS over Query String

GET/api/v1/sms/send

Sends one SMS message with all request values encoded as URL query parameters.

Use this for legacy integrations, gateway callbacks, monitoring tools, or environments that can issue GET requests but cannot reliably send JSON request bodies. Prefer Send SMS over JSON for backend services and new V1 integrations.

Because the message content is part of the URL, avoid this endpoint when URLs may be logged by proxies, load balancers, or client tooling.

Attributes

Name
apiKey
Mandatory
Type
string
Description
API key used to authenticate the request.
Name
from
Mandatory
Type
string
Description
Sender name. 1–11 alphanumeric characters. Must match the sender name assigned to your account.
Name
to
Mandatory
Type
string
Description
Destination phone number. See Phone Numbers for accepted formats.
Name
body
Mandatory
Type
string
Description
SMS text. Must not be empty and must not exceed the fragment limit.

Response Format

Field
data
Type
object
Description
Response payload for the accepted message.
Field
date
Type
string <date-time>
Description
Time when the API accepted and dispatched the message.
Field
messageId
Type
string
Description
UUID message identifier. Use this for status lookup.
Field
status
Type
string
Description
Acceptance status. Successful send responses return sent.
Request samples
Response samples

Send SMS over JSON

POST/api/v1/sms/send

Sends one SMS message with the sender, destination, and message text in a JSON request body.

Use this V1 JSON endpoint for existing integrations that need to preserve V1 compatibility while sending structured JSON over HTTP. For all other cases, use the V2 API, which is the recommended choice for new integrations.

Authentication still uses the apiKey query parameter. Pass it in the URL query string, not inside the JSON body.

Attributes

Name
apiKey
Mandatory
Type
string
Description
API key used to authenticate the request. Required in the URL query string.
Name
from
Mandatory
Type
string
Description
Sender name. 1–11 alphanumeric characters. Must match the sender name assigned to your account.
Name
to
Mandatory
Type
string
Description
Destination phone number. See Phone Numbers for accepted formats.
Name
body
Mandatory
Type
string
Description
SMS text. Must not be empty and must not exceed the fragment limit.

Response Format

Field
data
Type
object
Description
Response payload for the accepted message.
Field
date
Type
string <date-time>
Description
Time when the API accepted and dispatched the message.
Field
messageId
Type
string
Description
UUID message identifier. Use this for status lookup.
Field
status
Type
string
Description
Acceptance status. Successful send responses return sent.
Request samples
Response samples

Message Status Lookup

GET/api/v1/sms/{messageId}

Retrieves the current delivery status and message details for a previously submitted V1 SMS message.

Attributes

Name
messageId
Mandatory
Type
Path string
Description
UUID message identifier returned by the send endpoint.
Name
apiKey
Mandatory
Type
string
Description
API key used to authenticate the request.

Response Format

Field
data
Type
object
Description
Response payload for the requested message.
Field
messageId
Type
string
Description
UUID message identifier.
Field
from
Type
string
Description
Sender name used for the message.
Field
to
Type
string
Description
Normalized destination number in MSISDN format.
Field
text
Type
string
Description
SMS body stored for the message.
Field
fragmentCount
Type
number
Description
Number of billable SMS fragments when billing data is available.
Field
messageLength
Type
number
Description
Message text length when billing data is available.
Field
messagePrice
Type
number
Description
Total price when billing data is available.
Field
status
Type
string
Description
Delivery status: PENDING, SENT, DELIVERED, REJECTED, or FAILED.
Status
PENDING
Terminal
No
Description
API request received or message queued to be sent out.
Status
SENT
Terminal
No
Description
Accepted by upstream carrier/SMSC. Message is delivered to the operator at this point.
Status
DELIVERED
Terminal
Yes
Description
Confirmation of delivery received.
Status
REJECTED
Terminal
Yes
Description
Validation, account, sender, number, Free Trial number, blacklist, or upstream partner rejection.
Status
FAILED
Terminal
Yes
Description
Message delivery failed.
Field
message
Type
string
Description
Human-readable status description.
Field
submitDate
Type
string <date-time>
Description
Time when Beephub accepted the message.
Field
completeDate
Type
string <date-time>
Description
Time when the message reached a terminal status, if available.
Request samples
Response samples

SMS APIV2LATEST

The V2 API is the recommended choice for new integrations. It supports single-message and batch SMS sending, delivery status lookup, and idempotency through clientReference. All requests use JSON bodies and Bearer token authentication.

Authentication: Include Authorization: Bearer YOUR_API_KEY in every request header.

Error responses: All V2 errors follow RFC 9457 problem-details format with Content-Type: application/problem+json. Each error body includes type, title, status, detail, errorCode, and requestId. Validation errors additionally include an errors array with field-level details.

Request IDs: Every request generates a unique request ID returned in the X-Request-Id response header and echoed in the response body. Include this ID when contacting support.

Send SMS

POST/api/v2/sms:send

Sends one or more SMS messages in a single JSON request. The endpoint accepts batches of 1 to 500 messages. Each message is validated independently, so a batch can be partially accepted when some messages fail validation.

Returns 202 Accepted when at least one message is accepted. If some messages are rejected and at least one is accepted, the response state is PARTIAL. If all messages are rejected by validation, the endpoint returns 400 Bad Request. If every otherwise valid message fails internal processing before it can be queued, the endpoint returns 500 Internal Server Error.

Attributes

Name
Authorization
Mandatory
Type
Header string
Description
Bearer token. Format: Authorization: Bearer YOUR_API_KEY.
Name
from
Mandatory
Type
String, 1–11 alphanumeric chars
Description
Sender name. Must match the sender name assigned to your account.
Name
text
Mandatory
Type
String
Description
SMS text shared by all messages in the batch. Must not be empty and must not exceed the fragment limit.
Name
ttlSeconds
Type
number
Description
Message lifetime in seconds. Minimum 60, maximum 86400 (24 hours), default 86400. Beephub stops delivery attempts when this time expires; expired messages return delivery status EXPIRED.
Name
clientReference
Type
String, max 128 chars
Description
Client-defined idempotency key scoped per service. Protects against accidental duplicate sends when retrying after a network error or timeout. Reusing the same clientReference within the active TTL window returns 409 Conflict with error code IDEMPOTENCY_KEY_REUSE_CONFLICT. Use a stable, unique value per logical batch, such as an order ID or UUID. Do not reuse clientReference values across different batches.
Name
messages
Mandatory
Type
Array, 1–500 items
Description
Message destination list.
Name
to
Mandatory
Type
string
Description
Destination number. See Phone Numbers for accepted formats. Must be unique within the batch.
Name
clientMessageId
Type
String, 1–64 chars
Description
Client message identifier. Must be unique within the batch. Allowed characters: A–Z, a–z, 0–9, ., _, -.

Response Format

Field
requestId
Type
string
Description
Request correlation identifier. Include this when contacting support.
Field
state
Type
string
Description
Batch result: ACCEPTED (all messages accepted) or PARTIAL (some accepted, some rejected).
Field
acceptedAt
Type
string <date-time>
Description
Time when Beephub accepted the batch.
Field
clientReference
Type
string
Description
Echo of the client reference, if provided.
Field
messages
Type
array
Description
Per-recipient submission results.
Field
clientMessageId
Type
string
Description
Echo of the client message identifier, if provided.
Field
state
Type
string
Description
Per-message result: ACCEPTED or REJECTED.
Field
destination
Type
string
Description
Destination number for this message.
Field
messageId
Type
string
Description
Beephub message identifier for accepted messages. Use this for status lookup.
Field
deliveryStatus
Type
string
Description
Initial delivery status for accepted messages.
Field
error
Type
object
Description
Validation error details for rejected messages.
Field
code
Type
string
Description
Machine-readable error code.
Field
message
Type
string
Description
Human-readable error summary.
Field
details
Type
array
Description
Field-level validation errors with field, reason, and message.
Field
retryable
Type
boolean
Description
Whether the error is retryable. false for validation failures and true for retryable internal failures.
Request samples
Response samples

Message Status Lookup

GET/api/v2/sms/{messageId}

Retrieves the current delivery status of an SMS message.

The response includes X-Request-Id for support and troubleshooting correlation.

Attributes

Name
Authorization
Mandatory
Type
Header string
Description
Bearer token. Format: Authorization: Bearer YOUR_API_KEY.
Name
messageId
Mandatory
Type
Path string
Description
UUID message identifier returned by the send endpoint.

Response Format

Field
requestId
Type
string
Description
Request correlation identifier. Include this when contacting support.
Field
messageId
Type
string
Description
Beephub message identifier.
Field
to
Type
string
Description
Normalized destination number in MSISDN format.
Field
from
Type
string
Description
Sender name used for the message.
Field
deliveryStatus
Type
string
Description
Current delivery status.
Status
ACCEPTED
Terminal
No
Description
API request received.
Status
QUEUED
Terminal
No
Description
Message is queued to be sent out.
Status
SENT
Terminal
No
Description
Accepted by upstream carrier/SMSC. Message is delivered to the operator at this point.
Status
DELIVERED
Terminal
Yes
Description
Confirmation of delivery received.
Status
EXPIRED
Terminal
Yes
Description
Message expired before delivery.
Status
FAILED
Terminal
Yes
Description
Message delivery failed. For more details refer to failureReason field.
Field
failureReason
Type
string
Description
Human-readable failure description. null when no failure has occurred.
Field
acceptedAt
Type
string <date-time>
Description
Time when Beephub accepted the message.
Field
submittedAt
Type
string <date-time>
Description
Time when Beephub handed the message off to the carrier. null until this stage is reached.
Field
completedAt
Type
string <date-time>
Description
Time when the message reached a terminal status. null until a terminal state is reached.
Request samples
Response samples