G-SMS API documentation

Base URL and authentication

Every endpoint lives under a single base URL. Requests are authenticated with an API key sent as a Bearer token.

https://api.sms.gworldship.com

Authorization: Bearer gsk_your_api_key

• A key always starts with gsk_ and is shown once, when you create it in the console. We store its hash, not the key itself: if you lose it, revoke it and create another one.
• A key belongs to exactly one application. It identifies the account that pays and the application that owns the messages, so you never pass an account or application identifier in a request.
• Keep keys on your server. A key in a mobile app or in browser JavaScript can be read by anyone and spends your balance.
• Only GET /v1/pricing works without a key. Everything else returns 401 INVALID_API_KEY.

Your first SMS in two minutes

1. Create an account and confirm your phone number with the code you receive by SMS. Verification credits the account with XAF 100 — about twenty messages to Orange or MTN.
2. Create an application in the console. An application groups its own messages, keys and webhook endpoints; use one per project, or one per environment.
3. Generate an API key inside that application and copy it into your server configuration.
4. Run the request below.

Request

curl -X POST 'https://api.sms.gworldship.com/v1/sms' \
  -H 'Authorization: Bearer gsk_your_api_key' \
  -H 'Content-Type: application/json' \
  -d '{"to":"+237690000000","text":"Your verification code is 123456"}'

Response

HTTP/1.1 202 Accepted
Content-Type: application/json

{
  "messageId": "9f1c4b2e-5d3a-4c7e-8b21-6a0f7d9c1e45",
  "to": "+237690000000",
  "operator": "ORANGE",
  "segments": 1,
  "priceXaf": 5,
  "status": "QUEUED",
  "balanceAfterXaf": 95,
  "createdAt": "2026-09-12T08:41:03.512Z"
}

202 Accepted means the message was validated, priced, charged and queued — not yet delivered. Delivery is reported later, by webhook or by polling. Full reference for POST /v1/sms.

Endpoints

Response conventions

• Every response is JSON, UTF-8 encoded.
• Null fields are omitted. A message that has not failed carries no failureReason key at all — do not expect it to be present and null.
• Timestamps are ISO-8601 in UTC, for example 2026-09-12T08:41:03.512Z.
• Amounts are integers in XAF. There are no decimals in this currency.
• Errors use a single shape, { code, message }. Branch on code; the message is prose meant for a human reader and it can change without notice.

HTTP/1.1 402 Payment Required
Content-Type: application/json

{ "code": "INSUFFICIENT_BALANCE", "message": "Solde insuffisant" }

One documented exception breaks that rule, and it is the one that catches integrations: a duplicate client reference returns 409 with a message object, not an error object. Read why, and how to handle it.

What this API does not do

• No custom sender name. The recipient sees the number of the SIM that carries the message. G-SMS is designed for transactional traffic, where the content matters more than the label above it.
• No bulk endpoint. One request sends one message. Loop on your side, stay under ten requests per second, and use a client reference per message so a retry never sends twice.
• Cameroonian mobile numbers only. Accepted formats are +2376XXXXXXXX, 2376XXXXXXXX and 6XXXXXXXX; anything else is rejected with INVALID_NUMBER.
• Outgoing only. The API does not expose inbound messages.

Questions