Skip to main content
Talk to salesStart

Preflight Enrich & Score

Review table readiness, field mappings, and estimates without writing data or admitting a job.

POST/api/tables/{table_id}/enrich-and-score/preflight
HTTP referenceScope tables:readUpdated September 27, 2026

This page documents the canonical HTTP contract for this endpoint.

Preflight is read-only: it does not create columns, mutate rows, spend credits, or admit an operation. Inspect readiness.ready, blockers, warnings, normalized mappings, and estimates before execution. A 200 response may still have ready: false.

Automatic mappings use Jev's current classified schema when available, otherwise the backend field-mapping resolver. Explicit mappings override those suggestions. The mapping target allowlist is the set documented here; unmapped/unknown target keys are not part of the normalized plan. A row source may use a nested path. Do not invent table, row, or column IDs. With availableDataOnly, the service maps company facts (and optional company_provider_evidence) for stored-data setup; it does not perform external identity search or provider enrichment. For event tables, preflight reports preservesEventRows: true; repeated company/person events remain separate rows.

For scope.mode=all, preflight estimates current rows while execute freezes the exact set at admission. For selected, selected IDs are validated as rows in this table and reused at execute. Developer-key scope: tables:read; the authenticated user must also access the table.

Path parameters

  • table_idrequired

    string

    Target Research Table ID.

Body parameters

  • targetModerequired

    TargetMode

    accounts, people, or accounts_people.

  • scope · optional

    EnrichScoreScope

    Scope to review. Defaults to all; selected requires 1-10,000 unique rowIds from this table.

  • mappings · optional

    FieldMappings

    Optional explicit mappings keyed by canonical target. The server suggests mappings from current classified/schema fields or column meaning when omitted; supplied mappings override suggestions. Review normalized mappings in the response.

  • options · optional

    EnrichScoreOptions

    Scoring, available-data, output, and threshold settings. Fields use the defaults shown below.

  • fitColumnId · optional

    string | null

    Optional Fit column ID field. With includeScoring=true, selecting an existing Fit column is reported as a readiness blocker; turnkey execution does not edit 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.

TargetMode example

json
"accounts_people"

EnrichScoreScope

At most 10,000 rows per operation. Selected rows must be unique valid ObjectIds belonging to this table. Preflight reports the selected count; all-scope membership is frozen at execute admission, so rows arriving after preflight may be included.

Fields

  • mode · optional

    string: all | selected

    Default all.

  • rowIds · optional

    array<string> (max 10,000)

    Unique valid 24-character Mongo ObjectIds belonging to the target table; required for selected and forbidden for all.

EnrichScoreScope example

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

FieldMappings

Map supported canonical targets to existing table columns. Each value is a column-key string or an object containing column and/or columnId and optional path. If both identifiers are supplied, they must resolve to the same column. Extra keys in the reference object are rejected.

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

    string | ColumnReference

    Company lookup and Fit inputs.

  • person_name, person_first_name, person_last_name, person_email, person_linkedin_url, person_title, person_headline · optional

    string | 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.

FieldMappings example

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

ColumnReference

A source column reference; at least column or columnId must identify an existing column. If both are supplied, they must identify the same column.

Fields

  • column · optional

    string

    Existing column key.

  • columnId · optional

    string

    Existing column ID.

  • path · optional

    string

    Nested property path within the source cell value.

ColumnReference example

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

EnrichScoreOptions

All options are optional. The defaults below are applied when omitted.

Fields

  • includeScoring · optional

    boolean

    Default true. Also calculate Fit scores.

  • availableDataOnly · optional

    boolean

    Default false. Uses mapped row facts and available stored company/person data without external identity search or provider enrichment. An existing enrichment-enabled Company root blocks this mode; preflight reports the blocker rather than changing that root.

  • showComponentScores · optional

    boolean

    Default false. For combined Fit, expose native Company Fit and Person Fit projections beside Lead Fit.

  • addQualifiedCompanies · optional

    boolean

    Default false. Configure a Company workspace action for qualifying results; the write runs as a separate auditable operation.

  • addQualifiedLeads · optional

    boolean

    Default false. Configure a Lead workspace action for qualifying results; the write runs as a separate auditable operation.

  • companyFitThreshold · optional

    integer (0-100)

    Default 65.

  • leadFitThreshold · optional

    integer (0-100)

    Default 70.

EnrichScoreOptions example

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

PreflightResponse

Read-only result. The server supplies suggested/normalized mappings, estimates, table contract, readiness blockers/warnings, and a deterministic planId. This response is a review only; it does not reserve all-scope row membership.

Fields

  • planIdrequired

    string

    Server-generated reviewed-plan identity; pass it to execute.

  • planVersionrequired

    string

    Currently research_table.enrich_score_plan.v2.

  • tableIdrequired

    string

    Reviewed table.

  • targetModerequired

    TargetMode

    Reviewed target mode.

  • includeScoringrequired

    boolean

    Effective scoring setting.

  • scoperequired

    object

    Contains mode, rowCount, and preservesEventRows.

  • readinessrequired

    object

    Contains ready, blockers, and warnings.

  • estimates, mappings, tableContractrequired

    object

    Server-calculated estimate, normalized mappings, and table contract.

  • companyRoot, rubricVersion · optional

    object | string | null

    Present when applicable to the reviewed table and rubric.

PreflightResponse example

json
{
  "planId": "esp_example_plan_from_preflight",
  "planVersion": "research_table.enrich_score_plan.v2",
  "tableId": "000000000000000000000020",
  "targetMode": "accounts_people",
  "includeScoring": true,
  "scope": { "mode": "selected", "rowCount": 2, "preservesEventRows": false },
  "readiness": { "ready": true, "blockers": [], "warnings": [] },
  "estimates": {},
  "mappings": {},
  "companyRoot": null,
  "tableContract": {},
  "rubricVersion": null
}

Errors

StatusMeaning
400Invalid mappings or request values.
401Authentication required.
403Table access denied or the key is missing tables:read.
404Table not found.
422Request does not match the typed preflight schema.

Docs