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"
      }
    ]
  }'

const response = await fetch("/api/v1/operations/enrichment/batch/query", {
  method: "POST",
  headers: {
    "Content-Type": "application/json",
    Authorization: "Bearer <token>",
  },
  body: JSON.stringify({
    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",
      },
    ],
  }),
});

const enrichments = await response.json();

interface EnrichmentTask {
  entityId: string;
  field: "phones" | "emails" | "summary";
  entityType?: "person" | "company";
}

interface Enrichment {
  id: string;
  createdAt: string;
  updatedAt: string;
  entityId: string;
  entityType: "person" | "company" | "leadlist";
  field: string;
  status: "pending" | "finished" | "failed" | "timeout" | "cancelled";
  error: string | null;
  dataFound: boolean | null;
  createdBy: string;
  orgId: string;
  globalEnrichmentId: string | null;
  creditTransactionId: string | null;
}

const tasks: EnrichmentTask[] = [
  { 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",
  },
];

const response = await fetch("/api/v1/operations/enrichment/batch/query", {
  method: "POST",
  headers: {
    "Content-Type": "application/json",
    Authorization: `Bearer ${token}`,
  },
  body: JSON.stringify({ tasks }),
});

const enrichments: Enrichment[] = await response.json();

// Check for completed enrichments
const completed = enrichments.filter((e) => e.status === "finished");
const pending = enrichments.filter((e) => e.status === "pending");

[
  {
    "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": {
    "code": "VALIDATION_ERROR",
    "message": "At least one task is required"
  }
}

{
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "Maximum 200 tasks allowed per batch"
  }
}

{
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "Invalid uuid"
  }
}

{
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "Invalid enum value. Expected 'phones' | 'emails' | 'summary', received 'invalid'"
  }
}

{
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "Organization ID is missing"
  }
}

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"
      }
    ]
  }'

const response = await fetch("/api/v1/operations/enrichment/batch/query", {
  method: "POST",
  headers: {
    "Content-Type": "application/json",
    Authorization: "Bearer <token>",
  },
  body: JSON.stringify({
    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",
      },
    ],
  }),
});

const enrichments = await response.json();

interface EnrichmentTask {
  entityId: string;
  field: "phones" | "emails" | "summary";
  entityType?: "person" | "company";
}

interface Enrichment {
  id: string;
  createdAt: string;
  updatedAt: string;
  entityId: string;
  entityType: "person" | "company" | "leadlist";
  field: string;
  status: "pending" | "finished" | "failed" | "timeout" | "cancelled";
  error: string | null;
  dataFound: boolean | null;
  createdBy: string;
  orgId: string;
  globalEnrichmentId: string | null;
  creditTransactionId: string | null;
}

const tasks: EnrichmentTask[] = [
  { 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",
  },
];

const response = await fetch("/api/v1/operations/enrichment/batch/query", {
  method: "POST",
  headers: {
    "Content-Type": "application/json",
    Authorization: `Bearer ${token}`,
  },
  body: JSON.stringify({ tasks }),
});

const enrichments: Enrichment[] = await response.json();

// Check for completed enrichments
const completed = enrichments.filter((e) => e.status === "finished");
const pending = enrichments.filter((e) => e.status === "pending");

[
  {
    "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": {
    "code": "VALIDATION_ERROR",
    "message": "At least one task is required"
  }
}

{
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "Maximum 200 tasks allowed per batch"
  }
}

{
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "Invalid uuid"
  }
}

{
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "Invalid enum value. Expected 'phones' | 'emails' | 'summary', received 'invalid'"
  }
}

{
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "Organization ID is missing"
  }
}

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

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

string

required

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

string

required

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

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.

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

string

required

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

string

required

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

string

required

The UUID of the entity this enrichment belongs to.

string

required

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

string

required

The enrichment field: phones, emails, or summary.

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

string | null

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

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

string

required

User ID who initiated the enrichment.

string

required

Organization ID the enrichment belongs to.

string | null

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

string | null

Reference to the credit transaction if credits were consumed.

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"
      }
    ]
  }'

const response = await fetch("/api/v1/operations/enrichment/batch/query", {
  method: "POST",
  headers: {
    "Content-Type": "application/json",
    Authorization: "Bearer <token>",
  },
  body: JSON.stringify({
    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",
      },
    ],
  }),
});

const enrichments = await response.json();

interface EnrichmentTask {
  entityId: string;
  field: "phones" | "emails" | "summary";
  entityType?: "person" | "company";
}

interface Enrichment {
  id: string;
  createdAt: string;
  updatedAt: string;
  entityId: string;
  entityType: "person" | "company" | "leadlist";
  field: string;
  status: "pending" | "finished" | "failed" | "timeout" | "cancelled";
  error: string | null;
  dataFound: boolean | null;
  createdBy: string;
  orgId: string;
  globalEnrichmentId: string | null;
  creditTransactionId: string | null;
}

const tasks: EnrichmentTask[] = [
  { 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",
  },
];

const response = await fetch("/api/v1/operations/enrichment/batch/query", {
  method: "POST",
  headers: {
    "Content-Type": "application/json",
    Authorization: `Bearer ${token}`,
  },
  body: JSON.stringify({ tasks }),
});

const enrichments: Enrichment[] = await response.json();

// Check for completed enrichments
const completed = enrichments.filter((e) => e.status === "finished");
const pending = enrichments.filter((e) => e.status === "pending");

[
  {
    "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": {
    "code": "VALIDATION_ERROR",
    "message": "At least one task is required"
  }
}

{
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "Maximum 200 tasks allowed per batch"
  }
}

{
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "Invalid uuid"
  }
}

{
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "Invalid enum value. Expected 'phones' | 'emails' | 'summary', received 'invalid'"
  }
}

{
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "Organization ID is missing"
  }
}

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

Overview

Lead Lists

ICPs

Users

Prospects

Autocomplete

Enrichment

CRM Integration

Credits & Payments

Data Operations

Query Batch Enrichment Status

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

Authentication

Request

Response

Use Cases

Polling for Enrichment Completion

Checking Pre-existing Enrichments

Error Codes

Notes