---
title: Enrich accounts and contacts | Lightfield
description: 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](/help/settings/data-model/index.md). 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](/api/resources/enrichmentRun/methods/enrich/index.md):

Terminal window

```
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](/api/resources/enrichmentRun/methods/enrich/index.md), 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](/api/resources/enrichmentRun/methods/getEnrichmentRun/index.md) with the saved ID:

Terminal window

```
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](/using-the-api/manage-records/#retrieve-and-update-it/index.md) 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.