events

Ingest Event

Changed on Aug 4, 2026

Ingest a first-party event.

Every well-formed event is accepted and stored, whether or not its subject can be correlated to a known contact or company: correlation is best-effort and runs asynchronously. Replaying the same external_event_id (or the exact same event content) is idempotent: the event is accepted but never stored or processed twice.

Requires the events:write scope on the API key.

post/v1/events

Request

Base URL: https://api.topo.io
URL: https://api.topo.io/v1/events
Auth: HTTP bearer

Request body

event_namestring required

Custom event name (1–255 characters).

occurred_atstring date-time required

RFC 3339 timestamp when the event occurred.

external_event_idstring nullable

Optional stable identifier from the caller's system, used for idempotent replays.

payloadobject nullable

Free-form JSON attributes for the event.

Response

Successful Response

acceptedboolean required

Whether the event was accepted for processing.

idempotency_keystring required

Key under which the event was deduplicated.

Changes

Aug 4, 2026467ce2bf692b Revision changes
- breaking
  added the new required request property
- breaking
  added the new required request property
- breaking
  removed the required property from the response with the status
- warning
  removed the request property
- warning
  removed the request property
- warning
  removed the request property
- warning
  removed the request property /
- warning
  removed the request property /
- warning
  removed the request property /
- warning
  removed the request property /
- info
  added the new optional request property
- info
  added the new optional request property /
- info
  added the new optional request property /
- info
  added the new optional request property /
- info
  added the new optional request property /
- info
  added the required property to the response with the status

Operation history