REST API Reference.

Authentication

All requests go to https://api.cxperium.com under the /api/… path over HTTPS. Add the apikey header carrying your API key to every request.

curl https://api.cxperium.com/api/contacts?page=1&limit=10 \
  -H "apikey: $CX_API_KEY"

• Creating a key — in the dashboard go to Settings → API Integration and click Generate; available on Premium and Enterprise plans. Step by step: API Creation and Connection Operations.
• Postman collection — the View Collection button on the same screen gives you a collection with every endpoint on this page and sample bodies.
• One key per account — generating a new key immediately invalidates the previous one. Sub-users can also generate a key from the API Integration screen; doing so renews the account's shared key.
• Keep the key secret — it grants access to your whole account. Do not embed it in browser code or a mobile app; call from your server. If you think it has leaked, regenerate it in the dashboard; the old key becomes invalid.

An invalid, missing or plan-ineligible key returns 401:

{ "error": "Invalid API key!" }

Conventions

Request and response formats are the same across all endpoints. Bodies are JSON (Content-Type: application/json); the one exception is ticket creation with attachments (multipart/form-data).

Response envelope

# Successful request (200 / 201)
{ "status": 201, "success": true, "message": "OK", "data": { … } }

# Validation error (400) — which field was rejected and why is in error/message
{ "status": 400, "success": false, "error": "MEDIA_NOT_SUPPORTED_ON_CHANNEL", "message": "…" }

# Rate limit (429)
{ "error": "Too many requests, please slow down." }

Contacts

A contact is unique: the phone number is the identity. A second create request with the same number does not open a new record; it updates the existing one.

{
  "phone": "905551112233",          // required
  "userProfileName": "Jane Doe",    // required — the name shown in the dashboard
  "email": "jane@example.com",
  "language": "EN",
  "tags": ["66201122334455667788990a"],
  "custom": { "customerNo": "C-4821", "segment": "vip" }  // free custom fields; new keys become columns in the dashboard
}

Tags

Contact tags and ticket tags are separate lists.

Sending Messages

The WhatsApp rule: if the customer wrote to you within the last 24 hours you can send free-form messages; otherwise you can only reach them with a Meta-approved template. The endpoints are split along these two cases.

# Text
{ "type": "TEXT", "phone": "905551112233", "text": "Hi! Your order has been shipped." }

# Image by URL
{ "type": "IMAGE", "phone": "905551112233", "link": "https://example.com/campaign.jpg", "text": "September campaign" }

# Document as Base64
{ "type": "DOCUMENT", "phone": "905551112233", "media": "JVBERi0xLjcK…", "file_name": "invoice.pdf" }

The response is 201 and echoes the body you sent in data. If the channel does not support media you get 400 with MEDIA_NOT_SUPPORTED_ON_CHANNEL.

Surveys

Surveys are designed in the dashboard; through the API you list them, read results and generate personalised pre-filled links.

Notifications (Template Messages)

A notification schema is Cxperium's counterpart of the WhatsApp template submitted to Meta for approval. Creating, listing and deleting schemas is open on Professional and higher plans.

{
  "contact": { "phone": "905551112233" },
  "notification": {
    "template_name": "order_shipped",       // Meta-approved template name
    "name": "Shipping notification",        // task name (shown in the dashboard)
    "data": {
      "template_lang": "en",
      "bodyPayload": ["Jane", "TR-48291"],  // {{1}}, {{2}} … in order
      "headerPayload": { "format": "IMAGE", "link": "https://example.com/shipping.jpg" },  // if the template has a media header
      "buttonPayload": [ { "type": "QUICK_REPLY", "payload": "track_shipping" } ]          // if the template has buttons
    }
  }
}

Fill the body according to your template's structure: an empty bodyPayload array for a template without variables, no headerPayload for a template without a header. When a bulk send finishes, the NOTIFICATION_SENDING_COMPLETED webhook event arrives.

Tickets

Ticket statuses are NEW, OPEN, PENDING, CLOSED. Ticket creation accepts multipart/form-data so that files can be attached.

curl -X POST https://api.cxperium.com/api/ticket \
  -H "apikey: $CX_API_KEY" \
  -F "subject=Delivery delay" \
  -F "contactId=6612cc33dd44ee55ff667788" \
  -F "message=My order has not arrived for 5 days." \
  -F 'tags=["66201122334455667788990a"]' \
  -F "media=@invoice.pdf"

There are webhook events for creation, status and assignee changes and comments: Ticket events.

Live Chat

Live support chats are the records agents see in the dashboard. Through the API you can open chats, send messages and change the team or status.

For chat creation, message, status and assignee events see Chat events.

Webhook Management

Webhook definitions can be managed from the dashboard or the API; both see the same record. Delivery is exclusive to the Enterprise plan.

Event codes and the fields sent: Webhook Reference.

Assistant, Catalog, Pipeline and Other

Assistant endpoints used by chatbot integrations, WhatsApp catalog/product messages, and Pipeline management.

AI assistant

Catalog and product messages Meta Cloud API only

Pipeline

For using Pipeline in the dashboard see CRM Features → Pipeline.