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:
Authorization: Bearer <token> headerapiKey query parameter| Version | API Style | Authentication | Recommended Use |
|---|---|---|---|
| V2LATEST | JSON body, single or batch sending and status lookup | Authorization: Bearer <token> header | Default choice for all new integrations |
| V1 | Query-string or JSON body, single-message sending and status lookup | apiKey query parameter | 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:
- Verify your use case and start your Free Trial
- Configure IP Whitelisting for additional security (Optional)
- Create your account with a dedicated Sender ID and API key
- Provide you with NO SMS Number (Optional)
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
99555512345699555512345655512345699555512345600995555123456995555123456+995555123456+995555123456| Example | Accepted format | Normalized |
|---|---|---|
995555123456 | Georgian mobile number with country code | 995555123456 |
555123456 | Georgian mobile number without country code | 995555123456 |
00995555123456 | Georgian mobile number with international dialing prefix | 995555123456 |
+995555123456 | Georgian mobile number with leading + | 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, digits0–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 | Single message limit | Per-fragment limit (multipart) | Maximum characters |
|---|---|---|---|
| GSM-7 (standard alphabet) | 160 characters | 153 characters | 1530 characters |
| UCS-2 (Unicode / non-GSM characters) | 70 characters | 67 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
/api/v1/sms/sendSends 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
apiKeyfromtobody| Name | Type | Description |
|---|---|---|
apiKeyMandatory | string | API key used to authenticate the request. |
fromMandatory | string | Sender name. 1–11 alphanumeric characters. Must match the sender name assigned to your account. |
toMandatory | string | Destination phone number. See Phone Numbers for accepted formats. |
bodyMandatory | string | SMS text. Must not be empty and must not exceed the fragment limit. |
Response Format
datadatemessageIdstatussent.| Field | Type | Description | ||||||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
data | object | Response payload for the accepted message. | ||||||||||||
| ||||||||||||||
Send SMS over JSON
/api/v1/sms/sendSends 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
apiKeyfromtobody| Name | Type | Description |
|---|---|---|
apiKeyMandatory | string | API key used to authenticate the request. Required in the URL query string. |
fromMandatory | string | Sender name. 1–11 alphanumeric characters. Must match the sender name assigned to your account. |
toMandatory | string | Destination phone number. See Phone Numbers for accepted formats. |
bodyMandatory | string | SMS text. Must not be empty and must not exceed the fragment limit. |
Response Format
datadatemessageIdstatussent.| Field | Type | Description | ||||||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
data | object | Response payload for the accepted message. | ||||||||||||
| ||||||||||||||
Message Status Lookup
/api/v1/sms/{messageId}Retrieves the current delivery status and message details for a previously submitted V1 SMS message.
Attributes
messageIdapiKey| Name | Type | Description |
|---|---|---|
messageIdMandatory | Path string | UUID message identifier returned by the send endpoint. |
apiKeyMandatory | string | API key used to authenticate the request. |
Response Format
datamessageIdfromtextfragmentCountmessageLengthmessagePricestatusPENDING, SENT, DELIVERED, REJECTED, or FAILED.PENDINGSENTDELIVEREDREJECTEDFAILEDmessagesubmitDatecompleteDate| Field | Type | Description | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
data | object | Response payload for the requested message. | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
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
/api/v2/sms:sendSends 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
AuthorizationAuthorization: Bearer YOUR_API_KEY.fromtextttlSeconds60, maximum 86400 (24 hours), default 86400. Beephub stops delivery attempts when this time expires; expired messages return delivery status EXPIRED.clientReferenceclientReference 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.messagestoclientMessageIdA–Z, a–z, 0–9, ., _, -.| Name | Type | Description | |||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|
AuthorizationMandatory | Header string | Bearer token. Format: Authorization: Bearer YOUR_API_KEY. | |||||||||
fromMandatory | String, 1–11 alphanumeric chars | Sender name. Must match the sender name assigned to your account. | |||||||||
textMandatory | String | SMS text shared by all messages in the batch. Must not be empty and must not exceed the fragment limit. | |||||||||
ttlSeconds | number | 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. | |||||||||
clientReference | String, max 128 chars | 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. | |||||||||
messagesMandatory | Array, 1–500 items | Message destination list. | |||||||||
| |||||||||||
Response Format
requestIdstateACCEPTED (all messages accepted) or PARTIAL (some accepted, some rejected).acceptedAtclientReferencemessagesclientMessageIdstateACCEPTED or REJECTED.destinationmessageIddeliveryStatuserrorcodemessagedetailsfield, reason, and message.retryablefalse for validation failures and true for retryable internal failures.| Field | Type | Description | |||||||||||||||||||||||||||||||||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
requestId | string | Request correlation identifier. Include this when contacting support. | |||||||||||||||||||||||||||||||||||||||
state | string | Batch result: ACCEPTED (all messages accepted) or PARTIAL (some accepted, some rejected). | |||||||||||||||||||||||||||||||||||||||
acceptedAt | string <date-time> | Time when Beephub accepted the batch. | |||||||||||||||||||||||||||||||||||||||
clientReference | string | Echo of the client reference, if provided. | |||||||||||||||||||||||||||||||||||||||
messages | array | Per-recipient submission results. | |||||||||||||||||||||||||||||||||||||||
| |||||||||||||||||||||||||||||||||||||||||
Message Status Lookup
/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
AuthorizationAuthorization: Bearer YOUR_API_KEY.messageId| Name | Type | Description |
|---|---|---|
AuthorizationMandatory | Header string | Bearer token. Format: Authorization: Bearer YOUR_API_KEY. |
messageIdMandatory | Path string | UUID message identifier returned by the send endpoint. |
Response Format
requestIdmessageIdfromdeliveryStatusACCEPTEDQUEUEDSENTDELIVEREDEXPIREDFAILEDfailureReason field.failureReasonnull when no failure has occurred.acceptedAtsubmittedAtnull until this stage is reached.completedAtnull until a terminal state is reached.| Field | Type | Description | |||||||||||||||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
requestId | string | Request correlation identifier. Include this when contacting support. | |||||||||||||||||||||
messageId | string | Beephub message identifier. | |||||||||||||||||||||
to | string | Normalized destination number in MSISDN format. | |||||||||||||||||||||
from | string | Sender name used for the message. | |||||||||||||||||||||
deliveryStatus | string | Current delivery status. | |||||||||||||||||||||
| |||||||||||||||||||||||
failureReason | string | Human-readable failure description. null when no failure has occurred. | |||||||||||||||||||||
acceptedAt | string <date-time> | Time when Beephub accepted the message. | |||||||||||||||||||||
submittedAt | string <date-time> | Time when Beephub handed the message off to the carrier. null until this stage is reached. | |||||||||||||||||||||
completedAt | string <date-time> | Time when the message reached a terminal status. null until a terminal state is reached. | |||||||||||||||||||||
