POST/api/v1/events

Ingest Universal Business Event

Report customer actions, checkout orders, cart drops, or bookings from your store or backend. Softymize automatically correlates the event with your visual automations in the dashboard and triggers WhatsApp & Email workflows with zero latency.

Asynchronous Redis QueueAuto-Triggers Dashboard FlowsE.164 Phone Sanitization

Direct Dispatch APIs vs. Universal Events: When to use which?

Direct Channel APIs (/whatsapp/send, /email/send)

Use when your code needs to dictate the exact template, language, and immediate message content (e.g. sending a specific 2FA OTP code or an ad-hoc invoice).

Universal Events API (/events) — Recommended

Use when your website just wants to report a business action (e.g. order.created or cart.abandoned). Your marketing & operations teams can then manage, pause, or edit WhatsApp/Email messages directly in the Softymize Flow Builder without touching code!

Request Headers

Header	Type	Required	Description
Content-Type	string	Yes	Must be `application/json`.
X-Softymize-API-Key	string	Yes	Your workspace secret key (e.g. `sft_live_sk_...`).
X-Idempotency-Key	string	Optional	Unique transaction ID (e.g. `ord_99182a`) to prevent duplicate event ingestion within 24 hours.

Request Body Parameters

Field	Type	Requirement	Description
event	string	Required	Unique event identifier slug (e.g. `order.created`, `cart.abandoned`, `lead.captured`).
customer	object	Required	Customer profile container. Must contain at least `customer.phone` in E.164 format. Optionally includes `name` and `email`.
event_category	string	Optional	Category grouping: `commerce`, `healthcare`, `hotel`, or `crm`. If omitted, Softymize automatically infers the category from the event name.
data	object	Optional	Dynamic payload variables (e.g. `order_id`, `total`, `items`, `tracking_url`). All properties become dynamic merge tags inside your Softymize WhatsApp and Email automations.
metadata	object	Optional	Custom contextual data (e.g. IP address, UTM parameters, device type, user agent).

Code Examples (Order Ingestion)

Ingest Event Request (CURL)curl

curl -X POST https://api.softymize.com/api/v1/events \
  -H "X-Softymize-API-Key: sft_live_sk_9a8b7c6d5e4f3a2b1..." \
  -H "Content-Type: application/json" \
  -d '{
    "event": "order.created",
    "customer": {
      "name": "Rohan Sharma",
      "phone": "+919876543210",
      "email": "[email protected]"
    },
    "data": {
      "order_id": "ORD-100293",
      "total": "1499.00",
      "currency": "INR"
    }
  }'

Industry-Specific Payload Schemas

Select an industry category to view ready-to-use JSON payload structures:

ECOMMERCE Payload ExampleJSON

{
  "event": "order.created",
  "event_category": "commerce",
  "customer": {
    "name": "Rohan Sharma",
    "phone": "+919876543210",
    "email": "[email protected]"
  },
  "data": {
    "order_id": "ORD-100293",
    "total": "1499.00",
    "currency": "INR",
    "items_count": 3,
    "payment_method": "Prepaid",
    "tracking_url": "https://mybrand.com/track/ORD-100293"
  }
}

Gateway Response (HTTP 200 OK)

The API returns immediately with a unique event_id while background Redis workers evaluate your active workflow rules:

Success Response (HTTP 200 OK)JSON

{
  "event_id": "9f8a3c4b-12d3-4e5f-b8c9-7a6b5c4d3e2f",
  "event": "order.created",
  "event_category": "commerce",
  "status": "pending",
  "customer_phone": "+919876543210"
}

← Authentication & API Keys GET /api/v1/events Reference →