Skip to content

Lantern API docs (1.4.1)

Overview

The Lantern API provides two major processing modes to enhance your contact and business data:

🔄 Sync API - Real-time Processing (/v1/enrich/) Process individual records and get immediate responses. Perfect for:

  • Real-time user interfaces
  • Single record processing
  • Immediate validation workflows

Available Services:

  • Phone Enrichment: Find phone numbers for contacts
  • Email Enrichment: Discover professional email addresses
  • Company Enrichment: Get comprehensive firmographics and website-verified data
  • Person Enrichment: Enrich person records with contact and professional data
  • AI Enrichment: Generate insights, analysis, and structured data using advanced language models
  • Deep Research: Comprehensive research using advanced language models with real-time search capabilities

🎯 Match API - Object Matching (/v1/match/) Match Account/Contact/Lead objects with sophisticated matching logic. Perfect for:

  • CRM data deduplication
  • Lead-to-account matching
  • Contact matching and merging

Available Services:

  • Account Matching: Match company records with exact, fuzzy, and AI-assisted logic
  • Contact Matching: Match contact records with grouped boolean logic
  • Lead Matching: Match lead records with confidence scoring and explanations

🔗 Salesforce API - Lead Conversion (/v1/salesforce/) Convert Salesforce Leads to Contacts and Accounts with intelligent matching. Perfect for:

  • Automated lead conversion workflows
  • CRM data management
  • Lead-to-contact merging

Available Services:

  • Lead Conversion: Convert leads to contacts and accounts with duplicate prevention
  • Auto-Merge: Intelligent merging with configurable policies
  • Round-Robin Assignment: Automatic owner assignment from pools

🎯 Routing API - Round Robin Assignment (/v1/routing/) Assign Salesforce objects to users using intelligent round-robin logic. Perfect for:

  • Fair distribution of leads and opportunities
  • Automated user assignment
  • Pool-based routing management

Available Services:

  • Round Robin Assignment: Assign objects to users with sequence tracking
  • Pool Management: Organize users into assignment pools
  • Reset Rules: Support for resetting rotation with specific reasons

⚡ Triggers API - Instant Enrichment (/v1/triggers/) Trigger instant enrichment on Salesforce record creation/updates. Perfect for:

  • Real-time data enrichment
  • Automated workflow triggers
  • Near real-time processing

Available Services:

  • Salesforce Webhooks: Real-time trigger processing via Platform Events
  • Polling Fallback: SOQL-based polling every 2 minutes for comprehensive coverage
  • Instant Enrichment: Automatic enrichment workflows on record changes

📊 Logs API - Audit & Reporting (/v1/logs/) Comprehensive audit trails and reporting for all routing actions. Perfect for:

  • Compliance and audit requirements
  • Performance analysis and monitoring
  • User activity tracking

Available Services:

  • Route Log Export: Export logs with filtering and multiple formats (JSON/CSV)
  • Log Statistics: Statistical analysis of log data for reporting
  • Retention Management: Configurable retention policies and cleanup schedules

🚀 Async API - Batch Processing (/v1/agents/) Process multiple records (1-1000) asynchronously with results stored in S3. Perfect for:

  • Large-scale bulk processing
  • Background processing workflows
  • Cost breakdown results on s3 too

Available Services:

  • Phone Enrichment Batch: Bulk phone number enrichment
  • Email Enrichment Batch: Bulk email address enrichment
  • Deep Research Batch: Bulk AI-powered research with specialized agents

💳 Credits API - Credit Management (/v1/credits/) Monitor and manage your credit usage and availability. Perfect for:

  • Tracking credit consumption across time periods
  • Checking remaining credit balance

Available Services:

  • Credit Usage: Get detailed usage statistics for specific date ranges
  • Remaining Credits: Check current credit balance

🔄 Workflow Trigger API - External System Integration (/v1/workflows/) Trigger enrichment and routing workflows from external systems. Perfect for:

  • Eloqua, CDP, and Data Lake integrations
  • Marketing automation platform triggers
  • High-volume bursty event processing

Available Services:

  • Workflow Trigger: Generic interface for initiating workflows from any external system
  • Audit Logging: Complete request/response logging for compliance
  • Retry Logic: Automatic retries with exponential backoff

📝 Form Submit API - Direct Form Processing (/v1/forms/) Accept form submissions and immediately enrich and disposition data. Perfect for:

  • Marketing automation platform integrations
  • Website form processing
  • Real-time lead enrichment

Available Services:

  • Form Submission: Accept form data with validation
  • Immediate Enrichment: Sub-5 second processing with GDPR compliance
  • Flexible Output: Return enriched data or push to external systems

Processing Mode Comparison

FeatureSync APIMatch APISalesforce APIRouting APITriggers APILogs APIAsync APICredits APIWorkflow APIForm API
Records per request11-100111-1001-100001-1000N/A11
Response timeImmediateImmediateImmediateImmediateImmediateImmediateAsynchronousImmediateImmediateImmediate
Result deliveryDirect responseDirect responseDirect responseDirect responseDirect responseDirect responseS3 storageDirect responseDirect responseDirect response
Use caseReal-time processingObject matchingLead conversionUser assignmentInstant enrichmentAudit reportingBulk operationsCredit monitoringExternal system triggersForm processing
Rate limitsPer-minute limitsPer-minute limitsPer-minute limitsPer-minute limitsPer-minute limitsPer-minute limitsLower frequency limitsPer-minute limitsHigh burst supportHigh burst support

Base URL

https://api-gateway.agenthq.withlantern.com

Authentication

All requests must include your API key in the Authorization header:

Authorization: Bearer YOUR_API_KEY

Rate Limiting & Credits

  • Sync API Rate Limit: 50 requests per minute per API key. Can be lifted on request.
  • Async API Rate Limit: 1 batch request per minute per API key. Can be lifted on request.
  • Credits API Rate Limit: 10 requests per minute per API key. Can be lifted on request.
  • Headers: Rate limit and credit information is returned in response headers:
    • X-RateLimit-Limit: The rate limit ceiling for your API key
    • X-Credits-Remaining: Credits remaining in your account

Error Codes:

  • 429 Too Many Requests: Rate limit exceeded
  • 402 Payment Required: Credit limit exceeded

Best Practices

General Guidelines

  1. API Key Security: Keep your API key secure and never expose it in client-side code
  2. Rate Limit Handling: Implement exponential backoff when receiving 429 responses
  3. Error Handling: Always check the success field before processing results
  4. Credit Management: Monitor your credit usage and remaining balance through response headers

Sync API Guidelines

  1. Use Unique Record IDs: Always provide unique record IDs to enable caching and prevent duplicate processing
  2. Set Credit Limits: Use max_credits parameter to control spending per request
  3. Cache Awareness: Check the cached field to understand if fresh data was retrieved
  4. Monitor Confidence Levels: Use confidence scores to determine data quality for your use case

Async API Guidelines

  1. Batch Sizing: Submit 100-1000 records per batch for optimal performance
  2. Result Monitoring: Get submission details from API call when batch is accepted, then poll results from S3 until completion
  3. Credit Planning: Set appropriate max_credits limits for large batches
  4. Error Handling: Handle batch-level errors and individual record failures within results

Credits API Guidelines

  1. Proactive Monitoring: Check remaining credits before large operations
  2. Usage Tracking: Use date range filtering to analyze spending patterns
  3. Budget Planning: Monitor usage trends to forecast credit needs

AI Enrichment

  1. Clear Queries: Be specific and provide context for better responses
  2. JSON Format: Enable JSON formatting for structured data extraction tasks
  3. Monitor Confidence: Pay attention to confidence scores for quality assessment
Download OpenAPI description
openapi.json
openapi.yaml
Languages
Servers
Lantern API server

https://api-gateway.agenthq.withlantern.com/

Local API server

http://localhost:8000/

Enrichment

Operations

Phone Enrichment

Request

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
Security
BearerAuth
Bodyapplication/jsonrequired
record_idstring(Record Id)required

Your unique identifier for this record

first_nameFirst Name (string) or First Name (null)(First Name)
Any of:

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

string(First Name)
last_nameLast Name (string) or Last Name (null)(Last Name)
Any of:

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

string(Last Name)
companyCompany (string) or Company (null)(Company)
Any of:

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

string(Company)
emailEmail (string) or Email (null)(Email)
Any of:

Contact's email address (optional)

string(Email)
linkedin_idLinkedin Id (string) or Linkedin Id (null)(Linkedin Id)
Any of:

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

string(Linkedin Id)
domainDomain (string) or Domain (null)(Domain)
Any of:

Company domain (optional) - improves accuracy when provided

string(Domain)
curl -i -X POST \
  https://api-gateway.agenthq.withlantern.com/v1/enrich/phone \
  -H 'Authorization: Bearer <YOUR_ApiToken_HERE>' \
  -H 'Content-Type: application/json' \
  -d '{
    "record_id": "string",
    "first_name": "string",
    "last_name": "string",
    "company": "string",
    "email": "string",
    "linkedin_id": "john-doe-123456",
    "domain": "string"
  }'

Responses

Success Response

Bodyapplication/json
successboolean(Success)required

Boolean indicating request success

record_idstring(Record Id)required

Echo of the input record ID

first_nameFirst Name (string) or First Name (null)(First Name)
Any of:

Echo of input first name

string(First Name)
last_nameLast Name (string) or Last Name (null)(Last Name)
Any of:

Echo of input last name

string(Last Name)
companyCompany (string) or Company (null)(Company)
Any of:

Echo of input company

string(Company)
emailEmail (string) or Email (null)(Email)
Any of:

Echo of input email or email found during enrichment

string(Email)
linkedin_idLinkedin Id (string) or Linkedin Id (null)(Linkedin Id)
Any of:

Echo of input LinkedIn ID or LinkedIn profile found during enrichment

string(Linkedin Id)
phonePhone (string) or Phone (null)(Phone)
Any of:

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

string(Phone)
processing_time_msinteger(Processing Time Ms)required

Time taken to process the request in milliseconds

Response
application/json
{
  "success": true,
  "record_id": "contact_001",
  "first_name": "John",
  "last_name": "Smith",
  "company": "Acme Corp",
  "email": "john.smith@acme.com",
  "linkedin_id": "john-smith-123456",
  "phone": "+1-555-123-4567",
  "processing_time_ms": 1250
}

Email Enrichment

Request

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
Security
BearerAuth
Bodyapplication/jsonrequired
record_idstring(Record Id)required

Your unique identifier for this record

first_namestring(First Name)required

Contact's first name

last_namestring(Last Name)required

Contact's last name

companystring(Company)required

Company name or website URL where the contact works

company_domainCompany Domain (string) or Company Domain (null)(Company Domain)
Any of:

Company domain (optional)

string(Company Domain)
linkedin_idLinkedin Id (string) or Linkedin Id (null)(Linkedin Id)
Any of:

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

string(Linkedin Id)
max_creditsMax Credits (integer) or Max Credits (null)(Max Credits)
Any of:

Maximum credits to spend on this request

> 0
integer(Max Credits)> 0
curl -i -X POST \
  https://api-gateway.agenthq.withlantern.com/v1/enrich/email \
  -H 'Authorization: Bearer <YOUR_ApiToken_HERE>' \
  -H 'Content-Type: application/json' \
  -d '{
    "record_id": "string",
    "first_name": "string",
    "last_name": "string",
    "company": "string",
    "company_domain": "string",
    "linkedin_id": "john-doe-123456",
    "max_credits": 0
  }'

Responses

Success Response

Bodyapplication/json
successboolean(Success)required

Boolean indicating request success

record_idstring(Record Id)required

Echo of the input record ID

first_namestring(First Name)required

Echo of input first name

last_namestring(Last Name)required

Echo of input last name

companystring(Company)required

Echo of input company

emailEmail (string) or Email (null)(Email)
Any of:

Professional email address or null if not found

string(Email)
confidenceConfidence (number) or Confidence (null)(Confidence)
Any of:

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

[ 0 .. 1 ]
number(Confidence)[ 0 .. 1 ]
credits_consumedinteger(Credits Consumed)required

Number of credits used for this request

credits_remaininginteger(Credits Remaining)required

Credits remaining in your account after this request

processing_time_msinteger(Processing Time Ms)required

Time taken to process the request in milliseconds

cachedboolean(Cached)required

Boolean indicating if this result was returned from cache

Response
application/json
{
  "success": true,
  "record_id": "contact_001",
  "first_name": "John",
  "last_name": "Smith",
  "company": "Acme Corp",
  "email": "john.smith@acme.com",
  "confidence": "high",
  "credits_consumed": 3,
  "credits_remaining": 47,
  "processing_time_ms": 750,
  "cached": false
}

Company Enrichment

Request

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
Security
BearerAuth
Bodyapplication/jsonrequired
record_idstring(Record Id)required

Unique identifier for this enrichment request

company_nameCompany Name (string) or Company Name (null)(Company Name)
Any of:

Company name

string(Company Name)
domainDomain (string) or Domain (null)(Domain)
Any of:

Company domain

string(Domain)
countryCountry (string) or Country (null)(Country)
Any of:

Country code or name

string(Country)
external_idsExternal Ids (object) or External Ids (null)(External Ids)
Any of:

External system IDs (e.g., Salesforce account ID)

effortstring(EnrichmentEffortType)
Default "low"
Enum"low""medium""high"
max_creditsinteger(Max Credits)[ 1 .. 100 ]

Maximum credits to spend on this request

Default 1
curl -i -X POST \
  https://api-gateway.agenthq.withlantern.com/v1/enrich/company \
  -H 'Authorization: Bearer <YOUR_ApiToken_HERE>' \
  -H 'Content-Type: application/json' \
  -d '{
    "record_id": "string",
    "company_name": "string",
    "domain": "string",
    "country": "string",
    "external_ids": {
      "property1": "string",
      "property2": "string"
    },
    "effort": "low",
    "max_credits": 1
  }'

Responses

Success Response

Bodyapplication/json
successboolean(Success)required

Boolean indicating request success

record_idstring(Record Id)required

Unique identifier for this enrichment request

companyCompanyEnrichmentData (object) or null
Any of:

Company enrichment data response.

confidenceConfidence (number) or Confidence (null)(Confidence)
Any of:

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

[ 0 .. 1 ]
number(Confidence)[ 0 .. 1 ]
credits_consumedinteger(Credits Consumed)required

Number of credits used for this request

credits_remaininginteger(Credits Remaining)required

Credits remaining in your account after this request

processing_time_msinteger(Processing Time Ms)required

Time taken to process the request in milliseconds

cachedboolean(Cached)required

Boolean indicating if this result was returned from cache

Response
application/json
{
  "success": true,
  "record_id": "company_001",
  "company": {
    "name": "Databricks",
    "domain": "databricks.com",
    "linkedin_url": "https://www.linkedin.com/company/databricks",
    "hq": { … },
    "size_range": "500+",
    "industry": "Technology",
    "geo": { … },
    "last_verified_at": "2025-09-12T18:22:01Z"
  },
  "confidence": 0.9,
  "credits_consumed": 1,
  "credits_remaining": 10,
  "processing_time_ms": 1200,
  "cached": true
}

Person Enrichment

Request

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
Security
BearerAuth
Bodyapplication/jsonrequired
record_idstring(Record Id)required

Unique identifier for this enrichment request

first_namestring(First Name)required

Person's first name

last_namestring(Last Name)required

Person's last name

company_domainstring(Company Domain)required

Company domain where the person works

emailEmail (string) or Email (null)(Email)
Any of:

Person's email address

string(Email)
linkedin_idLinkedin Id (string) or Linkedin Id (null)(Linkedin Id)
Any of:

LinkedIn ID or profile URL

string(Linkedin Id)
effortstring(EnrichmentEffortType)
Default "low"
Enum"low""medium""high"
max_creditsinteger(Max Credits)[ 1 .. 100 ]

Maximum credits to spend on this request

Default 1
curl -i -X POST \
  https://api-gateway.agenthq.withlantern.com/v1/enrich/person \
  -H 'Authorization: Bearer <YOUR_ApiToken_HERE>' \
  -H 'Content-Type: application/json' \
  -d '{
    "record_id": "string",
    "first_name": "string",
    "last_name": "string",
    "company_domain": "string",
    "email": "string",
    "linkedin_id": "string",
    "effort": "low",
    "max_credits": 1
  }'

Responses

Success Response

Bodyapplication/json
successboolean(Success)required

Boolean indicating request success

record_idstring(Record Id)required

Unique identifier for this enrichment request

personPersonEnrichmentData (object) or null
Any of:

Person enrichment data response.

confidenceConfidence (number) or Confidence (null)(Confidence)
Any of:

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

[ 0 .. 1 ]
number(Confidence)[ 0 .. 1 ]
credits_consumedinteger(Credits Consumed)required

Number of credits used for this request

credits_remaininginteger(Credits Remaining)required

Credits remaining in your account after this request

processing_time_msinteger(Processing Time Ms)required

Time taken to process the request in milliseconds

cachedboolean(Cached)required

Boolean indicating if this result was returned from cache

Response
application/json
{
  "success": true,
  "record_id": "person_001",
  "person": {
    "full_name": "Jane Doe",
    "email": "jane.doe@trinet.com",
    "email_confidence": 0.93,
    "email_status": "valid",
    "phone": "+1-415-555-0199",
    "title": "Director, RevOps",
    "linkedin_url": "https://linkedin.com/in/janedoe",
    "job_last_seen_at": "2025-08-30T15:12:00Z"
  },
  "confidence": 0.9,
  "credits_consumed": 1,
  "credits_remaining": 10,
  "processing_time_ms": 1200,
  "cached": true
}

AI Enrichment

Request

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

{
  "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)
Security
BearerAuth
Bodyapplication/jsonrequired
querystring(Query)<= 8000 charactersrequired

The main prompt or question to send to the AI model

optionsAIEnrichmentOptions (object) or null
Any of:

Options for AI enrichment request.

effortstring(EnrichmentEffortType)
Default "low"
Enum"low""medium""high"
agent_typeAgent Type (string) or Agent Type (null)(Agent Type)
Any of:

Type of specialized agent to use for processing

string(Agent Type)
curl -i -X POST \
  https://api-gateway.agenthq.withlantern.com/v1/enrich/ai \
  -H 'Authorization: Bearer <YOUR_ApiToken_HERE>' \
  -H 'Content-Type: application/json' \
  -d '{
    "query": "string",
    "options": {
      "format_json": false
    },
    "effort": "low",
    "agent_type": "funding"
  }'

Responses

Success Response

Bodyapplication/json
successboolean(Success)required

Boolean indicating request success

querystring(Query)required

Echo of the input query

responseResponse (string) or Response (object)(Response)required
Any of:

AI-generated response

string(Response)
confidenceConfidence (number) or Confidence (null)(Confidence)
Any of:

AI confidence score (0.0-1.0) or null if disabled

[ 0 .. 1 ]
number(Confidence)[ 0 .. 1 ]
credits_consumedinteger(Credits Consumed)required

Number of credits used for this request

credits_remaininginteger(Credits Remaining)required

Credits remaining in your account after this request

token_usageobject(TokenUsage)required
token_usage.​prompt_tokensinteger(Prompt Tokens)required

Tokens used in the input

token_usage.​completion_tokensinteger(Completion Tokens)required

Tokens used in the response

token_usage.​total_tokensinteger(Total Tokens)required

Total tokens consumed

processing_time_msinteger(Processing Time Ms)required

Time taken to process the request in milliseconds

agent_usedstring(Agent Used)required

Type of agent that was used for processing

Response
application/json
{
  "success": true,
  "query": "Analyze the market trends for electric vehicles in 2024",
  "response": "Based on current market data, electric vehicle adoption is accelerating rapidly in 2024. Key trends include: 1) Increased affordability with new models under $30k, 2) Improved charging infrastructure with 40% more stations, 3) Enhanced battery technology offering 300+ mile ranges...",
  "confidence": 0.85,
  "credits_consumed": 5,
  "credits_remaining": 45,
  "token_usage": {
    "prompt_tokens": 45,
    "completion_tokens": 234,
    "total_tokens": 279
  },
  "processing_time_ms": 1200
}

Deep Research

Request

Conducts comprehensive research using advanced language models with real-time search capabilities.

Security
BearerAuth
Bodyapplication/jsonrequired
querystring(Query)<= 8000 charactersrequired

The research question or topic to investigate deeply

optionsDeepResearchOptions (object) or null
Any of:

Options for deep research requests.

agent_typeAgent Type (string) or Agent Type (null)(Agent Type)
Any of:

Type of specialized agent to use for processing

string(Agent Type)
curl -i -X POST \
  https://api-gateway.agenthq.withlantern.com/v1/enrich/research \
  -H 'Authorization: Bearer <YOUR_ApiToken_HERE>' \
  -H 'Content-Type: application/json' \
  -d '{
    "query": "Research the latest developments in renewable energy storage technology",
    "options": {
      "format_json": false
    },
    "agent_type": "funding"
  }'

Responses

Successful Response

Bodyapplication/json
successboolean(Success)required

Boolean indicating request success

querystring(Query)required

Echo of the input query

responseResponse (string) or Response (object)(Response)required
Any of:

Deep research response with comprehensive analysis

string(Response)
confidenceConfidence (number) or Confidence (null)(Confidence)
Any of:

AI confidence score (0.0-1.0) or null if disabled

[ 0 .. 1 ]
number(Confidence)[ 0 .. 1 ]
credits_consumedinteger(Credits Consumed)required

Number of credits used for this request

credits_remaininginteger(Credits Remaining)required

Credits remaining in your account after this request

token_usageobject(TokenUsage)required
token_usage.​prompt_tokensinteger(Prompt Tokens)required

Tokens used in the input

token_usage.​completion_tokensinteger(Completion Tokens)required

Tokens used in the response

token_usage.​total_tokensinteger(Total Tokens)required

Total tokens consumed

processing_time_msinteger(Processing Time Ms)required

Time taken to process the request in milliseconds

agent_usedstring(Agent Used)required

Type of agent that was used for processing

Response
application/json
{
  "success": true,
  "query": "string",
  "response": "string",
  "confidence": 1,
  "credits_consumed": 0,
  "credits_remaining": 0,
  "token_usage": {
    "prompt_tokens": 0,
    "completion_tokens": 0,
    "total_tokens": 0
  },
  "processing_time_ms": 0,
  "agent_used": "string"
}

Match

Operations

Salesforce

Operations

Routing

Operations

Triggers

Operations

Logs

Operations

Batch Agents

Operations

Credits

Operations

Forms

Operations

Workflows

Operations