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

Round Robin Assignment

Request

Assigns Salesforce objects to users using round-robin logic with pool management.

Overview

The Round Robin Assignment API provides intelligent assignment of Salesforce objects (leads, contacts, opportunities, accounts) to users based on configurable pools and rotation rules. It supports inactive user exclusion, reset rules, and maintains sequence tracking for fair distribution.

Request Body

  • object: Salesforce object type to assign (lead, contact, opportunity, account)
  • sf_id: Salesforce ID of the object to assign
  • pool: Round-robin pool identifier
  • exclude_inactive: Whether to exclude inactive users from assignment
  • reset_rules: Optional reset rules for the assignment

Reset Rules

  • reason: Reason for reset (e.g., 'bad_fit', 'user_request')
  • place_user_at_top: Optional user ID to place at top of rotation

Response Fields

  • success: Boolean indicating request success
  • assigned_to: User ID that was assigned
  • sequence: Current sequence number in the rotation
  • pool_size: Total number of active users in the pool
  • timestamp: ISO timestamp of the assignment
  • 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

Features

  • Pool Management: Organize users into assignment pools
  • Sequence Tracking: Maintains rotation sequence for fair distribution
  • Inactive User Exclusion: Automatically excludes inactive users
  • Reset Rules: Support for resetting rotation with specific reasons
  • Fair Distribution: Ensures equal distribution across active users
  • Audit Trail: Timestamps and sequence tracking for compliance

Credit Usage

Round Robin assignment consumes credits based on complexity:

  • Basic Assignment: 1 credit per assignment
  • With Reset Rules: +1 credit for reset operations
  • Pool Management: +0.5 credits for pool size calculation
Security
BearerAuth
Bodyapplication/jsonrequired
objectstring(Object)required

Salesforce object type to assign

Enum"lead""contact""opportunity""account"
sf_idstring(Sf Id)required

Salesforce ID of the object to assign

poolstring(Pool)required

Round-robin pool identifier

exclude_inactiveboolean(Exclude Inactive)

Whether to exclude inactive users from assignment

Default true
reset_rulesResetRules (object) or null
Any of:

Reset rules for round-robin assignment.

curl -i -X POST \
  https://api-gateway.agenthq.withlantern.com/v1/routing/assign \
  -H 'Authorization: Bearer <YOUR_ApiToken_HERE>' \
  -H 'Content-Type: application/json' \
  -d '{
    "object": "lead",
    "sf_id": "string",
    "pool": "string",
    "exclude_inactive": true,
    "reset_rules": {
      "reason": "string",
      "place_user_at_top": "string"
    }
  }'

Responses

Success Response

Bodyapplication/json
successboolean(Success)required

Boolean indicating request success

assigned_tostring(Assigned To)required

User ID that was assigned

sequenceinteger(Sequence)required

Current sequence number in the rotation

pool_sizeinteger(Pool Size)required

Total number of active users in the pool

timestampstring(Timestamp)required

ISO timestamp of the assignment

Response
application/json
{
  "success": true,
  "assigned_to": "005xx0002ABCDE",
  "sequence": 1245,
  "pool_size": 17,
  "timestamp": "2025-09-18T16:12:00Z",
  "credits_consumed": 1,
  "credits_remaining": 49,
  "processing_time_ms": 450,
  "cached": false
}

Triggers

Operations

Logs

Operations

Batch Agents

Operations

Credits

Operations

Forms

Operations

Workflows

Operations