# Phone Enrichment Batch

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
json
{
  "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:

json
{
  "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
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

Endpoint: POST /v1/agents/phone
Version: 1.4.1
Security: BearerAuth

## Request fields (application/json):

  - `ids` (any)
    List of IDs to process for phone enrichment

  - `records` (any)
    List of record objects to process for phone enrichment

  - `entity_type` (string)
    Type of entity being processed (must be 'person' for phone enrichment)

  - `max_credits` (integer, required)
    Maximum credits this request is allowed to consume

## Response 202 fields (application/json):

  - `run_id` (string, required)
    Unique identifier for the batch run

  - `result_path` (string, required)
    S3 bucket path where results will be stored

  - `credits_csv_path` (string, required)
    S3 bucket path where credit usage report will be stored

## Response 401 fields (application/json):

  - `error` (string, required)
    Error message

  - `details` (any)
    Additional error details

  - `request_id` (any)
    Request ID for tracking

  - `credits_required` (any)
    Credits required for insufficient credit errors

  - `credits_remaining` (any)
    Credits remaining for insufficient credit errors

  - `retry_after` (any)
    Seconds to wait before retrying for rate limit errors

## Response 402 fields (application/json):

  - `error` (string, required)
    Error message

  - `details` (any)
    Additional error details

  - `request_id` (any)
    Request ID for tracking

  - `credits_required` (any)
    Credits required for insufficient credit errors

  - `credits_remaining` (any)
    Credits remaining for insufficient credit errors

  - `retry_after` (any)
    Seconds to wait before retrying for rate limit errors

## Response 422 fields (application/json):

  - `detail` (array)

  - `detail.loc` (array, required)

  - `detail.msg` (string, required)

  - `detail.type` (string, required)

## Response 429 fields (application/json):

  - `error` (string, required)
    Error message

  - `details` (any)
    Additional error details

  - `request_id` (any)
    Request ID for tracking

  - `credits_required` (any)
    Credits required for insufficient credit errors

  - `credits_remaining` (any)
    Credits remaining for insufficient credit errors

  - `retry_after` (any)
    Seconds to wait before retrying for rate limit errors

## Response 500 fields (application/json):

  - `error` (string, required)
    Error message

  - `details` (any)
    Additional error details

  - `request_id` (any)
    Request ID for tracking

  - `credits_required` (any)
    Credits required for insufficient credit errors

  - `credits_remaining` (any)
    Credits remaining for insufficient credit errors

  - `retry_after` (any)
    Seconds to wait before retrying for rate limit errors


## Response 400 fields