Track a contact event

Requires an idempotency key via the Idempotency-Key header or idempotency_key body param. Duplicate events (same account + event type + idempotency key) return the existing event.

POST /v1/my/events

Track a contact event

cURL

curl --request POST \
  --url https://api.nitrosend.com/v1/my/events \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "event": "<string>",
  "contact_id": 123,
  "contact_email": "[e-mail]",
  "idempotency_key": "<string>",
  "amount": 123,
  "resource_uid": "<string>",
  "resource_name": "<string>",
  "resource_url": "<string>",
  "test": false,
  "data": {},
  "utm_source": "<string>",
  "utm_medium": "<string>",
  "utm_term": "<string>",
  "utm_content": "<string>",
  "utm_campaign": "<string>"
}
'

200

{
  "id": 123,
  "account_id": 123,
  "contact_id": 123,
  "user_id": 123,
  "event": "<string>",
  "amount": 123,
  "data": {},
  "idempotency_key": "<string>",
  "resource_uid": "<string>",
  "resource_name": "<string>",
  "resource_url": "<string>",
  "test": true,
  "generated": true,
  "chain_depth": 123,
  "ip": "<string>",
  "user_agent": "<string>",
  "browser": "<string>",
  "os": "<string>",
  "device_type": "<string>",
  "referrer": "<string>",
  "utm_source": "<string>",
  "utm_medium": "<string>",
  "utm_term": "<string>",
  "utm_content": "<string>",
  "utm_campaign": "<string>",
  "created_at": "2023-11-07T05:31:56Z",
  "updated_at": "2023-11-07T05:31:56Z"
}

Authorizations

Authorization · string · header · required

API key (nskey_live_...) or JWT token. API key is checked first; if not found, falls back to Devise JWT authentication.

Headers

Idempotency-Key · string

Idempotency key (alternative to body param)

Maximum string length: 128

Body

application/json

event · string · required

Event type name (lowercase, underscores)

Pattern: ^[a-z][a-z0-9_]{0,63}$

contact_id · integer

contact_email · string<email>

Alternative to contact_id — resolves contact by email

idempotency_key · string

Idempotency key (alternative to header)

Maximum string length: 128

amount · number<double>

resource_uid · string

resource_name · string

resource_url · string<uri>

test · boolean · default: false

data · object

Custom event payload (max 32KB)

utm_source · string

utm_medium · string

utm_term · string

utm_content · string

utm_campaign · string

Response

200

application/json

Duplicate event (idempotent — returns existing)

id · integer

account_id · integer

contact_id · integer

user_id · integer

event · string

amount · number<double> | null

data · object

idempotency_key · string | null

resource_uid · string | null

resource_name · string | null

resource_url · string | null

test · boolean

generated · boolean

chain_depth · integer

ip · string | null

user_agent · string | null

browser · string | null

os · string | null

device_type · string | null

referrer · string | null

utm_source · string | null

utm_medium · string | null

utm_term · string | null

utm_content · string | null

utm_campaign · string | null

created_at · string<date-time>

updated_at · string<date-time>