API reference

Endpoints, authentication, idempotency, limits and webhooks.

Authentication and headers

Base URL: https://api.coussema.com. Use an API key limited to the scopes you need, kept on the server side. Header: Authorization: Bearer <api-key> or x-api-key.

Use Idempotency-Key with the same payload when retrying a mutation.

Sending SMS

POST /v1/sms/send is asynchronous.

The 202 Accepted response confirms validation, storage and queueing.
The worker handles sending, retries and DLR reconciliation.
Keep message.id; provider.messageId stays null on this public surface. Accept 2xx successes and follow delivery by webhook or reporting.

http

POST /v1/sms/send
Authorization: Bearer csm_live_xxxxxxxxxxxx_xxx
Idempotency-Key: 3b0d0fa7-6f8d-4d8d-95e1-8a0bf8a1f0d1

{
  "to": "+243810000000",
  "message": "Votre code est 482019",
  "senderName": "COUSSEMA"
}

202 Accepted
{
  "success": true,
  "queued": true,
  "status": "accepted",
  "count": 1,
  "remainingQuota": 999,
  "message": {
    "id": "11111111-1111-4111-8111-111111111111",
    "clientReference": null
  },
  "provider": {
    "code": "coussema",
    "messageId": null,
    "httpStatus": 202
  }
}

Endpoints

Method	Route	Description
GET	/v1	Public index, service status and reference links.
GET	/v1/health	Health check for integrations and monitoring.
GET	/v1/openapi.json	OpenAPI 3.1 contract generated from the shared schemas.
GET	/v1/account	Commercial summary of the authenticated organization, quota included.
GET	/v1/usage	Ledger of usage and quota adjustments, paginated by cursor.
POST	/v1/sms/send	Asynchronous acceptance of a single SMS with an API key and idempotency; with `whatsappFirst`, the WhatsApp template goes first and the SMS only if the number has no WhatsApp (see WhatsApp API, « Multichannel by API »).
GET / POST	/v1/contacts	List and create contacts for the authenticated organization.
DELETE	/v1/contacts?id={contactId}	Delete a contact by UUID.
GET / POST	/v1/api-keys	List and create customer API keys.
DELETE	/v1/api-keys/{apiKeyId}	Revoke an API key by UUID.
GET / POST	/v1/campaigns	Immediate or scheduled campaigns on the shared runtime.
GET / POST	/v1/webhooks	List and create outgoing webhook endpoints.
DELETE	/v1/webhooks/{webhookEndpointId}	Disable an existing webhook endpoint.

Limits and errors

Every response carries an x-request-id. The SMS endpoint accepts up to 10000 requests per window; the X-RateLimit-* headers show what is left. This ceiling applies to API requests, not to the number of recipients grouped later by the worker/provider.

API errorsWebhooks

← Introduction Quickstart →