# Enrichment

## Phone Enrichment

 - [POST /v1/enrich/phone](https://developers.withlantern.com/openapi/enrichment/enrich_phone_v1_enrich_phone_post.md): 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

## Email Enrichment

 - [POST /v1/enrich/email](https://developers.withlantern.com/openapi/enrichment/enrich_email_v1_enrich_email_post.md): Enriches contact records with email address data using multiple data sources.

## Overview
The Email Enrichment API enriches contact records with email address data using multiple data sources. The service uses various lookup methods to find professional email addresses for contacts based on their name and company information.

## Request Body
- record_id: Your unique identifier for this record (required) - used for caching and duplicate detection
- first_name: Contact's first name (required)
- last_name: Contact's last name (required)
- company: Company name or website URL where the contact works (required)
- domain: Company domain (optional) - if not provided, will be extracted from company field
- linkedin: Contact's linkedin url (optional) - improves lookup accuracy when available
- max_credits: Maximum credits to spend on this request (optional, defaults to your account limit)

## Request Constraints
- Single record per request
- Must include record_id, first_name, last_name, and company
- record_id must be unique per contact record in your system
- domain is optional but improves accuracy when provided
- linkedin is optional but improves accuracy 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
- first_name: Echo of input first name
- last_name: Echo of input last name
- company: Echo of input company
- email: Professional email address or null if not found
- confidence: Confidence level (high, medium, low) or null
- 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 (no credits consumed if true)

## Credit Usage
Email enrichment consumes credits based on the data sources queried:
- Cached Result: 0 credits (if same record_id queried recently)
- Email Search: 5 credits

## Company Enrichment

 - [POST /v1/enrich/company](https://developers.withlantern.com/openapi/enrichment/enrich_company_v1_enrich_company_post.md): Enriches company records with firmographics and website-verified data.

## Overview
The Company Enrichment API enriches company records with comprehensive firmographics data including company details, location information, industry classification, size range, and geographic coordinates.

## Request Body
- record_id: Unique identifier for this enrichment request (required)
- company_name: Company name (optional) - improves accuracy when provided
- domain: Company domain (optional) - improves accuracy when provided
- country: Country code or name (optional) - helps with geographic targeting
- external_ids: External system IDs (optional) - for integration with CRM systems
- 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 is required
- company_name, domain are optional but improves accuracy when provided
- external_ids should be a dictionary of key-value pairs (e.g., {"sf_account_id": "001xx000..."})
- max_credits must be a positive integer if provided

## Response Fields
- success: Boolean indicating request success
- record_id: Echo of the input record ID
- company: Enriched company data object containing:
  - name: Company name
  - domain: Company domain
  - linkedin_url: LinkedIn company page URL
  - hq: Headquarters location (city, state, country, postal_code)
  - size_range: Employee size range (e.g., "500+")
  - industry: Industry classification
  - geo: Geographic coordinates and location details (lat, lon, county)
  - last_verified_at: ISO timestamp of last verification
- 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

## Credit Usage
Company enrichment consumes credits based on the data sources queried:
- Cached Result: 0 credits (if same company queried recently)
- Company Lookup: 5 credits

## Person Enrichment

 - [POST /v1/enrich/person](https://developers.withlantern.com/openapi/enrichment/enrich_person_v1_enrich_person_post.md): 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

## AI Enrichment

 - [POST /v1/enrich/ai](https://developers.withlantern.com/openapi/enrichment/enrich_ai_v1_enrich_ai_post.md): # AI Enrichment API

## Overview

The AI Enrichment API allows you to enrich data or generate insights using advanced language models. Send a query or prompt and receive AI-generated responses that can include analysis, summaries, recommendations, or structured data extraction.

## Request Body

json
{
  "query": "string (required)",
  "options": {
    "format_json": "boolean (optional)"
  },
  "effort": "string (optional, default: low)"
  "max_credits": "integer (optional)"
}


## Field Descriptions

- query: The main prompt or question to send to the AI model (required)
- options (optional): Additional configuration options
    - format_json: Whether to return response in structured JSON format (defaults to false)
- effort (optional): Specifies the level of enrichment effort to apply, by default is low
- max_credits must be a positive integer if provided

## Request Constraints

- query is required and must be non-empty
- options.format_json when provided must be a boolean value
- effort when provided accepted values are: low, medium, high
- Query length should not exceed 8000 characters

## Response Fields

- success: Boolean indicating request success
- query: Echo of the input query
- response: AI-generated response (string or structured object based on format_json setting)
- confidence: AI confidence score in the response (0.0-1.0)
- credits_consumed: Number of credits used for this request
- credits_remaining: Credits remaining in your account after this request
- token_usage: Token consumption details
    - prompt_tokens: Tokens used in the input
    - completion_tokens: Tokens used in the response
    - total_tokens: Total tokens consumed
- processing_time_ms: Time taken to process the request in milliseconds

## Confidence Levels

- 0.9-1.0: Very high confidence - factual, well-supported responses
- 0.7-0.9: High confidence - good quality responses with minor uncertainty
- 0.5-0.7: Medium confidence - reasonable responses but may need verification
- 0.0-0.5: Low confidence - speculative or uncertain responses

## Common Use Cases

1. Data Analysis & Insights: Analyze trends, patterns, and generate business insights
2. Content Generation: Create marketing copy, emails, summaries, and reports
3. Data Extraction: Parse unstructured text and extract structured information
4. Research & Summarization: Synthesize information and provide comprehensive overviews
5. Decision Support: Generate recommendations and evaluate options
6. Text Enhancement: Improve, rewrite, or optimize existing content

## Credit Usage

AI enrichment consumes credits based on the complexity and length of the response:

- Simple Queries: 1-3 credits (short responses, basic analysis)
- Standard Queries: 3-6 credits (medium-length responses, data extraction)
- Complex Analysis: 6-12 credits (detailed analysis, research, long-form content)
- JSON Structured Output: +1-2 credits additional (for formatting and validation)

## Deep Research

 - [POST /v1/enrich/research](https://developers.withlantern.com/openapi/enrichment/deep_research_v1_enrich_research_post.md): Conducts comprehensive research using advanced language models with real-time search capabilities.