# Enrichment Run

## Enrich a record

`client.enrichmentRun.enrich(stringentityID, EnrichmentRunEnrichParamsparams, RequestOptionsoptions?): 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](/using-the-api/scopes/):** `contacts:update` to enrich a contact, `accounts:update` to enrich an account

**[Rate limit category](/using-the-api/rate-limits/):** Write

### Parameters

- `entityID: string`

  The ID of the record to enrich.

- `params: EnrichmentRunEnrichParams`

  - `entitySlug: "contacts" | "accounts"`

    Path param: The type of record to enrich.

    - `"contacts"`

    - `"accounts"`

  - `fields?: Array<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. 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.

### Returns

- `EnrichmentRunEnrichResponse`

  - `enrichmentRun: EnrichmentRun | null`

    The run, or null when the request was skipped.

    - `id: string`

      The enrichment run ID.

    - `completedAt: string | null`

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

    - `createdAt: string`

    - `entityId: string`

      The ID of the record being enriched.

    - `entityType: "contact" | "account"`

      The type of record being enriched.

      - `"contact"`

      - `"account"`

    - `startedAt: string | null`

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

    - `status: "queued" | "running" | "completed" | 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<string>`

      The fields this run set out to fill.

    - `trigger: "creation" | "manual"`

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

      - `"creation"`

      - `"manual"`

    - `updatedAt: string`

  - `reason: "no_targets" | "no_operations" | null`

    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.

    - `"no_targets"`

    - `"no_operations"`

  - `status: "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.

    - `"started"`

    - `"already_running"`

    - `"skipped"`

### Example

```typescript
import Lightfield from 'lightfield';

const client = new Lightfield({
  apiKey: 'My API Key',
});

const enrichmentRunEnrichResponse = await client.enrichmentRun.enrich('entityId', {
  entitySlug: 'contacts',
});

console.log(enrichmentRunEnrichResponse.enrichmentRun);
```

#### Response

```json
{
  "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"
}
```

## Get enrichment run status

`client.enrichmentRun.getEnrichmentRun(stringrunID, RequestOptionsoptions?): EnrichmentRunGetEnrichmentRunResponse`

**get** `/v1/enrichmentRun/{runId}`

Returns the status of an enrichment run by its ID.

**[Required scopes](/using-the-api/scopes/):** `contacts:read` for a contact run, `accounts:read` for an account run

**[Rate limit category](/using-the-api/rate-limits/):** Read

### Parameters

- `runID: string`

  The enrichment run ID.

### Returns

- `EnrichmentRunGetEnrichmentRunResponse`

  - `id: string`

    The enrichment run ID.

  - `completedAt: string | null`

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

  - `createdAt: string`

  - `entityId: string`

    The ID of the record being enriched.

  - `entityType: "contact" | "account"`

    The type of record being enriched.

    - `"contact"`

    - `"account"`

  - `startedAt: string | null`

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

  - `status: "queued" | "running" | "completed" | 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<string>`

    The fields this run set out to fill.

  - `trigger: "creation" | "manual"`

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

    - `"creation"`

    - `"manual"`

  - `updatedAt: string`

### Example

```typescript
import Lightfield from 'lightfield';

const client = new Lightfield({
  apiKey: 'My API Key',
});

const enrichmentRunGetEnrichmentRunResponse = await client.enrichmentRun.getEnrichmentRun('runId');

console.log(enrichmentRunGetEnrichmentRunResponse.id);
```

#### Response

```json
{
  "id": "id",
  "completedAt": "completedAt",
  "createdAt": "createdAt",
  "entityId": "entityId",
  "entityType": "contact",
  "startedAt": "startedAt",
  "status": "queued",
  "targetFields": [
    "string"
  ],
  "trigger": "creation",
  "updatedAt": "updatedAt"
}
```

## Domain Types

### Enrichment Run Enrich Response

- `EnrichmentRunEnrichResponse`

  - `enrichmentRun: EnrichmentRun | null`

    The run, or null when the request was skipped.

    - `id: string`

      The enrichment run ID.

    - `completedAt: string | null`

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

    - `createdAt: string`

    - `entityId: string`

      The ID of the record being enriched.

    - `entityType: "contact" | "account"`

      The type of record being enriched.

      - `"contact"`

      - `"account"`

    - `startedAt: string | null`

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

    - `status: "queued" | "running" | "completed" | 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<string>`

      The fields this run set out to fill.

    - `trigger: "creation" | "manual"`

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

      - `"creation"`

      - `"manual"`

    - `updatedAt: string`

  - `reason: "no_targets" | "no_operations" | null`

    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.

    - `"no_targets"`

    - `"no_operations"`

  - `status: "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.

    - `"started"`

    - `"already_running"`

    - `"skipped"`

### Enrichment Run Get Enrichment Run Response

- `EnrichmentRunGetEnrichmentRunResponse`

  - `id: string`

    The enrichment run ID.

  - `completedAt: string | null`

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

  - `createdAt: string`

  - `entityId: string`

    The ID of the record being enriched.

  - `entityType: "contact" | "account"`

    The type of record being enriched.

    - `"contact"`

    - `"account"`

  - `startedAt: string | null`

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

  - `status: "queued" | "running" | "completed" | 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<string>`

    The fields this run set out to fill.

  - `trigger: "creation" | "manual"`

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

    - `"creation"`

    - `"manual"`

  - `updatedAt: string`