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

Export Route Logs

Request

Export route logs for audit and reporting purposes.

Overview

The Route Logs API provides comprehensive audit trails for all routing, conversion, merging, and enrichment actions performed on Salesforce objects. It supports filtering, export formats, and configurable retention policies.

Query Parameters

  • from: Start date for log export (ISO format, required)
  • to: End date for log export (ISO format, required)
  • pool: Filter by specific pool name (optional)
  • object: Filter by specific object type (Lead, Contact, Account, Opportunity) (optional)
  • action: Filter by specific action type (assign, convert, merge, enrich) (optional)
  • format: Export format (json, csv) (optional, default: json)
  • include_diff: Include diff data in export (optional, default: true)
  • limit: Maximum number of records to return (optional, default: 1000, max: 10000)

Response Fields

Each log entry includes:

  • timestamp: ISO timestamp of the action
  • object: Salesforce object type
  • object_id: Salesforce ID of the object
  • action: Action performed (assign, convert, merge, enrich)
  • pool: Round-robin pool name (for assign actions)
  • assigned_to: Salesforce ID of assigned user (for assign actions)
  • prev_owner: Previous owner ID (for assign/convert actions)
  • sequence: Round-robin sequence number (for assign actions)
  • reason: Reason for the action
  • request_id: Request ID for tracking
  • idempotency_key: Idempotency key for duplicate prevention
  • diff: Field changes for enrichment/merge actions

Export Formats

JSON Format (Default)

Returns structured JSON data with full field information.

CSV Format

Returns comma-separated values suitable for spreadsheet applications.

  • Headers: timestamp, object, object_id, action, pool, assigned_to, prev_owner, sequence, reason, request_id, idempotency_key, diff
  • Diff data is JSON-encoded in the diff column

Use Cases

  • Audit Compliance: Track all actions for regulatory compliance
  • Performance Analysis: Analyze routing patterns and efficiency
  • User Activity: Monitor user assignments and activity
  • Enrichment Tracking: Track data enrichment changes and sources
  • Troubleshooting: Debug routing issues and user assignments

Retention Policy

  • Default Retention: 365 days
  • Maximum Retention: 1095 days (3 years)
  • Auto Cleanup: Enabled by default (daily at 2 AM)
  • Configurable: Retention can be adjusted per organization

Rate Limits

  • Standard Export: 10 requests per minute
  • Large Exports: 2 requests per minute (for exports > 5000 records)
  • Statistics: 20 requests per minute
Security
BearerAuth
Query
from_datestring(date-time)(From Date)required

Start date for log export (ISO format)

to_datestring(date-time)(To Date)required

End date for log export (ISO format)

poolPool (string) or Pool (null)(Pool)
Any of:

Filter by specific pool name

string(Pool)
objectObject (string) or Object (null)(Object)
Any of:

Filter by specific object type

string(Object)
actionAction (string) or Action (null)(Action)
Any of:

Filter by specific action type

string(Action)
formatstring(Format)

Export format (json, csv)

Default "json"
include_diffboolean(Include Diff)

Include diff data in export

Default true
limitinteger(Limit)[ 1 .. 10000 ]

Maximum number of records to return

Default 1000
curl -i -X GET \
  'https://api-gateway.agenthq.withlantern.com/v1/logs/routing?from_date=2019-08-24T14%3A15%3A22Z&to_date=2019-08-24T14%3A15%3A22Z&pool=string&object=string&action=string&format=json&include_diff=true&limit=1000' \
  -H 'Authorization: Bearer <YOUR_ApiToken_HERE>'

Responses

Success Response

Bodyapplication/jsonArray [
timestampstring(date-time)(Timestamp)required

ISO timestamp of the action

objectstring(Object)required

Salesforce object type

Enum"Lead""Contact""Account""Opportunity"
object_idstring(Object Id)required

Salesforce ID of the object

actionstring(Action)required

Action performed on the object

Enum"assign""convert""merge""enrich"
poolPool (string) or Pool (null)(Pool)
Any of:

Round-robin pool name (for assign actions)

string(Pool)
assigned_toAssigned To (string) or Assigned To (null)(Assigned To)
Any of:

Salesforce ID of assigned user (for assign actions)

string(Assigned To)
prev_ownerPrev Owner (string) or Prev Owner (null)(Prev Owner)
Any of:

Previous owner ID (for assign/convert actions)

string(Prev Owner)
sequenceSequence (integer) or Sequence (null)(Sequence)
Any of:

Round-robin sequence number (for assign actions)

integer(Sequence)
reasonReason (string) or Reason (null)(Reason)
Any of:

Reason for the action (e.g., 'round_robin', 'manual_override')

string(Reason)
request_idRequest Id (string) or Request Id (null)(Request Id)
Any of:

Request ID for tracking

string(Request Id)
idempotency_keyIdempotency Key (string) or Idempotency Key (null)(Idempotency Key)
Any of:

Idempotency key for duplicate prevention

string(Idempotency Key)
diffDiff (object) or Diff (null)(Diff)
Any of:

Field changes for enrichment/merge actions

]
Response
application/json
[
  {
    "timestamp": "2025-09-18T16:12:00Z",
    "object": "Lead",
    "object_id": "00Qxx0000Lm789U",
    "action": "assign",
    "pool": "SDR_WEST_01",
    "assigned_to": "005xx0002ABCDE",
    "prev_owner": "005xx0001ZZZZZ",
    "sequence": 1245,
    "reason": "round_robin",
    "request_id": "req_abc123",
    "idempotency_key": "c1f2-..."
  },
  {
    "timestamp": "2025-09-18T16:15:00Z",
    "object": "Lead",
    "object_id": "00Qxx0000Lm78AA",
    "action": "enrich",
    "reason": "auto_enrichment",
    "request_id": "req_def456",
    "idempotency_key": "a3b4-...",
    "diff": { … }
  }
]

Batch Agents

Operations

Credits

Operations

Forms

Operations

Workflows

Operations