Enrich a record

$ lightfield enrichment-run enrich

POST/v1/enrichmentRun/{entitySlug}/{entityId}

Looks up missing information for a record from Lightfield’s enrichment providers and writes it back to it. Accepts contacts and accounts.

Enrichment runs in the background: this returns as soon as the run is created. Poll GET /v1/enrichmentRun/{runId} for its status. A record can only have one enrichment run at a time — if one is already in flight, this returns that run rather than starting a second. A 409 means another request claimed the record at the same moment; retry after a short wait.

Which fields are enriched, and whether a provider answer overwrites an existing value or is raised as a suggestion, come from the workspace’s enrichment settings. Naming fields explicitly also reaches fields set to enrich only on request, under the suggestion write policy; it never reaches a field turned off.

Required scopes: contacts:update to enrich a contact, accounts:update to enrich an account

Rate limit category: Write

ParametersExpand Collapse

--entity-slug: "contacts" or "accounts"

Path param: The type of record to enrich.

--entity-id: string

Path param: The ID of the record to enrich.

--field: optional array of string

Body param: Fields to enrich, e.g. ["email", "title"]. Named fields are refreshed even when they already hold a value, so this is how a stale value is replaced. Omit to fill only the fields the record is missing; if any of those the workspace enriches only on request, no run starts and the response names them (manual_fields_unconfirmed). Naming a field the workspace’s settings enrich only on request enriches it, and its answer is raised as a suggestion rather than written over a value the record already holds. Naming a field the settings turn off is rejected with 400 enrichment_field_disabled. A named field is not used to look the record up — the run derives it fresh from the record’s other identifiers — so naming every identifier (a contact’s name and email together) leaves nothing to search by and is rejected with 400 enrichment_fields_not_enrichable, creating no run; refresh them one at a time. phone is turned off unless the workspace opts into it, so naming it is rejected with 400 enrichment_field_disabled; where it is turned on, it is filled only when another field’s lookup happens to return it, so requesting it on its own is rejected with 400 enrichment_fields_not_enrichable.

ReturnsExpand Collapse

enrichmentRun_enrich_response: object { enrichmentRun, manualFields, plannedFields, 2 more }

enrichmentRun: object { id, completedAt, createdAt, 7 more }

The run, or null when the request was skipped.

id: string

The enrichment run ID.

completedAt: string

When the run finished, or null while it is still open.

createdAt: string

entityId: string

The ID of the record being enriched.

entityType: "contact" or "account"

The type of record being enriched.

"contact"

"account"

startedAt: string

When the run began executing, or null while it is queued.

status: "queued" or "running" or "completed" or 2 more

Where the run is: queued and running are in flight; completed, failed and timed_out are final.

"queued"

"running"

"completed"

"failed"

"timed_out"

targetFields: array of string

The fields this run set out to fill.

trigger: "creation" or "manual" or "update"

What started the run: creation when the record was created, update when it later gained an email or account, manual when requested through the API.

"creation"

"manual"

"update"

updatedAt: string

manualFields: array of string

Under manual_fields_unconfirmed, the missing fields the workspace enriches only on request. Add them to fields to include them, as suggestions. Null otherwise.

plannedFields: array of string

Under manual_fields_unconfirmed, the fields a run would have filled. Name these in fields to enrich them without the fields enriched only on request. Null otherwise.

reason: "no_targets" or "no_operations" or "manual_fields_unconfirmed"

Why the request was skipped: no_targets when the workspace enriches nothing this record is missing, no_operations when no provider can be scheduled for the targeted fields — because none looks them up on request, or because the record lacks the inputs (such as an email or domain) a lookup would need. manual_fields_unconfirmed when fields was omitted and the record is missing fields the workspace enriches only on request: no run was started, and plannedFields and manualFields say what to name in a second request. Null otherwise.

"no_targets"

"no_operations"

"manual_fields_unconfirmed"

status: "started" or "already_running" or "skipped"

started when this request began a run, already_running when one was already enriching the record, skipped when there was nothing to enrich.

"started"

"already_running"

"skipped"

Enrich a record

lightfield enrichment-run enrich \
  --api-key 'My API Key' \
  --entity-slug contacts \
  --entity-id entityId

{
  "enrichmentRun": {
    "id": "id",
    "completedAt": "completedAt",
    "createdAt": "createdAt",
    "entityId": "entityId",
    "entityType": "contact",
    "startedAt": "startedAt",
    "status": "queued",
    "targetFields": [
      "string"
    ],
    "trigger": "creation",
    "updatedAt": "updatedAt"
  },
  "manualFields": [
    "string"
  ],
  "plannedFields": [
    "string"
  ],
  "reason": "no_targets",
  "status": "started"
}

Returns Examples

{
  "enrichmentRun": {
    "id": "id",
    "completedAt": "completedAt",
    "createdAt": "createdAt",
    "entityId": "entityId",
    "entityType": "contact",
    "startedAt": "startedAt",
    "status": "queued",
    "targetFields": [
      "string"
    ],
    "trigger": "creation",
    "updatedAt": "updatedAt"
  },
  "manualFields": [
    "string"
  ],
  "plannedFields": [
    "string"
  ],
  "reason": "no_targets",
  "status": "started"
}