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

Lead → Contact Auto-Convert & Merge

Request

Converts Salesforce Leads to Contacts and Accounts with sophisticated matching and merging logic.

Overview

The Salesforce Conversion API provides automated Lead-to-Contact conversion with intelligent matching, duplicate prevention, and merge policies. It uses Salesforce Lead.Convert under the hood with batch API and includes duplicate protection via pre-check matching.

Request Body

  • lead_sf_id: Salesforce Lead ID to convert (required)
  • match_policy: Match policy configuration for contact and account matching
  • merge_policy: Merge policy configuration for handling matches
  • set_owner_round_robin_pool: Optional round-robin pool for owner assignment
  • logs: Logging configuration for conversion process

Match Policy

  • contact: Contact matching rules and creation policy
  • account: Account matching rules and creation policy
  • by: List of field rules for matching (e.g., ["email:eq", "name_company:fuzzy0.8"])
  • create_if_no_match: Whether to create new record if no match found

Merge Policy

  • on_contact_match: Action when contact match is found
    • merge_lead_into_contact: Moves notes/activities, preserves owner history
    • create_separate_contact: Creates separate contact record
  • on_account_match: Action when account match is found
    • attach_to_account: Attaches lead to existing account
    • create_separate_account: Creates separate account record

Response Fields

  • success: Boolean indicating request success
  • status: Conversion status (converted, failed, duplicate)
  • account_id: Created or matched Account ID
  • contact_id: Created or matched Contact ID
  • owner_id: Assigned Owner ID
  • actions: List of actions performed during conversion
  • 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

  • Duplicate Protection: Pre-check via /v1/match to avoid duplicate contacts/accounts
  • Idempotent: Same Idempotency-Key repeats return prior result
  • Batch Processing: Uses Salesforce Lead.Convert with batch API
  • Round-Robin Assignment: Optional owner assignment from specified pools
  • Comprehensive Logging: Route logs and enrichment differences

Credit Usage

Salesforce conversion consumes credits based on complexity:

  • Basic Conversion: 3 credits per lead
  • With Matching: +2 credits for duplicate checking
  • With Round-Robin: +1 credit for owner assignment
Security
BearerAuth
Bodyapplication/jsonrequired
lead_sf_idstring(Lead Sf Id)required

Salesforce Lead ID to convert

match_policyobject(ConversionMatchPolicy)required
match_policy.​contactobject(MatchPolicy)required
match_policy.​contact.​byArray of strings(By)required

List of field rules for matching

match_policy.​contact.​create_if_no_matchboolean(Create If No Match)required

Whether to create new record if no match found

match_policy.​accountobject(MatchPolicy)required
match_policy.​account.​byArray of strings(By)required

List of field rules for matching

match_policy.​account.​create_if_no_matchboolean(Create If No Match)required

Whether to create new record if no match found

merge_policyobject(MergePolicy)required
merge_policy.​on_contact_matchstring(On Contact Match)required

Action when contact match is found

merge_policy.​on_account_matchstring(On Account Match)required

Action when account match is found

set_owner_round_robin_poolSet Owner Round Robin Pool (string) or Set Owner Round Robin Pool (null)(Set Owner Round Robin Pool)
Any of:

Round-robin pool for owner assignment

string(Set Owner Round Robin Pool)
logsobject(ConversionLogs)
curl -i -X POST \
  https://api-gateway.agenthq.withlantern.com/v1/salesforce/convert \
  -H 'Authorization: Bearer <YOUR_ApiToken_HERE>' \
  -H 'Content-Type: application/json' \
  -d '{
    "lead_sf_id": "string",
    "match_policy": {
      "contact": {
        "by": [
          "string"
        ],
        "create_if_no_match": true
      },
      "account": {
        "by": [
          "string"
        ],
        "create_if_no_match": true
      }
    },
    "merge_policy": {
      "on_contact_match": "string",
      "on_account_match": "string"
    },
    "set_owner_round_robin_pool": "string",
    "logs": {
      "route_log": true,
      "enrichment_diff": true
    }
  }'

Responses

Success Response

Bodyapplication/json
successboolean(Success)required

Boolean indicating request success

statusstring(Status)required

Conversion status

Enum"converted""failed""duplicate"
account_idAccount Id (string) or Account Id (null)(Account Id)
Any of:

Created or matched Account ID

string(Account Id)
contact_idContact Id (string) or Contact Id (null)(Contact Id)
Any of:

Created or matched Contact ID

string(Contact Id)
owner_idOwner Id (string) or Owner Id (null)(Owner Id)
Any of:

Assigned Owner ID

string(Owner Id)
actionsArray of strings(Actions)required

List of actions performed during conversion

Response
application/json
{
  "success": true,
  "status": "converted",
  "account_id": "001xx0001ABCDEF",
  "contact_id": "003xx0002HIJKLM",
  "owner_id": "005xx0003NOPQRS",
  "actions": [
    "lead_merged",
    "contact_created",
    "assigned_round_robin"
  ],
  "credits_consumed": 6,
  "credits_remaining": 44,
  "processing_time_ms": 2500,
  "cached": false
}

Routing

Operations

Triggers

Operations

Logs

Operations

Batch Agents

Operations

Credits

Operations

Forms

Operations

Workflows

Operations