Suggest event-stream field mappings

Derive deterministic candidate identity and event-field mappings from a sample payload or supplied field list. This helper does not save a definition.

POST/api/table-event-streams/suggest-mappings

HTTP referenceScope tables:readUpdated September 27, 2026

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.

Suggestions are heuristic and may be empty when no sample fields are available. Review and validate suggested table column keys before saving a definition. The response shape is abridged and illustrative.

Body parameters

sample_payload · optional
any
Optional representative event payload.
fields · optional
array<object>
Optional fields with required key and optional label, data_type, sample_values, and schema.

Name	Type	Description
sample_payload	any	Optional representative event payload.
fields	array<object>	Optional fields with required key and optional label, data_type, sample_values, and schema.

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	A supplied field descriptor is invalid.

Example

bash

curl -X POST "https://app.autotouch.ai/api/table-event-streams/suggest-mappings" \
  -H "Authorization: Bearer $AUTOTOUCH_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"sample_payload":{"company":{"domain":"example.test"},"event_type":"hiring","occurred_at":"2026-09-27T12:00:00Z"}}'

Request body

json

{
  "sample_payload": {
    "company": {
      "domain": "example.test"
    },
    "event_type": "hiring",
    "occurred_at": "2026-09-27T12:00:00Z"
  }
}

Response example

json

{
  "item": {
    "company_identity": {
      "kind": "company_domain",
      "column_key": "domain",
      "path": "company.domain"
    },
    "person_identity": null,
    "dedupe": {
      "mode": "row_id"
    },
    "timestamp": {
      "column_key": "occurred_at",
      "path": "occurred_at"
    },
    "source_url": null,
    "suggestions": {},
    "warnings": []
  }
}