---
title: "Ingest Event"
method: POST
path: "/v1/events"
tags: ["events"]
---

# Ingest Event

`POST /v1/events`

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.

## Request body

- PublicEventInput
  - `event_name` string, required — Custom event name (1–255 characters).
  - `occurred_at` string, date-time, required — RFC 3339 timestamp when the event occurred.
  - `external_event_id` string, nullable — Optional stable identifier from the caller's system, used for idempotent replays.
  - `subject` PublicEventSubjectInput, required
    - `email` string, nullable — Email address of the event subject.
    - `linkedin_url` string, nullable — LinkedIn profile URL of the event subject.
    - `company_domain` string, nullable — Company domain associated with the event subject.
    - `external_contact_id` string, nullable — Contact identifier in the connected CRM.
    - `external_company_id` string, nullable — Company identifier in the connected CRM.
  - `payload` object, nullable — Free-form JSON attributes for the event.

## Response `202`

Successful Response

- PublicEventAcceptedOutput
  - `accepted` boolean, required — Whether the event was accepted for processing.
  - `idempotency_key` string, required — Key under which the event was deduplicated.

---

[API](https://skmtc.net/topo/apis/topo-public-api.md) · [All operations](https://skmtc.net/topo/apis/topo-public-api/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/topo/topo-public-api/revisions/2f1c56db78f8/schema)