Create Event

Define a new custom event for your organization. An event definition is a named schema — once defined, you can send events against it and use them to trigger automations.

Endpoint

POST /events

Returns: 201 Created

Headers

Header	Value	Required
Authorization	Bearer <your-api-key>	Yes
Content-Type	application/json	Yes

Body Parameters

Parameter	Type	Required	Description
name	string	Yes	Unique event name for your organization. 1–80 characters. Immutable after creation.
description	string	No	Human-readable description. Max 2000 characters.
schema	object	No	Field schema that ingested payloads are validated against. Defaults to no fields. See below.
conversion	object	No	Mark this event as a conversion and map its revenue value/currency. See below.

Schema object

schema.fields is an array of field definitions. Payloads sent to this event are validated against them.

Field	Type	Description
name	string	Field identifier. Letters, digits, and underscores; must start with a letter or underscore. Max 64 characters.
type	string	One of string, number, boolean, date.
required	boolean	Whether the field must be present in every payload.

{
  "name": "order.completed",
  "description": "Fired when a customer completes checkout.",
  "schema": {
    "fields": [
      { "name": "order_id", "type": "string", "required": true },
      { "name": "total", "type": "number", "required": true },
      { "name": "is_gift", "type": "boolean", "required": false }
    ]
  }
}

Conversion object

Mark an event as a conversion so it counts toward goals and revenue reporting. The revenue value and currency are read from fields on the event's own schema.

Field	Type	Required	Description
enabled	boolean	Yes	Whether this event counts as a conversion. false clears any existing config.
value_field	string | null	When enabled	Numeric schema field holding the revenue value. Send null for a count-only conversion (no revenue). Required when enabled is true.
currencies	string[]	For monetary	Accepted ISO-4217 currency codes (e.g. ["SAR","USD"]). Required when value_field is a (non-null) field name. One = fixed currency; many = read per event from currency_field.
currency_field	string	When >1 currency	Schema field holding each event's ISO-4217 currency. Required when more than one currency is accepted.

{
  "name": "order.completed",
  "schema": {
    "fields": [
      { "name": "order_id", "type": "string", "required": true },
      { "name": "total", "type": "number", "required": true },
      { "name": "currency", "type": "string", "required": true }
    ]
  },
  "conversion": {
    "enabled": true,
    "value_field": "total",
    "currencies": ["SAR", "USD"],
    "currency_field": "currency"
  }
}

Explicit value field

Unlike the dashboard, the API never guesses the revenue field. When enabling a conversion you must send value_field — either a numeric field name, or null for a count-only conversion. Omitting value_field while enabled is true returns 422.

If the conversion config is rejected, the event is still created

The event definition is saved before the conversion config is applied. If the conversion object is invalid (e.g. missing value_field), the request returns an error but the event has already been created with no conversion config. Do not retry the same POST — it will return 409 (duplicate name). Instead, fix the conversion config with PATCH /events/:id.

Define before you send

You must create an event definition before sending events to it. A send for an undefined name returns 404.

---

Response

{
  "id": "01957e3a-4b5c-7d8e-9f0a-1b2c3d4e5f6a",
  "name": "order.completed",
  "description": "Fired when a customer completes checkout.",
  "schema": {
    "fields": [
      { "name": "order_id", "type": "string", "required": true },
      { "name": "total", "type": "number", "required": true },
      { "name": "is_gift", "type": "boolean", "required": false }
    ]
  },
  "conversion": {
    "enabled": false,
    "value_field": null,
    "currency_field": null,
    "currencies": null
  },
  "created_at": "2026-06-01T12:00:00.000Z",
  "updated_at": "2026-06-01T12:00:00.000Z"
}

Field	Type	Description
id	string	Unique event ID (UUIDv7)
name	string	Event name (unique per organization, immutable)
description	string | null	Description, or null
schema	object	The field schema ({ "fields": [...] })
conversion	object	Conversion config: enabled, value_field, currency_field, currencies (all null when not a conversion)
created_at	string	ISO 8601 timestamp
updated_at	string	ISO 8601 timestamp

---

Examples

cURL

curl -X POST "https://api.arsel.sa/v1/events" \
  -H "Authorization: Bearer be_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "order.completed",
    "description": "Fired when a customer completes checkout.",
    "schema": {
      "fields": [
        { "name": "order_id", "type": "string", "required": true },
        { "name": "total", "type": "number", "required": true }
      ]
    }
  }'

JavaScript

const response = await fetch("https://api.arsel.sa/v1/events", {
  method: "POST",
  headers: {
    "Content-Type": "application/json",
    Authorization: "Bearer be_your_api_key",
  },
  body: JSON.stringify({
    name: "order.completed",
    description: "Fired when a customer completes checkout.",
    schema: {
      fields: [
        { name: "order_id", type: "string", required: true },
        { name: "total", type: "number", required: true },
      ],
    },
  }),
});

const event = await response.json();
console.log(event.id);

Python

import requests

response = requests.post(
    "https://api.arsel.sa/v1/events",
    headers={
        "Content-Type": "application/json",
        "Authorization": "Bearer be_your_api_key",
    },
    json={
        "name": "order.completed",
        "description": "Fired when a customer completes checkout.",
        "schema": {
            "fields": [
                {"name": "order_id", "type": "string", "required": True},
                {"name": "total", "type": "number", "required": True},
            ]
        },
    },
)

print(response.json()["id"])

C#

using var client = new HttpClient();
client.DefaultRequestHeaders.Add("Authorization", "Bearer be_your_api_key");

var payload = new
{
    name = "order.completed",
    description = "Fired when a customer completes checkout.",
    schema = new
    {
        fields = new[]
        {
            new { name = "order_id", type = "string", required = true },
            new { name = "total", type = "number", required = true }
        }
    }
};

var json = System.Text.Json.JsonSerializer.Serialize(payload);
var content = new StringContent(json, System.Text.Encoding.UTF8, "application/json");
var response = await client.PostAsync("https://api.arsel.sa/v1/events", content);
Console.WriteLine(await response.Content.ReadAsStringAsync());

PHP

<?php
$ch = curl_init("https://api.arsel.sa/v1/events");
curl_setopt($ch, CURLOPT_HTTPHEADER, [
    "Content-Type: application/json",
    "Authorization: Bearer be_your_api_key"
]);
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_POST, true);
curl_setopt($ch, CURLOPT_POSTFIELDS, json_encode([
    "name" => "order.completed",
    "description" => "Fired when a customer completes checkout.",
    "schema" => [
        "fields" => [
            ["name" => "order_id", "type" => "string", "required" => true],
            ["name" => "total", "type" => "number", "required" => true]
        ]
    ]
]));
$response = curl_exec($ch);
echo $response;
curl_close($ch);

---

Error Responses

409 Conflict

{
  "status_code": 409,
  "name": "conflict",
  "message": "An event named \"order.completed\" already exists"
}

400 Bad Conversion

{
  "status_code": 400,
  "name": "bad_request",
  "message": "\"total\" is not a numeric field on this event."
}

422 Validation Error

{
  "status_code": 422,
  "name": "validation_error",
  "message": "name must be longer than or equal to 1 characters"
}

401 Unauthorized

{
  "status_code": 401,
  "name": "unauthorized",
  "message": "Invalid or missing API key"
}