Qlara Platform API
Overview
The Partner Gateway API is a unified REST interface that lets you:
- Track delivery of messages sent via SMS, RCS, and WhatsApp — poll per-message status or configure a webhook
- Manage contacts and lists used as campaign targets
- Create and manage bulk campaigns across SMS, RCS, and WhatsApp channels
- Browse and export the full history of sent messages
- Handle two-way conversations through the inbox
- Upload media (images, videos) reused across campaigns and conversations
- Connect social profiles (Facebook, Instagram, LinkedIn, Google, TikTok)
Note: Message sending (SMS, RCS, WhatsApp) is handled by separate upstream services. This API provides delivery tracking, campaign management, contact management, and conversation handling.
Authentication
Every request must include a valid API key in the X-API-Key HTTP header:
X-API-Key: <your-api-key>
API keys are scoped to your account. Use the API Keys section to create and manage them.
Request Identification
Every response carries an X-Request-Id header with the identifier the platform assigned to the request:
X-Request-Id: 16d9b2a9ca97da0d8c4c4ea2ae689017
Quote it when contacting support about a specific call: it is the key our logs are searched by.
Supported Channels
| Channel | Key | Available Operations |
|---|---|---|
| SMS | SMS | Delivery tracking, history, campaigns |
| RCS | RCS | Delivery tracking, history, campaigns |
WHATSAPP | Delivery tracking, history, campaigns |
Delivery Statuses
Every delivery-tracking endpoint reports the same normalised deliveryStatus, and the
delivery-status webhook sends the matching numeric code. Both come from one table:
| Code | deliveryStatus | deliveryStatusDescription | Channels | Meaning |
|---|---|---|---|---|
| 1 | ACCEPTED | accepted | SMS | Accepted and handed to the carrier; no delivery receipt has come back yet. Not final. |
| 2 | REJECTED | rejected | SMS | The carrier refused the message. Final. |
| 3 | DELIVERED | delivered | SMS, RCS, WhatsApp | The carrier confirmed the message reached the handset. Final. |
| 4 | EXPIRED | expired | SMS, RCS, WhatsApp | Not delivered within its validity window; the carrier discarded it. Final. |
| 5 | DELETED | deleted | SMS | The message was cancelled before it could be delivered. Final. |
| 6 | UNDELIVERABLE | undeliverable | SMS | The destination cannot receive the message (unreachable or invalid number). Final. |
| 9 | ERROR | general error | RCS, WhatsApp | Delivery failed. Final. |
| 10 | DISABLED | disabled | RCS, WhatsApp | The recipient has the channel switched off. Final. |
| 11 | UNSUPPORTED | unsupported | RCS, WhatsApp | The recipient's device or number does not support the channel. Final. |
| 12 | CONVERSATION_CLOSED | conversation closed | The 24-hour customer-service window had closed. Final. | |
| 0 | UNKNOWN | unknown | SMS, RCS, WhatsApp | The platform holds no status for this message. |
A message that has been sent but not yet confirmed reads ACCEPTED on SMS and UNKNOWN on RCS and
WhatsApp, which have no intermediate code of their own. deliveryDate is set only once a receipt
arrives, so a DELIVERED message carries one.
The delivery-status webhook carries the same numbers, so one table reads both the API and the
callback. The callback registered through POST /partner-gateway/v1/webhooks/delivery-status sends
the code as statusCode and the third column as description; the SMS platform's own delivery
callback sends the same number as DELIVERY_STATUS.
Core Workflows
1 — Track message delivery status
GET /partner-gateway/v1/messages/status/{customerMessageId}?channel=SMS
-> 200 { deliveryStatus: "DELIVERED" }
You can also query RCS and WhatsApp message statuses through their dedicated endpoints.
2 — Receive delivery events via webhook (no polling)
POST /partner-gateway/v1/webhooks/delivery-status
{ "callbackUrl": "https://your-server.example.com/webhook" }
The platform will POST delivery events to that URL automatically.
3 — Run a bulk campaign
POST /partner-gateway/v1/campaigns -> create campaign (draft)
PUT /partner-gateway/v1/campaigns/{id}/confirm -> schedule & send
GET /partner-gateway/v1/campaigns/stats -> delivery statistics
4 — Export message history
POST /partner-gateway/v1/messages/history/export -> 202 Accepted
GET /partner-gateway/v1/exports -> poll until isAvailableForDownload = true
GET /partner-gateway/v1/exports/{exportId} -> retrieve download URL
Asynchronous Operations
Operations that may take a long time (campaign sending, data exports) return
202 Accepted immediately and process in the background.
Use the corresponding list or status endpoint to monitor progress.
Common HTTP Status Codes
| Code | Meaning |
|---|---|
| 200 | OK — request succeeded |
| 201 | Created — resource created successfully |
| 202 | Accepted — asynchronous job queued |
| 204 | No Content — operation succeeded with no response body |
| 400 | Bad Request — validation error; inspect the response body for details |
| 401 | Unauthorized — missing or invalid X-API-Key |
| 404 | Not Found — the requested resource does not exist |
| 409 | Conflict — the resource already exists (e.g. a webhook is already configured) |
| 500 | Internal Server Error |
| 502 | Bad Gateway — upstream channel provider returned an error |
Authentication
- API Key: ApiKeyAuth
Autenticazione
Security Scheme Type: | apiKey |
|---|---|
Header parameter name: | X-API-Key |