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

Submit Form

Request

Accepts form submissions and immediately enriches and dispositions the data.

Overview

The Form Submit API is designed to accept form submissions directly from marketing automation platforms or websites. It provides immediate enrichment and disposition of submitted data with two possible outcomes:

  1. Return enriched lead data in the response
  2. Push the enriched lead to Salesforce or Marketing Automation (MA) tool

Authentication

Requires an API key configured per site or system.

Rate Limits

Designed for near-real-time processing (less than 5 seconds end-to-end) and supports high-volume campaign bursts.

Request Body

  • name: Contact name
  • email: Contact email address (validated)
  • company: Company name
  • phone: Phone number (validated)
  • title: Job title
  • additional_fields: Additional form fields as key-value pairs
  • form_source: Source of form submission
  • enrichment_preferences: Enrichment preferences and configuration
  • output_preferences: Output preferences (return data vs push to external system)

Response Fields

  • success: Boolean indicating request success
  • status: Processing status (enriched, pushed, failed)
  • request_id: Unique request ID for tracking
  • processing_time_ms: Processing time in milliseconds
  • enriched_lead: Enriched lead data (if requested)
  • push_status: Status of push to external system (if applicable)
  • credits_consumed: Number of credits used
  • credits_remaining: Credits remaining in account
  • gdpr_safe: Whether enrichment was GDPR compliant
  • cached: Whether result was from cache

Features

  • Input Validation: Email and phone number validation
  • GDPR Compliance: Safe enrichment practices
  • Real-time Processing: Sub-5 second end-to-end processing
  • High Volume Support: Optimized for campaign bursts
  • Flexible Output: Return enriched data or push to external systems
  • Audit Trail: Complete logging for compliance

Credit Usage

Form submissions consume credits based on processing:

  • Basic Submission: 2 credits per form
  • With Enrichment: +3 credits for enrichment processing
  • With Push: +1 credit for external system push
Security
BearerAuth
Bodyapplication/jsonrequired
form_namestring(Form Name)required

Name of the form

form_payloadobject(Form Payload)required

Payload of the form

form_payload.​property name*anyadditional property
curl -i -X POST \
  https://api-gateway.agenthq.withlantern.com/v1/forms/submit \
  -H 'Authorization: Bearer <YOUR_ApiToken_HERE>' \
  -H 'Content-Type: application/json' \
  -d '{
    "form_name": "string",
    "form_payload": {}
  }'

Responses

Success Response

Bodyapplication/json
tenant_idinteger(Tenant Id)required

Tenant ID

submission_idstring(uuid)(Submission Id)required

Submission ID

submitted_atstring(date-time)(Submitted At)required

Submission timestamp

form_namestring(Form Name)required

Name of the form

form_payloadobject(Form Payload)required

Payload of the form

form_payload.​property name*anyadditional property
Response
application/json
{
  "tenant_id": 1,
  "submission_id": "123e4567-e89b-12d3-a456-426614174000",
  "submission_timestamp": "2024-01-15T10:30:00Z",
  "form_name": "Lead Generation Form",
  "form_payload": {
    "name": "John Doe",
    "email": "john.doe@example.com",
    "company": "Acme Corp",
    "phone": "+1-555-123-4567",
    "title": "VP Sales"
  }
}

Workflows

Operations