Read sequence variable catalog

This page documents the canonical HTTP contract for this endpoint.

The endpoint requires an authenticated user, and developer API keys require sequences:read under the current API authorization resolver. The route resolves custom variables against the caller's organization.

The example is abbreviated to representative variables; the live response returns all enabled standard, custom, and source-table entries. Use only keys in allowedVariableKeys for templates. Structured research-table columns are listed separately and blocked for bare scalar template interpolation; project or split them into scalar columns first. A source table is optional for standard lead/company/user variables. The source of truth and authoring rules are documented by the canonical sequences.variable_catalog operation.

Query parameters

sequenceId · optional
string
Sequence whose linked source table can be used when sourceTableId is omitted.
sourceTableId · optional
string
Optional source table for research columns; must agree with the selected sequence source table. The current handler returns HTTP 500 for a conflicting table.
includeCustomFields · optional
boolean
Include organization-defined CRM variables; default true.
includeResearchFields · optional
boolean
Include source-table scalar and structured research variables; default true.
includeRouteSuggestions · optional
boolean
Include route candidate suggestions when source-table context exists; default true.
routeSampleLimit · optional
integer
Route suggestion sample size, 1–250; default 100.

Name	Type	Description
sequenceId	string	Sequence whose linked source table can be used when sourceTableId is omitted.
sourceTableId	string	Optional source table for research columns; must agree with the selected sequence source table. The current handler returns HTTP 500 for a conflicting table.
includeCustomFields	boolean	Include organization-defined CRM variables; default true.
includeResearchFields	boolean	Include source-table scalar and structured research variables; default true.
includeRouteSuggestions	boolean	Include route candidate suggestions when source-table context exists; default true.
routeSampleLimit	integer	Route suggestion sample size, 1–250; default 100.

Errors

Status	Meaning
401	Authentication required or authenticated user has no organization context.
403	Developer API key lacks sequences:read.
404	Sequence or source table is not available to the organization.
422	routeSampleLimit must be between 1 and 250.
500	Current limitation: conflicting sequence and explicit source-table context is not translated into a client-error response.

Example

bash

curl 'https://app.autotouch.ai/api/sequences/variable-catalog?includeCustomFields=true&includeResearchFields=true' \
  -H "Authorization: Bearer $AUTOTOUCH_API_KEY"

Response example

json

{
  "tool": "read_sequence_variable_catalog",
  "schema_version": "sequence_variable_catalog.v1",
  "mode": "scratch_crm",
  "sequence": null,
  "sourceTable": null,
  "availableSources": ["lead", "company", "user", "custom_fields"],
  "unavailableSources": ["research_table"],
  "variables": {
    "lead": [{"key": "first_name", "label": "First name", "source": "lead", "syntax": "{{first_name}}"}],
    "company": [{"key": "company_name_clean", "label": "Company name", "source": "company", "syntax": "{{company_name_clean}}", "preferredForCopy": true}],
    "user": [{"key": "user_first_name", "label": "Sender first name", "source": "user", "syntax": "{{user_first_name}}"}],
    "customFields": {"lead": [], "company": []},
    "researchTable": [],
    "researchTableStructured": []
  },
  "allowedVariableKeys": ["first_name", "last_name", "full_name", "title", "linkedin_url", "business_email", "primary_phone", "company_name_clean", "company_domain", "website", "industry", "employee_count", "company_linkedin_url", "user_first_name", "user_last_name", "user_full_name", "company", "company_name", "company_name_normalized"],
  "blockedTemplateVariableKeys": [],
  "routing": {
    "supported": true,
    "mechanisms": ["lead_field", "company_field", "custom_field", "source_field_route"],
    "sourceFieldRouteAvailable": false,
    "candidateFields": [],
    "defaultBranchGuidance": "Use a default branch for blank or unexpected route values."
  },
  "mapping": {
    "variableMap": "template variable -> source table column id/key for table-linked enrollment and draft hydration",
    "requiredVariables": "variables that must resolve before provider handoff or strict enrollment checks",
    "researchContext.fieldIds": "optional source-table column ids to expose as focused AI draft/task context",
    "fallback": "if researchContext.fieldIds are omitted, AI draft context falls back to starred/is_important source-table columns",
    "templateScalarOnly": "Bare {{...}} template variables must resolve to scalar values. JSON/object/array research table columns are excluded; split or project them to scalar columns before using them in copy."
  }
}