Samva
DashboardAPI
ChannelsPlatformMailboxesDevelopersEmail templatesIntegrationsAPI Reference
Events

Record a contact event (Preview)

Preview · Available to selected organizations. Records a custom contact event. Identify the contact by exactly one ID, external ID, or email.

POST
/v1/events

Records a custom contact event. Identify the contact by exactly one ID, external ID, or email. A missing email or external ID creates a contact; an unknown contact ID returns 404. An organization-scoped idempotency key replays the original event. Event names use letters, digits, underscores, hyphens, and dots, up to 255 characters; contact. and samva. prefixes are reserved. Properties allow at most 50 keys and 32 KiB of UTF-8 JSON. Events are retained for 90 days.

Authorization

apiKey
x-api-key<token>

In: header

Request Body

application/json

TypeScript Definitions

Use the request body type in TypeScript.

contact*||
name*string
Length1 <= length <= 255
properties?|null
occurredAt?string|null
idempotencyKey?|null

Response Body

application/json

application/json

application/json

application/json

application/json

application/json

application/json

application/json

application/json

application/json

curl -X POST "https://example.com/v1/events" \  -H "Content-Type: application/json" \  -d '{    "contact": {      "id": "string"    },    "name": "string"  }'
{  "id": "string",  "contactId": "string",  "name": "string",  "source": "api",  "properties": {    "property1": "string",    "property2": "string"  },  "occurredAt": "string",  "recordedAt": "string"}

Related documentation

Record contact events in a batch (Preview)

Preview · Available to selected organizations. Validates the full request shape, contact references, and event names before processing.

List contact events (Preview)

Preview · Available to selected organizations. Returns custom and Samva lifecycle events, newest occurrence first, within the 90-day retention window. Pass nextCursor back as cursor for the next page.