Bulk Enrichment - Lance API

curl -X POST "https://app.lance.so/api/v1/operations/enrichment/bulk" \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{
    "selection": {
      "mode": "manual",
      "includedIds": [
        "550e8400-e29b-41d4-a716-446655440001",
        "550e8400-e29b-41d4-a716-446655440002"
      ]
    },
    "field": "emails"
  }'

[
  {
    "id": "123e4567-e89b-12d3-a456-426614174000",
    "createdAt": "2025-01-13T10:30:00.000Z",
    "updatedAt": "2025-01-13T10:30:00.000Z",
    "entityId": "550e8400-e29b-41d4-a716-446655440001",
    "entityType": "person",
    "field": "emails",
    "status": "pending",
    "error": null,
    "createdBy": "user_2abc123",
    "orgId": "org_xyz789",
    "globalEnrichmentId": null,
    "creditTransactionId": "txn_456def",
    "dataFound": null
  },
  {
    "id": "123e4567-e89b-12d3-a456-426614174001",
    "createdAt": "2025-01-13T10:30:00.000Z",
    "updatedAt": "2025-01-13T10:30:00.000Z",
    "entityId": "550e8400-e29b-41d4-a716-446655440002",
    "entityType": "person",
    "field": "emails",
    "status": "finished",
    "error": null,
    "createdBy": "user_2abc123",
    "orgId": "org_xyz789",
    "globalEnrichmentId": "global_789",
    "creditTransactionId": null,
    "dataFound": true
  }
]

POST

api

operations

enrichment

bulk

curl -X POST "https://app.lance.so/api/v1/operations/enrichment/bulk" \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{
    "selection": {
      "mode": "manual",
      "includedIds": [
        "550e8400-e29b-41d4-a716-446655440001",
        "550e8400-e29b-41d4-a716-446655440002"
      ]
    },
    "field": "emails"
  }'

[
  {
    "id": "123e4567-e89b-12d3-a456-426614174000",
    "createdAt": "2025-01-13T10:30:00.000Z",
    "updatedAt": "2025-01-13T10:30:00.000Z",
    "entityId": "550e8400-e29b-41d4-a716-446655440001",
    "entityType": "person",
    "field": "emails",
    "status": "pending",
    "error": null,
    "createdBy": "user_2abc123",
    "orgId": "org_xyz789",
    "globalEnrichmentId": null,
    "creditTransactionId": "txn_456def",
    "dataFound": null
  },
  {
    "id": "123e4567-e89b-12d3-a456-426614174001",
    "createdAt": "2025-01-13T10:30:00.000Z",
    "updatedAt": "2025-01-13T10:30:00.000Z",
    "entityId": "550e8400-e29b-41d4-a716-446655440002",
    "entityType": "person",
    "field": "emails",
    "status": "finished",
    "error": null,
    "createdBy": "user_2abc123",
    "orgId": "org_xyz789",
    "globalEnrichmentId": "global_789",
    "creditTransactionId": null,
    "dataFound": true
  }
]

This endpoint triggers bulk contact enrichment for multiple leads at once. It supports both manual selection (explicit IDs) and bulk selection (intent-based selection with filters). The endpoint validates credit availability before processing and handles enrichment in batches.

Credit Consumption

This endpoint consumes credits based on the number of leads being enriched. The system validates that sufficient credits are available before starting any enrichment operations. If credits are insufficient, the entire operation fails without consuming any credits.

Email enrichment: Consumes credits per lead
Phone enrichment: Consumes credits per lead

Request

Body Parameters

selection

object

required

The selection payload specifying which leads to enrich.

Show Selection Object Properties

selection.mode

string

required

The selection mode. Determines how leads are selected.Allowed values: manual, bulk

manual: Explicit selection where specific lead IDs are provided
bulk: Intent-based selection using filters and a target count

selection.startIndex

integer

The starting index for bulk selection. Only used when mode is bulk.Minimum: 0

selection.targetCount

integer

The number of leads to select starting from startIndex. Only used when mode is bulk.Minimum: 1 Maximum: 1000

selection.excludedIds

array

Array of lead IDs to exclude from the bulk selection range.Item type: string (UUID)

selection.includedIds

array

Array of lead IDs to explicitly include. In manual mode, this is the primary way to specify leads. In bulk mode, these are added to the bulk selection.Item type: string (UUID)

selection.filters

object

The search filters used to reproduce the exact search results. Required for bulk mode to resolve the selection into specific lead IDs.

field

string

required

The type of contact information to enrich. Allowed values: phones, emails

Response

Returns an array of enrichment objects representing both newly created and existing enrichment tasks.

response

array

required

Array of enrichment objects.

Show Enrichment Object Properties

string

required

Unique identifier (UUID) of the enrichment task.

createdAt

string

required

ISO 8601 timestamp of when the enrichment was created.

updatedAt

string

required

ISO 8601 timestamp of when the enrichment was last updated.

entityId

string

required

The UUID of the entity (person) being enriched.

entityType

string

required

The type of entity being enriched.Values: person, company, leadlist

field

string

required

The field being enriched.Values: phones, emails

status

string

required

The current status of the enrichment task.Values:

pending - Enrichment is queued or in progress
finished - Enrichment completed successfully
failed - Enrichment failed
timeout - Enrichment timed out
cancelled - Enrichment was cancelled

error

string

Error message if the enrichment failed. null for successful enrichments.

createdBy

string

required

The user ID who initiated the enrichment.

orgId

string

required

The organization ID that owns this enrichment.

globalEnrichmentId

string

Reference to the global enrichment record if data was found in the shared cache. null if no cached data exists.

creditTransactionId

string

Reference to the credit transaction for this enrichment. null if no credits were consumed (e.g., data was cached).

dataFound

boolean | null

Indicates whether enrichment data was found.

true - Data was found during enrichment
false - No data was found
null - Unknown or pending

value

unknown | null

Optional enrichment payload value. Present for enrichments that return data (e.g., company summaries). null or omitted for standard phone/email enrichments.

Selection Modes

Manual Mode

Use manual mode when you have specific lead IDs to enrich:

{
  "selection": {
    "mode": "manual",
    "includedIds": [
      "550e8400-e29b-41d4-a716-446655440001",
      "550e8400-e29b-41d4-a716-446655440002"
    ]
  },
  "field": "emails"
}

Bulk Mode

Use bulk mode to enrich a range of leads from search results. This requires filters to reproduce the search:

{
  "selection": {
    "mode": "bulk",
    "startIndex": 0,
    "targetCount": 100,
    "excludedIds": ["550e8400-e29b-41d4-a716-446655440003"],
    "filters": {
      "job_title": ["Software Engineer", "Developer"]
    }
  },
  "field": "phones"
}

curl -X POST "https://app.lance.so/api/v1/operations/enrichment/bulk" \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{
    "selection": {
      "mode": "manual",
      "includedIds": [
        "550e8400-e29b-41d4-a716-446655440001",
        "550e8400-e29b-41d4-a716-446655440002"
      ]
    },
    "field": "emails"
  }'

[
  {
    "id": "123e4567-e89b-12d3-a456-426614174000",
    "createdAt": "2025-01-13T10:30:00.000Z",
    "updatedAt": "2025-01-13T10:30:00.000Z",
    "entityId": "550e8400-e29b-41d4-a716-446655440001",
    "entityType": "person",
    "field": "emails",
    "status": "pending",
    "error": null,
    "createdBy": "user_2abc123",
    "orgId": "org_xyz789",
    "globalEnrichmentId": null,
    "creditTransactionId": "txn_456def",
    "dataFound": null
  },
  {
    "id": "123e4567-e89b-12d3-a456-426614174001",
    "createdAt": "2025-01-13T10:30:00.000Z",
    "updatedAt": "2025-01-13T10:30:00.000Z",
    "entityId": "550e8400-e29b-41d4-a716-446655440002",
    "entityType": "person",
    "field": "emails",
    "status": "finished",
    "error": null,
    "createdBy": "user_2abc123",
    "orgId": "org_xyz789",
    "globalEnrichmentId": "global_789",
    "creditTransactionId": null,
    "dataFound": true
  }
]

Error Codes

Status Code	Error Code	Description
`400`	`VALIDATION_ERROR`	Invalid request body, missing required fields, or invalid field values
`401`	`UNAUTHORIZED`	Missing or invalid authentication
`402`	`INSUFFICIENT_CREDITS`	Not enough credits to complete the bulk enrichment
`500`	`INTERNAL_ERROR`	Server error during enrichment processing

Notes

Batching: The system processes enrichments in batches to avoid overwhelming enrichment providers
Deduplication: If an enrichment already exists for a lead/field combination, the existing enrichment is returned instead of creating a duplicate
Credit Pre-validation: Credits are validated before any processing begins; if insufficient, the operation fails atomically
Maximum Selection: Bulk mode is limited to 1000 leads per request
Filters Required: When using bulk mode, the filters field is required to resolve the selection

Query Batch Enrichment Status CRM Settings

​Credit Consumption

​Request

​Body Parameters

​Response

​Selection Modes

​Manual Mode

​Bulk Mode

​Error Codes

​Notes

Credit Consumption

Request

Body Parameters

Response

Selection Modes

Manual Mode

Bulk Mode

Error Codes

Notes