Quickest path to live
Grab your App ID and App Secret, fire a single test event with the cURL snippet below, then open your segment's preview to watch the profile appear instantly — confirming the whole pipeline end to end.
How it works
Overview
Send events, and profiles flow into segments automatically.
The platform is event-driven. Your website or app sends behavioral events (a signup, a purchase, a login) to a single ingestion endpoint. Each event is recorded against a customer profile, created or matched on the fly. Segments are defined by criteria and resolved at read time, so the moment a matching event arrives the profile appears in every segment it qualifies for — and in any automation triggered by those segments. There is nothing to sync.
1 · Send events
POST events to /events with your App ID and App Secret. Identify the user by email, external_id, or phone.
2 · Profiles update
The profile is upserted and the event (with its properties) is appended to its activity history.
3 · Segments & flows react
Criteria-based segments re-evaluate on read; automation flows triggered by a segment enroll matching profiles live.
Best practices
No batch import or nightly sync — ingestion is continuous.
Send events from your server (the App Secret must stay private).
Use a stable identifier (email or external_id) so events merge into one profile.
Credentials
Authentication
Authenticate every request with your App ID and App Secret.
Each account has an App ID (public identifier, app_…) and an App Secret (sensitive key, sk_live_…). Find them in the dashboard under Integrations → Webhooks → Setup, or on the in-app Segmentation Guide. Send both as HTTP headers on every ingestion request. The secret can be rotated at any time; rotating it keeps the same App ID so your integration identity is stable.
App ID
Public account identifier, e.g. app_3f9a1c7b2e10. Safe to keep in config; sent as the X-App-Id header.
App Secret
Private key, e.g. sk_live_… Treat it like a password — store it server-side only, never in browser code.
Rotation
Regenerate the secret from the dashboard if it leaks. Update your servers with the new value; the App ID is unchanged.
Required headers
X-App-Id: app_3f9a1c7b2e10 X-App-Secret: sk_live_Xy7...redacted Content-Type: application/json
Best practices
Never expose the App Secret in client-side / browser JavaScript.
Store credentials in environment variables or a secrets manager.
Rotate the secret immediately if you suspect it was exposed.
Ingestion
Send an Event
POST a single event to /events.
This is the core endpoint. Provide the event_type, a user object that identifies the profile, and optional properties. The API responds with HTTP 202 Accepted and the resolved profile_id. The profile is matched (or created) by email → external_id → phone, in that order.
event_type (required)
The event key, snake_case — e.g. purchase, login, first_deposit. Custom events use the key you define in the catalog.
user (required)
Identity + attributes. At least one of email, external_id, or phone. Optional first_name, last_name, geo, attributes.
properties (optional)
Event-specific data such as value, currency, product_id. Used by segment criteria and personalization.
cURL
curl -X POST "https://api.engage.nevtan.com/api/v1/events" \
-H "X-App-Id: app_3f9a1c7b2e10" \
-H "X-App-Secret: sk_live_Xy7...redacted" \
-H "Content-Type: application/json" \
-d '{
"event_type": "purchase",
"user": {
"email": "jane@example.com",
"external_id": "user_123",
"first_name": "Jane",
"attributes": { "plan": "pro" }
},
"properties": { "value": 49.99, "currency": "USD" },
"idempotency_key": "order_5567"
}'Node.js (fetch)
await fetch("https://api.engage.nevtan.com/api/v1/events", {
method: "POST",
headers: {
"X-App-Id": process.env.ENGAGE_APP_ID,
"X-App-Secret": process.env.ENGAGE_APP_SECRET,
"Content-Type": "application/json",
},
body: JSON.stringify({
event_type: "purchase",
user: { email: "jane@example.com", external_id: "user_123" },
properties: { value: 49.99, currency: "USD" },
idempotency_key: "order_5567",
}),
});Python (requests)
import requests
requests.post(
"https://api.engage.nevtan.com/api/v1/events",
headers={
"X-App-Id": APP_ID,
"X-App-Secret": APP_SECRET,
},
json={
"event_type": "purchase",
"user": {"email": "jane@example.com", "external_id": "user_123"},
"properties": {"value": 49.99, "currency": "USD"},
"idempotency_key": "order_5567",
},
timeout=10,
)PHP (cURL)
$ch = curl_init("https://api.engage.nevtan.com/api/v1/events");
curl_setopt_array($ch, [
CURLOPT_POST => true,
CURLOPT_RETURNTRANSFER => true,
CURLOPT_HTTPHEADER => [
"X-App-Id: " . getenv("ENGAGE_APP_ID"),
"X-App-Secret: " . getenv("ENGAGE_APP_SECRET"),
"Content-Type: application/json",
],
CURLOPT_POSTFIELDS => json_encode([
"event_type" => "purchase",
"user" => ["email" => "jane@example.com"],
"properties" => ["value" => 49.99, "currency" => "USD"],
]),
]);
$response = curl_exec($ch);Success response — HTTP 202
{ "success": true, "profile_id": "664f0a9c1d2e3f4a5b6c7d8e", "error": null }Best practices
Always send from your backend so the secret is never in the browser.
Pass an idempotency_key to safely retry on network failure.
A 202 means accepted — inspect success/error in the JSON body.
Throughput
Batch Events
Send many events in one request with /events/batch.
When you have a queue of events (e.g. a server flushing buffered activity), POST them together. The response reports how many were accepted and the per-event result so you can retry only the failures.
cURL
curl -X POST "https://api.engage.nevtan.com/api/v1/events/batch" \
-H "X-App-Id: app_3f9a1c7b2e10" \
-H "X-App-Secret: sk_live_Xy7...redacted" \
-H "Content-Type: application/json" \
-d '{
"events": [
{ "event_type": "login", "user": { "email": "jane@example.com" } },
{ "event_type": "purchase", "user": { "email": "jane@example.com" },
"properties": { "value": 49.99 } }
]
}'Response — HTTP 202
{
"success": true,
"accepted": 2,
"total": 2,
"results": [
{ "success": true, "profile_id": "664f...8e", "error": null },
{ "success": true, "profile_id": "664f...8e", "error": null }
]
}Best practices
Group events per flush rather than one request per event.
Read the results array to retry only failed items.
Keep batches to a reasonable size (a few hundred events).
Profile matching
Identity & Profiles
How events merge into a single customer profile.
Each event carries a user object. The platform resolves it to a profile by checking email first, then external_id, then phone. If no profile matches, a new one is created. Use a consistent identifier across events so a person's activity stays on one profile rather than fragmenting.
Identity priority
email → external_id → phone. The first that matches an existing profile wins; otherwise a profile is created.
Attributes
user.attributes and top-level fields (first_name, geo…) update the profile, so the latest event keeps it current.
Anonymous → known
Track with external_id early, then add email later — events stitch onto the same profile once an identifier overlaps.
Best practices
Pick one primary identifier (usually email) and send it consistently.
Send external_id for logged-in users so anonymous activity merges later.
Include geo and attributes when you have them — they power segment criteria.
Your taxonomy
Custom Events
Define events that match your business.
Beyond the standard events, you can model your own. In the dashboard's Event Catalog, add a custom event for your industry — give it a name and the event_type key is generated for you (e.g. “Bonus Claimed” → bonus_claimed). Then start sending that event_type from the ingestion API and it becomes available in the segment builder.
Naming
Keys are snake_case and stable. Pick clear, lower-case names: cart_abandoned, kyc_completed, lesson_completed.
Properties
Attach any JSON properties; segment criteria can filter and aggregate on them (e.g. sum of value over 30 days).
Industry scope
Events are organized by industry so each account sees a relevant catalog in the builder.
Best practices
Decide your event_type keys up front and keep them consistent.
Send the same property names every time for reliable segmentation.
Register custom events in the catalog so your team can build on them.
Audiences
Segments
Define criteria; membership is computed live.
A segment is a saved set of conditions, combined with AND / OR. Members are resolved at read time from current profile and event data, so segments are always up to date. Build them in the dashboard; the ingestion API feeds them automatically.
Marketing consent
Channel + subscription status, optionally constrained by subscribe date.
Activity & events
Did / did not do an event, N times, within a time window (last X days or all time).
Profile attribute
Any field on the profile — e.g. geo.country is IN, attributes.plan is pro.
Best practices
Use AND to narrow, OR to broaden.
Preview the live count and sample profiles before saving.
Once saved, a segment can be a campaign audience or an automation trigger.
Lifecycle
Automations
Trigger automation flows from a segment.
Use a segment as the trigger of a Custom Flow. Anyone who matches enters the journey, and because membership is live, profiles that match later are enrolled automatically — exactly like a list-triggered flow. Build emails, delays, and YES/NO branches in the flow builder, then activate.
Segment trigger
Choose the Audience Segment trigger, search and select your segment, and the audience size is shown.
Continuous enrollment
New matches are added over time; you don't re-import or re-run the flow.
Credits & safety
Each send deducts email credits; if you run out, flows auto-pause and resume after a top-up.
Best practices
Drive lifecycle journeys (winback, onboarding) from behavioral segments.
Test with sample profiles before activating.
Monitor step-level conversion to refine the flow.
Contract
API Reference
Endpoints, fields, status codes, and errors.
A quick reference for the ingestion surface. All requests are JSON over HTTPS and authenticated with the App ID / App Secret headers.
Endpoints
Base URL
https://api.engage.nevtan.com/api/v1
Send event
POST /events
Batch events
POST /events/batch
Auth headers
X-App-Id, X-App-Secret
Success
HTTP 202 · { success, profile_id, error }
Event fields
event_type
string · required
Event key (snake_case), e.g. purchase, login.
user
object · required
Identity + attributes. One of email / external_id / phone required.
user.email
string
Primary identity.
user.external_id
string
Your own user id.
user.phone
string
Phone identity.
user.first_name / last_name
string
Optional profile name fields.
properties
object
Event-specific data (value, currency, product_id…).
Status & error handling
202 Accepted
Event received and recorded.
Done
success: false
Invalid app credentials, or per-event error.
Fix & retry
4xx
Malformed request (bad JSON, missing event_type/user).
Fix request
5xx / network
Transient server or connectivity issue.
Retry idempotently
Best practices
Retry idempotently with idempotency_key on 5xx or network errors.
Treat a missing/invalid credential response as a configuration error, not a retry.
Log the profile_id from responses to correlate with the dashboard.
Security note
The App Secret authorizes writes to your account's data. Keep it on your server, inject it from environment variables, and rotate it if exposed. Do not embed it in front-end code, mobile apps, or public repositories.