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

Match

Operations

Salesforce

Operations

Routing

Operations

Triggers

Operations

Logs

Operations

Batch Agents

Operations

Credits

Operations

Forms

Operations

Workflows

Operations

Trigger Workflow

Request

Triggers enrichment and routing workflows from external systems.

Overview

The Workflow Trigger API provides a generic interface for initiating enrichment and routing workflows from various external systems like Eloqua, Customer Data Platforms (CDP), Data Lakes, and other marketing automation platforms.

Authentication

Requires either an API key or OAuth2 bearer token in the Authorization header.

Rate Limits

Designed to support bursty event traffic, capable of handling hundreds of requests per minute.

Request Body

  • record_data: Generic record payload containing fields for Lead, Contact, Opportunity, or other custom objects
  • source_system: Optional source system identifier (e.g., 'eloqua', 'cdp', 'data_lake')
  • enrichment_preferences: Optional enrichment preferences and configuration

Response Fields

  • success: Boolean indicating request success
  • status: Workflow status (triggered, queued, failed)
  • request_id: Unique request ID for tracking
  • workflow_id: ID of the triggered workflow
  • processing_time_ms: Processing time in milliseconds
  • enrichment_job_id: ID of enrichment job created (if applicable)
  • credits_consumed: Number of credits used
  • credits_remaining: Credits remaining in account
  • cached: Whether result was from cache

Features

  • Generic Payload: Accepts any record type (Lead, Contact, Opportunity, custom objects)
  • Audit Logging: All requests and responses are logged for compliance
  • Retry Logic: Automatic retries on failure with exponential backoff
  • High Throughput: Optimized for bursty event traffic
  • Credit Tracking: Transparent credit consumption tracking

Credit Usage

Workflow triggers consume credits based on complexity:

  • Basic Trigger: 1 credit per record
  • With Enrichment: +2 credits for enrichment processing
  • With Routing: +1 credit for routing logic
Security
BearerAuth
Path
workflow_idstring(Workflow Id)required
Bodyapplication/jsonrequired
record_dataobject(Record Data)required

Generic record payload containing fields for Lead, Contact, Opportunity, or other custom objects

record_data.​property name*anyadditional property
source_systemSource System (string) or Source System (null)(Source System)
Any of:

Source system identifier (e.g., 'eloqua', 'cdp', 'data_lake')

string(Source System)
enrichment_preferencesEnrichment Preferences (object) or Enrichment Preferences (null)(Enrichment Preferences)
Any of:

Optional enrichment preferences and configuration

curl -i -X POST \
  'https://api-gateway.agenthq.withlantern.com/v1/workflows/{workflow_id}/trigger' \
  -H 'Authorization: Bearer <YOUR_ApiToken_HERE>' \
  -H 'Content-Type: application/json' \
  -d '{
    "record_data": {},
    "source_system": "string",
    "enrichment_preferences": {}
  }'

Responses

Success Response

Bodyapplication/json
successboolean(Success)required

Boolean indicating request success

statusstring(Status)required

Status of the workflow trigger

Enum"triggered""queued""failed"
request_idstring(Request Id)required

Unique request ID for tracking

workflow_idstring(Workflow Id)required

ID of the triggered workflow

processing_time_msinteger(Processing Time Ms)required

Time taken to process the request in milliseconds

enrichment_job_idEnrichment Job Id (string) or Enrichment Job Id (null)(Enrichment Job Id)
Any of:

ID of the enrichment job created (if applicable)

string(Enrichment Job Id)
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

cachedboolean(Cached)

Boolean indicating if this result was returned from cache

Default false
Response
application/json
{
  "success": true,
  "status": "triggered",
  "request_id": "req_1234567890abcdef",
  "workflow_id": "wf_workflow_123",
  "processing_time_ms": 150,
  "enrichment_job_id": "job_9876543210fedcba",
  "credits_consumed": 3,
  "credits_remaining": 97,
  "cached": false
}