Skip to content

Phone & Email Enrichment Batch

Request

Process multiple records for combined phone and email enrichment in batch mode.

Overview

The Phone & Email Enrichment Batch API allows you to submit multiple person records for both phone number and email address enrichment processing asynchronously in a single operation.

Key Differences from Individual APIs:

  • Phone API (/v1/agents/phone): Process records for phone enrichment only
  • Email API (/v1/agents/email): Process records for email enrichment only
  • Phone & Email API (/v1/agents/phone-email): Process records for both phone and email enrichment simultaneously

This endpoint accepts a batch of records and processes them asynchronously using workflow orchestration for both phone and email enrichment, making it ideal for comprehensive contact enrichment operations.

Request Body

Submit IDs for processing:

  • ids: Array of person IDs to process (1-1000 IDs)

Required fields:

  • entity_type: Type of entity being processed (must be 'person' for phone & email enrichment) (required)
  • max_credits: Maximum credits this batch operation is allowed to consume (required)

Response

  • run_id: Unique identifier for the batch run
  • result_path: S3 bucket path where results will be stored upon completion
  • credits_csv_path: S3 bucket path where credit usage report will be stored upon completion

Credit Usage

Credits are consumed based on the number of records processed and the success rate of both phone and email lookups. The batch will stop processing if the credit limit is reached.

Batch Limits

  • Minimum: 1 record
  • Maximum: 1000 records per batch
  • Records with missing required fields will be skipped

Example

Example: Submit IDs for processing

{
  "ids": ["550e8400-e29b-41d4-a716-446655440001", "550e8400-e29b-41d4-a716-446655440002", "550e8400-e29b-41d4-a716-446655440003"],
  "entity_type": "person",
  "max_credits": 200
}

Output

The results CSV will contain the following columns:

{
  "id": "string | Unique record identifier",
  "first_name": "string | Person's given name",
  "last_name": "string | Person's surname",
  "company_name": "string | Organization name",
  "company_url": "string | Company website domain",
  "linkedin": "string | LinkedIn profile URL or username",
  "email": "string | Email address",
  "email_found": "boolean | Email enrichment success flag",
  "phone_number": "string | Phone number (E.164 format when available)",
  "phone_found": "boolean | Phone enrichment success flag"
}

Example Output CSV

company_name,company_url,first_name,id,last_name,linkedin,email,email_found,phone_number,phone_found
Acme Corp,acme.com,John,550e8400-e29b-41d4-a716-446655440001,Smith,john-smith-123456789,john.smith@acme.com,true,+1-555-123-4567,true
TechCorp,techcorp.com,Jane,550e8400-e29b-41d4-a716-446655440002,Doe,jane-doe-987654321,,false,,false
Global Solutions,globalsolutions.com,Michael,550e8400-e29b-41d4-a716-446655440003,Johnson,michael-johnson-345678901,michael.johnson@globalsolutions.com,true,,false
Security
BearerAuth
Bodyapplication/jsonrequired
idsArray of strings or null(Ids)
Any of:

List of IDs to process for phone enrichment

[ 1 .. 1000 ] items
Array of strings
recordsArray of objects or null(Records)
Any of:

List of record objects to process for phone enrichment

entity_typestring(Entity Type)

Type of entity being processed (must be 'person' for phone enrichment)

Default:"person"
Value:"person"
max_creditsinteger, > 0(Max Credits)required

Maximum credits this request is allowed to consume

curl -i -X POST \
  https://api-gateway.agenthq.withlantern.com/v1/agents/phone-email \
  -H 'Authorization: Bearer <YOUR_ApiToken_HERE>' \
  -H 'Content-Type: application/json' \
  -d '{
    "entity_type": "person",
    "ids": [
      "550e8400-e29b-41d4-a716-446655440001",
      "550e8400-e29b-41d4-a716-446655440002",
      "550e8400-e29b-41d4-a716-446655440003"
    ],
    "max_credits": 100
  }'

Responses

Batch processing started successfully

Bodyapplication/json
run_idstring(Run Id)required

Unique identifier for the batch run

result_pathstring(Result Path)required

S3 bucket path where results will be stored

credits_csv_pathstring(Credits Csv Path)required

S3 bucket path where credit usage report will be stored

Response
{
  "run_id": "550e8400-e29b-41d4-a716-446655440000",
  "result_path": "s3://{s3_bucket}/{entity_type}/phone-email-enrichment-batch_2025-01-15_550e8400-e29b-41d4-a716-446655440000.csv",
  "credits_csv_path": "s3://{s3_bucket}/{entity_type}/phone-email-enrichment/2025-01-15/550e8400-e29b-41d4-a716-446655440000_credits.csv"
}