# Person Enrichment

Enriches person records with comprehensive contact and professional data.

## Overview
The Person Enrichment API enriches person records with comprehensive contact information, professional details, and verification status. This service provides detailed person data including contact information, job titles, seniority levels, and email/phone verification status.

## Request Body
- record_id: Unique identifier for this enrichment request (required)
- first_name: Person's first name (required)
- last_name: Person's last name (required)
- company_domain: Company domain where the person works (required)
- email: Person's email address (optional)
- linkedin_id: LinkedIn ID or profile URL (optional)
- effort: Enrichment effort level (optional, default: low)
- max_credits: Maximum credits to spend on this request (optional, defaults to your account limit)

## Request Constraints
- record_id, first_name, last_name, and company_domain are required
- company_domain should be a valid domain format
- email should be a valid email format when provided
- max_credits must be a positive integer if provided

## Response Fields
- success: Boolean indicating request success
- record_id: Echo of the input record ID
- person: Enriched person data object containing:
  - full_name: Person's full name
  - email: Person's email address
  - email_confidence: Email confidence score (0.0-1.0)
  - email_status: Email verification status (valid, accept_all, risky, invalid, unknown)
  - phone: Phone number
  - title: Job title
  - linkedin_url: LinkedIn profile URL
  - job_last_seen_at: ISO timestamp when job information was last verified
- confidence: Confidence score (0.0-1.0) or null if disabled/not found
- credits_consumed: Number of credits used for this request
- credits_remaining: Credits remaining in your account after this request
- processing_time_ms: Time taken to process the request in milliseconds
- cached: Boolean indicating if this result was returned from cache

## Email Status Values
- valid: Email address is valid and deliverable
- accept_all: Email server accepts all emails (catch-all)
- risky: Email address may be risky or temporary
- invalid: Email address is invalid or undeliverable
- unknown: Email status could not be determined

## Credit Usage
Person enrichment consumes credits based on the data sources queried:
- Cached Result: 0 credits (if same person queried recently)
- Person Lookup: 4 credits

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

## Request fields (application/json):

  - `record_id` (string, required)
    Unique identifier for this enrichment request

  - `first_name` (string, required)
    Person's first name

  - `last_name` (string, required)
    Person's last name

  - `company_domain` (string, required)
    Company domain where the person works

  - `email` (any)
    Person's email address

  - `linkedin_id` (any)
    LinkedIn ID or profile URL

  - `effort` (string)
    Enrichment effort type
    Enum: "low", "medium", "high"

  - `max_credits` (integer)
    Maximum credits to spend on this request

## Response 200 fields (application/json):

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

  - `record_id` (string, required)
    Unique identifier for this enrichment request

  - `person` (any)
    Enriched person data

  - `confidence` (any)
    Confidence score (0.0-1.0) or null if disabled/not found

  - `credits_consumed` (integer, required)
    Number of credits used for this request

  - `credits_remaining` (integer, required)
    Credits remaining in your account after this request

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

  - `cached` (boolean, required)
    Boolean indicating if this result was returned from cache

## 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 402 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