BCOM SMS DEVELOPER API

Document No. BCOM-SMS-API-1 · Version 1.1 · Status: Issued for client use · Numbering: ITU-T E.164

1. Purpose

This document sets out the terms on which BCOM provides the BCOM SMS Developer API, and the technical rules for submitting Short Message Service traffic. API access is free. The Client requests an API key on the BCOM API page. That key is linked to the Client’s BCOM SMS account. Each successful send deducts Credits from the wallet on the dashboard. Message submission requires an approved Sender ID on the same account.

2. Definitions

Term	Meaning
BCOM	The provider of the BCOM SMS Developer API
Client	The registered business that accepts these terms and holds the account
API	The HTTPS interface described in this document
E.164	The international public telecommunication numbering plan. A mobile number is expressed with a country code and the national number, with no trunk prefix
Sender ID	The alphanumeric originator displayed on the handset, not exceeding 11 characters
Credits	The prepaid units from which each message segment is charged
Personal data	Data relating to an identified or identifiable person, including a mobile number
Controller	The Client, who determines why and how recipient data are used
Processor	BCOM, who transmits messages on the Client’s instructions

3. Fees

API access. There is no plan fee and no API set-up fee. The Client clicks Request API on the BCOM API page and the API key is generated immediately.

Credits. Traffic is prepaid. Credits are purchased on Purchase credits and held in the Client’s BCOM SMS wallet. Every successful API send deducts Credits from that wallet. REST JSON, HTTP GET, form POST, and XML use the same account and the same balance.

An approved Sender ID may remain registered independently of API use. Insufficient Credits refuse the submission.

4. Onboarding

The Client completes the following steps in order before submitting traffic.

(i) Open a BCOM SMS account, sign in, and enter the BCOM API page from the dashboard. That page is the starting point for the API key, this document, and the integration styles.
(ii) Read this document on that page, or download the PDF from the same page. The Client shall not request an API key until these terms have been read.
(iii) Accept the commercial terms, the messaging rules, and the data-protection terms. BCOM records the account, the date and time, and the version accepted.
(iv) Click Request API. BCOM generates the API key immediately and links it to the same BCOM SMS account. There is no plan fee and no API set-up fee.
(v) Purchase Credits on Purchase credits. Those Credits are held in the dashboard wallet. Every successful API send deducts from that wallet.
(vi) Request a Sender ID on the Sender IDs page. Traffic may be submitted only under a Sender ID that BCOM has approved for the Client’s registered business.
(vii) Choose an integration style — REST JSON, HTTP GET, form POST, or XML — and submit messages from the Client’s own server. All four styles use the same API key and the same Credit balance.

The BCOM API page displays the API key, the integration styles, the wallet Credit balance, and this document.

5. Commercial terms

API access is free. Credits are payable as stated in Section 3. The API key remains under the Client’s control and is stored on the Client’s server. Exposure of the key is notified to itsupport@bcom.africa, and the key is regenerated. BCOM may suspend API access if the Client is in breach of these terms.

6. Messaging rules

The Client shall submit traffic only under a Sender ID approved for the Client’s registered business. The Sender ID shall identify that business. It shall not imitate another enterprise, a financial institution, or a public authority.

A marketing message shall be sent only where the recipient has given prior, specific, and informed consent to that sender and to that subject. The message shall identify the sender and the purpose. Where the message offers a product or service for a charge, it shall state the price. The recipient shall be given a clear means of withdrawing consent, and the Client shall honour that withdrawal without delay.

A transactional message requested by the recipient, including a one-time password or a receipt, is a separate purpose and shall not be used as authority for marketing.

The Client shall not submit fraudulent, deceptive, or otherwise unlawful content, and shall not route traffic so as to conceal its origin. The Client shall retain evidence of consent, the Sender ID used, and the purpose of the message, and shall maintain its own opt-out register.

These duties are given in accordance with the Electronic and Postal Communications Act, 2010, the Electronic and Postal Communications (Value Added Services) Regulations, 2018, and the Electronic and Postal Communications (Tele-Traffic) (Amendment) Regulations, 2023, together with any direction of the Tanzania Communications Regulatory Authority applicable to application-to-person messaging.

7. Data protection

The service is provided in the United Republic of Tanzania. Processing of personal data is subject to the Personal Data Protection Act, 2022, and the Personal Data Protection (Personal Data Collection and Processing) Regulations, 2023 (GN No. 449C of 2023).

The Client is the Controller. BCOM is the Processor. BCOM processes the recipient number, message content, Sender ID, and delivery result solely to transmit the message, to account for Credits, to provide support, and to investigate abuse. BCOM does not determine the recipients or the content.

The Client warrants that it has a lawful basis for each number submitted, that the data are limited to what the stated purpose requires, and that data collected for one purpose are not reused for marketing without a fresh lawful basis. Sensitive personal data shall not be placed in a message unless the Client holds the prior written consent required by law.

BCOM shall apply appropriate technical and organisational measures to protect personal data against unauthorised access, loss, and unlawful processing. Where BCOM becomes aware of a personal-data breach affecting the Client’s traffic, BCOM shall notify the Client without undue delay. A request by a data subject for access, rectification, or erasure is addressed to the Client. BCOM shall assist the Client in respect of the logs BCOM holds.

Each party remains responsible for any registration it is required to hold with the Personal Data Protection Commission.

8. Authentication

Every request carries the API key. REST JSON, form POST, and XML use the header. HTTP GET may pass api_key as a query parameter.

Authorization: Bearer YOUR_API_KEY
Content-Type: application/json

The key is displayed on the BCOM API page after Request API. It is confidential. It shall not be embedded in a mobile application, a public website, or a source-code repository. Requests are made from the Client’s server.

A missing or rejected key returns HTTP 401.

Further 401 responses are: Invalid API key., API key has been revoked., Account is suspended., and API access is not enabled for this account.

9. International numbering

Destination numbers are submitted in E.164 international form. The supported destination for this version is the United Republic of Tanzania, country code 255.

Accepted form	Example	Treated as
E.164, preferred	`+255712345678`	`255712345678`
E.164 digits	`255712345678`	`255712345678`
National trunk form	`0712345678` or `0612345678`	`255712345678`

The national number is nine digits after 255. A leading plus sign is accepted and removed. Any other country code is rejected.

10. Submit a message

All styles below are linked to the same BCOM SMS account and deduct Credits from the dashboard wallet.

REST JSON. POST https://www.sms.bcom.africa/api/sms/v1/messages/send/ with Content-Type: application/json.

HTTP GET. GET https://www.sms.bcom.africa/api/sms/v1/send/?api_key=YOUR_API_KEY&to=+255712345678&message=Hello&sender_id=YOURBRAND

Form POST. POST https://www.sms.bcom.africa/api/sms/v1/send/ as application/x-www-form-urlencoded.

XML. POST https://www.sms.bcom.africa/api/sms/v1/messages/send/ with Content-Type: application/xml.

The equivalent REST path is POST https://www.sms.bcom.africa/api/sms/v1/send/.

curl -X POST "https://www.sms.bcom.africa/api/sms/v1/messages/send/" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d "{\"to\":\"+255712345678\",\"message\":\"Hello from BCOM SMS\",\"sender_id\":\"YOURBRAND\"}"

Field	Required	Aliases	Description
`to`	Yes	`phone`, `recipient`	One E.164 mobile number
`message`	Yes	`text`, `body`	Message text
`sender_id`	No	`sender`	Approved Sender ID. If omitted, the account default is used

{
  "success": true,
  "sent": 1,
  "failed": 0,
  "credits_used": 1,
  "request_id": "31951",
  "to": "255712345678",
  "balance": 120
}

The Client shall retain request_id for reconciliation. One Credit is charged for each message segment. balance is the Credit balance after the submission. to is returned in international digits, without the plus sign.

HTTP 400 means the body is not valid JSON or XML. HTTP 422 means the submission was refused. The error field states the reason, including a missing field, a number that is not valid E.164 for Tanzania, the absence of an approved Sender ID, a Sender ID that is not on the account, or insufficient Credits.

11. Credit balance

GET https://www.sms.bcom.africa/api/sms/v1/balance/

{
  "success": true,
  "balance": 120,
  "currency": "credits"
}

currency is credits. The figure is the message wallet. It is not an amount in Tanzanian shillings.

12. Sender IDs

GET https://www.sms.bcom.africa/api/sms/v1/sender-ids/

{
  "success": true,
  "sender_ids": [
    { "name": "YOURBRAND", "is_default": true }
  ],
  "default_sender_id": "YOURBRAND"
}

Only approved Sender IDs are returned. A name under review is omitted, and a submission that uses it is rejected. Request Sender IDs on the Sender IDs page of the account.

13. Service information

GET https://www.sms.bcom.africa/api/sms/v1/

The response states the service name, version 1, status, the address of this document, and the list of endpoints. The Client may use it to confirm the key and the availability of the service.

14. Status codes

HTTP status	Meaning
200	The request succeeded
400	The body is not valid JSON or XML
401	The key is missing, invalid, or revoked, or the account or API access is inactive
422	The number, message, Sender ID, or Credit balance cannot be accepted

This version does not provide a separate test environment. The Client tests with an approved Sender ID, a limited Credit balance, and a number under the Client’s control.

15. Operation

The Client shall call the API from its backend only, confirm the Credit balance before a bulk submission, and keep consent and opt-out records in its own systems. One account serves one legal entity and only the Sender IDs approved for that entity. BCOM may suspend the key where traffic breaches Sections 6 or 7.

Correspondence on a Sender ID or a refused submission is sent to itsupport@bcom.africa and includes the account email address. A refused submission also includes request_id.