Set up a table event stream

This page documents the canonical HTTP contract for this endpoint.

definition is validated as a table event stream definition. The server supplies table_id to the nested definition. Its contract fields are: required name; optional canonical signal_type, match, output, normalization, other_label, company_identity, person_identity, timestamp/title/summary/source-URL/topic/funding-round columns and paths, sample payload, suggested fields, and provision_fit_analysis (false); subject_type (company default; company, lead, person_company); required identity; readiness.mode (any_resolved default; person_resolved or both_resolved); dedupe (row_id default, column, fingerprint); payload.include_all_columns (true default), property column keys, mappings, and additional properties; and company/person attribute mappings. Identity mappings require kind from company_id/company_domain/company_linkedin_url/lead_id/email/person_linkedin_url and nonblank column_key, with optional normalized path. A match requires mode all/any plus at least one condition; each condition has a column key, optional path, operator equals/not_equals/in/exists/not_exists (equals default), and a value except for exists/not_exists. Output has a canonical signal_type, optional subtype, and attributes object. Dedupe column mode requires column_key; fingerprint mode requires column_keys. Normalization uses version 1, family website_event/content_engagement/news, mode auto/fixed (auto default), and optional source mapping. Signal subtype and normalization compatibility are validated by the signal catalog. If both body and Idempotency-Key are provided they must match or the route returns 409. listener_session_id is response-only; it is intentionally absent from the request schema.

Body parameters

schema_version · optional
string
research_table.event_table_setup.v1 (default) or legacy command_center.event_table_setup_plan.v1.
setup_mode · optional
string
new_event_table (default) or existing_table.
table_id · optional
string|null
Existing table ObjectId; required for existing_table.
table_name · optional
string|null
Required for new_event_table.
definitionrequired
object
Validated TableEventStreamCreate definition; nested contract described below.
activate_listener · optional
boolean
Ensure permanent listener; default false and never rotates its token.
finalize_sample_capture · optional
boolean
Finalize sample capture and emit captured rows; default false.
idempotency_key · optional
string|null
Optional retry identity, maximum 200 chars; may also use Idempotency-Key header.
summary · optional
string|null
Optional operation summary.

Name	Type	Description
schema_version	string	research_table.event_table_setup.v1 (default) or legacy command_center.event_table_setup_plan.v1.
setup_mode	string	new_event_table (default) or existing_table.
table_id	string\|null	Existing table ObjectId; required for existing_table.
table_name	string\|null	Required for new_event_table.
definitionrequired	object	Validated TableEventStreamCreate definition; nested contract described below.
activate_listener	boolean	Ensure permanent listener; default false and never rotates its token.
finalize_sample_capture	boolean	Finalize sample capture and emit captured rows; default false.
idempotency_key	string\|null	Optional retry identity, maximum 200 chars; may also use Idempotency-Key header.
summary	string\|null	Optional operation summary.

Errors

Status	Meaning
401	Authentication is required.
403	The caller lacks access to the resource or the tables:write scope.
422	The request does not satisfy the route or typed request contract.
409	Idempotency-Key header and body key differ.

Example

bash

curl -X POST "https://app.autotouch.ai/api/table-event-streams/setup" \
  -H "Authorization: Bearer $AUTOTOUCH_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "table_name": "Product events",
  "definition": {
    "name": "Product event stream",
    "identity": {"kind": "company_domain", "column_key": "company_domain"},
    "output": {"signal_type": "news"},
    "payload": {"include_all_columns": true}
  }
}'

Request body

json

{
  "table_name": "Product events",
  "definition": {
    "name": "Product event stream",
    "identity": {"kind": "company_domain", "column_key": "company_domain"},
    "output": {"signal_type": "news"},
    "payload": {"include_all_columns": true}
  }
}

Response example

json

{
  "status": "completed",
  "table_id": "68d2c6a1a833d60619000001",
  "created_table": true,
  "definition_id": "68d2c6a1a833d60619000002",
  "listener_session_id": null,
  "webhook_url": null,
  "stream": {"item": {"id": "68d2c6a1a833d60619000002", "name": "Product event stream", "table_id": "68d2c6a1a833d60619000001", "identity": {"kind": "company_domain", "column_key": "company_domain"}, "output": {"signal_type": "news"}}, "auto_columns": [], "fit_analysis": {"skipped": "fit_not_requested"}, "layout": {}},
  "listener": null,
  "reprocessed_sample_rows": 0,
  "idempotent_replay": false
}