# Beem API

## Docs

- [Introduction](https://docs.beem.africa/index.md): Build reliable communication experiences with the Beem API platform.
- [Quickstart](https://docs.beem.africa/quickstart.md): Get up and running with the Beem APIs in just a few minutes.
- [Introduction](https://docs.beem.africa/guides/sms/index.md): Send SMS messages and receive delivery reports using the Beem SMS REST API.
- [Prerequisites](https://docs.beem.africa/guides/sms/prerequisites.md): Account, sender ID, and credit requirements before using the SMS API.
- [Authentication](https://docs.beem.africa/guides/sms/authentication.md): Generate SMS API credentials and authenticate requests using Basic Auth or an access token.
- [Sender ID registration](https://docs.beem.africa/guides/sms/sender-id.md): Register and activate a Sender ID before sending SMS through the API.
- [Sending flow](https://docs.beem.africa/guides/sms/sending-flow.md): End-to-end flow from sending an SMS request to receiving a delivery report.
- [Delivery reports](https://docs.beem.africa/guides/sms/delivery-reports.md): Retrieve SMS delivery status using the Delivery Reports API.
- [Monitoring & API logs](https://docs.beem.africa/guides/sms/monitoring.md): Track SMS submissions and API activity from the Beem Dashboard.
- [API responses](https://docs.beem.africa/guides/sms/api-responses.md): HTTP status codes and SMS API response codes for send and related operations.
- [API lifecycle](https://docs.beem.africa/guides/sms/api-lifecycle.md): Authenticate, send messages, and track delivery with the SMS API.
- [Security](https://docs.beem.africa/guides/sms/security.md): Best practices for securing SMS API credentials and rotating keys.
- [Send SMS](https://docs.beem.africa/api-reference/send-sms.md): Send an SMS message to one or more recipients. Supports JSON (`application/json`) and XML (`application/xml`) request bodies.
- [Get vendor balance](https://docs.beem.africa/api-reference/get-vendor-balance.md)
- [Get delivery reports](https://docs.beem.africa/api-reference/get-delivery-reports.md): Retrieve SMS delivery status for a sent message. Check delivery status at least 5 minutes after submitting an SMS to allow time for delivery updates from mobile network operators.
- [List sender names](https://docs.beem.africa/api-reference/list-sender-names.md)
- [List SMS templates](https://docs.beem.africa/api-reference/list-sms-templates.md)
- [Create SMS template](https://docs.beem.africa/api-reference/create-sms-template.md)
- [Update SMS template](https://docs.beem.africa/api-reference/update-sms-template.md)
- [Delete SMS template](https://docs.beem.africa/api-reference/delete-sms-template.md)
- [Introduction](https://docs.beem.africa/guides/multicountry-sms/index.md): Send and receive international SMS messages over HTTP, or connect via SMPP.
- [Prerequisites](https://docs.beem.africa/guides/multicountry-sms/prerequisites.md): Set up your Multicountry SMS account and obtain credentials before sending messages.
- [Message encoding](https://docs.beem.africa/guides/multicountry-sms/message-encoding.md): GSM text encoding, UCS2, binary messages, URL encoding, and address formatting.
- [Sending messages](https://docs.beem.africa/guides/multicountry-sms/sending-messages.md): Send outbound SMS from your application to the Messaging Platform.
- [API responses](https://docs.beem.africa/guides/multicountry-sms/api-responses.md): HTTP status codes and platform response codes for Multicountry SMS send operations.
- [Throughput & connections](https://docs.beem.africa/guides/multicountry-sms/throughput.md): HTTP and SMPP throughput limits and concurrent connection rules.
- [Delivery reports](https://docs.beem.africa/guides/multicountry-sms/delivery-reports.md): Receive delivery reports (DLRs) from the Messaging Platform via DLRADDRESS.
- [Inbound two-way SMS](https://docs.beem.africa/guides/multicountry-sms/inbound-two-way.md): Receive mobile-originated messages from the Messaging Platform on your callback URL.
- [Parameters reference](https://docs.beem.africa/guides/multicountry-sms/parameters.md): Send, delivery report, and inbound parameter reference for Multicountry SMS.
- [Send message](https://docs.beem.africa/api-reference/send-message.md): Send a text or binary SMS message. Credentials are passed as form parameters (USERNAME and PASSWORD). Returns a plain-text response with message ID, status code, and optional status text on separate lines.
- [Send message (JSON response)](https://docs.beem.africa/api-reference/send-message-json-response.md): Send a text or binary SMS message and receive a JSON response containing results and account balance.
- [Send message (XML response)](https://docs.beem.africa/api-reference/send-message-xml-response.md): Send a text or binary SMS message and receive an XML response containing results and account balance.
- [Check balance](https://docs.beem.africa/api-reference/check-balance.md): Retrieve your available account balance.
- [Receive inbound message or DLR](https://docs.beem.africa/api-reference/receive-inbound-message-or-dlr.md): Webhook your application must implement. The Messaging Platform POSTs inbound mobile-originated messages and delivery reports to your configured callback URL. Replace the server URL with your own HTTPS endpoint.
- [SMPP integration](https://docs.beem.africa/guides/multicountry-sms/smpp.md): Connect to the Beem Messaging Platform using the SMPP protocol.
- [SMPP error codes](https://docs.beem.africa/guides/multicountry-sms/smpp-error-codes.md): Common SMPP status codes returned when send or receive operations fail.
- [Introduction](https://docs.beem.africa/guides/two-way-sms/index.md): Receive inbound SMS messages on your application through a callback URL.
- [Prerequisites](https://docs.beem.africa/guides/two-way-sms/prerequisites.md): Request a Two-Way SMS number and configure your callback URL.
- [Inbound callbacks](https://docs.beem.africa/guides/two-way-sms/inbound-callbacks.md): Handle inbound SMS callbacks from Beem on your server.
- [Security](https://docs.beem.africa/guides/two-way-sms/security.md): Validate callback requests using your Beem API Key.
- [Introduction](https://docs.beem.africa/guides/contact/index.md): Organize contacts into address books and manage them through the Beem Contacts API.
- [Prerequisites](https://docs.beem.africa/guides/contact/prerequisites.md): Account and authentication requirements for the Contacts API.
- [Authentication](https://docs.beem.africa/guides/contact/authentication.md): Authenticate Contacts API requests using Basic Auth or an access token.
- [Address books](https://docs.beem.africa/guides/contact/address-books.md): Create, view, update, and delete address books to organize your contacts.
- [Contacts](https://docs.beem.africa/guides/contact/contacts.md): Add, retrieve, update, and remove contacts across address books.
- [Search and filtering](https://docs.beem.africa/guides/contact/search-and-filtering.md): Search address books and contacts with pagination and filters.
- [API responses](https://docs.beem.africa/guides/contact/api-responses.md): HTTP status codes and API response codes returned by the Contacts API.
- [Best practices](https://docs.beem.africa/guides/contact/best-practices.md): Recommendations for keeping your contact database organized.
- [List address books](https://docs.beem.africa/api-reference/list-address-books.md)
- [Create address book](https://docs.beem.africa/api-reference/create-address-book.md)
- [Update address book](https://docs.beem.africa/api-reference/update-address-book.md)
- [Delete address book](https://docs.beem.africa/api-reference/delete-address-book.md)
- [List contacts](https://docs.beem.africa/api-reference/list-contacts.md)
- [Create contact](https://docs.beem.africa/api-reference/create-contact.md)
- [Update contact](https://docs.beem.africa/api-reference/update-contact.md)
- [Delete contact](https://docs.beem.africa/api-reference/delete-contact.md)
- [Introduction](https://docs.beem.africa/guides/moja/index.md): The Beem Moja service is an all-in-one communication platform for sales and customer service across WhatsApp, Google Business Messaging, Facebook, Instagram, and SMS.
- [Prerequisites](https://docs.beem.africa/guides/moja/prerequisites.md): Create a Beem account, set up a Moja channel, and obtain API credentials.
- [Authentication](https://docs.beem.africa/guides/moja/authentication.md): Authenticate MOJA API requests using Basic Auth or an access token.
- [Active sessions](https://docs.beem.africa/guides/moja/active-sessions.md): List users with open MOJA chat sessions before sending session messages.
- [Send session message](https://docs.beem.africa/guides/moja/send-session-message.md): Send text, media, location, quick reply, and list messages to users with an active MOJA session.
- [Inbound callbacks](https://docs.beem.africa/guides/moja/inbound-callbacks.md): Receive inbound user replies from MOJA session messages at your callback URL.
- [API responses](https://docs.beem.africa/guides/moja/api-responses.md): HTTP status codes and API responses returned by the MOJA Chat and Broadcast APIs.
- [Get active sessions](https://docs.beem.africa/api-reference/moja/conversations/get-active-sessions.md): Returns active chat sessions for the authenticated vendor.
- [Send session message](https://docs.beem.africa/api-reference/moja/conversations/send-session-message.md): Send a message to a user with an active session. Session messaging is limited to the 24-hour window after the user last interacted with your business; outside that window use approved WhatsApp templates instead.
- [Receive a message](https://docs.beem.africa/api-reference/moja/conversations/receive-a-message.md): Webhook your application must implement. Beem POSTs inbound user messages to the callback_url supplied in the send session message request. Replace the server URL with your own HTTPS endpoint.
- [WhatsApp templates](https://docs.beem.africa/guides/moja/whatsapp-templates.md): Pre-approved WhatsApp message templates for initiating or re-engaging customer conversations.
- [Template categories](https://docs.beem.africa/guides/moja/template-categories.md): Marketing, Utility, and Authentication WhatsApp template categories and their supported content.
- [Request a template](https://docs.beem.africa/guides/moja/requesting-templates.md): Submit WhatsApp templates for approval through the Engage Portal or Moja.
- [Retrieve templates](https://docs.beem.africa/guides/moja/retrieve-templates.md): Retrieve a paginated list of WhatsApp message templates for your account.
- [Send template message](https://docs.beem.africa/guides/moja/send-template.md): Send approved WhatsApp templates with placeholders, media, and multiple recipients.
- [Delivery reports](https://docs.beem.africa/guides/moja/delivery-reports.md): Receive real-time WhatsApp template delivery status updates via callback URL.
- [List message templates](https://docs.beem.africa/api-reference/moja/broadcast/list-message-templates.md): Fetch WhatsApp message templates for the authenticated account.
- [Send template message](https://docs.beem.africa/api-reference/moja/broadcast/send-template-message.md): Send an approved WhatsApp template to one or more recipients.
- [Receive template delivery report](https://docs.beem.africa/api-reference/moja/broadcast/receive-template-delivery-report.md): Webhook your application must implement. Beem POSTs WhatsApp template delivery status updates (accepted, delivered, read, failed) to the callback URL configured in the Engage portal under API Setup. Replace the server URL with your own HTTPS endpoint.
- [Introduction](https://docs.beem.africa/guides/ussd/index.md): Build interactive USSD applications that work across multiple mobile networks through a single API.
- [Authentication](https://docs.beem.africa/guides/ussd/authentication.md): Authenticate USSD API requests using HTTP Basic Authentication or an access token.
- [USSD callback](https://docs.beem.africa/guides/ussd/callback.md): Implement the callback endpoint that receives USSD session events from Beem.
- [Check balance](https://docs.beem.africa/guides/ussd/check-balance.md): Retrieve your available USSD credit balance.
- [USSD simulator](https://docs.beem.africa/api-reference/ussd/simulator.md): Test your USSD callback with the Beem sandbox simulator.
- [Check USSD credit balance](https://docs.beem.africa/api-reference/ussd/check-ussd-credit-balance.md): Retrieve available USSD credit balance for your account. Set app_name to USSD.
- [Receive USSD session callback](https://docs.beem.africa/api-reference/ussd/receive-ussd-session-callback.md): Webhook your application must implement. When a subscriber dials your USSD code, Beem POSTs session events (initiate, continue, terminate) to the callback URL configured in the Beem dashboard. Respond with the next menu prompt. Replace the server URL with your own HTTPS endpoint.
- [Introduction](https://docs.beem.africa/guides/airtime/index.md): Send airtime credit directly to mobile numbers on supported networks via API.
- [Prerequisites](https://docs.beem.africa/guides/airtime/prerequisites.md): Create a Beem account and obtain Airtime API credentials.
- [Authentication](https://docs.beem.africa/guides/airtime/authentication.md): Authenticate Airtime API requests using HTTP Basic Authentication or an access token.
- [Sending airtime](https://docs.beem.africa/guides/airtime/sending-airtime.md): Send an airtime top-up request to a mobile number.
- [Callbacks](https://docs.beem.africa/guides/airtime/callbacks.md): Receive final airtime transaction status via callback URL.
- [Transaction status](https://docs.beem.africa/guides/airtime/transaction-status.md): Check the status of an airtime transfer by transaction ID.
- [Check balance](https://docs.beem.africa/guides/airtime/check-balance.md): Retrieve your available airtime credit balance.
- [Response codes](https://docs.beem.africa/guides/airtime/response-codes.md): Airtime API status and error codes.
- [Send airtime](https://docs.beem.africa/api-reference/send-airtime.md): Submit an airtime top-up request. Returns immediately with a transaction ID while disbursement is processed asynchronously.
- [Check transaction status](https://docs.beem.africa/api-reference/check-transaction-status.md): Poll the status of a previously submitted airtime transfer.
- [Receive airtime callback](https://docs.beem.africa/api-reference/receive-airtime-callback.md): Webhook your application must implement. Beem POSTs the final transfer status to your configured callback URL. Replace the server URL with your own HTTPS endpoint.
- [Check credit balance](https://docs.beem.africa/api-reference/check-credit-balance.md): Retrieve available credit balance for a product. Set app_name to AIRTIME, USSD, BPAY, or another registered product name.
- [Introduction](https://docs.beem.africa/guides/payments-collection/index.md): Receive mobile money payments from subscribers via a unified Bpay API.
- [Prerequisites](https://docs.beem.africa/guides/payments-collection/prerequisites.md): Set up your Bpay account, billpay number, and collection product.
- [Authentication](https://docs.beem.africa/guides/payments-collection/authentication.md): Authenticate Bpay Collection API requests using Basic Auth or an access token.
- [Callbacks](https://docs.beem.africa/guides/payments-collection/callbacks.md): Receive payment collection notifications from Bpay on your server.
- [Check balance](https://docs.beem.africa/guides/payments-collection/check-balance.md): Retrieve your available Bpay credit balance.
- [Bpay collection simulator](https://docs.beem.africa/api-reference/payments-collection/simulator.md): Test your payment collection callback with the Beem sandbox simulator.
- [Check Bpay credit balance](https://docs.beem.africa/api-reference/payments-collection/check-bpay-credit-balance.md): Retrieve available Bpay (Payments Collection) credit balance for your account. Set app_name to BPAY.
- [Receive payment collection callback](https://docs.beem.africa/api-reference/payments-collection/receive-payment-collection-callback.md): Webhook your application must implement. When a subscriber initiates a mobile money payment, Bpay POSTs transaction details to your callback URL. Respond with successful true to accept or false to decline. Replace the server URL with your own HTTPS endpoint.
- [Introduction](https://docs.beem.africa/guides/payments-checkout/index.md): Accept mobile money payments using Beem's hosted checkout page or embedded iframe.
- [Prerequisites](https://docs.beem.africa/guides/payments-checkout/prerequisites.md): Set up your Bpay account and configure checkout routes.
- [Authentication](https://docs.beem.africa/guides/payments-checkout/authentication.md): Authenticate Bpay Checkout API requests using Basic Auth or an access token.
- [Redirect method](https://docs.beem.africa/guides/payments-checkout/redirect-method.md): Send customers to Beem's hosted checkout page to complete payment.
- [Iframe method](https://docs.beem.africa/guides/payments-checkout/iframe-method.md): Embed Beem checkout on your website using the checkout library.
- [Callbacks](https://docs.beem.africa/guides/payments-checkout/callbacks.md): Receive checkout payment status notifications from Bpay.
- [Error codes](https://docs.beem.africa/guides/payments-checkout/error-codes.md): Common checkout error codes and failure scenarios.
- [Sandbox](https://docs.beem.africa/guides/payments-checkout/sandbox.md): Test your checkout integration using the Beem dashboard simulator.
- [Request checkout page](https://docs.beem.africa/api-reference/payments-checkout/request-checkout-page.md): Request Beem's hosted checkout page. Set `sendSource=true` to receive a checkout URL in the response (recommended for backend redirects). Omit or set `sendSource=false` for an HTTP 302 redirect (recommended for frontend redirects).
- [Whitelist website for iframe checkout](https://docs.beem.africa/api-reference/payments-checkout/whitelist-website-for-iframe-checkout.md): Whitelist your website domain before embedding the Beem checkout library. Only HTTPS origins are accepted.
- [Receive checkout payment callback](https://docs.beem.africa/api-reference/payments-checkout/receive-checkout-payment-callback.md): Webhook your application must implement. After a customer completes or fails a checkout payment, Bpay POSTs the payment status to your configured callback URL. Replace the server URL with your own HTTPS endpoint.
- [Introduction](https://docs.beem.africa/guides/otp/index.md): Verify customer mobile numbers using secure One-Time Passwords (OTP) with a simple REST API.
- [Prerequisites](https://docs.beem.africa/guides/otp/prerequisites.md): Everything you need before integrating the Beem OTP API.
- [Authentication](https://docs.beem.africa/guides/otp/authentication.md): Set up OTP credentials and authenticate requests using Basic Auth or an access token.
- [Verification flow](https://docs.beem.africa/guides/otp/verification-flow.md): How to request an OTP, deliver it to the user, and verify the code.
- [OTP lifecycle](https://docs.beem.africa/guides/otp/otp-lifecycle.md): Generate, deliver, and verify one-time passwords.
- [API responses](https://docs.beem.africa/guides/otp/api-responses.md): OTP API response codes for request and verify operations.
- [Security](https://docs.beem.africa/guides/otp/security.md): Best practices for storing OTP API credentials and PIN IDs.
- [Request OTP](https://docs.beem.africa/api-reference/request-otp.md)
- [Verify OTP](https://docs.beem.africa/api-reference/verify-otp.md)

## OpenAPI Specs

- [sms](https://docs.beem.africa/openapi/sms.json)
- [multicountry-sms](https://docs.beem.africa/openapi/multicountry-sms.json)
- [moja](https://docs.beem.africa/openapi/moja.json)
- [contact](https://docs.beem.africa/openapi/contact.json)
- [ussd](https://docs.beem.africa/openapi/ussd.json)
- [payments-collection](https://docs.beem.africa/openapi/payments-collection.json)
- [payments-checkout](https://docs.beem.africa/openapi/payments-checkout.json)
- [otp](https://docs.beem.africa/openapi/otp.json)
- [airtime](https://docs.beem.africa/openapi/airtime.json)

## Optional

- [Documentation](https://beem.africa/beem-api)
- [Blog](https://beem.africa/blog)