Create or update a table event stream

This page documents the canonical HTTP contract for this endpoint.

Developer API keys need the listed scope. A valid authenticated user session may also call this route.

Identity objects use kind (company_id, company_domain, company_linkedin_url, lead_id, email, or person_linkedin_url), non-empty column_key, and optional payload path; subject_type determines which identity kinds and paired company/person mappings are meaningful. Successful upsert saves an active definition and claims the table’s single active event controller; a competing active claim returns 409. It reconciles the event-table contract, may create projection/metadata columns and update layout, and returns auto_columns, fit_analysis, and layout. fit-analysis columns are created only when provision_fit_analysis=true. This is a mutating configuration endpoint, not an event ingest call.

Body parameters

table_idrequired
string
Research table identifier; caller must have table access.
namerequired
string
Non-empty display name.
signal_type · optional
string
Supported normalized signal type; when routed output is supplied, its signal type is authoritative.
subject_type · optional
string
company, lead, or person_company.
identityrequired
object
Identity kind, non-empty table column_key, and optional payload path.
match · optional
object
Optional matching object with mode all|any and a non-empty conditions array. Each condition has a non-empty column_key, optional payload path, operator equals|not_equals|in|exists|not_exists, and value (required except for exists/not_exists).
output · optional
object
Optional output with canonical signal_type, optional signal_subtype, and attributes object; can be synthesized when match or normalization is supplied.
normalization · optional
object
Optional {version:1,family:website_event|content_engagement|news,mode:auto|fixed,source?:{column_key,path?}}; family must match a supported output, and fixed mode requires output.signal_subtype.
dedupe · optional
object
{mode:row_id|column|fingerprint, column_key?, column_keys?, path?}; column requires column_key, fingerprint requires at least one column_keys entry.
payload · optional
object
{include_all_columns:boolean=true, property_column_keys:string[], property_mappings:[{column_key,path?,property_key?}], additional_properties:[{property_key,value_template}]}.
readiness · optional
object
{mode:any_resolved|person_resolved|both_resolved}.
other_label · optional
string
Optional label for a supported other signal.
company_identity · optional
object
Optional company identity mapping for person_company subjects; same identity shape as identity.
person_identity · optional
object
Optional person identity mapping for person_company subjects; same identity shape as identity.
timestamp_column_key · optional
string
Optional table column containing event timestamp.
timestamp_path · optional
string
Optional payload path containing timestamp.
title_template · optional
string
Optional event title template.
summary_template · optional
string
Optional event summary template.
source_url_column_key · optional
string
Optional table column containing event source URL.
source_url_path · optional
string
Optional payload path containing source URL.
topic_column_key · optional
string
Optional table column containing topic.
topic_path · optional
string
Optional payload path containing topic.
funding_round_column_key · optional
string
Optional table column containing funding round.
funding_round_path · optional
string
Optional payload path containing funding round.
company_attribute_mappings · optional
object
Optional {mappings:{field_key:{column_key,path?,property_key?}}} target-attribute container; the mappings object may also be supplied directly.
person_attribute_mappings · optional
object
Optional {mappings:{field_key:{column_key,path?,property_key?}}} target-attribute container; the mappings object may also be supplied directly.
sample_payload · optional
any
Optional representative event payload.
fields · optional
array<object>
Optional fields with key, label?, data_type?, sample_values?, schema?.
provision_fit_analysis · optional
boolean
When true, also provision fit-analysis columns for active stream subject types.

Name	Type	Description
table_idrequired	string	Research table identifier; caller must have table access.
namerequired	string	Non-empty display name.
signal_type	string	Supported normalized signal type; when routed output is supplied, its signal type is authoritative.
subject_type	string	company, lead, or person_company.
identityrequired	object	Identity kind, non-empty table column_key, and optional payload path.
match	object	Optional matching object with mode all\|any and a non-empty conditions array. Each condition has a non-empty column_key, optional payload path, operator equals\|not_equals\|in\|exists\|not_exists, and value (required except for exists/not_exists).
output	object	Optional output with canonical signal_type, optional signal_subtype, and attributes object; can be synthesized when match or normalization is supplied.
normalization	object	Optional {version:1,family:website_event\|content_engagement\|news,mode:auto\|fixed,source?:{column_key,path?}}; family must match a supported output, and fixed mode requires output.signal_subtype.
dedupe	object	{mode:row_id\|column\|fingerprint, column_key?, column_keys?, path?}; column requires column_key, fingerprint requires at least one column_keys entry.
payload	object	{include_all_columns:boolean=true, property_column_keys:string[], property_mappings:[{column_key,path?,property_key?}], additional_properties:[{property_key,value_template}]}.
readiness	object	{mode:any_resolved\|person_resolved\|both_resolved}.
other_label	string	Optional label for a supported other signal.
company_identity	object	Optional company identity mapping for person_company subjects; same identity shape as identity.
person_identity	object	Optional person identity mapping for person_company subjects; same identity shape as identity.
timestamp_column_key	string	Optional table column containing event timestamp.
timestamp_path	string	Optional payload path containing timestamp.
title_template	string	Optional event title template.
summary_template	string	Optional event summary template.
source_url_column_key	string	Optional table column containing event source URL.
source_url_path	string	Optional payload path containing source URL.
topic_column_key	string	Optional table column containing topic.
topic_path	string	Optional payload path containing topic.
funding_round_column_key	string	Optional table column containing funding round.
funding_round_path	string	Optional payload path containing funding round.
company_attribute_mappings	object	Optional {mappings:{field_key:{column_key,path?,property_key?}}} target-attribute container; the mappings object may also be supplied directly.
person_attribute_mappings	object	Optional {mappings:{field_key:{column_key,path?,property_key?}}} target-attribute container; the mappings object may also be supplied directly.
sample_payload	any	Optional representative event payload.
fields	array<object>	Optional fields with key, label?, data_type?, sample_values?, schema?.
provision_fit_analysis	boolean	When true, also provision fit-analysis columns for active stream subject types.

Errors

Status	Meaning
401	Authentication is missing or invalid.
403	The credential is invalid or lacks the required scope, or the caller cannot access the resource.
422	The request model or normalization/output combination is invalid.
403	The caller cannot access the requested table.
404	The table does not exist.
410	The table is being deleted.
409	Another active definition owns the table’s single active event controller; active-controller claim failed.

Example

bash

curl -X POST "https://app.autotouch.ai/api/table-event-streams" \
  -H "Authorization: Bearer $AUTOTOUCH_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"table_id":"table-id","name":"Hiring signals","signal_type":"hiring","subject_type":"company","identity":{"kind":"company_domain","column_key":"domain"},"dedupe":{"mode":"row_id"}}'

Request body

json

{
  "table_id": "table-id",
  "name": "Hiring signals",
  "signal_type": "hiring",
  "subject_type": "company",
  "identity": {
    "kind": "company_domain",
    "column_key": "domain"
  },
  "dedupe": {
    "mode": "row_id"
  }
}

Response example

json

{
  "item": {
    "id": "event-stream-id",
    "table_id": "table-id",
    "name": "Hiring signals",
    "status": "active",
    "subject_type": "company",
    "identity": {
      "kind": "company_domain",
      "column_key": "domain"
    }
  },
  "auto_columns": [],
  "fit_analysis": {
    "skipped": "fit_not_requested"
  },
  "layout": {}
}