Enrich accounts and contacts

Work with CRM data

Start an enrichment run, handle an existing run, and verify its results under your workspace settings.

Use enrichment to look up missing or stale account and contact information. The API starts a background run; field selection and write behavior are controlled by Data model settings. A completed run does not guarantee that every requested field has a provider result.

Start a run

Grant accounts:update and accounts:read for accounts, or the corresponding contact scopes. Start with one record whose identifying information, such as its website or email, is present.

Call Enrich a record:

curl "https://api.lightfield.app/v1/enrichmentRun/accounts/$ACCOUNT_ID" \
  -X POST \
  -H "Authorization: Bearer $LIGHTFIELD_API_KEY" \
  -H "Lightfield-Version: 2026-03-01" \
  -H "Content-Type: application/json" \
  -d '{}'

Use contacts in place of accounts for a contact. An empty body fills missing fields enabled by workspace settings. To refresh a specific field, send a fields array using the enrichment field names in the request schema, such as {"fields":["title"]} for a contact.

Named fields override field selection, not the write policy. An answer can become a suggestion instead of overwriting a saved value. Keep at least one usable identifier outside the requested field list; refreshing every identifier at once can leave nothing to search by. phone alone cannot start a lookup.

Interpret the start response

`status`	Next action
`started`	Save `enrichmentRun.id` and poll it.
`already_running`	Follow the returned existing run; do not start duplicates.
`skipped`	Read `reason`. `no_targets` means no configured missing fields; `no_operations` means no provider lookup could be scheduled for the target fields and available identifiers.

A simultaneous request can return 409 before either caller sees the other’s run. Wait briefly and retry; the API can then return the existing run.

Poll and verify

Call Get an enrichment run with the saved ID:

curl "https://api.lightfield.app/v1/enrichmentRun/$RUN_ID" \
  -H "Authorization: Bearer $LIGHTFIELD_API_KEY" \
  -H "Lightfield-Version: 2026-03-01"

queued and running are in progress. Poll with a bounded delay and timeout. completed, failed and timed_out are final; stop polling those runs.

On completion, retrieve the account or contact and inspect the intended fields. If a value did not change, check the field’s write policy and any suggestion before starting another run.

For 400 enrichment_fields_not_enrichable, correct the requested fields or identifying data first. Refresh identifiers one at a time. Repeating the same invalid body does not create a useful run. For 403, check the resource’s update scope and the caller’s write permissions.