AckdbEventTypeDefinition

Complete source event contract, including ownership and optional subject mappings. entity is company-only; person extracts an affiliated actor; person_only resolves one independent human without an affiliation.

Properties

sourceTypestringrequired

eventTypestringrequired

descriptionstringrequired

What this event represents (for AI agents and workflow builders)

categorystring | null

Cross-source activity category for this event (e.g. `billing`, `communication`, `meeting`). Lets agents filter related events across different sources.

contentNaturestring | null

How the event's content should be treated downstream (e.g. for embedding). `conversational` content is chunked + embedded; `structured`/`activity-signal` is not.

"conversational""structured""activity-signal"null

rationalestring

Why this event is included and which redundant events it replaces

replacesEventsarray of

Source events intentionally excluded because this event covers their signal

string

fieldsobjectrequired

Per-field definitions with type, description, computeHint, example

promotedMetadataFieldsarray of

Fields promoted to entity_events.metadata for fast queryability

string

traitHintsarray of

Traits that should be updated when this event is ingested

traitKeystring

computeHintstring

updateStrategystring

"always""first_only""latest"

ingestExampleobject

Complete POST /ingest request body - copy-pasteable template

eventScopestring

Ownership comes from the event type: entity is company-only, person is a person at a company, person_only is the human alone. Personal requests omit company links (or send empty arrays), forbid non-null entityId/contactId and nonempty contacts/traits/files, and resolve a durable person key or explicit personId. Personal structured/activity events create no affiliations.

"entity""person""person_only"

contactMappingsarray of

AckdbContactMappingInput

Example

AckdbEventTypeDefinition example

{
  "sourceType": "stripe",
  "eventType": "invoice.paid",
  "description": "string",
  "category": "billing",
  "contentNature": "structured",
  "rationale": "string",
  "replacesEvents": [
    "string"
  ],
  "fields": {},
  "promotedMetadataFields": [
    "string"
  ],
  "traitHints": [
    {
      "traitKey": "string",
      "computeHint": "string",
      "updateStrategy": "always"
    }
  ],
  "ingestExample": {},
  "eventScope": "entity",
  "contactMappings": [
    {
      "role": "string",
      "nameField": "string",
      "emailField": "string",
      "titleField": "string",
      "externalIdField": "string",
      "externalIdType": "string",
      "linkedinUrlField": "string",
      "phoneField": "string",
      "departmentField": "string",
      "excludeWhen": {},
      "startedAtField": "string",
      "endedAtField": "string",
      "externalIdScope": "person",
      "endsPrior": false,
      "isPrimary": false
    }
  ]
}