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 API

Request

Supports exact, fuzzy, and AI-assisted matching with grouped boolean logic.

Overview

The Match API provides sophisticated matching capabilities for Account, Contact, and Lead objects. It supports multiple matching modes including simple field matching, grouped boolean logic, and AI-assisted matching with natural language explanations.

Request Body

  • object: Object type to match (account, contact, lead)
  • candidates: List of candidates to match against Salesforce records
  • rules: Matching rules configuration
  • context: Optional context information (Salesforce instance, org ID, etc.)
  • max_credits: Maximum credits to spend on this request

Matching Modes

Simple Mode

Basic field-by-field matching with exact and fuzzy rules.

Grouped Mode

Advanced boolean logic with grouped rules:

  • groups: List of rule groups
  • all: Rules within a group that must all match
  • any: Whether any group needs to be true
  • threshold: Overall confidence cutoff

AI Mode

AI-assisted matching using LLM scoring:

  • Natural language explanations
  • Context-aware matching
  • Use when structured rules fail

Field Rules

  • field:exact: Exact string match
  • field:fuzzy0.x: Fuzzy match with 0.x threshold
  • field:eq: Equality match
  • field:contains: Contains match

Response Fields

  • success: Boolean indicating request success
  • results: List of candidate results with matches
  • 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

Credit Usage

Match API consumes credits based on complexity:

  • Simple Mode: 1 credit per candidate
  • Grouped Mode: 2 credits per candidate
  • AI Mode: 5 credits per candidate
Security
BearerAuth
Bodyapplication/jsonrequired
objectstring(Object)required

Object type to match

Enum"account""contact""lead"
candidatesArray of objects(Candidates)required

List of candidates to match

candidates[].​company_nameCompany Name (string) or Company Name (null)(Company Name)
Any of:

Company name

string(Company Name)
candidates[].​domainDomain (string) or Domain (null)(Domain)
Any of:

Company domain

string(Domain)
candidates[].​billing_streetBilling Street (string) or Billing Street (null)(Billing Street)
Any of:

Billing street address

string(Billing Street)
candidates[].​phonePhone (string) or Phone (null)(Phone)
Any of:

Phone number

string(Phone)
candidates[].​emailEmail (string) or Email (null)(Email)
Any of:

Email address

string(Email)
candidates[].​first_nameFirst Name (string) or First Name (null)(First Name)
Any of:

First name (for contacts/leads)

string(First Name)
candidates[].​last_nameLast Name (string) or Last Name (null)(Last Name)
Any of:

Last name (for contacts/leads)

string(Last Name)
candidates[].​titleTitle (string) or Title (null)(Title)
Any of:

Job title (for contacts/leads)

string(Title)
rulesobject(MatchRules)required
rules.​modestring(Mode)required

Matching mode

Enum"simple""grouped""ai"
rules.​groupsArray of Groups (objects) or Groups (null)(Groups)
Any of:

Match groups (for grouped mode)

rules.​anyboolean(Any)

Match if any group is true

Default true
rules.​thresholdnumber(Threshold)[ 0 .. 1 ]required

Overall confidence cutoff

rules.​effortEffort (string) or Effort (null)(Effort)
Any of:

Enrichment effort level (for AI mode)

string(Effort)
Enum"low""medium""high"
contextContext (object) or Context (null)(Context)
Any of:

Context information

max_creditsinteger(Max Credits)[ 1 .. 100 ]

Maximum credits to spend

Default 1
curl -i -X POST \
  https://api-gateway.agenthq.withlantern.com/v1/match \
  -H 'Authorization: Bearer <YOUR_ApiToken_HERE>' \
  -H 'Content-Type: application/json' \
  -d '{
    "object": "account",
    "candidates": [
      {
        "company_name": "string",
        "domain": "string",
        "billing_street": "string",
        "phone": "string",
        "email": "string",
        "first_name": "string",
        "last_name": "string",
        "title": "string"
      }
    ],
    "rules": {
      "mode": "simple",
      "groups": [
        {
          "all": [
            "string"
          ]
        }
      ],
      "any": true,
      "threshold": 1,
      "effort": "low"
    },
    "context": {},
    "max_credits": 1
  }'

Responses

Success Response

Bodyapplication/json
successboolean(Success)required

Boolean indicating request success

resultsArray of objects(Results)required

List of candidate results

results[].​input_indexinteger(Input Index)required

Index of the input candidate

results[].​matchesArray of objects(Matches)required

List of matches found

results[].​matches[].​sf_idstring(Sf Id)required

Salesforce ID of the matched record

results[].​matches[].​objectstring(Object)required

Object type of the matched record (e.g., 'Account', 'Contact', 'Lead')

results[].​matches[].​confidencenumber(Confidence)[ 0 .. 1 ]required

Overall confidence score

results[].​matches[].​explanationsArray of strings(Explanations)required

List of match explanations (e.g., ['domain eq', 'name fuzzy 0.86'])

results[].​matches[].​fieldsobject(Fields)required

Matched record fields (e.g., {'Name': 'Company Name', 'Website': 'example.com'})

results[].​matches[].​fields.​property name*anyadditional property
results[].​best_matchboolean(Best Match)required

Whether this is the best match

results[].​statusstring(Status)required

Match status

Enum"matched""no_match""ambiguous"
confidenceConfidence (number) or Confidence (null)(Confidence)
Any of:

Confidence score (0.0-1.0) or null if disabled/not found

[ 0 .. 1 ]
number(Confidence)[ 0 .. 1 ]
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,
  "results": [
    { … }
  ],
  "confidence": 0.9,
  "credits_consumed": 1,
  "credits_remaining": 10,
  "processing_time_ms": 1200,
  "cached": true
}

Salesforce

Operations

Routing

Operations

Triggers

Operations

Logs

Operations

Batch Agents

Operations

Credits

Operations

Forms

Operations

Workflows

Operations