API Integration

API Endpoints

Send messages via REST API:

POST /api/v1/integrations/messages/send
X-API-Key: YOUR_API_KEY
Content-Type: application/json

{"channel": "sms", "to": "+40712345678", "body": "Your OTP: 123456"}

// Returns HTTP 201 with status "queued" — delivery is async.
// Poll GET /api/v1/integrations/messages/{id}/status or use webhooks.

Webhooks

Receive real-time delivery status updates:

• Message sent notification
• Delivery confirmation (DLR)
• Bounce / failure alerts
• Inbound message notifications

Delivery status (delivered vs. accepted)

Important: a "sent" status only means the carrier accepted the message — NOT that it reached the handset. The real delivery outcome arrives from the carrier a few seconds to minutes later. Use the delivery_status field (delivered | failed | pending | cancelled) and delivery_confirmed for the true result.

Push (recommended)

Subscribe to the message.delivered / message.failed webhooks. We forward the real status the moment the carrier tells us — no polling needed.

POST /api/v1/integrations/webhooks
X-API-Key: YOUR_API_KEY

{"delivery_profile": "sms_only"}
// subscribes to message.sent, message.delivered, message.failed

// Webhook we send you when the carrier confirms:
{
  "event": "message.delivered",
  "data": {
    "id": 12345,
    "channel": "sms",
    "to": "+40712345678",
    "status": "delivered",
    "delivery_status": "delivered",   // delivered | failed | pending | cancelled
    "delivery_confirmed": true,
    "delivered_at": "2026-07-30T10:15:03Z"
  }
}

Polling

Or poll a message’s current status at any time:

GET /api/v1/integrations/messages/{id}/status
X-API-Key: YOUR_API_KEY

// Response
{
  "id": 12345,
  "status": "sent",
  "delivery_status": "pending",       // still waiting on the carrier DLR
  "delivery_confirmed": false
}

Phone number format

For SMS, WhatsApp, Viber and RCS the "to" field must contain a valid phone number. International E.164 format is recommended, but Romanian local formats are accepted and normalised automatically.

• +40740123456 — international format, recommended
• 0740123456 — Romanian local format, normalised automatically
• 0040740123456 — 00 international prefix, normalised automatically

What we reject

Numbers that cannot be a real destination are rejected with 422 at request time, rather than accepted and failed later. For example +6840242000 (no such country code) or +4074012345 (one digit short for Romania). These never reach a carrier and are never billed.

In a batch send, an invalid number is reported individually with error_code INVALID_DESTINATION and does not stop the remaining valid recipients.

Authentication

Authenticate API requests with your API key:

X-API-Key: YOUR_API_KEY