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

Salesforce Trigger Webhook

Request

Handles instant enrichment on Salesforce record creation/updates via webhook.

Overview

The Salesforce Trigger API provides instant enrichment capabilities for Salesforce records through webhook-based triggers. It supports both real-time webhook processing and polling-based enrichment for comprehensive coverage of record changes.

Request Body

  • object: Salesforce object type that triggered the event (Lead, Contact, Account, Opportunity)
  • ids: List of Salesforce record IDs that changed
  • event: Salesforce trigger event type (after_insert, after_update, after_undelete)
  • org_id: Salesforce organization ID

Trigger Events

  • after_insert: Triggered when new records are created
  • after_update: Triggered when existing records are updated
  • after_undelete: Triggered when records are undeleted

Response Fields

  • success: Boolean indicating request success
  • processed_count: Number of records processed
  • enrichment_jobs: List of enrichment job IDs created
  • workflow_status: Status of the enrichment workflow (started, queued, failed)
  • credits_consumed: Number of credits used
  • credits_remaining: Credits remaining in account
  • processing_time_ms: Processing time in milliseconds
  • cached: Whether result was from cache

Enrichment Options

Webhook Processing (Real-time)

  • Immediate Processing: Records are processed immediately upon webhook receipt
  • Platform Events: Uses Salesforce Platform Events for reliable delivery
  • Apex Callouts: Triggered via Apex callouts from Salesforce triggers
  • Low Latency: Near real-time enrichment with minimal delay

Polling Processing (Fallback)

  • SOQL Queries: Polls Salesforce every 2 minutes for new/changed records
  • Watermark Tracking: Uses SystemModstamp and Id for efficient filtering
  • Batch Processing: Processes records in batches for optimal performance
  • Reliable Coverage: Ensures no records are missed even if webhooks fail

Features

  • Dual Processing: Both webhook and polling support for comprehensive coverage
  • Automatic Enrichment: Triggers enrichment workflows based on object type
  • Job Tracking: Creates enrichment jobs for monitoring and debugging
  • Credit Management: Tracks credit consumption per enrichment job
  • Error Handling: Robust error handling with retry mechanisms
  • Audit Trail: Comprehensive logging for compliance and debugging

Credit Usage

Trigger processing consumes credits based on enrichment type:

  • Lead Enrichment: 2 credits per lead
  • Contact Enrichment: 1 credit per contact
  • Account Enrichment: 3 credits per account
  • Opportunity Enrichment: 1 credit per opportunity
Security
BearerAuth
Bodyapplication/jsonrequired
objectstring(Object)required

Salesforce object type that triggered the event

Enum"lead""contact""account""opportunity"
idsArray of strings(Ids)required

List of Salesforce record IDs that changed

eventstring(Event)required

Salesforce trigger event type

Enum"after_insert""after_update""after_undelete"
org_idstring(Org Id)required

Salesforce organization ID

curl -i -X POST \
  https://api-gateway.agenthq.withlantern.com/v1/triggers/salesforce \
  -H 'Authorization: Bearer <YOUR_ApiToken_HERE>' \
  -H 'Content-Type: application/json' \
  -d '{
    "object": "lead",
    "ids": [
      "string"
    ],
    "event": "after_insert",
    "org_id": "string"
  }'

Responses

Success Response

Bodyapplication/json
successboolean(Success)required

Boolean indicating request success

processed_countinteger(Processed Count)required

Number of records processed

enrichment_jobsArray of strings(Enrichment Jobs)required

List of enrichment job IDs created

workflow_statusstring(Workflow Status)required

Status of the enrichment workflow

Enum"started""queued""failed"
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,
  "processed_count": 2,
  "enrichment_jobs": [
    "job_001",
    "job_002"
  ],
  "workflow_status": "started",
  "credits_consumed": 4,
  "credits_remaining": 46,
  "processing_time_ms": 850,
  "cached": false
}

Polling Status

Request

Get the current status of polling-based enrichment.

Overview

This endpoint provides information about the current polling status, including last poll time, records processed, watermark value, and next scheduled poll.

Response Fields

  • last_poll_time: ISO timestamp of last poll
  • records_processed: Number of records processed in last poll
  • watermark_value: Current watermark value
  • next_poll_time: ISO timestamp of next scheduled poll

Use Cases

  • Monitor polling performance
  • Debug enrichment issues
  • Verify watermark progression
  • Check polling schedule
Security
BearerAuth
curl -i -X GET \
  https://api-gateway.agenthq.withlantern.com/v1/triggers/polling/status \
  -H 'Authorization: Bearer <YOUR_ApiToken_HERE>'

Responses

Success Response

Bodyapplication/json
last_poll_timestring(Last Poll Time)required

ISO timestamp of last poll

records_processedinteger(Records Processed)required

Number of records processed in last poll

watermark_valuestring(Watermark Value)required

Current watermark value

next_poll_timestring(Next Poll Time)required

ISO timestamp of next scheduled poll

Response
application/json
{
  "last_poll_time": "string",
  "records_processed": 0,
  "watermark_value": "string",
  "next_poll_time": "string"
}

Logs

Operations

Batch Agents

Operations

Credits

Operations

Forms

Operations

Workflows

Operations