Event ingest

Send your own events into Senderz from a backend, a POS, a subscription system or anything else that knows when something happened. Every accepted event is written to the canonical event ledger, attached to a profile, added to that profile’s timeline, and handed to the automation engine.

Send an event

POST /api/v1/events/ingest

Returns 200 OK. Authenticated with the X-Sender-Tenant and X-API-Key header pair, not a bearer token.

string

required

Your Workspace ID. The workspace slug or the workspace UUID, both accepted.

string

required

A workspace API key (sk_evt_...).

Body

string

required

The event name, 1 to 128 characters. Normalized to lower_snake_case, so Quiz Completed, quiz-completed and quiz_completed all resolve to the same event. The first time a name arrives it is created in your workspace’s event catalogue.

string

A unique id for this occurrence, up to 255 characters. Two deliveries carrying the same eventId are counted once. Send one on every call.

string

ISO-8601 timestamp of when the event happened. Defaults to the time the request is received. Use it for any historical import.

object

What happened. Arbitrary key and value pairs describing this occurrence. Keys are normalized to lower_snake_case, so orderTotal is stored as order_total. The whole bag is capped at 32 KB.

integer

Monetary value in minor currency units (agorot, cents). 24990 is 249.90. Feeds revenue reports and attribution. Must be a whole number, a decimal is rejected.

string

Currency code for value, up to 8 characters. For example ILS.

object

Profile fields to set on the resolved contact. Validated against your workspace’s field catalogue. Deliberately separate from properties.

string

Profile first name, up to 255 characters. Written on any resolved contact, new or existing.

string

Profile last name, up to 255 characters. Written on any resolved contact, new or existing.

Identity

At least one identifier is required. See How a profile is resolved.

string

An existing Senderz profile UUID. The strongest identifier, it wins outright.

string

An id owned by your own system, up to 255 characters. Unique within externalNamespace.

string

Names the system that owns externalId, up to 64 characters. For example billing.

string

Contact email, up to 320 characters. Must be a valid address.

string

Contact phone, up to 32 characters. Normalized to E.164.

string

A device or browser id, up to 128 characters. Records activity before a visitor identifies themselves.

The request body is whitelisted. An undocumented field returns 400.

Response

string

One of ok, duplicate, anonymous or no_contact.

Value	Meaning
`ok`	Recorded and attached to a profile.
`duplicate`	An event with this `eventId` was already recorded for this workspace. Nothing was written and no automation ran a second time.
`anonymous`	Recorded against the `anonymousId` because no profile could be resolved or created. It attaches to a profile later, when the visitor identifies.
`no_contact`	Nothing was recorded. Either no identifier was supplied, or the identifiers supplied matched no profile and could not create one.

string | null

The canonical ledger id for this event, for correlating with your own records. This is the Senderz id, not the eventId you supplied. null when nothing was recorded.

boolean

true when the supplied eventId had already been seen. Omitted when the request carried no identifier at all.

string | null

The resolved or created profile UUID. null for anonymous and no_contact.

boolean

true if this event created the profile.

integer

How many automation enrolments were dispatched while handling this request. Downstream effects are drained per workspace, so this can include a small number of enrolments left pending by an earlier call.

Example

curl -X POST https://api.senderz.app/api/v1/events/ingest \
  -H "X-Sender-Tenant: your-workspace-slug" \
  -H "X-API-Key: your-api-key" \
  -H "Content-Type: application/json" \
  -d '{
    "event": "subscription_renewed",
    "eventId": "sub_8842:renewal:2026-08-26",
    "email": "dana@example.com",
    "externalId": "cust_8842",
    "externalNamespace": "billing",
    "occurredAt": "2026-08-26T09:14:00.000Z",
    "value": 24990,
    "currency": "ILS",
    "properties": {
      "plan": "pro",
      "seats": 3,
      "renewal_number": 4
    },
    "profileProperties": {
      "city": "Tel Aviv"
    },
    "firstName": "Dana"
  }'

const res = await fetch("https://api.senderz.app/api/v1/events/ingest", {
  method: "POST",
  headers: {
    "X-Sender-Tenant": process.env.SENDERZ_WORKSPACE,
    "X-API-Key": process.env.SENDERZ_API_KEY,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    event: "subscription_renewed",
    eventId: `sub_8842:renewal:${renewalDate}`,
    email: "dana@example.com",
    externalId: "cust_8842",
    externalNamespace: "billing",
    value: 24990,
    currency: "ILS",
    properties: { plan: "pro", seats: 3 },
  }),
});
const { data } = await res.json();

import requests

res = requests.post(
    "https://api.senderz.app/api/v1/events/ingest",
    headers={
        "X-Sender-Tenant": WORKSPACE,
        "X-API-Key": API_KEY,
    },
    json={
        "event": "subscription_renewed",
        "eventId": "sub_8842:renewal:2026-08-26",
        "email": "dana@example.com",
        "value": 24990,
        "currency": "ILS",
        "properties": {"plan": "pro", "seats": 3},
    },
)
data = res.json()["data"]

{
  "success": true,
  "data": {
    "status": "ok",
    "eventId": "9c4a1f2e-77b0-4d31-8e55-1c0a3d4b6f21",
    "duplicate": false,
    "contactId": "b2f1c0de-1234-4a56-9abc-0123456789ab",
    "created": false,
    "enrolled": 1
  }
}

How a profile is resolved

Identifiers are tried in a fixed order. The first one that matches an existing profile wins.

contactId

An internal profile UUID wins outright, before anything else is consulted.

externalId within externalNamespace

An id set deliberately by the system that owns the customer record.

Lowercased and trimmed before matching.

phone

Normalized to E.164 before matching.

anonymousId

A device or browser, matched last.

Every identifier on the payload is linked to the resolved profile, so the next event carrying any one of them finds the same person. If two identifiers on a single event point at two different profiles and the two profiles do not contradict each other, they are folded into one. An ambiguous conflict is left alone rather than merged.

When a profile is created

If nothing matches, a profile is created only when the event carries an email or a phone. It is created with source api, and any contact_created automation fires for it.

An externalId or an anonymousId alone cannot create a profile. An id naming a billing record or a browser is not a contactable person, and creating profiles from them would fill your audience with rows that can never be messaged.Sending only an externalId for a customer Senderz has never seen returns status: "no_contact" and records nothing. Pair the externalId with an email or phone the first time you see a customer, then the external id alone resolves on every call after that.

Anonymous activity

An event carrying an anonymousId and nothing else is recorded against that id and returns status: "anonymous" with contactId: null. Send the same anonymousId together with an email or phone once the visitor identifies themselves, and the earlier anonymous events are attached to the profile at that moment. Their history is preserved rather than starting from the moment of signup.

Deduplication

Send an eventId on every call. It is the only way two genuine repeats of the same action can be told apart from one delivery arriving twice.

With an eventId, deduplication is exact. Two deliveries carrying the same id are one event: the second returns status: "duplicate", writes nothing, and fires no automation. Two different ids are two events even when every other field matches, so a customer who buys the same item twice is counted twice. Without an eventId, the event falls back to a per contact, per event name, per minute window. A burst of identical calls collapses into one, which also means two genuine repeats inside the same minute collapse into one and are silently lost. This fallback exists so integrations built before eventId keep working, not as a recommended mode. Use something your own system already treats as unique. An order id, an invoice id, or a composite like sub_8842:renewal:2026-08-26 all work.

Event names and property keys

Both are normalized on the way in.

You send	Stored as
`Quiz Completed`	`quiz_completed`
`quiz-completed`	`quiz_completed`
`orderTotal`	`order_total`
`Order Total`	`order_total`

Normalizing means orderTotal and order-total never become three separate properties. It also means the key you reference later, in a segment filter or a merge tag, is the normalized one.

Property types are fixed on first sight

The first value a property carries decides its type: boolean, number, string, datetime, list or object. A string that looks like an ISO date is recognized as datetime. A later value of an incompatible type is rejected with 400 and code metric_property_type_conflict rather than being written where no filter would match it. Widening from datetime to string is allowed; narrowing is not. A number sent as the string "49.90" stays a string, it is never coerced, so send numbers as JSON numbers.

Revenue

value is a whole number of minor currency units, paired with currency. Send 24990 and ILS for 249.90 shekels. Sending 249.90 is rejected as a non-integer. Events carrying a value feed revenue reports and attribution, so an event like subscription_renewed or booking_paid should carry one.

Backdating

occurredAt places the event at the moment it really happened. Any historical import needs it, otherwise every backfilled row lands with today’s timestamp and every time-windowed report and segment reads them as activity from today.

Backdating does not suppress automations. An event with an occurredAt two years ago still enrols any matching automation the moment it is accepted. Pause the relevant automations before running a historical import, or a two-year-old order will send someone a message today.

What happens downstream

An accepted event does four things.

Ledger entry

Written to the canonical event ledger with its properties, value, currency and timestamp. This is what segments and reports read.

Timeline entry

Added to the profile’s activity feed as a custom event carrying the event name and its properties.

Automation enrolment

Enrols any automation whose trigger is a custom event matching this name.

Event catalogue

A new event name appears in your workspace’s event catalogue and in GET /public/events.

The timeline entry carries the property bag only when it is under 8 KB. A larger bag is omitted from the timeline row for readability; the full payload is still recorded in the ledger, and only a bag over 32 KB is rejected outright.

Matching an automation trigger

The automation’s configured custom event name is normalized the same way as the incoming one, so an automation built on Quiz Completed in the builder is triggered by quiz_completed sent through this endpoint.

Custom event names appear in the event catalogue returned by GET /public/events, but they cannot be subscribed to as outbound webhook events. Outbound webhooks use a fixed dotted vocabulary such as email.opened.

Using event properties in automations

Properties become flat merge tags in automation email and SMS templates. A property stored as order_total is referenced as {{order_total}}. value is available as {{amount}} and currency as {{currency}} when the properties do not already define those keys. Only primitive values become merge tags. Nested objects and arrays are skipped, and the identity and compliance tags {{firstName}}, {{lastName}}, {{email}}, {{phone}} and {{unsubscribeUrl}} are reserved and cannot be shadowed by a property of the same name. See Automations for how to build the trigger.

properties vs profileProperties

The two are separate on purpose.

	`properties`	`profileProperties`
Describes	The occurrence	The person
Stored on	The event	The contact record
Example	`plan`, `seats`, `order_total`	`city`, `birthday`, `account_tier`
Validation	Type fixed on first sight	Checked against the field catalogue
Used by	Event filters, merge tags	Profile filters, personalization

An event property never becomes a contact field. If you want a value to persist on the person, put it in profileProperties. profileProperties, firstName and lastName are written to any resolved profile, new or existing. Every key is checked against your workspace’s field catalogue: an unknown key or a computed field is skipped. If every key in the request is rejected, the call returns 400 with code profile_field_invalid.

Errors

Errors use the standard envelope. See Errors and rate limits.

Status	Code	Cause
`401`		`Missing tenant or API key`. One of the two headers is absent.
`401`		`Invalid API key`. The key does not belong to the workspace, or has been revoked.
`400`		Body validation failed. A missing or over-long `event`, an invalid `email`, a `contactId` that is not a UUID, a non-ISO-8601 `occurredAt`, a non-integer `value`, a `properties` value that is not an object, or an undocumented field.
`400`	`metric_event_identity_required`	Every identifier supplied normalized away, for example a `phone` that could not be parsed with no `email` alongside it.
`400`	`metric_name_invalid`	The `event` name normalizes to nothing usable.
`400`	`metric_inactive`	The event exists in the workspace catalogue but has been deactivated.
`400`	`metric_event_properties_too_large`	The `properties` bag exceeds 32 KB.
`400`	`metric_event_properties_invalid`	The `properties` bag could not be serialized.
`400`	`metric_property_type_conflict`	A property arrived with a type incompatible with the one already recorded for it.
`400`	`metric_event_id_too_long`	`eventId` is longer than 255 characters.
`400`	`profile_field_invalid`	Every key in `profileProperties`, `firstName` and `lastName` was rejected by the field catalogue.
`429`		Rate limited. Back off and retry with exponential delay.

An event that carried no identifier at all is not an error. It returns 200 with status: "no_contact", so an older integration keeps working rather than starting to fail.

Introduction

Ingest & transactional

Public API

Send an event

Body

Identity

Response

Example

How a profile is resolved

When a profile is created

Anonymous activity

Deduplication

Event names and property keys

Property types are fixed on first sight

Revenue

Backdating

What happens downstream

Ledger entry

Timeline entry

Automation enrolment

Event catalogue

Matching an automation trigger

Using event properties in automations

properties vs profileProperties

Errors

​Send an event

​Body

​Identity

​Response

​Example

​How a profile is resolved

​When a profile is created

​Anonymous activity

​Deduplication

​Event names and property keys

​Property types are fixed on first sight

​Revenue

​Backdating

​What happens downstream

Ledger entry

Timeline entry

Automation enrolment

Event catalogue

​Matching an automation trigger

​Using event properties in automations

​properties vs profileProperties

​Errors

Send an event

Body

Identity

Response

Example

How a profile is resolved

When a profile is created

Anonymous activity

Deduplication

Event names and property keys

Property types are fixed on first sight

Revenue

Backdating

What happens downstream

Matching an automation trigger

Using event properties in automations

properties vs profileProperties

Errors