Skip to content

Phone Enrichment Batch

Request

Process multiple records for phone enrichment in batch mode.

Overview

The Phone Enrichment Batch API allows you to submit multiple person records for phone number enrichment processing asynchronously.

Key Differences from Sync API:

  • Sync API (/v1/enrich/phone): Process one record at a time, get immediate response with phone number
  • Batch API (/v1/agents/phone): Submit 1-1000 records, get job ID, 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 phone 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 phone number 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": ["550e8400-e29b-41d4-a716-446655440001", "550e8400-e29b-41d4-a716-446655440002", "550e8400-e29b-41d4-a716-446655440003"],
  "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",
  "phone_number": "string | Phone number (E.164 format when available)",
  "phone_found": "boolean | Phone enrichment success flag"
}

Example Output CSV

id,first_name,last_name,company_name,company_url,linkedin,phone_number,phone_found
550e8400-e29b-41d4-a716-446655440001,John,Smith,Acme Corp,acme.com,john-smith-123456789,+1-555-123-4567,true
550e8400-e29b-41d4-a716-446655440002,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 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 \
  -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-enrichment-batch_2025-01-15_550e8400-e29b-41d4-a716-446655440000.csv",
  "credits_csv_path": "s3://{s3_bucket}/{s3_prefix}/phone-enrichment/2025-01-15/550e8400-e29b-41d4-a716-446655440000_credits.csv"
}