# Phone & Email Enrichment Batch

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

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

Endpoint: POST /v1/agents/phone-email
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