Skip to content

Email Enrichment Batch

Request

Process multiple records for email enrichment in batch mode.

Overview

The Email Enrichment Batch API allows you to submit multiple person records for email address enrichment processing asynchronously.

Key Differences from Sync API:

  • Sync API (/v1/enrich/email): Process one record at a time, get immediate response with email address
  • Batch API (/v1/agents/email): Submit 1-1000 records, results stored in S3 when complete

This endpoint accepts a batch of records and processes them asynchronously using workflow orchestration, making it ideal for bulk processing 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 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 email address 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

Examples

Example: Submit IDs for processing

{
  "ids": ["6ba7b810-9dad-11d1-80b4-00c04fd430c8", "6ba7b811-9dad-11d1-80b4-00c04fd430c8", "6ba7b812-9dad-11d1-80b4-00c04fd430c8"],
  "entity_type": "person",
  "max_credits": 100
}

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

Example Output CSV

id,first_name,last_name,company_name,company_url,linkedin,email,email_found
6ba7b810-9dad-11d1-80b4-00c04fd430c8,John,Smith,Acme Corp,acme.com,john-smith-123456789,john.smith@acme.com,true
6ba7b811-9dad-11d1-80b4-00c04fd430c8,Jane,Doe,TechCorp,techcorp.com,jane-doe-987654321,,false
Security
BearerAuth
Bodyapplication/jsonrequired
idsArray of strings or null(Ids)
Any of:

List of IDs to process for email enrichment

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

List of record objects to process for email enrichment

entity_typestring(Entity Type)

Type of entity being processed (must be 'person' for email 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/email \
  -H 'Authorization: Bearer <YOUR_ApiToken_HERE>' \
  -H 'Content-Type: application/json' \
  -d '{
    "entity_type": "person",
    "ids": [
      "6ba7b810-9dad-11d1-80b4-00c04fd430c8",
      "6ba7b811-9dad-11d1-80b4-00c04fd430c8",
      "6ba7b812-9dad-11d1-80b4-00c04fd430c8"
    ],
    "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": "6ba7b810-9dad-11d1-80b4-00c04fd430c8",
  "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"
}