# Lantern API docs ## 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 | Feature | Sync API | Match API | Salesforce API | Routing API | Triggers API | Logs API | Async API | Credits API | Workflow API | Form API | |---------|----------|-----------|---------------|-------------|--------------|----------|-----------|-------------|-------------|----------| | **Records per request** | 1 | 1-100 | 1 | 1 | 1-100 | 1-10000 | 1-1000 | N/A | 1 | 1 | | **Response time** | Immediate | Immediate | Immediate | Immediate | Immediate | Immediate | Asynchronous | Immediate | Immediate | Immediate | | **Result delivery** | Direct response | Direct response | Direct response | Direct response | Direct response | Direct response | S3 storage | Direct response | Direct response | Direct response | | **Use case** | Real-time processing | Object matching | Lead conversion | User assignment | Instant enrichment | Audit reporting | Bulk operations | Credit monitoring | External system triggers | Form processing | | **Rate limits** | Per-minute limits | Per-minute limits | Per-minute limits | Per-minute limits | Per-minute limits | Per-minute limits | Lower frequency limits | Per-minute limits | High burst support | High 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 Version: 1.4.1 ## Servers Lantern API server ``` https://api-gateway.agenthq.withlantern.com ``` Local API server ``` http://localhost:8000 ``` ## Security ### BearerAuth Type: http Scheme: bearer Bearer Format: ApiToken ## Download OpenAPI description [Lantern API docs](https://developers.withlantern.com/_bundle/openapi.yaml) ## Enrichment ### Phone Enrichment - [POST /v1/enrich/phone](https://developers.withlantern.com/openapi/enrichment/enrich_phone_v1_enrich_phone_post.md): Enriches contact records with phone number data using multiple data sources. ## Overview The Phone Enrichment API enriches contact records with phone number data using multiple data sources. The service intelligently cascades through different lookup methods to maximize success rates. ## Request Body - record_id: Your unique identifier for this record (required) - used for caching and duplicate detection - first_name: Contact's first name (optional) - required for name-based enrichment - last_name: Contact's last name (optional) - required for name-based enrichment - company: Company name or website URL (optional) - required for name-based enrichment - email: Contact's email address (optional) - can be used standalone for enrichment - linkedin_id: Contact's linkedin profile identifier/slug (optional) - can be used standalone for enrichment - domain: Company domain (optional) - enhances name/company enrichment method ## Request Constraints - Single record per request - Must include record_id - record_id must be unique per contact record in your system - Must provide at least one of the following data combinations: - Name + Company/Domain: first_name, last_name, company (optionally enhanced with domain) - LinkedIn Profile Only: linkedin_id - Email Only: email - Enrichment prioritizes data in this order: 1. Name + Company/Domain: Primary method when available 2. LinkedIn Profile: Fallback when name/company data is incomplete 3. Email Only: Final fallback when other data is insufficient ## Response Fields - success: Boolean indicating request success - record_id: Echo of the input record ID - first_name: Echo of input first name (or null if not provided) - last_name: Echo of input last name (or null if not provided) - company: Echo of input company (or null if not provided) - email: Echo of input email or email found during enrichment (or null if not found) - linkedin_id: Echo of input LinkedIn ID or LinkedIn profile found during enrichment (or null if not found) - phone: International format phone number (E.164) or null if not found - processing_time_ms: Time taken to process the request in milliseconds ### Email Enrichment - [POST /v1/enrich/email](https://developers.withlantern.com/openapi/enrichment/enrich_email_v1_enrich_email_post.md): Enriches contact records with email address data using multiple data sources. ## Overview The Email Enrichment API enriches contact records with email address data using multiple data sources. The service uses various lookup methods to find professional email addresses for contacts based on their name and company information. ## Request Body - record_id: Your unique identifier for this record (required) - used for caching and duplicate detection - first_name: Contact's first name (required) - last_name: Contact's last name (required) - company: Company name or website URL where the contact works (required) - domain: Company domain (optional) - if not provided, will be extracted from company field - linkedin: Contact's linkedin url (optional) - improves lookup accuracy when available - max_credits: Maximum credits to spend on this request (optional, defaults to your account limit) ## Request Constraints - Single record per request - Must include record_id, first_name, last_name, and company - record_id must be unique per contact record in your system - domain is optional but improves accuracy when provided - linkedin is optional but improves accuracy when provided - max_credits must be a positive integer if provided ## Response Fields - success: Boolean indicating request success - record_id: Echo of the input record ID - first_name: Echo of input first name - last_name: Echo of input last name - company: Echo of input company - email: Professional email address or null if not found - confidence: Confidence level (high, medium, low) or null - credits_consumed: Number of credits used for this request - credits_remaining: Credits remaining in your account after this request - processing_time_ms: Time taken to process the request in milliseconds - cached: Boolean indicating if this result was returned from cache (no credits consumed if true) ## Credit Usage Email enrichment consumes credits based on the data sources queried: - Cached Result: 0 credits (if same record_id queried recently) - Email Search: 5 credits ### Company Enrichment - [POST /v1/enrich/company](https://developers.withlantern.com/openapi/enrichment/enrich_company_v1_enrich_company_post.md): Enriches company records with firmographics and website-verified data. ## Overview The Company Enrichment API enriches company records with comprehensive firmographics data including company details, location information, industry classification, size range, and geographic coordinates. ## Request Body - record_id: Unique identifier for this enrichment request (required) - company_name: Company name (optional) - improves accuracy when provided - domain: Company domain (optional) - improves accuracy when provided - country: Country code or name (optional) - helps with geographic targeting - external_ids: External system IDs (optional) - for integration with CRM systems - effort: Enrichment effort level (optional, default: low) - max_credits: Maximum credits to spend on this request (optional, defaults to your account limit) ## Request Constraints - record_id is required - company_name, domain are optional but improves accuracy when provided - external_ids should be a dictionary of key-value pairs (e.g., {"sf_account_id": "001xx000..."}) - max_credits must be a positive integer if provided ## Response Fields - success: Boolean indicating request success - record_id: Echo of the input record ID - company: Enriched company data object containing: - name: Company name - domain: Company domain - linkedin_url: LinkedIn company page URL - hq: Headquarters location (city, state, country, postal_code) - size_range: Employee size range (e.g., "500+") - industry: Industry classification - geo: Geographic coordinates and location details (lat, lon, county) - last_verified_at: ISO timestamp of last verification - confidence: Confidence score (0.0-1.0) or null if disabled/not found - credits_consumed: Number of credits used for this request - credits_remaining: Credits remaining in your account after this request - processing_time_ms: Time taken to process the request in milliseconds - cached: Boolean indicating if this result was returned from cache ## Credit Usage Company enrichment consumes credits based on the data sources queried: - Cached Result: 0 credits (if same company queried recently) - Company Lookup: 5 credits ### Person Enrichment - [POST /v1/enrich/person](https://developers.withlantern.com/openapi/enrichment/enrich_person_v1_enrich_person_post.md): Enriches person records with comprehensive contact and professional data. ## Overview The Person Enrichment API enriches person records with comprehensive contact information, professional details, and verification status. This service provides detailed person data including contact information, job titles, seniority levels, and email/phone verification status. ## Request Body - record_id: Unique identifier for this enrichment request (required) - first_name: Person's first name (required) - last_name: Person's last name (required) - company_domain: Company domain where the person works (required) - email: Person's email address (optional) - linkedin_id: LinkedIn ID or profile URL (optional) - effort: Enrichment effort level (optional, default: low) - max_credits: Maximum credits to spend on this request (optional, defaults to your account limit) ## Request Constraints - record_id, first_name, last_name, and company_domain are required - company_domain should be a valid domain format - email should be a valid email format when provided - max_credits must be a positive integer if provided ## Response Fields - success: Boolean indicating request success - record_id: Echo of the input record ID - person: Enriched person data object containing: - full_name: Person's full name - email: Person's email address - email_confidence: Email confidence score (0.0-1.0) - email_status: Email verification status (valid, accept_all, risky, invalid, unknown) - phone: Phone number - title: Job title - linkedin_url: LinkedIn profile URL - job_last_seen_at: ISO timestamp when job information was last verified - confidence: Confidence score (0.0-1.0) or null if disabled/not found - credits_consumed: Number of credits used for this request - credits_remaining: Credits remaining in your account after this request - processing_time_ms: Time taken to process the request in milliseconds - cached: Boolean indicating if this result was returned from cache ## Email Status Values - valid: Email address is valid and deliverable - accept_all: Email server accepts all emails (catch-all) - risky: Email address may be risky or temporary - invalid: Email address is invalid or undeliverable - unknown: Email status could not be determined ## Credit Usage Person enrichment consumes credits based on the data sources queried: - Cached Result: 0 credits (if same person queried recently) - Person Lookup: 4 credits ### AI Enrichment - [POST /v1/enrich/ai](https://developers.withlantern.com/openapi/enrichment/enrich_ai_v1_enrich_ai_post.md): # AI Enrichment API ## Overview The AI Enrichment API allows you to enrich data or generate insights using advanced language models. Send a query or prompt and receive AI-generated responses that can include analysis, summaries, recommendations, or structured data extraction. ## Request Body json { "query": "string (required)", "options": { "format_json": "boolean (optional)" }, "effort": "string (optional, default: low)" "max_credits": "integer (optional)" } ## Field Descriptions - query: The main prompt or question to send to the AI model (required) - options (optional): Additional configuration options - format_json: Whether to return response in structured JSON format (defaults to false) - effort (optional): Specifies the level of enrichment effort to apply, by default is low - max_credits must be a positive integer if provided ## Request Constraints - query is required and must be non-empty - options.format_json when provided must be a boolean value - effort when provided accepted values are: low, medium, high - Query length should not exceed 8000 characters ## Response Fields - success: Boolean indicating request success - query: Echo of the input query - response: AI-generated response (string or structured object based on format_json setting) - confidence: AI confidence score in the response (0.0-1.0) - credits_consumed: Number of credits used for this request - credits_remaining: Credits remaining in your account after this request - token_usage: Token consumption details - prompt_tokens: Tokens used in the input - completion_tokens: Tokens used in the response - total_tokens: Total tokens consumed - processing_time_ms: Time taken to process the request in milliseconds ## Confidence Levels - 0.9-1.0: Very high confidence - factual, well-supported responses - 0.7-0.9: High confidence - good quality responses with minor uncertainty - 0.5-0.7: Medium confidence - reasonable responses but may need verification - 0.0-0.5: Low confidence - speculative or uncertain responses ## Common Use Cases 1. Data Analysis & Insights: Analyze trends, patterns, and generate business insights 2. Content Generation: Create marketing copy, emails, summaries, and reports 3. Data Extraction: Parse unstructured text and extract structured information 4. Research & Summarization: Synthesize information and provide comprehensive overviews 5. Decision Support: Generate recommendations and evaluate options 6. Text Enhancement: Improve, rewrite, or optimize existing content ## Credit Usage AI enrichment consumes credits based on the complexity and length of the response: - Simple Queries: 1-3 credits (short responses, basic analysis) - Standard Queries: 3-6 credits (medium-length responses, data extraction) - Complex Analysis: 6-12 credits (detailed analysis, research, long-form content) - JSON Structured Output: +1-2 credits additional (for formatting and validation) ### Deep Research - [POST /v1/enrich/research](https://developers.withlantern.com/openapi/enrichment/deep_research_v1_enrich_research_post.md): Conducts comprehensive research using advanced language models with real-time search capabilities. ## Match ### Match API - [POST /v1/match](https://developers.withlantern.com/openapi/match/match_objects_v1_match_post.md): 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 ## Salesforce ### Lead → Contact Auto-Convert & Merge - [POST /v1/salesforce/convert](https://developers.withlantern.com/openapi/salesforce/convert_lead_v1_salesforce_convert_post.md): 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 ## Routing ### Round Robin Assignment - [POST /v1/routing/assign](https://developers.withlantern.com/openapi/routing/assign_object_v1_routing_assign_post.md): 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 ## Triggers ### Salesforce Trigger Webhook - [POST /v1/triggers/salesforce](https://developers.withlantern.com/openapi/triggers/salesforce_trigger_v1_triggers_salesforce_post.md): Handles instant enrichment on Salesforce record creation/updates via webhook. ## Overview The Salesforce Trigger API provides instant enrichment capabilities for Salesforce records through webhook-based triggers. It supports both real-time webhook processing and polling-based enrichment for comprehensive coverage of record changes. ## Request Body - object: Salesforce object type that triggered the event (Lead, Contact, Account, Opportunity) - ids: List of Salesforce record IDs that changed - event: Salesforce trigger event type (after_insert, after_update, after_undelete) - org_id: Salesforce organization ID ## Trigger Events - after_insert: Triggered when new records are created - after_update: Triggered when existing records are updated - after_undelete: Triggered when records are undeleted ## Response Fields - success: Boolean indicating request success - processed_count: Number of records processed - enrichment_jobs: List of enrichment job IDs created - workflow_status: Status of the enrichment workflow (started, queued, failed) - 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 ## Enrichment Options ### Webhook Processing (Real-time) - Immediate Processing: Records are processed immediately upon webhook receipt - Platform Events: Uses Salesforce Platform Events for reliable delivery - Apex Callouts: Triggered via Apex callouts from Salesforce triggers - Low Latency: Near real-time enrichment with minimal delay ### Polling Processing (Fallback) - SOQL Queries: Polls Salesforce every 2 minutes for new/changed records - Watermark Tracking: Uses SystemModstamp and Id for efficient filtering - Batch Processing: Processes records in batches for optimal performance - Reliable Coverage: Ensures no records are missed even if webhooks fail ## Features - Dual Processing: Both webhook and polling support for comprehensive coverage - Automatic Enrichment: Triggers enrichment workflows based on object type - Job Tracking: Creates enrichment jobs for monitoring and debugging - Credit Management: Tracks credit consumption per enrichment job - Error Handling: Robust error handling with retry mechanisms - Audit Trail: Comprehensive logging for compliance and debugging ## Credit Usage Trigger processing consumes credits based on enrichment type: - Lead Enrichment: 2 credits per lead - Contact Enrichment: 1 credit per contact - Account Enrichment: 3 credits per account - Opportunity Enrichment: 1 credit per opportunity ### Polling Status - [GET /v1/triggers/polling/status](https://developers.withlantern.com/openapi/triggers/get_polling_status_v1_triggers_polling_status_get.md): Get the current status of polling-based enrichment. ## Overview This endpoint provides information about the current polling status, including last poll time, records processed, watermark value, and next scheduled poll. ## Response Fields - last_poll_time: ISO timestamp of last poll - records_processed: Number of records processed in last poll - watermark_value: Current watermark value - next_poll_time: ISO timestamp of next scheduled poll ## Use Cases - Monitor polling performance - Debug enrichment issues - Verify watermark progression - Check polling schedule ## Logs ### Export Route Logs - [GET /v1/logs/routing](https://developers.withlantern.com/openapi/logs/export_route_logs_v1_logs_routing_get.md): Export route logs for audit and reporting purposes. ## Overview The Route Logs API provides comprehensive audit trails for all routing, conversion, merging, and enrichment actions performed on Salesforce objects. It supports filtering, export formats, and configurable retention policies. ## Query Parameters - from: Start date for log export (ISO format, required) - to: End date for log export (ISO format, required) - pool: Filter by specific pool name (optional) - object: Filter by specific object type (Lead, Contact, Account, Opportunity) (optional) - action: Filter by specific action type (assign, convert, merge, enrich) (optional) - format: Export format (json, csv) (optional, default: json) - include_diff: Include diff data in export (optional, default: true) - limit: Maximum number of records to return (optional, default: 1000, max: 10000) ## Response Fields Each log entry includes: - timestamp: ISO timestamp of the action - object: Salesforce object type - object_id: Salesforce ID of the object - action: Action performed (assign, convert, merge, enrich) - pool: Round-robin pool name (for assign actions) - assigned_to: Salesforce ID of assigned user (for assign actions) - prev_owner: Previous owner ID (for assign/convert actions) - sequence: Round-robin sequence number (for assign actions) - reason: Reason for the action - request_id: Request ID for tracking - idempotency_key: Idempotency key for duplicate prevention - diff: Field changes for enrichment/merge actions ## Export Formats ### JSON Format (Default) Returns structured JSON data with full field information. ### CSV Format Returns comma-separated values suitable for spreadsheet applications. - Headers: timestamp, object, object_id, action, pool, assigned_to, prev_owner, sequence, reason, request_id, idempotency_key, diff - Diff data is JSON-encoded in the diff column ## Use Cases - Audit Compliance: Track all actions for regulatory compliance - Performance Analysis: Analyze routing patterns and efficiency - User Activity: Monitor user assignments and activity - Enrichment Tracking: Track data enrichment changes and sources - Troubleshooting: Debug routing issues and user assignments ## Retention Policy - Default Retention: 365 days - Maximum Retention: 1095 days (3 years) - Auto Cleanup: Enabled by default (daily at 2 AM) - Configurable: Retention can be adjusted per organization ## Rate Limits - Standard Export: 10 requests per minute - Large Exports: 2 requests per minute (for exports > 5000 records) - Statistics: 20 requests per minute ## Batch Agents ### Phone Enrichment Batch - [POST /v1/agents/phone](https://developers.withlantern.com/openapi/batch-agents/phone_enrich_batch_v1_agents_phone_post.md): Process multiple records for phone enrichment in batch mode. ## Overview The Phone Enrichment Batch API allows you to submit multiple person records for phone number enrichment processing asynchronously. Key Differences from Sync API: - Sync API (/v1/enrich/phone): Process one record at a time, get immediate response with phone number - Batch API (/v1/agents/phone): Submit 1-1000 records, get job ID, results stored in S3 when complete This endpoint accepts a batch of records and processes them asynchronously using workflow orchestration, making it ideal for bulk processing operations. ## Request Body Submit IDs for processing: - ids: Array of person IDs to process (1-1000 IDs) Required fields: - entity_type: Type of entity being processed (must be 'person' for phone enrichment) (required) - max_credits: Maximum credits this batch operation is allowed to consume (required) ## Response - run_id: Unique identifier for the batch run - result_path: S3 bucket path where results will be stored upon completion - credits_csv_path: S3 bucket path where credit usage report will be stored upon completion ## Credit Usage Credits are consumed based on the number of records processed and the success rate of phone number lookups. The batch will stop processing if the credit limit is reached. ## Batch Limits - Minimum: 1 record - Maximum: 1000 records per batch - Records with missing required fields will be skipped ## Examples ### Example: Submit IDs for processing json { "ids": ["550e8400-e29b-41d4-a716-446655440001", "550e8400-e29b-41d4-a716-446655440002", "550e8400-e29b-41d4-a716-446655440003"], "entity_type": "person", "max_credits": 100 } ## Output The results CSV will contain the following columns: json { "id": "string | Unique record identifier", "first_name": "string | Person's given name", "last_name": "string | Person's surname", "company_name": "string | Organization name", "company_url": "string | Company website domain", "linkedin": "string | LinkedIn profile URL or username", "phone_number": "string | Phone number (E.164 format when available)", "phone_found": "boolean | Phone enrichment success flag" } ### Example Output CSV csv id,first_name,last_name,company_name,company_url,linkedin,phone_number,phone_found 550e8400-e29b-41d4-a716-446655440001,John,Smith,Acme Corp,acme.com,john-smith-123456789,+1-555-123-4567,true 550e8400-e29b-41d4-a716-446655440002,Jane,Doe,TechCorp,techcorp.com,jane-doe-987654321,,false ### Email Enrichment Batch - [POST /v1/agents/email](https://developers.withlantern.com/openapi/batch-agents/email_enrich_batch_v1_agents_email_post.md): Process multiple records for email enrichment in batch mode. ## Overview The Email Enrichment Batch API allows you to submit multiple person records for email address enrichment processing asynchronously. Key Differences from Sync API: - Sync API (/v1/enrich/email): Process one record at a time, get immediate response with email address - Batch API (/v1/agents/email): Submit 1-1000 records, results stored in S3 when complete This endpoint accepts a batch of records and processes them asynchronously using workflow orchestration, making it ideal for bulk processing operations. ## Request Body Submit IDs for processing: - ids: Array of person IDs to process (1-1000 IDs) Required fields: - entity_type: Type of entity being processed (must be 'person' for email enrichment) (required) - max_credits: Maximum credits this batch operation is allowed to consume (required) ## Response - run_id: Unique identifier for the batch run - result_path: S3 bucket path where results will be stored upon completion - credits_csv_path: S3 bucket path where credit usage report will be stored upon completion ## Credit Usage Credits are consumed based on the number of records processed and the success rate of email address lookups. The batch will stop processing if the credit limit is reached. ## Batch Limits - Minimum: 1 record - Maximum: 1000 records per batch - Records with missing required fields will be skipped ## Examples ### Example: Submit IDs for processing json { "ids": ["6ba7b810-9dad-11d1-80b4-00c04fd430c8", "6ba7b811-9dad-11d1-80b4-00c04fd430c8", "6ba7b812-9dad-11d1-80b4-00c04fd430c8"], "entity_type": "person", "max_credits": 100 } ## Output The results CSV will contain the following columns: json { "id": "string | Unique record identifier", "first_name": "string | Person's given name", "last_name": "string | Person's surname", "company_name": "string | Organization name", "company_url": "string | Company website domain", "linkedin": "string | LinkedIn profile URL or username", "email": "string | Email address", "email_found": "boolean | Email enrichment success flag" } ### Example Output CSV csv id,first_name,last_name,company_name,company_url,linkedin,email,email_found 6ba7b810-9dad-11d1-80b4-00c04fd430c8,John,Smith,Acme Corp,acme.com,john-smith-123456789,john.smith@acme.com,true 6ba7b811-9dad-11d1-80b4-00c04fd430c8,Jane,Doe,TechCorp,techcorp.com,jane-doe-987654321,,false ### Deep Research Batch - [POST /v1/agents/deep-research](https://developers.withlantern.com/openapi/batch-agents/deep_research_batch_v1_agents_deep_research_post.md): Process multiple records for AI deep research in batch mode. ## Overview The Deep Research Batch API allows you to submit multiple records for AI-powered deep research processing asynchronously. Key Differences from Sync API: - Sync API (/v1/enrich/research): Process one query at a time, get immediate response with research results - Batch API (/v1/agents/deep-research): Submit 1-1000 IDs, get job ID, comprehensive research results stored in S3 when complete This endpoint accepts a batch of IDs and processes them asynchronously using specialized research agents and workflow orchestration, making it ideal for large-scale research operations. ## Request Body - ids: Array of IDs to process for deep research (1-1000 IDs) (required) - query_hint: Query hint for research context (optional) - entity_type: Type of entity being processed (company or person) (required) - effort: Effort level for deep research processing (low, medium, high) - defaults to medium - agent_type: Type of specialized agent to use for deep research (defaults to 'general') - max_credits: Maximum credits this batch operation is allowed to consume (required) ## Response - run_id: Unique identifier for the batch run - result_path: S3 bucket path where results will be stored upon completion - credits_csv_path: S3 bucket path where credit usage report will be stored upon completion ## Processing 1. IDs are converted to CSV format with entity type, agent type, and query hint enrichment 2. CSV is uploaded to S3 storage 3. Deep research workflow is triggered for batch processing 4. Results are stored in the specified S3 location ## Entity Types Supported entity types for deep research: - company: Business organizations and companies - person: Individual contacts and people ## Agent Types Different agent types specialize in different research domains: - general: General purpose research agent (default) - funding: Research funding opportunities, investors, grants - legal: Legal research, compliance, regulatory information ## Credit Usage Credits are consumed based on the effort level, number of records processed, and research complexity. Higher effort levels consume more credits but provide more comprehensive results. ## Batch Limits - Minimum: 1 ID - Maximum: 1000 IDs per batch - Invalid or empty IDs will be skipped ## Example json { "ids": ["a1b2c3d4-e5f6-7890-abcd-ef1234567890", "a1b2c3d4-e5f6-7890-abcd-ef1234567891", "a1b2c3d4-e5f6-7890-abcd-ef1234567892"], "query_hint": "Research funding opportunities for AI startups", "entity_type": "company", "effort": "medium", "agent_type": "funding", "max_credits": 200 } ### Phone & Email Enrichment Batch - [POST /v1/agents/phone-email](https://developers.withlantern.com/openapi/batch-agents/phone_email_enrich_batch_v1_agents_phone_email_post.md): Process multiple records for combined phone and email enrichment in batch mode. ## Overview The Phone & Email Enrichment Batch API allows you to submit multiple person records for both phone number and email address enrichment processing asynchronously in a single operation. Key Differences from Individual APIs: - Phone API (/v1/agents/phone): Process records for phone enrichment only - Email API (/v1/agents/email): Process records for email enrichment only - Phone & Email API (/v1/agents/phone-email): Process records for both phone and email enrichment simultaneously This endpoint accepts a batch of records and processes them asynchronously using workflow orchestration for both phone and email enrichment, making it ideal for comprehensive contact enrichment operations. ## Request Body Submit IDs for processing: - ids: Array of person IDs to process (1-1000 IDs) Required fields: - entity_type: Type of entity being processed (must be 'person' for phone & email enrichment) (required) - max_credits: Maximum credits this batch operation is allowed to consume (required) ## Response - run_id: Unique identifier for the batch run - result_path: S3 bucket path where results will be stored upon completion - credits_csv_path: S3 bucket path where credit usage report will be stored upon completion ## Credit Usage Credits are consumed based on the number of records processed and the success rate of both phone and email lookups. The batch will stop processing if the credit limit is reached. ## Batch Limits - Minimum: 1 record - Maximum: 1000 records per batch - Records with missing required fields will be skipped ## Example ### Example: Submit IDs for processing json { "ids": ["550e8400-e29b-41d4-a716-446655440001", "550e8400-e29b-41d4-a716-446655440002", "550e8400-e29b-41d4-a716-446655440003"], "entity_type": "person", "max_credits": 200 } ## Output The results CSV will contain the following columns: json { "id": "string | Unique record identifier", "first_name": "string | Person's given name", "last_name": "string | Person's surname", "company_name": "string | Organization name", "company_url": "string | Company website domain", "linkedin": "string | LinkedIn profile URL or username", "email": "string | Email address", "email_found": "boolean | Email enrichment success flag", "phone_number": "string | Phone number (E.164 format when available)", "phone_found": "boolean | Phone enrichment success flag" } ### Example Output CSV csv company_name,company_url,first_name,id,last_name,linkedin,email,email_found,phone_number,phone_found Acme Corp,acme.com,John,550e8400-e29b-41d4-a716-446655440001,Smith,john-smith-123456789,john.smith@acme.com,true,+1-555-123-4567,true TechCorp,techcorp.com,Jane,550e8400-e29b-41d4-a716-446655440002,Doe,jane-doe-987654321,,false,,false Global Solutions,globalsolutions.com,Michael,550e8400-e29b-41d4-a716-446655440003,Johnson,michael-johnson-345678901,michael.johnson@globalsolutions.com,true,,false ### Get Run Status - [GET /v1/agents/runs/{run_id}/status](https://developers.withlantern.com/openapi/batch-agents/get_workflow_run_status_v1_agents_runs__run_id__status_get.md): Retrieve the current status of a run by its ID. ## Overview This endpoint allows you to quickly check the status of a run without retrieving all the detailed information. ## Path Parameters - run_id: The unique identifier of the batch run (UUID format) ## Response Returns the run ID and its current status. ## Examples ### Example Response json { "run_id": "123e4567-e89b-12d3-a456-426614174000", "status": "completed" } ### Possible Status Values - queued: The run is queued - completed: The run has completed successfully - failed: The run has failed ## HTTP Status Codes | Code | Meaning | |------|---------| | 200 OK | Run status retrieved successfully | | 400 Bad Request | Invalid run ID format | | 404 Not Found | Run not found | | 500 Internal Server Error | Server error occurred while retrieving status | ## Credits ### Get Credit Usage - [GET /v1/credits/usage](https://developers.withlantern.com/openapi/credits/get_credit_usage_v1_credits_usage_get.md): 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 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 - [GET /v1/credits/remaining](https://developers.withlantern.com/openapi/credits/get_remaining_credits_v1_credits_remaining_get.md): 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 json { "success": true, "tenant_id": 123, "remaining_credits": 4750.25 } ## Forms ### Submit Form - [POST /v1/forms/submit](https://developers.withlantern.com/openapi/forms/submit_form_v1_forms_submit_post.md): 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 ## Workflows ### Trigger Workflow - [POST /v1/workflows/{workflow_id}/trigger](https://developers.withlantern.com/openapi/workflows/trigger_workflow_v1_workflows__workflow_id__trigger_post.md): Triggers enrichment and routing workflows from external systems. ## Overview The Workflow Trigger API provides a generic interface for initiating enrichment and routing workflows from various external systems like Eloqua, Customer Data Platforms (CDP), Data Lakes, and other marketing automation platforms. ## Authentication Requires either an API key or OAuth2 bearer token in the Authorization header. ## Rate Limits Designed to support bursty event traffic, capable of handling hundreds of requests per minute. ## Request Body - record_data: Generic record payload containing fields for Lead, Contact, Opportunity, or other custom objects - source_system: Optional source system identifier (e.g., 'eloqua', 'cdp', 'data_lake') - enrichment_preferences: Optional enrichment preferences and configuration ## Response Fields - success: Boolean indicating request success - status: Workflow status (triggered, queued, failed) - request_id: Unique request ID for tracking - workflow_id: ID of the triggered workflow - processing_time_ms: Processing time in milliseconds - enrichment_job_id: ID of enrichment job created (if applicable) - credits_consumed: Number of credits used - credits_remaining: Credits remaining in account - cached: Whether result was from cache ## Features - Generic Payload: Accepts any record type (Lead, Contact, Opportunity, custom objects) - Audit Logging: All requests and responses are logged for compliance - Retry Logic: Automatic retries on failure with exponential backoff - High Throughput: Optimized for bursty event traffic - Credit Tracking: Transparent credit consumption tracking ## Credit Usage Workflow triggers consume credits based on complexity: - Basic Trigger: 1 credit per record - With Enrichment: +2 credits for enrichment processing - With Routing: +1 credit for routing logic