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

Get Credit Usage

Request

Get credit usage for a tenant within a specified date range.

Overview

This endpoint retrieves credit usage information for a tenant within a specified date range. It supports optional filtering by workflow ID, workflow run ID, and custom key-value pairs.

Query Parameters

  • start_date: Start date for the calculation period (required)
  • end_date: End date for the calculation period (required)
  • workflow_id: Optional workflow ID for filtering results
  • workflow_run_id: Optional workflow run ID for filtering results
  • custom_key: Optional custom key for filtering results
  • custom_value: Optional custom value for filtering results

Response Fields

  • success: Boolean indicating request success
  • tenant_id: The tenant ID
  • start_date: Echo of the start date
  • end_date: Echo of the end date
  • credits_used: Total credits used in the specified period

Authentication

This endpoint requires authentication via Bearer token. The tenant ID is automatically extracted from the authenticated user's token.

Example Request

GET /v1/credits/usage?start_date=2024-01-01T00:00:00Z&end_date=2024-12-31T23:59:59Z&workflow_id=workflow-123

Example Response

{
  "success": true,
  "tenant_id": 123,
  "start_date": "2024-01-01T00:00:00Z",
  "end_date": "2024-12-31T23:59:59Z",
  "credits_used": 1250.5
}
Security
BearerAuth
Query
start_datestring(date-time)(Start Date)required

Start date for credit calculation

end_datestring(date-time)(End Date)required

End date for credit calculation

workflow_idWorkflow Id (string) or Workflow Id (null)(Workflow Id)
Any of:

Optional workflow ID for filtering

string(Workflow Id)
workflow_run_idWorkflow Run Id (string) or Workflow Run Id (null)(Workflow Run Id)
Any of:

Optional workflow run ID for filtering

string(Workflow Run Id)
custom_keyCustom Key (string) or Custom Key (null)(Custom Key)
Any of:

Optional custom key for filtering

string(Custom Key)
custom_valueCustom Value (string) or Custom Value (null)(Custom Value)
Any of:

Optional custom value for filtering

string(Custom Value)
curl -i -X GET \
  'https://api-gateway.agenthq.withlantern.com/v1/credits/usage?start_date=2019-08-24T14%3A15%3A22Z&end_date=2019-08-24T14%3A15%3A22Z&workflow_id=string&workflow_run_id=string&custom_key=string&custom_value=string' \
  -H 'Authorization: Bearer <YOUR_ApiToken_HERE>'

Responses

Success Response

Bodyapplication/json
successboolean(Success)required

Boolean indicating request success

tenant_idinteger(Tenant Id)required

Tenant ID

start_datestring(date-time)(Start Date)required

Start date for credit calculation

end_datestring(date-time)(End Date)required

End date for credit calculation

credits_usednumber(Credits Used)required

Total credits used in the period

Response
application/json
{
  "success": true,
  "tenant_id": 123,
  "start_date": "2024-01-01T00:00:00Z",
  "end_date": "2024-12-31T23:59:59Z",
  "credits_used": 1250.5
}

Get Remaining Credits

Request

Get the current remaining credits for a tenant.

Overview

This endpoint retrieves the current remaining credits available for the authenticated tenant.

Response Fields

  • success: Boolean indicating request success
  • tenant_id: The tenant ID
  • remaining_credits: Current remaining credits for the tenant
  • total_credits: Total credits for the tenant

Authentication

This endpoint requires authentication via Bearer token. The tenant ID is automatically extracted from the authenticated user's token.

Example Response

{
  "success": true,
  "tenant_id": 123,
  "remaining_credits": 4750.25
}
Security
BearerAuth
curl -i -X GET \
  https://api-gateway.agenthq.withlantern.com/v1/credits/remaining \
  -H 'Authorization: Bearer <YOUR_ApiToken_HERE>'

Responses

Success Response

Bodyapplication/json
successboolean(Success)required

Boolean indicating request success

tenant_idinteger(Tenant Id)required

Tenant ID

remaining_creditsnumber(Remaining Credits)required

Remaining credits for the tenant

total_creditsnumber(Total Credits)required

Total credits for the tenant

Response
application/json
{
  "success": true,
  "tenant_id": 123,
  "remaining_credits": 4750.25
}

Forms

Operations

Workflows

Operations