Person Enrichment - Lance API

curl -X POST "https://app.lance.so/api/v1/operations/enrichment/550e8400-e29b-41d4-a716-446655440000?field=emails" \
  -H "Authorization: Bearer <token>"

{
  "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "createdAt": "2024-01-15T10:30:00.000Z",
  "updatedAt": "2024-01-15T10:30:00.000Z",
  "entityId": "550e8400-e29b-41d4-a716-446655440000",
  "entityType": "person",
  "field": "emails",
  "status": "pending",
  "error": null,
  "dataFound": null,
  "createdBy": "user_2abc123def456",
  "orgId": "org_xyz789",
  "globalEnrichmentId": null,
  "creditTransactionId": null
}

POST

api

operations

enrichment

{personId}

curl -X POST "https://app.lance.so/api/v1/operations/enrichment/550e8400-e29b-41d4-a716-446655440000?field=emails" \
  -H "Authorization: Bearer <token>"

{
  "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "createdAt": "2024-01-15T10:30:00.000Z",
  "updatedAt": "2024-01-15T10:30:00.000Z",
  "entityId": "550e8400-e29b-41d4-a716-446655440000",
  "entityType": "person",
  "field": "emails",
  "status": "pending",
  "error": null,
  "dataFound": null,
  "createdBy": "user_2abc123def456",
  "orgId": "org_xyz789",
  "globalEnrichmentId": null,
  "creditTransactionId": null
}

This endpoint manages the enrichment process for a person’s contact information. Use the POST method to trigger a new enrichment and the GET method to check the status of an existing enrichment request.

Long-Running Operation

This endpoint supports a maximum execution time of 800 seconds (~13 minutes). Enrichment involves calling multiple external providers which can take time to process.

Credit Consumption

Triggering enrichment consumes credits from your organization’s balance. Email enrichment and phone enrichment have different credit costs. Ensure you have sufficient credits before making requests.

Trigger Enrichment

POST /api/v1/operations/enrichment/{personId}

Triggers the enrichment process for a person’s phone numbers or email addresses. If a pending or completed enrichment already exists, returns the existing enrichment without consuming additional credits.

Path Parameters

personId

string

required

The unique identifier (UUID) of the person to enrich. Example: 550e8400-e29b-41d4-a716-446655440000

Query Parameters

field

string

required

The type of contact information to enrich. Allowed values: phones | emails - phones - Enrich phone numbers for the person - emails - Enrich email addresses for the person

Response

string

required

The unique identifier (UUID) of the enrichment record.

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 person being enriched (matches the personId path parameter).

entityType

string

required

The type of entity being enriched. Always person for this endpoint.

field

string

required

The field being enriched. Either phones or emails.

status

string

required

The current status of the enrichment request. Possible values: - pending

Enrichment is in progress - finished - Enrichment completed successfully - failed - Enrichment failed due to an error - timeout - Enrichment exceeded the maximum processing time - cancelled - Enrichment was cancelled

error

string | null

required

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

dataFound

boolean | null

required

Indicates whether contact data was found during enrichment. - true - Data was found and added to the person - false - No data was found - null - Enrichment is pending or status unknown

createdBy

string

required

The Clerk user ID of the user who triggered the enrichment.

orgId

string

required

The organization ID associated with this enrichment.

globalEnrichmentId

string | null

required

Reference to the global enrichment record if data was cached from a previous enrichment.

creditTransactionId

string | null

required

Reference to the credit transaction if credits were consumed for this enrichment.

curl -X POST "https://app.lance.so/api/v1/operations/enrichment/550e8400-e29b-41d4-a716-446655440000?field=emails" \
  -H "Authorization: Bearer <token>"

{
  "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "createdAt": "2024-01-15T10:30:00.000Z",
  "updatedAt": "2024-01-15T10:30:00.000Z",
  "entityId": "550e8400-e29b-41d4-a716-446655440000",
  "entityType": "person",
  "field": "emails",
  "status": "pending",
  "error": null,
  "dataFound": null,
  "createdBy": "user_2abc123def456",
  "orgId": "org_xyz789",
  "globalEnrichmentId": null,
  "creditTransactionId": null
}

Get Enrichment Status

GET /api/v1/operations/enrichment/{personId}

Retrieves the current status of an enrichment request for a person.

Path Parameters

personId

string

required

The unique identifier (UUID) of the person whose enrichment status to retrieve. Example: 550e8400-e29b-41d4-a716-446655440000

Query Parameters

field

string

required

The type of contact enrichment to check. Allowed values: phones | emails

Response

Returns the same enrichment object structure as the POST method.

curl -X GET "https://app.lance.so/api/v1/operations/enrichment/550e8400-e29b-41d4-a716-446655440000?field=emails" \
  -H "Authorization: Bearer <token>"

{
  "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "createdAt": "2024-01-15T10:30:00.000Z",
  "updatedAt": "2024-01-15T10:35:00.000Z",
  "entityId": "550e8400-e29b-41d4-a716-446655440000",
  "entityType": "person",
  "field": "emails",
  "status": "finished",
  "error": null,
  "dataFound": true,
  "createdBy": "user_2abc123def456",
  "orgId": "org_xyz789",
  "globalEnrichmentId": "g1h2i3j4-k5l6-7890-mnop-qr1234567890",
  "creditTransactionId": "c1d2e3f4-g5h6-7890-ijkl-mn1234567890"
}

Error Codes

Status Code	Error Code	Description
`400`	`VALIDATION_ERROR`	Missing or invalid `personId` or `field` parameter
`401`	`UNAUTHORIZED`	Missing or invalid authentication token
`402`	`INSUFFICIENT_CREDITS`	Organization does not have enough credits for the enrichment
`404`	`NOT_FOUND`	Enrichment not found (GET only)
`500`	`INTERNAL_ERROR`	Server error during enrichment processing

Enrichment Behavior

Idempotency

The POST endpoint is idempotent for active enrichments:

If a pending or finished enrichment exists for the same person and field, it returns the existing enrichment without consuming credits
If a failed, timeout, or cancelled enrichment exists, a new enrichment is created

Asynchronous Processing

Enrichment runs asynchronously after the initial response:

POST immediately returns with a pending status
The enrichment process runs in the background
Use GET to poll for completion status

Timeout Handling

Enrichments that remain in pending status beyond the maximum age are automatically marked as timeout when queried via GET.

Notes

Authentication is required via Clerk (both user and organization must be authenticated)
Each enrichment consumes credits based on the field type (enrichment_email or enrichment_phone)
Enriched data is cached globally to avoid redundant API calls for the same person
The endpoint reuses existing enrichments to minimize credit consumption

Autocomplete Schools Batch Enrichment

​Long-Running Operation

​Credit Consumption

​Trigger Enrichment

POST /api/v1/operations/enrichment/{personId}

​Path Parameters

​Query Parameters

​Response

​Get Enrichment Status

GET /api/v1/operations/enrichment/{personId}

​Path Parameters

​Query Parameters

​Response

​Error Codes

​Enrichment Behavior

​Idempotency

​Asynchronous Processing

​Timeout Handling

​Notes

Long-Running Operation

Credit Consumption

Trigger Enrichment

Path Parameters

Query Parameters

Response

Get Enrichment Status

Path Parameters

Query Parameters

Response

Error Codes

Enrichment Behavior

Idempotency

Asynchronous Processing

Timeout Handling

Notes