Execute Enrich & Score - Autotouch AI

This page documents the canonical HTTP contract for this endpoint.

Run preflight first and copy its exact planId, version, target mode, scope, normalized mappings, and options into execute. Execute recomputes the plan and rejects drift; selected IDs must still belong to the table. For all-scope, execute freezes membership at admission, which may include rows added after preflight.

Lookup may call external providers and consume credits unless availableDataOnly is true. That option uses mapped row facts and available stored company/person data, but cannot change an existing enrichment-enabled Company root. Lookup and Fit columns are configured to update when their source values change. Qualified-company/lead flags configure post-Fit actions and are not part of the operation's progress.

Admission provisions/reuses managed columns and creates a durable operation; it does not mean lookup/scoring has completed. Poll Get operation run by operationRunId. Developer-key scopes are tables:read, columns:write, columns:run, companies:write, and leads:write; the authenticated user must also access the table.

Path parameters

table_idrequired
string
Must be the table reviewed by preflight.

Name	Type	Description
table_idrequired	string	Must be the table reviewed by preflight.

Body parameters

planIdrequired
string
Exact planId returned by preflight.
planVersionrequired
string
Currently research_table.enrich_score_plan.v2.
idempotencyKeyrequired
string (8-200 characters)
Caller-generated stable key for safe retries of this admission request.
targetModerequired
TargetMode
Must match the target mode reviewed at preflight.
scope · optional
EnrichScoreScope
Must reproduce the scope reviewed at preflight. For all mode, row membership is frozen when execute admits the operation.
mappings · optional
FieldMappings
Must reproduce the normalized mappings reviewed at preflight; see the complete definitions on that page.
options · optional
EnrichScoreOptions
Must reproduce the options reviewed at preflight.
fitColumnId · optional
string | null
Must match the reviewed preflight input; scored execution does not support selecting an existing Fit column.

Name	Type	Description
planIdrequired	string	Exact planId returned by preflight.
planVersionrequired	string	Currently research_table.enrich_score_plan.v2.
idempotencyKeyrequired	string (8-200 characters)	Caller-generated stable key for safe retries of this admission request.
targetModerequired	TargetMode	Must match the target mode reviewed at preflight.
scope	EnrichScoreScope	Must reproduce the scope reviewed at preflight. For all mode, row membership is frozen when execute admits the operation.
mappings	FieldMappings	Must reproduce the normalized mappings reviewed at preflight; see the complete definitions on that page.
options	EnrichScoreOptions	Must reproduce the options reviewed at preflight.
fitColumnId	string \| null	Must match the reviewed preflight input; scored execution does not support selecting an existing Fit column.

Definitions

TargetMode

Select which records the table should resolve and score.

Fields

accounts · optional
string
Resolve companies and score company fit.
people · optional
string
Resolve people and score lead fit.
accounts_people · optional
string
Resolve companies and people, then score both when enabled.

Name	Type	Description
accounts	string	Resolve companies and score company fit.
people	string	Resolve people and score lead fit.
accounts_people	string	Resolve companies and people, then score both when enabled.

TargetMode example

json

"accounts_people"

EnrichScoreScope

At most 10,000 rows per operation. Selected mode accepts unique valid row ObjectIds; all mode freezes the row set at execute admission.

Fields

mode · optional
string: all | selected
Default all.
rowIds · optional
array<string>
Valid 24-character Mongo ObjectIds; only with selected mode.

Name	Type	Description
mode	string: all \| selected	Default all.
rowIds	array<string>	Valid 24-character Mongo ObjectIds; only with selected mode.

EnrichScoreScope example

json

{"mode":"selected","rowIds":["000000000000000000000001"]}

FieldMappings

A map from canonical target field names to a source column key or a ColumnReference object.

Fields

company_id, company_domain, company_linkedin_url, linkedin_company_id, company_name, company_description, company_industry, company_employee_count, company_size, company_country, company_state, company_city · optional
ColumnReference
Company lookup and Fit inputs.
person_name, person_first_name, person_last_name, person_email, person_linkedin_url, person_title, person_headline · optional
ColumnReference
Person lookup and Fit inputs.
company_provider_evidence · optional
string | ColumnReference
Optional existing company evidence source, used by available-data-only company setup when mapped.

Name	Type	Description
company_id, company_domain, company_linkedin_url, linkedin_company_id, company_name, company_description, company_industry, company_employee_count, company_size, company_country, company_state, company_city	ColumnReference	Company lookup and Fit inputs.
person_name, person_first_name, person_last_name, person_email, person_linkedin_url, person_title, person_headline	ColumnReference	Person lookup and Fit inputs.
company_provider_evidence	string \| ColumnReference	Optional existing company evidence source, used by available-data-only company setup when mapped.

FieldMappings example

json

{"company_domain":{"column":"website","columnId":"000000000000000000000010"},"person_title":{"column":"job_title","columnId":"000000000000000000000011","path":"primary_role.title"}}

ColumnReference

If both column and columnId are supplied, they must identify the same existing table column.

Fields

column · optional
string
Existing column key.
columnId · optional
string
Existing column ID.
path · optional
string
Optional nested JSON path in the source cell.

Name	Type	Description
column	string	Existing column key.
columnId	string	Existing column ID.
path	string	Optional nested JSON path in the source cell.

ColumnReference example

json

{"column":"job_title","columnId":"000000000000000000000011","path":"primary_role.title"}

EnrichScoreOptions

Every field is optional; the backend rejects unknown option keys and applies these defaults/bounds.

Fields

includeScoring · optional
boolean
Default true.
availableDataOnly · optional
boolean
Default false. Uses mapped row facts and available stored company/person data; disables external identity search/provider enrichment. Preflight blocks reuse of an existing enrichment-enabled Company root in this mode.
showComponentScores · optional
boolean
Default false. For combined Fit, expose Company Fit and Person Fit beside Lead Fit.
addQualifiedCompanies · optional
boolean
Default false. Configure a separate auditable Company workspace action.
addQualifiedLeads · optional
boolean
Default false. Configure a separate auditable Lead workspace action.
companyFitThreshold · optional
integer (0-100)
Default 65.
leadFitThreshold · optional
integer (0-100)
Default 70.

Name	Type	Description
includeScoring	boolean	Default true.
availableDataOnly	boolean	Default false. Uses mapped row facts and available stored company/person data; disables external identity search/provider enrichment. Preflight blocks reuse of an existing enrichment-enabled Company root in this mode.
showComponentScores	boolean	Default false. For combined Fit, expose Company Fit and Person Fit beside Lead Fit.
addQualifiedCompanies	boolean	Default false. Configure a separate auditable Company workspace action.
addQualifiedLeads	boolean	Default false. Configure a separate auditable Lead workspace action.
companyFitThreshold	integer (0-100)	Default 65.
leadFitThreshold	integer (0-100)	Default 70.

EnrichScoreOptions example

json

{"includeScoring":true,"availableDataOnly":false,"showComponentScores":false,"addQualifiedCompanies":false,"addQualifiedLeads":false,"companyFitThreshold":65,"leadFitThreshold":70}

ExecuteResponse

Durable operation admission receipt. Admission queues work; it does not mean enrichment or scoring is complete.

Fields

operationRunId, operation_run_idrequired
string
Canonical and compatibility aliases for the same operation run ID.
planRunIdrequired
string
Plan-run identity.
queuedrequired
boolean
Whether work was queued.
title, summaryrequired
string
Human-readable receipt details.
columns · optional
object
Provisioned or reused managed columns.

Name	Type	Description
operationRunId, operation_run_idrequired	string	Canonical and compatibility aliases for the same operation run ID.
planRunIdrequired	string	Plan-run identity.
queuedrequired	boolean	Whether work was queued.
title, summaryrequired	string	Human-readable receipt details.
columns	object	Provisioned or reused managed columns.

ExecuteResponse example

json

{
  "operationRunId": "oprun_example_01",
  "operation_run_id": "oprun_example_01",
  "planRunId": "planrun_example_01",
  "queued": true,
  "title": "Enrich and score table",
  "summary": "Enrich & Score operation queued",
  "columns": {}
}

Errors

Status	Meaning
400	Invalid request or mapping.
401	Authentication required.
403	Table access denied or one or more required scopes are missing.
404	Table or reviewed plan not found.
409	Plan drift, table state change, conflicting admission, or idempotency conflict.
422	Request does not match the typed execution schema.

Example

bash

curl -X POST "https://app.autotouch.ai/api/tables/TABLE_ID/enrich-and-score" \
  -H "Authorization: Bearer stk_your_key_id.your_secret" \
  -H "Content-Type: application/json" \
  -d '{"planId":"<PLAN_ID_FROM_PREFLIGHT>","planVersion":"research_table.enrich_score_plan.v2","idempotencyKey":"table-enrich-score-request-001","targetMode":"accounts_people","scope":{"mode":"all"}}'

Request body

json

{
  "planId": "<PLAN_ID_FROM_PREFLIGHT>",
  "planVersion": "research_table.enrich_score_plan.v2",
  "idempotencyKey": "table-enrich-score-request-001",
  "targetMode": "accounts_people",
  "scope": { "mode": "selected", "rowIds": ["000000000000000000000001", "000000000000000000000002"] },
  "mappings": {
    "company_domain": { "column": "website", "columnId": "000000000000000000000010" },
    "person_title": { "column": "job_title", "columnId": "000000000000000000000011", "path": "primary_role.title" }
  },
  "options": { "includeScoring": true, "availableDataOnly": false, "showComponentScores": false, "addQualifiedCompanies": false, "addQualifiedLeads": false, "companyFitThreshold": 65, "leadFitThreshold": 70 }
}

Response example

json

{
  "operationRunId": "oprun_example_01",
  "operation_run_id": "oprun_example_01",
  "planRunId": "planrun_example_01",
  "queued": true,
  "title": "Enrich and score table",
  "summary": "Enrich & Score operation queued",
  "columns": {}
}