# Phone Enrichment

Enriches contact records with phone number data using multiple data sources.

## Overview
The Phone Enrichment API enriches contact records with phone number data using multiple data sources. The service intelligently cascades through different lookup methods to maximize success rates.

## Request Body
- record_id: Your unique identifier for this record (required) - used for caching and duplicate detection
- first_name: Contact's first name (optional) - required for name-based enrichment
- last_name: Contact's last name (optional) - required for name-based enrichment
- company: Company name or website URL (optional) - required for name-based enrichment
- email: Contact's email address (optional) - can be used standalone for enrichment
- linkedin_id: Contact's linkedin profile identifier/slug (optional) - can be used standalone for enrichment
- domain: Company domain (optional) - enhances name/company enrichment method

## Request Constraints
- Single record per request
- Must include record_id
- record_id must be unique per contact record in your system
- Must provide at least one of the following data combinations:
  - Name + Company/Domain: first_name, last_name, company (optionally enhanced with domain)
  - LinkedIn Profile Only: linkedin_id
  - Email Only: email
- Enrichment prioritizes data in this order:
  1. Name + Company/Domain: Primary method when available
  2. LinkedIn Profile: Fallback when name/company data is incomplete
  3. Email Only: Final fallback when other data is insufficient

## Response Fields
- success: Boolean indicating request success
- record_id: Echo of the input record ID
- first_name: Echo of input first name (or null if not provided)
- last_name: Echo of input last name (or null if not provided)
- company: Echo of input company (or null if not provided)
- email: Echo of input email or email found during enrichment (or null if not found)
- linkedin_id: Echo of input LinkedIn ID or LinkedIn profile found during enrichment (or null if not found)
- phone: International format phone number (E.164) or null if not found
- processing_time_ms: Time taken to process the request in milliseconds

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

## Request fields (application/json):

  - `record_id` (string, required)
    Your unique identifier for this record

  - `first_name` (any)
    Contact's first name (required for name-based enrichment)

  - `last_name` (any)
    Contact's last name (required for name-based enrichment)

  - `company` (any)
    Company name or website URL (required for name-based enrichment)

  - `email` (any)
    Contact's email address (optional)

  - `linkedin_id` (any)
    LinkedIn profile identifier/slug (e.g., 'john-doe-123456')

  - `domain` (any)
    Company domain (optional) - improves accuracy when provided

## Response 200 fields (application/json):

  - `success` (boolean, required)
    Boolean indicating request success

  - `record_id` (string, required)
    Echo of the input record ID

  - `first_name` (any)
    Echo of input first name

  - `last_name` (any)
    Echo of input last name

  - `company` (any)
    Echo of input company

  - `email` (any)
    Echo of input email or email found during enrichment

  - `linkedin_id` (any)
    Echo of input LinkedIn ID or LinkedIn profile found during enrichment

  - `phone` (any)
    International format phone number (E.164) or null if not found

  - `processing_time_ms` (integer, required)
    Time taken to process the request in milliseconds

## Response 400 fields (application/json):

  - `success` (boolean)
    Always false for error responses

  - `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 401 fields (application/json):

  - `success` (boolean)
    Always false for error responses

  - `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):

  - `success` (boolean)
    Always false for error responses

  - `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):

  - `success` (boolean)
    Always false for error responses

  - `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