Enrich a record

enrichment_run.enrich(, ) -> EnrichmentRunEnrichResponse

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.

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 overrides which fields are enriched, but not the write policy.

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

Rate limit category: Write

ParametersExpand Collapse

entity_slug: Literal["contacts", "accounts"]

The type of record to enrich.

One of the following:

"contacts"

"accounts"

entity_id: str

The ID of the record to enrich.

fields: Optional[Sequence[str]]

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. Naming a field the workspace’s settings turn off enriches it anyway, and its answer is raised as a suggestion rather than written over a value the record already holds. profilePhotoUrl has no suggestion form, so it stays rejected while it is turned off. 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 skipped with no_operations. phone is filled only when another field’s lookup happens to return it, so requesting it on its own is skipped the same way.

ReturnsExpand Collapse

class EnrichmentRunEnrichResponse: …

enrichment_run: Optional[EnrichmentRun]

The run, or null when the request was skipped.

id: str

The enrichment run ID.

completed_at: Optional[str]

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

created_at: str

entity_id: str

The ID of the record being enriched.

entity_type: Literal["contact", "account"]

The type of record being enriched.

One of the following:

"contact"

"account"

started_at: Optional[str]

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

status: Literal["queued", "running", "completed", 2 more]

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

One of the following:

"queued"

"running"

"completed"

"failed"

"timed_out"

target_fields: List[str]

The fields this run set out to fill.

trigger: Literal["creation", "manual"]

What started the run: creation when the record was created, manual when requested through the API.

One of the following:

"creation"

"manual"

updated_at: str

reason: Optional[Literal["no_targets", "no_operations"]]

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. Null otherwise.

One of the following:

"no_targets"

"no_operations"

status: Literal["started", "already_running", "skipped"]

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

One of the following:

"started"

"already_running"

"skipped"

Enrich a record

from lightfield import Lightfield

client = Lightfield(
    api_key="My API Key",
)
enrichment_run_enrich_response = client.enrichment_run.enrich(
    entity_id="entityId",
    entity_slug="contacts",
)
print(enrichment_run_enrich_response.enrichment_run)

{
  "enrichmentRun": {
    "id": "id",
    "completedAt": "completedAt",
    "createdAt": "createdAt",
    "entityId": "entityId",
    "entityType": "contact",
    "startedAt": "startedAt",
    "status": "queued",
    "targetFields": [
      "string"
    ],
    "trigger": "creation",
    "updatedAt": "updatedAt"
  },
  "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"
  },
  "reason": "no_targets",
  "status": "started"
}