Skip to content

Enrich a record

client.EnrichmentRun.Enrich(ctx, entityID, params) (*EnrichmentRunEnrichResponse, error)
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
entityID string

The ID of the record to enrich.

params EnrichmentRunEnrichParams
EntitySlug param.Field[EnrichmentRunEnrichParamsEntitySlug]

Path param: The type of record to enrich.

const EnrichmentRunEnrichParamsEntitySlugContacts EnrichmentRunEnrichParamsEntitySlug = "contacts"
const EnrichmentRunEnrichParamsEntitySlugAccounts EnrichmentRunEnrichParamsEntitySlug = "accounts"
Fields param.Field[[]string]Optional

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
type EnrichmentRunEnrichResponse struct{…}
EnrichmentRun EnrichmentRunEnrichResponseEnrichmentRun

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 string

The type of record being enriched.

One of the following:
const EnrichmentRunEnrichResponseEnrichmentRunEntityTypeContact EnrichmentRunEnrichResponseEnrichmentRunEntityType = "contact"
const EnrichmentRunEnrichResponseEnrichmentRunEntityTypeAccount EnrichmentRunEnrichResponseEnrichmentRunEntityType = "account"
StartedAt string

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

Status string

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

One of the following:
const EnrichmentRunEnrichResponseEnrichmentRunStatusQueued EnrichmentRunEnrichResponseEnrichmentRunStatus = "queued"
const EnrichmentRunEnrichResponseEnrichmentRunStatusRunning EnrichmentRunEnrichResponseEnrichmentRunStatus = "running"
const EnrichmentRunEnrichResponseEnrichmentRunStatusCompleted EnrichmentRunEnrichResponseEnrichmentRunStatus = "completed"
const EnrichmentRunEnrichResponseEnrichmentRunStatusFailed EnrichmentRunEnrichResponseEnrichmentRunStatus = "failed"
const EnrichmentRunEnrichResponseEnrichmentRunStatusTimedOut EnrichmentRunEnrichResponseEnrichmentRunStatus = "timed_out"
TargetFields []string

The fields this run set out to fill.

Trigger string

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.

One of the following:
const EnrichmentRunEnrichResponseEnrichmentRunTriggerCreation EnrichmentRunEnrichResponseEnrichmentRunTrigger = "creation"
const EnrichmentRunEnrichResponseEnrichmentRunTriggerManual EnrichmentRunEnrichResponseEnrichmentRunTrigger = "manual"
const EnrichmentRunEnrichResponseEnrichmentRunTriggerUpdate EnrichmentRunEnrichResponseEnrichmentRunTrigger = "update"
UpdatedAt string
ManualFields []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 []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 EnrichmentRunEnrichResponseReason

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.

One of the following:
const EnrichmentRunEnrichResponseReasonNoTargets EnrichmentRunEnrichResponseReason = "no_targets"
const EnrichmentRunEnrichResponseReasonNoOperations EnrichmentRunEnrichResponseReason = "no_operations"
const EnrichmentRunEnrichResponseReasonManualFieldsUnconfirmed EnrichmentRunEnrichResponseReason = "manual_fields_unconfirmed"
Status EnrichmentRunEnrichResponseStatus

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:
const EnrichmentRunEnrichResponseStatusStarted EnrichmentRunEnrichResponseStatus = "started"
const EnrichmentRunEnrichResponseStatusAlreadyRunning EnrichmentRunEnrichResponseStatus = "already_running"
const EnrichmentRunEnrichResponseStatusSkipped EnrichmentRunEnrichResponseStatus = "skipped"

Enrich a record

package main

import (
  "context"
  "fmt"

  "github.com/Lightfld/lightfield-go"
  "github.com/Lightfld/lightfield-go/option"
)

func main() {
  client := githubcomlightfldlightfieldgo.NewClient(
    option.WithAPIKey("My API Key"),
  )
  enrichmentRunEnrichResponse, err := client.EnrichmentRun.Enrich(
    context.TODO(),
    "entityId",
    githubcomlightfldlightfieldgo.EnrichmentRunEnrichParams{
      EntitySlug: githubcomlightfldlightfieldgo.EnrichmentRunEnrichParamsEntitySlugContacts,
    },
  )
  if err != nil {
    panic(err.Error())
  }
  fmt.Printf("%+v\n", enrichmentRunEnrichResponse.EnrichmentRun)
}
{
  "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"
}