Query Batch Enrichment Status

curl -X POST "https://api.lance.app/api/v1/operations/enrichment/batch/query" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer <token>" \
  -d '{
    "tasks": [
      {
        "entityId": "550e8400-e29b-41d4-a716-446655440000",
        "field": "phones"
      },
      {
        "entityId": "550e8400-e29b-41d4-a716-446655440001",
        "field": "emails"
      },
      {
        "entityId": "660e8400-e29b-41d4-a716-446655440002",
        "field": "summary",
        "entityType": "company"
      }
    ]
  }'

[
  {
    "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "createdAt": "2025-01-13T10:30:00.000Z",
    "updatedAt": "2025-01-13T10:30:15.000Z",
    "entityId": "550e8400-e29b-41d4-a716-446655440000",
    "entityType": "person",
    "field": "phones",
    "status": "finished",
    "error": null,
    "dataFound": true,
    "createdBy": "user_abc123",
    "orgId": "org_xyz789",
    "globalEnrichmentId": "global_123",
    "creditTransactionId": "credit_456"
  },
  {
    "id": "b2c3d4e5-f6a7-8901-bcde-f23456789012",
    "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,
    "dataFound": null,
    "createdBy": "user_abc123",
    "orgId": "org_xyz789",
    "globalEnrichmentId": null,
    "creditTransactionId": null
  }
]

POST

api

operations

enrichment

batch

query

curl -X POST "https://api.lance.app/api/v1/operations/enrichment/batch/query" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer <token>" \
  -d '{
    "tasks": [
      {
        "entityId": "550e8400-e29b-41d4-a716-446655440000",
        "field": "phones"
      },
      {
        "entityId": "550e8400-e29b-41d4-a716-446655440001",
        "field": "emails"
      },
      {
        "entityId": "660e8400-e29b-41d4-a716-446655440002",
        "field": "summary",
        "entityType": "company"
      }
    ]
  }'

[
  {
    "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "createdAt": "2025-01-13T10:30:00.000Z",
    "updatedAt": "2025-01-13T10:30:15.000Z",
    "entityId": "550e8400-e29b-41d4-a716-446655440000",
    "entityType": "person",
    "field": "phones",
    "status": "finished",
    "error": null,
    "dataFound": true,
    "createdBy": "user_abc123",
    "orgId": "org_xyz789",
    "globalEnrichmentId": "global_123",
    "creditTransactionId": "credit_456"
  },
  {
    "id": "b2c3d4e5-f6a7-8901-bcde-f23456789012",
    "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,
    "dataFound": null,
    "createdBy": "user_abc123",
    "orgId": "org_xyz789",
    "globalEnrichmentId": null,
    "creditTransactionId": null
  }
]

This endpoint allows you to efficiently check the status of multiple enrichment operations at once. Instead of making individual requests for each entity, you can query up to 200 enrichment tasks in a single batch request. This is particularly useful when polling for enrichment completion across multiple leads.

Authentication

This endpoint requires authentication with a valid organization context.

Requests without a valid organization ID will receive a 400 Bad Request response with the message “Organization ID is missing”.

Request

tasks

array

required

An array of enrichment task queries. Each task specifies an entity and the enrichment field to check. Constraints: - Minimum: 1 task - Maximum: 200 tasks per batch

Show Task Object Properties

entityId

string

required

The UUID of the entity (person or company) to query enrichment status for. Format: UUID v4 Example: "550e8400-e29b-41d4-a716-446655440000"

field

string

required

The enrichment field to query. Allowed values: - phones - Phone number enrichment - emails - Email address enrichment - summary - AI-generated summary enrichment

entityType

string

default:"person"

The type of entity being queried. Allowed values: - person - Individual contact (default) - company - Company/organization

Response

The response is an array of enrichment objects for tasks that have enrichment records. Tasks without existing enrichment records are omitted from the response.

enrichments

array

Array of enrichment status objects. May be shorter than the input if some entities don’t have enrichment records.

Show Enrichment Object Properties

string

required

Unique identifier for the enrichment record. Format: UUID v4

createdAt

string

required

Timestamp when the enrichment was created. Format: ISO 8601 datetime

updatedAt

string

required

Timestamp when the enrichment was last updated. Format: ISO 8601 datetime

entityId

string

required

The UUID of the entity this enrichment belongs to.

entityType

string

required

The type of entity: person, company, or leadlist.

field

string

required

The enrichment field: phones, emails, or summary.

status

string

required

Current status of the enrichment. Possible values: - pending - Enrichment is in progress - finished - Enrichment completed successfully

failed - Enrichment failed due to an error - timeout - Enrichment exceeded maximum processing time - cancelled - Enrichment was cancelled

error

string | null

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

dataFound

boolean | null

Whether data was found during enrichment. - null - Unknown or enrichment still pending - true - Data was found and enriched - false - No data found for this entity

createdBy

string

required

User ID who initiated the enrichment.

orgId

string

required

Organization ID the enrichment belongs to.

globalEnrichmentId

string | null

Reference to the global enrichment record if data was cached globally.

creditTransactionId

string | null

Reference to the credit transaction if credits were consumed.

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.

Use Cases

Polling for Enrichment Completion

When you trigger batch enrichment for multiple leads, use this endpoint to poll for completion status:

Trigger batch enrichment via the enrichment trigger endpoint
Store the entity IDs and fields being enriched
Periodically call this endpoint to check status
Process leads as their enrichments complete

Checking Pre-existing Enrichments

Before triggering new enrichments, use this endpoint to check which entities already have enrichment data, avoiding duplicate processing and unnecessary credit consumption.

curl -X POST "https://api.lance.app/api/v1/operations/enrichment/batch/query" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer <token>" \
  -d '{
    "tasks": [
      {
        "entityId": "550e8400-e29b-41d4-a716-446655440000",
        "field": "phones"
      },
      {
        "entityId": "550e8400-e29b-41d4-a716-446655440001",
        "field": "emails"
      },
      {
        "entityId": "660e8400-e29b-41d4-a716-446655440002",
        "field": "summary",
        "entityType": "company"
      }
    ]
  }'

[
  {
    "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "createdAt": "2025-01-13T10:30:00.000Z",
    "updatedAt": "2025-01-13T10:30:15.000Z",
    "entityId": "550e8400-e29b-41d4-a716-446655440000",
    "entityType": "person",
    "field": "phones",
    "status": "finished",
    "error": null,
    "dataFound": true,
    "createdBy": "user_abc123",
    "orgId": "org_xyz789",
    "globalEnrichmentId": "global_123",
    "creditTransactionId": "credit_456"
  },
  {
    "id": "b2c3d4e5-f6a7-8901-bcde-f23456789012",
    "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,
    "dataFound": null,
    "createdBy": "user_abc123",
    "orgId": "org_xyz789",
    "globalEnrichmentId": null,
    "creditTransactionId": null
  }
]

Error Codes

Status Code	Error Code	Description
`400`	`VALIDATION_ERROR`	Invalid request body, empty tasks array, or exceeds 200 task limit
`401`	`UNAUTHORIZED`	Missing or invalid authentication
`500`	`INTERNAL_ERROR`	Server error during enrichment query

Notes

The response array may be shorter than the input tasks array if some entities don’t have enrichment records
Enrichments that exceed the maximum processing time are automatically marked as timeout status
The dataFound field is null while enrichment is pending and becomes true or false upon completion
This endpoint is read-only and does not trigger new enrichments or consume credits
For efficient polling, consider implementing exponential backoff when checking for pending enrichments

Batch Enrichment Bulk Enrichment

​Authentication

​Request

​Response

​Use Cases

​Polling for Enrichment Completion

​Checking Pre-existing Enrichments

​Error Codes

​Notes

Authentication

Request

Response

Use Cases

Polling for Enrichment Completion

Checking Pre-existing Enrichments

Error Codes

Notes