openapi: 3.1.0
info:
  title: Lantern API docs
  description: >-
    ## 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
paths:
  /v1/enrich/phone:
    post:
      tags:
        - Enrichment
      summary: Phone Enrichment
      description: >-
        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
      operationId: enrich_phone_v1_enrich_phone_post
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/PhoneEnrichmentRequest'
        required: true
      responses:
        '200':
          description: Success Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PhoneEnrichmentResponse'
              example:
                success: true
                record_id: contact_001
                first_name: John
                last_name: Smith
                company: Acme Corp
                email: john.smith@acme.com
                linkedin_id: john-smith-123456
                phone: +1-555-123-4567
                processing_time_ms: 1250
        '400':
          description: Bad Request - Invalid input parameters
          content:
            application/json:
              schema:
                $ref: >-
                  #/components/schemas/api_gateway__models__enrichment__ErrorResponse
        '401':
          description: Unauthorized - Invalid or missing API key
          content:
            application/json:
              schema:
                $ref: >-
                  #/components/schemas/api_gateway__models__enrichment__ErrorResponse
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
        '429':
          description: Rate Limited - Too many requests
          content:
            application/json:
              schema:
                $ref: >-
                  #/components/schemas/api_gateway__models__enrichment__ErrorResponse
        '500':
          description: Internal Server Error
          content:
            application/json:
              schema:
                $ref: >-
                  #/components/schemas/api_gateway__models__enrichment__ErrorResponse
  /v1/enrich/email:
    post:
      tags:
        - Enrichment
      summary: Email Enrichment
      description: >-
        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
      operationId: enrich_email_v1_enrich_email_post
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/EmailEnrichmentRequest'
        required: true
      responses:
        '200':
          description: Success Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/EmailEnrichmentResponse'
              example:
                success: true
                record_id: contact_001
                first_name: John
                last_name: Smith
                company: Acme Corp
                email: john.smith@acme.com
                confidence: high
                credits_consumed: 3
                credits_remaining: 47
                processing_time_ms: 750
                cached: false
        '400':
          description: Bad Request - Invalid input parameters
          content:
            application/json:
              schema:
                $ref: >-
                  #/components/schemas/api_gateway__models__enrichment__ErrorResponse
        '401':
          description: Unauthorized - Invalid or missing API key
          content:
            application/json:
              schema:
                $ref: >-
                  #/components/schemas/api_gateway__models__enrichment__ErrorResponse
        '402':
          description: Insufficient Credits - Not enough credits to complete request
          content:
            application/json:
              schema:
                $ref: >-
                  #/components/schemas/api_gateway__models__enrichment__ErrorResponse
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
        '429':
          description: Rate Limited - Too many requests
          content:
            application/json:
              schema:
                $ref: >-
                  #/components/schemas/api_gateway__models__enrichment__ErrorResponse
        '500':
          description: Internal Server Error
          content:
            application/json:
              schema:
                $ref: >-
                  #/components/schemas/api_gateway__models__enrichment__ErrorResponse
  /v1/enrich/company:
    post:
      tags:
        - Enrichment
      summary: Company Enrichment
      description: >-
        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
      operationId: enrich_company_v1_enrich_company_post
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CompanyEnrichmentRequest'
        required: true
      responses:
        '200':
          description: Success Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CompanyEnrichmentResponse'
              example:
                success: true
                record_id: company_001
                company:
                  name: Databricks
                  domain: databricks.com
                  linkedin_url: https://www.linkedin.com/company/databricks
                  hq:
                    city: San Francisco
                    state: CA
                    country: US
                    postal_code: '94105'
                  size_range: 500+
                  industry: Technology
                  geo:
                    lat: 37.79
                    lon: -122.39
                    county: San Francisco
                  last_verified_at: '2025-09-12T18:22:01Z'
                confidence: 0.9
                credits_consumed: 1
                credits_remaining: 10
                processing_time_ms: 1200
                cached: true
        '400':
          description: Bad Request - Invalid input parameters
          content:
            application/json:
              schema:
                $ref: >-
                  #/components/schemas/api_gateway__models__enrichment__ErrorResponse
        '401':
          description: Unauthorized - Invalid or missing API key
          content:
            application/json:
              schema:
                $ref: >-
                  #/components/schemas/api_gateway__models__enrichment__ErrorResponse
        '402':
          description: Insufficient Credits - Not enough credits to complete request
          content:
            application/json:
              schema:
                $ref: >-
                  #/components/schemas/api_gateway__models__enrichment__ErrorResponse
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
        '429':
          description: Rate Limited - Too many requests
          content:
            application/json:
              schema:
                $ref: >-
                  #/components/schemas/api_gateway__models__enrichment__ErrorResponse
        '500':
          description: Internal Server Error
          content:
            application/json:
              schema:
                $ref: >-
                  #/components/schemas/api_gateway__models__enrichment__ErrorResponse
  /v1/enrich/person:
    post:
      tags:
        - Enrichment
      summary: Person Enrichment
      description: >-
        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
      operationId: enrich_person_v1_enrich_person_post
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/PersonEnrichmentRequest'
        required: true
      responses:
        '200':
          description: Success Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PersonEnrichmentResponse'
              example:
                success: true
                record_id: person_001
                person:
                  full_name: Jane Doe
                  email: jane.doe@trinet.com
                  email_confidence: 0.93
                  email_status: valid
                  phone: +1-415-555-0199
                  title: Director, RevOps
                  linkedin_url: https://linkedin.com/in/janedoe
                  job_last_seen_at: '2025-08-30T15:12:00Z'
                confidence: 0.9
                credits_consumed: 1
                credits_remaining: 10
                processing_time_ms: 1200
                cached: true
        '400':
          description: Bad Request - Invalid input parameters
          content:
            application/json:
              schema:
                $ref: >-
                  #/components/schemas/api_gateway__models__enrichment__ErrorResponse
        '401':
          description: Unauthorized - Invalid or missing API key
          content:
            application/json:
              schema:
                $ref: >-
                  #/components/schemas/api_gateway__models__enrichment__ErrorResponse
        '402':
          description: Insufficient Credits - Not enough credits to complete request
          content:
            application/json:
              schema:
                $ref: >-
                  #/components/schemas/api_gateway__models__enrichment__ErrorResponse
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
        '429':
          description: Rate Limited - Too many requests
          content:
            application/json:
              schema:
                $ref: >-
                  #/components/schemas/api_gateway__models__enrichment__ErrorResponse
        '500':
          description: Internal Server Error
          content:
            application/json:
              schema:
                $ref: >-
                  #/components/schemas/api_gateway__models__enrichment__ErrorResponse
  /v1/enrich/ai:
    post:
      tags:
        - Enrichment
      summary: AI Enrichment
      description: >-
        # 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)
      operationId: enrich_ai_v1_enrich_ai_post
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/AIEnrichmentRequest'
        required: true
      responses:
        '200':
          description: Success Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AIEnrichmentResponse'
              examples:
                text_response:
                  summary: Text Format Response
                  value:
                    success: true
                    query: Analyze the market trends for electric vehicles in 2024
                    response: >-
                      Based on current market data, electric vehicle adoption is
                      accelerating rapidly in 2024. Key trends include: 1)
                      Increased affordability with new models under $30k, 2)
                      Improved charging infrastructure with 40% more stations,
                      3) Enhanced battery technology offering 300+ mile
                      ranges...
                    confidence: 0.85
                    credits_consumed: 5
                    credits_remaining: 45
                    token_usage:
                      prompt_tokens: 45
                      completion_tokens: 234
                      total_tokens: 279
                    processing_time_ms: 1200
                json_response:
                  summary: JSON Format Response
                  value:
                    success: true
                    query: Extract key information from this company description
                    response:
                      company_name: TechCorp Solutions
                      industry: Software Development
                      employee_count: 250-500
                      founded: '2018'
                      headquarters: San Francisco, CA
                      key_products:
                        - CRM Software
                        - Analytics Platform
                        - Mobile Apps
                    confidence: 0.92
                    credits_consumed: 3
                    credits_remaining: 42
                    token_usage:
                      prompt_tokens: 67
                      completion_tokens: 89
                      total_tokens: 156
                    processing_time_ms: 950
        '400':
          description: Bad Request
          content:
            application/json:
              schema:
                $ref: >-
                  #/components/schemas/api_gateway__models__enrichment__ErrorResponse
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: >-
                  #/components/schemas/api_gateway__models__enrichment__ErrorResponse
        '402':
          description: Insufficient Credits
          content:
            application/json:
              schema:
                $ref: >-
                  #/components/schemas/api_gateway__models__enrichment__ErrorResponse
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
        '429':
          description: Rate Limited
          content:
            application/json:
              schema:
                $ref: >-
                  #/components/schemas/api_gateway__models__enrichment__ErrorResponse
        '500':
          description: Internal Server Error
          content:
            application/json:
              schema:
                $ref: >-
                  #/components/schemas/api_gateway__models__enrichment__ErrorResponse
  /v1/enrich/research:
    post:
      tags:
        - Enrichment
      summary: Deep Research
      description: >-
        Conducts comprehensive research using advanced language models with
        real-time search capabilities.
      operationId: deep_research_v1_enrich_research_post
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/DeepResearchRequest'
        required: true
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DeepResearchResponse'
        '400':
          description: Bad Request
          content:
            application/json:
              schema:
                $ref: >-
                  #/components/schemas/api_gateway__models__enrichment__ErrorResponse
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: >-
                  #/components/schemas/api_gateway__models__enrichment__ErrorResponse
        '402':
          description: Insufficient Credits
          content:
            application/json:
              schema:
                $ref: >-
                  #/components/schemas/api_gateway__models__enrichment__ErrorResponse
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
        '429':
          description: Rate Limited
          content:
            application/json:
              schema:
                $ref: >-
                  #/components/schemas/api_gateway__models__enrichment__ErrorResponse
        '500':
          description: Internal Server Error
          content:
            application/json:
              schema:
                $ref: >-
                  #/components/schemas/api_gateway__models__enrichment__ErrorResponse
  /v1/match:
    post:
      tags:
        - Match
      summary: Match API
      description: >-
        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
      operationId: match_objects_v1_match_post
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/MatchRequest'
        required: true
      responses:
        '200':
          description: Success Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/MatchResponse'
              example:
                success: true
                results:
                  - input_index: 0
                    matches:
                      - sf_id: 001xx0001ABCDEF
                        object: Account
                        confidence: 0.91
                        explanations:
                          - domain eq
                          - name fuzzy 0.86
                        fields:
                          Name: TriNet Group, Inc.
                          Website: trinet.com
                          Phone: +1-800-874-6388
                    best_match: true
                    status: matched
                confidence: 0.9
                credits_consumed: 1
                credits_remaining: 10
                processing_time_ms: 1200
                cached: true
        '400':
          description: Bad Request - Invalid input parameters
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/api_gateway__models__match__ErrorResponse'
        '401':
          description: Unauthorized - Invalid or missing API key
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/api_gateway__models__match__ErrorResponse'
        '402':
          description: Insufficient Credits - Not enough credits to complete request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/api_gateway__models__match__ErrorResponse'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
        '429':
          description: Rate Limited - Too many requests
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/api_gateway__models__match__ErrorResponse'
        '500':
          description: Internal Server Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/api_gateway__models__match__ErrorResponse'
  /v1/salesforce/convert:
    post:
      tags:
        - Salesforce
      summary: Lead → Contact Auto-Convert & Merge
      description: >-
        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
      operationId: convert_lead_v1_salesforce_convert_post
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ConvertRequest'
        required: true
      responses:
        '200':
          description: Success Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ConvertResponse'
              example:
                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
        '400':
          description: Bad Request - Invalid input parameters
          content:
            application/json:
              schema:
                $ref: >-
                  #/components/schemas/api_gateway__models__salesforce__ErrorResponse
        '401':
          description: Unauthorized - Invalid or missing API key
          content:
            application/json:
              schema:
                $ref: >-
                  #/components/schemas/api_gateway__models__salesforce__ErrorResponse
        '402':
          description: Insufficient Credits - Not enough credits to complete request
          content:
            application/json:
              schema:
                $ref: >-
                  #/components/schemas/api_gateway__models__salesforce__ErrorResponse
        '409':
          description: Conflict - Duplicate record detected
          content:
            application/json:
              schema:
                $ref: >-
                  #/components/schemas/api_gateway__models__salesforce__ErrorResponse
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
        '429':
          description: Rate Limited - Too many requests
          content:
            application/json:
              schema:
                $ref: >-
                  #/components/schemas/api_gateway__models__salesforce__ErrorResponse
        '500':
          description: Internal Server Error
          content:
            application/json:
              schema:
                $ref: >-
                  #/components/schemas/api_gateway__models__salesforce__ErrorResponse
  /v1/routing/assign:
    post:
      tags:
        - Routing
      summary: Round Robin Assignment
      description: >-
        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
      operationId: assign_object_v1_routing_assign_post
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/AssignRequest'
        required: true
      responses:
        '200':
          description: Success Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AssignResponse'
              example:
                success: true
                assigned_to: 005xx0002ABCDE
                sequence: 1245
                pool_size: 17
                timestamp: '2025-09-18T16:12:00Z'
                credits_consumed: 1
                credits_remaining: 49
                processing_time_ms: 450
                cached: false
        '400':
          description: Bad Request - Invalid input parameters
          content:
            application/json:
              schema:
                $ref: >-
                  #/components/schemas/api_gateway__models__routing__ErrorResponse
        '401':
          description: Unauthorized - Invalid or missing API key
          content:
            application/json:
              schema:
                $ref: >-
                  #/components/schemas/api_gateway__models__routing__ErrorResponse
        '402':
          description: Insufficient Credits - Not enough credits to complete request
          content:
            application/json:
              schema:
                $ref: >-
                  #/components/schemas/api_gateway__models__routing__ErrorResponse
        '404':
          description: Not Found - Pool or user not found
          content:
            application/json:
              schema:
                $ref: >-
                  #/components/schemas/api_gateway__models__routing__ErrorResponse
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
        '429':
          description: Rate Limited - Too many requests
          content:
            application/json:
              schema:
                $ref: >-
                  #/components/schemas/api_gateway__models__routing__ErrorResponse
        '500':
          description: Internal Server Error
          content:
            application/json:
              schema:
                $ref: >-
                  #/components/schemas/api_gateway__models__routing__ErrorResponse
  /v1/triggers/salesforce:
    post:
      tags:
        - Triggers
      summary: Salesforce Trigger Webhook
      description: >-
        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
      operationId: salesforce_trigger_v1_triggers_salesforce_post
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/TriggerRequest'
        required: true
      responses:
        '200':
          description: Success Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TriggerResponse'
              example:
                success: true
                processed_count: 2
                enrichment_jobs:
                  - job_001
                  - job_002
                workflow_status: started
                credits_consumed: 4
                credits_remaining: 46
                processing_time_ms: 850
                cached: false
        '400':
          description: Bad Request - Invalid input parameters
          content:
            application/json:
              schema:
                $ref: >-
                  #/components/schemas/api_gateway__models__triggers__ErrorResponse
        '401':
          description: Unauthorized - Invalid or missing API key
          content:
            application/json:
              schema:
                $ref: >-
                  #/components/schemas/api_gateway__models__triggers__ErrorResponse
        '402':
          description: Insufficient Credits - Not enough credits to complete request
          content:
            application/json:
              schema:
                $ref: >-
                  #/components/schemas/api_gateway__models__triggers__ErrorResponse
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
        '429':
          description: Rate Limited - Too many requests
          content:
            application/json:
              schema:
                $ref: >-
                  #/components/schemas/api_gateway__models__triggers__ErrorResponse
        '500':
          description: Internal Server Error
          content:
            application/json:
              schema:
                $ref: >-
                  #/components/schemas/api_gateway__models__triggers__ErrorResponse
  /v1/triggers/polling/status:
    get:
      tags:
        - Triggers
      summary: Polling Status
      description: >-
        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
      operationId: get_polling_status_v1_triggers_polling_status_get
      responses:
        '200':
          description: Success Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PollingStatus'
        '401':
          description: Unauthorized - Invalid or missing API key
          content:
            application/json:
              schema:
                $ref: >-
                  #/components/schemas/api_gateway__models__triggers__ErrorResponse
        '500':
          description: Internal Server Error
          content:
            application/json:
              schema:
                $ref: >-
                  #/components/schemas/api_gateway__models__triggers__ErrorResponse
  /v1/logs/routing:
    get:
      tags:
        - Logs
      summary: Export Route Logs
      description: >-
        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
      operationId: export_route_logs_v1_logs_routing_get
      parameters:
        - name: from_date
          in: query
          required: true
          schema:
            type: string
            format: date-time
            description: Start date for log export (ISO format)
            title: From Date
          description: Start date for log export (ISO format)
        - name: to_date
          in: query
          required: true
          schema:
            type: string
            format: date-time
            description: End date for log export (ISO format)
            title: To Date
          description: End date for log export (ISO format)
        - name: pool
          in: query
          required: false
          schema:
            anyOf:
              - type: string
              - type: 'null'
            description: Filter by specific pool name
            title: Pool
          description: Filter by specific pool name
        - name: object
          in: query
          required: false
          schema:
            anyOf:
              - type: string
              - type: 'null'
            description: Filter by specific object type
            title: Object
          description: Filter by specific object type
        - name: action
          in: query
          required: false
          schema:
            anyOf:
              - type: string
              - type: 'null'
            description: Filter by specific action type
            title: Action
          description: Filter by specific action type
        - name: format
          in: query
          required: false
          schema:
            type: string
            description: Export format (json, csv)
            default: json
            title: Format
          description: Export format (json, csv)
        - name: include_diff
          in: query
          required: false
          schema:
            type: boolean
            description: Include diff data in export
            default: true
            title: Include Diff
          description: Include diff data in export
        - name: limit
          in: query
          required: false
          schema:
            type: integer
            maximum: 10000
            minimum: 1
            description: Maximum number of records to return
            default: 1000
            title: Limit
          description: Maximum number of records to return
      responses:
        '200':
          description: Success Response
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/RouteLog'
                title: Response Export Route Logs V1 Logs Routing Get
              example:
                - timestamp: '2025-09-18T16:12:00Z'
                  object: Lead
                  object_id: 00Qxx0000Lm789U
                  action: assign
                  pool: SDR_WEST_01
                  assigned_to: 005xx0002ABCDE
                  prev_owner: 005xx0001ZZZZZ
                  sequence: 1245
                  reason: round_robin
                  request_id: req_abc123
                  idempotency_key: c1f2-...
                - timestamp: '2025-09-18T16:15:00Z'
                  object: Lead
                  object_id: 00Qxx0000Lm78AA
                  action: enrich
                  reason: auto_enrichment
                  request_id: req_def456
                  idempotency_key: a3b4-...
                  diff:
                    Company:
                      to: Databricks
                    Industry:
                      from: Unknown
                      to: Software
        '400':
          description: Bad Request - Invalid query parameters
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/api_gateway__models__logs__ErrorResponse'
        '401':
          description: Unauthorized - Invalid or missing API key
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/api_gateway__models__logs__ErrorResponse'
        '402':
          description: Insufficient Credits - Not enough credits to complete request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/api_gateway__models__logs__ErrorResponse'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
        '429':
          description: Rate Limited - Too many requests
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/api_gateway__models__logs__ErrorResponse'
        '500':
          description: Internal Server Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/api_gateway__models__logs__ErrorResponse'
  /v1/agents/phone:
    post:
      tags:
        - Batch Agents
      summary: Phone Enrichment Batch
      description: >-
        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

        <!-- Choose **one** of the following options: -->


        **Submit IDs for processing:**

        - `ids`: Array of person IDs to process (1-1000 IDs)


        <!-- **Option 2: Submit record objects**

        - `records`: Array of person record objects to process (1-1000 records)
          - `id`: Unique identifier for the record (required)
          - `first_name`: Person's first name (optional)
          - `last_name`: Person's last name (optional)
          - `company`: Company name or website URL (optional)
          - `email`: Person's email address (optional)
          - `linkedin`: LinkedIn profile URL or identifier (optional) -->

        **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
        }

        ```


        <!-- ### Example 2: Submit record objects

        ```json

        {
          "records": [
            {
              "id": "550e8400-e29b-41d4-a716-446655440001",
              "first_name": "John",
              "last_name": "Smith",
              "company": "Acme Corp",
              "email": "john@acme.com",
              "linkedin": "https://linkedin.com/in/johnsmith"
            },
            {
              "id": "550e8400-e29b-41d4-a716-446655440002",
              "first_name": "Jane",
              "last_name": "Doe",
              "company": "TechCorp"
            }
          ],
          "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

        ```
      operationId: phone_enrich_batch_v1_agents_phone_post
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/PhoneEnrichBatchRequest'
        required: true
      responses:
        '202':
          description: Batch processing started successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BatchResponse'
              example:
                run_id: 550e8400-e29b-41d4-a716-446655440000
                result_path: >-
                  s3://{s3_bucket}/{entity_type}/phone-enrichment-batch_2025-01-15_550e8400-e29b-41d4-a716-446655440000.csv
                credits_csv_path: >-
                  s3://{s3_bucket}/{s3_prefix}/phone-enrichment/2025-01-15/550e8400-e29b-41d4-a716-446655440000_credits.csv
        '400':
          description: Bad Request - Invalid input parameters
        '401':
          description: Unauthorized - Invalid or missing API key
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BatchErrorResponse'
        '402':
          description: Insufficient Credits - Not enough credits available
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BatchErrorResponse'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
        '429':
          description: Rate Limited - Too many requests
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BatchErrorResponse'
        '500':
          description: Internal Server Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BatchErrorResponse'
  /v1/agents/email:
    post:
      tags:
        - Batch Agents
      summary: Email Enrichment Batch
      description: >-
        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

        <!-- Choose **one** of the following options: -->


        **Submit IDs for processing:**

        - `ids`: Array of person IDs to process (1-1000 IDs)


        <!-- **Option 2: Submit record objects**

        - `records`: Array of person record objects to process (1-1000 records)
          - `id`: Unique identifier for the record (required)
          - `first_name`: Person's first name (optional)
          - `last_name`: Person's last name (optional)
          - `company`: Company name (optional)
          - `company_domain`: Company domain or website URL (optional)
          - `linkedin`: LinkedIn profile URL or identifier (optional) -->

        **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
        }

        ```


        <!-- ### Example 2: Submit record objects

        ```json

        {
          "records": [
            {
              "id": "6ba7b810-9dad-11d1-80b4-00c04fd430c8",
              "first_name": "John",
              "last_name": "Smith",
              "company": "Acme Corp",
              "company_domain": "acme.com",
              "linkedin": "https://linkedin.com/in/johnsmith"
            },
            {
              "id": "6ba7b811-9dad-11d1-80b4-00c04fd430c8",
              "first_name": "Jane",
              "last_name": "Doe",
              "company": "TechCorp"
            }
          ],
          "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

        ```
      operationId: email_enrich_batch_v1_agents_email_post
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/EmailEnrichBatchRequest'
        required: true
      responses:
        '202':
          description: Batch processing started successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BatchResponse'
              example:
                run_id: 6ba7b810-9dad-11d1-80b4-00c04fd430c8
                result_path: >-
                  s3://{s3_bucket}/{entity_type}/phone-email-enrichment-batch_2025-01-15_550e8400-e29b-41d4-a716-446655440000.csv
                credits_csv_path: >-
                  s3://{s3_bucket}/{entity_type}/phone-email-enrichment/2025-01-15/550e8400-e29b-41d4-a716-446655440000_credits.csv
        '400':
          description: Bad Request - Invalid input parameters
        '401':
          description: Unauthorized - Invalid or missing API key
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BatchErrorResponse'
        '402':
          description: Insufficient Credits - Not enough credits available
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BatchErrorResponse'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
        '429':
          description: Rate Limited - Too many requests
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BatchErrorResponse'
        '500':
          description: Internal Server Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BatchErrorResponse'
  /v1/agents/deep-research:
    post:
      tags:
        - Batch Agents
      summary: Deep Research Batch
      description: >-
        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
        }

        ```
      operationId: deep_research_batch_v1_agents_deep_research_post
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/DeepResearchBatchRequest'
        required: true
      responses:
        '202':
          description: Batch processing started successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BatchResponse'
              example:
                run_id: a1b2c3d4-e5f6-7890-abcd-ef1234567890
                result_path: >-
                  s3://{s3_bucket}/{entity_type}/phone-email-enrichment-batch_2025-01-15_550e8400-e29b-41d4-a716-446655440000.csv
                credits_csv_path: >-
                  s3://{s3_bucket}/{entity_type}/phone-email-enrichment/2025-01-15/550e8400-e29b-41d4-a716-446655440000_credits.csv
        '400':
          description: Bad Request - Invalid input parameters
        '401':
          description: Unauthorized - Invalid or missing API key
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BatchErrorResponse'
        '402':
          description: Insufficient Credits - Not enough credits available
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BatchErrorResponse'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
        '429':
          description: Rate Limited - Too many requests
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BatchErrorResponse'
        '500':
          description: Internal Server Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BatchErrorResponse'
  /v1/agents/phone-email:
    post:
      tags:
        - Batch Agents
      summary: Phone & Email Enrichment Batch
      description: >-
        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

        ```
      operationId: phone_email_enrich_batch_v1_agents_phone_email_post
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/PhoneEnrichBatchRequest'
        required: true
      responses:
        '202':
          description: Batch processing started successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BatchResponse'
              example:
                run_id: 550e8400-e29b-41d4-a716-446655440000
                result_path: >-
                  s3://{s3_bucket}/{entity_type}/phone-email-enrichment-batch_2025-01-15_550e8400-e29b-41d4-a716-446655440000.csv
                credits_csv_path: >-
                  s3://{s3_bucket}/{entity_type}/phone-email-enrichment/2025-01-15/550e8400-e29b-41d4-a716-446655440000_credits.csv
        '400':
          description: Bad Request - Invalid input parameters
        '401':
          description: Unauthorized - Invalid or missing API key
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BatchErrorResponse'
        '402':
          description: Insufficient Credits - Not enough credits available
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BatchErrorResponse'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
        '429':
          description: Rate Limited - Too many requests
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BatchErrorResponse'
        '500':
          description: Internal Server Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BatchErrorResponse'
  /v1/agents/runs/{run_id}/status:
    get:
      tags:
        - Batch Agents
      summary: Get Run Status
      description: >-
        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 |
      operationId: get_workflow_run_status_v1_agents_runs__run_id__status_get
      parameters:
        - name: run_id
          in: path
          required: true
          schema:
            type: string
            title: Run Id
      responses:
        '200':
          description: Run status retrieved successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RunStatusResponse'
              example:
                run_id: 123e4567-e89b-12d3-a456-426614174000
                status: completed
        '400':
          description: Invalid run ID format
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RunErrorResponse'
        '401':
          description: Unauthorized - Invalid or missing API key
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RunErrorResponse'
        '404':
          description: Run not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RunErrorResponse'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
        '500':
          description: Internal Server Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RunErrorResponse'
  /v1/credits/usage:
    get:
      tags:
        - Credits
      summary: Get Credit Usage
      description: >-
        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
        }

        ```
      operationId: get_credit_usage_v1_credits_usage_get
      parameters:
        - name: start_date
          in: query
          required: true
          schema:
            type: string
            format: date-time
            description: Start date for credit calculation
            title: Start Date
          description: Start date for credit calculation
        - name: end_date
          in: query
          required: true
          schema:
            type: string
            format: date-time
            description: End date for credit calculation
            title: End Date
          description: End date for credit calculation
        - name: workflow_id
          in: query
          required: false
          schema:
            anyOf:
              - type: string
              - type: 'null'
            description: Optional workflow ID for filtering
            title: Workflow Id
          description: Optional workflow ID for filtering
        - name: workflow_run_id
          in: query
          required: false
          schema:
            anyOf:
              - type: string
              - type: 'null'
            description: Optional workflow run ID for filtering
            title: Workflow Run Id
          description: Optional workflow run ID for filtering
        - name: custom_key
          in: query
          required: false
          schema:
            anyOf:
              - type: string
              - type: 'null'
            description: Optional custom key for filtering
            title: Custom Key
          description: Optional custom key for filtering
        - name: custom_value
          in: query
          required: false
          schema:
            anyOf:
              - type: string
              - type: 'null'
            description: Optional custom value for filtering
            title: Custom Value
          description: Optional custom value for filtering
      responses:
        '200':
          description: Success Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CreditUsageResponse'
              example:
                success: true
                tenant_id: 123
                start_date: '2024-01-01T00:00:00Z'
                end_date: '2024-12-31T23:59:59Z'
                credits_used: 1250.5
        '400':
          description: Bad Request - Invalid input parameters
          content:
            application/json:
              schema:
                $ref: >-
                  #/components/schemas/api_gateway__models__credits__ErrorResponse
        '401':
          description: Unauthorized - Invalid or missing API key
          content:
            application/json:
              schema:
                $ref: >-
                  #/components/schemas/api_gateway__models__credits__ErrorResponse
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
        '429':
          description: Rate Limited - Too many requests
          content:
            application/json:
              schema:
                $ref: >-
                  #/components/schemas/api_gateway__models__credits__ErrorResponse
        '500':
          description: Internal Server Error
          content:
            application/json:
              schema:
                $ref: >-
                  #/components/schemas/api_gateway__models__credits__ErrorResponse
  /v1/credits/remaining:
    get:
      tags:
        - Credits
      summary: Get Remaining Credits
      description: >-
        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
        }

        ```
      operationId: get_remaining_credits_v1_credits_remaining_get
      responses:
        '200':
          description: Success Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RemainingCreditsResponse'
              example:
                success: true
                tenant_id: 123
                remaining_credits: 4750.25
        '401':
          description: Unauthorized - Invalid or missing API key
          content:
            application/json:
              schema:
                $ref: >-
                  #/components/schemas/api_gateway__models__credits__ErrorResponse
        '429':
          description: Rate Limited - Too many requests
          content:
            application/json:
              schema:
                $ref: >-
                  #/components/schemas/api_gateway__models__credits__ErrorResponse
        '500':
          description: Internal Server Error
          content:
            application/json:
              schema:
                $ref: >-
                  #/components/schemas/api_gateway__models__credits__ErrorResponse
  /v1/forms/submit:
    post:
      tags:
        - Forms
      summary: Submit Form
      description: >-
        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
      operationId: submit_form_v1_forms_submit_post
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/FormSubmitRequest'
        required: true
      responses:
        '200':
          description: Success Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/FormSubmitResponse'
              example:
                tenant_id: 1
                submission_id: 123e4567-e89b-12d3-a456-426614174000
                submission_timestamp: '2024-01-15T10:30:00Z'
                form_name: Lead Generation Form
                form_payload:
                  name: John Doe
                  email: john.doe@example.com
                  company: Acme Corp
                  phone: +1-555-123-4567
                  title: VP Sales
        '400':
          description: Bad Request - Invalid input parameters or validation errors
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/FormErrorResponse'
        '401':
          description: Unauthorized - Invalid or missing API key
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/FormErrorResponse'
        '402':
          description: Insufficient Credits - Not enough credits to complete request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/FormErrorResponse'
        '409':
          description: Conflict - Duplicate form submission detected
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/FormErrorResponse'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
        '429':
          description: Rate Limited - Too many requests
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/FormErrorResponse'
        '500':
          description: Internal Server Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/FormErrorResponse'
  /v1/workflows/{workflow_id}/trigger:
    post:
      tags:
        - Workflows
      summary: Trigger Workflow
      description: >-
        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
      operationId: trigger_workflow_v1_workflows__workflow_id__trigger_post
      parameters:
        - name: workflow_id
          in: path
          required: true
          schema:
            type: string
            title: Workflow Id
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/WorkflowTriggerRequest'
      responses:
        '200':
          description: Success Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/WorkflowTriggerResponse'
              example:
                success: true
                status: triggered
                request_id: req_1234567890abcdef
                workflow_id: wf_workflow_123
                processing_time_ms: 150
                enrichment_job_id: job_9876543210fedcba
                credits_consumed: 3
                credits_remaining: 97
                cached: false
        '400':
          description: Bad Request - Invalid input parameters
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/WorkflowErrorResponse'
        '401':
          description: Unauthorized - Invalid or missing API key
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/WorkflowErrorResponse'
        '402':
          description: Insufficient Credits - Not enough credits to complete request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/WorkflowErrorResponse'
        '409':
          description: Conflict - Duplicate workflow trigger detected
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/WorkflowErrorResponse'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
        '429':
          description: Rate Limited - Too many requests
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/WorkflowErrorResponse'
        '500':
          description: Internal Server Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/WorkflowErrorResponse'
components:
  schemas:
    AIEnrichmentOptions:
      properties:
        format_json:
          type: boolean
          title: Format Json
          description: Whether to return response in structured JSON format
          default: false
      type: object
      title: AIEnrichmentOptions
      description: Options for AI enrichment request.
    AIEnrichmentRequest:
      properties:
        query:
          type: string
          maxLength: 8000
          title: Query
          description: The main prompt or question to send to the AI model
        options:
          anyOf:
            - $ref: '#/components/schemas/AIEnrichmentOptions'
            - type: 'null'
          description: Additional configuration options
        effort:
          $ref: '#/components/schemas/EnrichmentEffortType'
          description: Enrichment effort type
          default: low
          examples:
            - low
            - medium
            - high
        agent_type:
          anyOf:
            - type: string
            - type: 'null'
          title: Agent Type
          description: Type of specialized agent to use for processing
          examples:
            - funding
            - legal
      type: object
      required:
        - query
      title: AIEnrichmentRequest
      description: Request model for AI enrichment.
    AIEnrichmentResponse:
      properties:
        success:
          type: boolean
          title: Success
          description: Boolean indicating request success
        query:
          type: string
          title: Query
          description: Echo of the input query
        response:
          anyOf:
            - type: string
            - additionalProperties: true
              type: object
          title: Response
          description: AI-generated response
        confidence:
          anyOf:
            - type: number
              maximum: 1
              minimum: 0
            - type: 'null'
          title: Confidence
          description: AI confidence score (0.0-1.0) or null if disabled
        credits_consumed:
          type: integer
          title: Credits Consumed
          description: Number of credits used for this request
        credits_remaining:
          type: integer
          title: Credits Remaining
          description: Credits remaining in your account after this request
        token_usage:
          $ref: '#/components/schemas/TokenUsage'
          description: Token consumption details
        processing_time_ms:
          type: integer
          title: Processing Time Ms
          description: Time taken to process the request in milliseconds
        agent_used:
          type: string
          title: Agent Used
          description: Type of agent that was used for processing
      type: object
      required:
        - success
        - query
        - response
        - credits_consumed
        - credits_remaining
        - token_usage
        - processing_time_ms
        - agent_used
      title: AIEnrichmentResponse
      description: Response model for AI enrichment.
    AgentType:
      type: string
      enum:
        - funding
        - legal
        - general
      title: AgentType
    AssignRequest:
      properties:
        object:
          type: string
          enum:
            - lead
            - contact
            - opportunity
            - account
          title: Object
          description: Salesforce object type to assign
        sf_id:
          type: string
          title: Sf Id
          description: Salesforce ID of the object to assign
        pool:
          type: string
          title: Pool
          description: Round-robin pool identifier
        exclude_inactive:
          type: boolean
          title: Exclude Inactive
          description: Whether to exclude inactive users from assignment
          default: true
        reset_rules:
          anyOf:
            - $ref: '#/components/schemas/ResetRules'
            - type: 'null'
          description: Optional reset rules for the assignment
      type: object
      required:
        - object
        - sf_id
        - pool
      title: AssignRequest
      description: Request model for round-robin assignment.
    AssignResponse:
      properties:
        success:
          type: boolean
          title: Success
          description: Boolean indicating request success
        assigned_to:
          type: string
          title: Assigned To
          description: User ID that was assigned
        sequence:
          type: integer
          title: Sequence
          description: Current sequence number in the rotation
        pool_size:
          type: integer
          title: Pool Size
          description: Total number of active users in the pool
        timestamp:
          type: string
          title: Timestamp
          description: ISO timestamp of the assignment
      type: object
      required:
        - success
        - assigned_to
        - sequence
        - pool_size
        - timestamp
      title: AssignResponse
      description: Response model for round-robin assignment.
    BatchErrorResponse:
      properties:
        error:
          type: string
          title: Error
          description: Error message
        details:
          anyOf:
            - type: string
            - type: 'null'
          title: Details
          description: Additional error details
        request_id:
          anyOf:
            - type: string
            - type: 'null'
          title: Request Id
          description: Request ID for tracking
        credits_required:
          anyOf:
            - type: integer
            - type: 'null'
          title: Credits Required
          description: Credits required for insufficient credit errors
        credits_remaining:
          anyOf:
            - type: integer
            - type: 'null'
          title: Credits Remaining
          description: Credits remaining for insufficient credit errors
        retry_after:
          anyOf:
            - type: integer
            - type: 'null'
          title: Retry After
          description: Seconds to wait before retrying for rate limit errors
      type: object
      required:
        - error
      title: BatchErrorResponse
      description: Error response model for batch operations.
    BatchResponse:
      properties:
        run_id:
          type: string
          title: Run Id
          description: Unique identifier for the batch run
        result_path:
          type: string
          title: Result Path
          description: S3 bucket path where results will be stored
        credits_csv_path:
          type: string
          title: Credits Csv Path
          description: S3 bucket path where credit usage report will be stored
      type: object
      required:
        - run_id
        - result_path
        - credits_csv_path
      title: BatchResponse
      description: Response model for batch operations.
    CompanyEnrichmentData:
      properties:
        name:
          anyOf:
            - type: string
            - type: 'null'
          title: Name
          description: Company name
        domain:
          anyOf:
            - type: string
            - type: 'null'
          title: Domain
          description: Company domain
        linkedin_url:
          anyOf:
            - type: string
            - type: 'null'
          title: Linkedin Url
          description: LinkedIn company page URL
        hq:
          anyOf:
            - $ref: '#/components/schemas/CompanyLocation'
            - type: 'null'
          description: Headquarters location
        size_range:
          anyOf:
            - type: string
            - type: 'null'
          title: Size Range
          description: Employee size range (e.g., '500+')
        industry:
          anyOf:
            - type: string
            - type: 'null'
          title: Industry
          description: Industry classification
        geo:
          anyOf:
            - $ref: '#/components/schemas/CompanyGeo'
            - type: 'null'
          description: Geographic coordinates and location details
        last_verified_at:
          anyOf:
            - type: string
            - type: 'null'
          title: Last Verified At
          description: ISO timestamp of last verification
      type: object
      title: CompanyEnrichmentData
      description: Company enrichment data response.
    CompanyEnrichmentRequest:
      properties:
        record_id:
          type: string
          title: Record Id
          description: Unique identifier for this enrichment request
        company_name:
          anyOf:
            - type: string
            - type: 'null'
          title: Company Name
          description: Company name
        domain:
          anyOf:
            - type: string
            - type: 'null'
          title: Domain
          description: Company domain
        country:
          anyOf:
            - type: string
            - type: 'null'
          title: Country
          description: Country code or name
        external_ids:
          anyOf:
            - additionalProperties:
                type: string
              type: object
            - type: 'null'
          title: External Ids
          description: External system IDs (e.g., Salesforce account ID)
        effort:
          $ref: '#/components/schemas/EnrichmentEffortType'
          description: Enrichment effort type
          default: low
          examples:
            - low
            - medium
            - high
        max_credits:
          type: integer
          maximum: 100
          minimum: 1
          title: Max Credits
          description: Maximum credits to spend on this request
          default: 1
      type: object
      required:
        - record_id
      title: CompanyEnrichmentRequest
      description: Request model for company enrichment.
    CompanyEnrichmentResponse:
      properties:
        success:
          type: boolean
          title: Success
          description: Boolean indicating request success
        record_id:
          type: string
          title: Record Id
          description: Unique identifier for this enrichment request
        company:
          anyOf:
            - $ref: '#/components/schemas/CompanyEnrichmentData'
            - type: 'null'
          description: Enriched company data
        confidence:
          anyOf:
            - type: number
              maximum: 1
              minimum: 0
            - type: 'null'
          title: Confidence
          description: Confidence score (0.0-1.0) or null if disabled/not found
        credits_consumed:
          type: integer
          title: Credits Consumed
          description: Number of credits used for this request
        credits_remaining:
          type: integer
          title: Credits Remaining
          description: Credits remaining in your account after this request
        processing_time_ms:
          type: integer
          title: Processing Time Ms
          description: Time taken to process the request in milliseconds
        cached:
          type: boolean
          title: Cached
          description: Boolean indicating if this result was returned from cache
      type: object
      required:
        - success
        - record_id
        - credits_consumed
        - credits_remaining
        - processing_time_ms
        - cached
      title: CompanyEnrichmentResponse
      description: Response model for company enrichment.
    CompanyGeo:
      properties:
        lat:
          anyOf:
            - type: number
            - type: 'null'
          title: Lat
          description: Latitude coordinate
        lon:
          anyOf:
            - type: number
            - type: 'null'
          title: Lon
          description: Longitude coordinate
        county:
          anyOf:
            - type: string
            - type: 'null'
          title: County
          description: County or administrative division
      type: object
      title: CompanyGeo
      description: Geographic coordinates and location details.
    CompanyLocation:
      properties:
        city:
          anyOf:
            - type: string
            - type: 'null'
          title: City
          description: City name
        state:
          anyOf:
            - type: string
            - type: 'null'
          title: State
          description: State or province
        country:
          anyOf:
            - type: string
            - type: 'null'
          title: Country
          description: Country code or name
        postal_code:
          anyOf:
            - type: string
            - type: 'null'
          title: Postal Code
          description: Postal or ZIP code
      type: object
      title: CompanyLocation
      description: Company headquarters location information.
    ConversionLogs:
      properties:
        route_log:
          type: boolean
          title: Route Log
          description: Whether to log routing information
          default: true
        enrichment_diff:
          type: boolean
          title: Enrichment Diff
          description: Whether to log enrichment differences
          default: true
      type: object
      title: ConversionLogs
      description: Logging configuration for conversion.
    ConversionMatchPolicy:
      properties:
        contact:
          $ref: '#/components/schemas/MatchPolicy'
          description: Contact matching policy
        account:
          $ref: '#/components/schemas/MatchPolicy'
          description: Account matching policy
      type: object
      required:
        - contact
        - account
      title: ConversionMatchPolicy
      description: Match policy configuration for conversion.
    ConvertRequest:
      properties:
        lead_sf_id:
          type: string
          title: Lead Sf Id
          description: Salesforce Lead ID to convert
        match_policy:
          $ref: '#/components/schemas/ConversionMatchPolicy'
          description: Match policy configuration
        merge_policy:
          $ref: '#/components/schemas/MergePolicy'
          description: Merge policy configuration
        set_owner_round_robin_pool:
          anyOf:
            - type: string
            - type: 'null'
          title: Set Owner Round Robin Pool
          description: Round-robin pool for owner assignment
        logs:
          $ref: '#/components/schemas/ConversionLogs'
          description: Logging configuration
      type: object
      required:
        - lead_sf_id
        - match_policy
        - merge_policy
      title: ConvertRequest
      description: Request model for Salesforce lead conversion.
    ConvertResponse:
      properties:
        success:
          type: boolean
          title: Success
          description: Boolean indicating request success
        status:
          type: string
          enum:
            - converted
            - failed
            - duplicate
          title: Status
          description: Conversion status
        account_id:
          anyOf:
            - type: string
            - type: 'null'
          title: Account Id
          description: Created or matched Account ID
        contact_id:
          anyOf:
            - type: string
            - type: 'null'
          title: Contact Id
          description: Created or matched Contact ID
        owner_id:
          anyOf:
            - type: string
            - type: 'null'
          title: Owner Id
          description: Assigned Owner ID
        actions:
          items:
            type: string
          type: array
          title: Actions
          description: List of actions performed during conversion
      type: object
      required:
        - success
        - status
        - actions
      title: ConvertResponse
      description: Response model for Salesforce lead conversion.
    CreditUsageResponse:
      properties:
        success:
          type: boolean
          title: Success
          description: Boolean indicating request success
        tenant_id:
          type: integer
          title: Tenant Id
          description: Tenant ID
        start_date:
          type: string
          format: date-time
          title: Start Date
          description: Start date for credit calculation
        end_date:
          type: string
          format: date-time
          title: End Date
          description: End date for credit calculation
        credits_used:
          type: number
          title: Credits Used
          description: Total credits used in the period
      type: object
      required:
        - success
        - tenant_id
        - start_date
        - end_date
        - credits_used
      title: CreditUsageResponse
      description: Response model for credit usage.
    DeepResearchBatchRequest:
      properties:
        ids:
          items:
            type: string
          type: array
          maxItems: 1000
          minItems: 1
          title: Ids
          description: List of IDs to process for deep research
        query_hint:
          type: string
          title: Query Hint
          description: Query hint for research context (optional)
          default: ''
        entity_type:
          $ref: '#/components/schemas/EntityType'
          description: Type of entity being processed (company or person)
        effort:
          $ref: '#/components/schemas/EnrichmentEffortType'
          description: Effort level for deep research processing
          default: medium
        agent_type:
          $ref: '#/components/schemas/AgentType'
          description: >-
            Type of specialized agent to use for deep research (defaults to
            'general')
          default: general
        max_credits:
          type: integer
          exclusiveMinimum: 0
          title: Max Credits
          description: Maximum credits this request is allowed to consume
      type: object
      required:
        - ids
        - entity_type
        - max_credits
      title: DeepResearchBatchRequest
      description: Request model for deep research batch operations.
    DeepResearchOptions:
      properties:
        format_json:
          type: boolean
          title: Format Json
          description: Whether to format the response as JSON
          default: false
      type: object
      title: DeepResearchOptions
      description: Options for deep research requests.
    DeepResearchRequest:
      properties:
        query:
          type: string
          maxLength: 8000
          title: Query
          description: The research question or topic to investigate deeply
          examples:
            - >-
              Research the latest developments in renewable energy storage
              technology
            - >-
              Analyze the competitive landscape for AI-powered customer service
              platforms
            - What are the emerging trends in sustainable agriculture practices?
        options:
          anyOf:
            - $ref: '#/components/schemas/DeepResearchOptions'
            - type: 'null'
          description: Additional options for the deep research
        agent_type:
          anyOf:
            - type: string
            - type: 'null'
          title: Agent Type
          description: Type of specialized agent to use for processing
          examples:
            - funding
            - legal
      type: object
      required:
        - query
      title: DeepResearchRequest
      description: Request model for deep research LLM calls.
    DeepResearchResponse:
      properties:
        success:
          type: boolean
          title: Success
          description: Boolean indicating request success
        query:
          type: string
          title: Query
          description: Echo of the input query
        response:
          anyOf:
            - type: string
            - additionalProperties: true
              type: object
          title: Response
          description: Deep research response with comprehensive analysis
        confidence:
          anyOf:
            - type: number
              maximum: 1
              minimum: 0
            - type: 'null'
          title: Confidence
          description: AI confidence score (0.0-1.0) or null if disabled
        credits_consumed:
          type: integer
          title: Credits Consumed
          description: Number of credits used for this request
        credits_remaining:
          type: integer
          title: Credits Remaining
          description: Credits remaining in your account after this request
        token_usage:
          $ref: '#/components/schemas/TokenUsage'
          description: Token consumption details
        processing_time_ms:
          type: integer
          title: Processing Time Ms
          description: Time taken to process the request in milliseconds
        agent_used:
          type: string
          title: Agent Used
          description: Type of agent that was used for processing
      type: object
      required:
        - success
        - query
        - response
        - credits_consumed
        - credits_remaining
        - token_usage
        - processing_time_ms
        - agent_used
      title: DeepResearchResponse
      description: Response model for deep research.
    EmailEnrichBatchRequest:
      properties:
        ids:
          anyOf:
            - items:
                type: string
              type: array
              maxItems: 1000
              minItems: 1
            - type: 'null'
          title: Ids
          description: List of IDs to process for email enrichment
        records:
          anyOf:
            - items:
                $ref: '#/components/schemas/EmailEnrichmentRecord'
              type: array
              maxItems: 1000
              minItems: 1
            - type: 'null'
          title: Records
          description: List of record objects to process for email enrichment
        entity_type:
          type: string
          const: person
          title: Entity Type
          description: >-
            Type of entity being processed (must be 'person' for email
            enrichment)
          default: person
        max_credits:
          type: integer
          exclusiveMinimum: 0
          title: Max Credits
          description: Maximum credits this request is allowed to consume
      type: object
      required:
        - max_credits
      title: EmailEnrichBatchRequest
      description: Request model for email enrichment batch operations.
      examples:
        - entity_type: person
          ids:
            - 6ba7b810-9dad-11d1-80b4-00c04fd430c8
            - 6ba7b811-9dad-11d1-80b4-00c04fd430c8
            - 6ba7b812-9dad-11d1-80b4-00c04fd430c8
          max_credits: 100
    EmailEnrichmentRecord:
      properties:
        id:
          type: string
          title: Id
          description: Unique identifier for the record
        first_name:
          anyOf:
            - type: string
            - type: 'null'
          title: First Name
          description: Person's first name
        last_name:
          anyOf:
            - type: string
            - type: 'null'
          title: Last Name
          description: Person's last name
        company:
          anyOf:
            - type: string
            - type: 'null'
          title: Company
          description: Company name or website URL
        company_domain:
          anyOf:
            - type: string
            - type: 'null'
          title: Company Domain
          description: Company domain
        linkedin:
          anyOf:
            - type: string
            - type: 'null'
          title: Linkedin
          description: LinkedIn profile URL or identifier
      type: object
      required:
        - id
      title: EmailEnrichmentRecord
      description: Record model for email enrichment batch operations.
    EmailEnrichmentRequest:
      properties:
        record_id:
          type: string
          title: Record Id
          description: Your unique identifier for this record
        first_name:
          type: string
          title: First Name
          description: Contact's first name
        last_name:
          type: string
          title: Last Name
          description: Contact's last name
        company:
          type: string
          title: Company
          description: Company name or website URL where the contact works
        company_domain:
          anyOf:
            - type: string
            - type: 'null'
          title: Company Domain
          description: Company domain (optional)
        linkedin_id:
          anyOf:
            - type: string
            - type: 'null'
          title: Linkedin Id
          description: LinkedIn profile identifier/slug (e.g., 'john-doe-123456')
          examples:
            - john-doe-123456
            - jane-smith-789
        max_credits:
          anyOf:
            - type: integer
              exclusiveMinimum: 0
            - type: 'null'
          title: Max Credits
          description: Maximum credits to spend on this request
      type: object
      required:
        - record_id
        - first_name
        - last_name
        - company
      title: EmailEnrichmentRequest
      description: Request model for email enrichment.
    EmailEnrichmentResponse:
      properties:
        success:
          type: boolean
          title: Success
          description: Boolean indicating request success
        record_id:
          type: string
          title: Record Id
          description: Echo of the input record ID
        first_name:
          type: string
          title: First Name
          description: Echo of input first name
        last_name:
          type: string
          title: Last Name
          description: Echo of input last name
        company:
          type: string
          title: Company
          description: Echo of input company
        email:
          anyOf:
            - type: string
            - type: 'null'
          title: Email
          description: Professional email address or null if not found
        confidence:
          anyOf:
            - type: number
              maximum: 1
              minimum: 0
            - type: 'null'
          title: Confidence
          description: Confidence score (0.0-1.0) or null if disabled/not found
        credits_consumed:
          type: integer
          title: Credits Consumed
          description: Number of credits used for this request
        credits_remaining:
          type: integer
          title: Credits Remaining
          description: Credits remaining in your account after this request
        processing_time_ms:
          type: integer
          title: Processing Time Ms
          description: Time taken to process the request in milliseconds
        cached:
          type: boolean
          title: Cached
          description: Boolean indicating if this result was returned from cache
      type: object
      required:
        - success
        - record_id
        - first_name
        - last_name
        - company
        - credits_consumed
        - credits_remaining
        - processing_time_ms
        - cached
      title: EmailEnrichmentResponse
      description: Response model for email enrichment.
    EmailStatus:
      type: string
      enum:
        - valid
        - accept_all
        - risky
        - invalid
        - unknown
      title: EmailStatus
    EnrichmentEffortType:
      type: string
      enum:
        - low
        - medium
        - high
      title: EnrichmentEffortType
    EntityType:
      type: string
      enum:
        - person
        - company
      title: EntityType
    FormErrorResponse:
      properties:
        success:
          type: boolean
          title: Success
          description: Always false for error responses
          default: false
        error:
          type: string
          title: Error
          description: Error message
        details:
          anyOf:
            - type: string
            - type: 'null'
          title: Details
          description: Additional error details
        request_id:
          anyOf:
            - type: string
            - type: 'null'
          title: Request Id
          description: Request ID for tracking
        validation_errors:
          anyOf:
            - additionalProperties:
                type: string
              type: object
            - type: 'null'
          title: Validation Errors
          description: Field-specific validation errors
        retry_after:
          anyOf:
            - type: integer
            - type: 'null'
          title: Retry After
          description: Seconds to wait before retrying for rate limit errors
      type: object
      required:
        - error
      title: FormErrorResponse
      description: Error response model for Form Submit API.
    FormSubmitRequest:
      properties:
        form_name:
          type: string
          title: Form Name
          description: Name of the form
        form_payload:
          additionalProperties: true
          type: object
          title: Form Payload
          description: Payload of the form
      type: object
      required:
        - form_name
        - form_payload
      title: FormSubmitRequest
      description: Request model for Form Submit API.
    FormSubmitResponse:
      properties:
        tenant_id:
          type: integer
          title: Tenant Id
          description: Tenant ID
        submission_id:
          type: string
          format: uuid
          title: Submission Id
          description: Submission ID
        submitted_at:
          type: string
          format: date-time
          title: Submitted At
          description: Submission timestamp
        form_name:
          type: string
          title: Form Name
          description: Name of the form
        form_payload:
          additionalProperties: true
          type: object
          title: Form Payload
          description: Payload of the form
      type: object
      required:
        - tenant_id
        - submission_id
        - submitted_at
        - form_name
        - form_payload
      title: FormSubmitResponse
      description: Response model for Form Submit API.
    HTTPValidationError:
      properties:
        detail:
          items:
            $ref: '#/components/schemas/ValidationError'
          type: array
          title: Detail
      type: object
      title: HTTPValidationError
    MatchCandidate:
      properties:
        company_name:
          anyOf:
            - type: string
            - type: 'null'
          title: Company Name
          description: Company name
        domain:
          anyOf:
            - type: string
            - type: 'null'
          title: Domain
          description: Company domain
        billing_street:
          anyOf:
            - type: string
            - type: 'null'
          title: Billing Street
          description: Billing street address
        phone:
          anyOf:
            - type: string
            - type: 'null'
          title: Phone
          description: Phone number
        email:
          anyOf:
            - type: string
            - type: 'null'
          title: Email
          description: Email address
        first_name:
          anyOf:
            - type: string
            - type: 'null'
          title: First Name
          description: First name (for contacts/leads)
        last_name:
          anyOf:
            - type: string
            - type: 'null'
          title: Last Name
          description: Last name (for contacts/leads)
        title:
          anyOf:
            - type: string
            - type: 'null'
          title: Title
          description: Job title (for contacts/leads)
      type: object
      title: MatchCandidate
      description: Individual candidate for matching.
    MatchCandidateResult:
      properties:
        input_index:
          type: integer
          title: Input Index
          description: Index of the input candidate
        matches:
          items:
            $ref: '#/components/schemas/MatchResult'
          type: array
          title: Matches
          description: List of matches found
        best_match:
          type: boolean
          title: Best Match
          description: Whether this is the best match
        status:
          type: string
          enum:
            - matched
            - no_match
            - ambiguous
          title: Status
          description: Match status
      type: object
      required:
        - input_index
        - matches
        - best_match
        - status
      title: MatchCandidateResult
      description: Result for a single candidate.
    MatchGroup:
      properties:
        all:
          items:
            type: string
          type: array
          title: All
          description: List of field rules that must all match
      type: object
      required:
        - all
      title: MatchGroup
      description: Match group with boolean logic.
    MatchPolicy:
      properties:
        by:
          items:
            type: string
          type: array
          title: By
          description: List of field rules for matching
        create_if_no_match:
          type: boolean
          title: Create If No Match
          description: Whether to create new record if no match found
      type: object
      required:
        - by
        - create_if_no_match
      title: MatchPolicy
      description: Match policy for contact or account matching.
    MatchRequest:
      properties:
        object:
          type: string
          enum:
            - account
            - contact
            - lead
          title: Object
          description: Object type to match
        candidates:
          items:
            $ref: '#/components/schemas/MatchCandidate'
          type: array
          title: Candidates
          description: List of candidates to match
        rules:
          $ref: '#/components/schemas/MatchRules'
          description: Matching rules configuration
        context:
          anyOf:
            - additionalProperties: true
              type: object
            - type: 'null'
          title: Context
          description: Context information
        max_credits:
          type: integer
          maximum: 100
          minimum: 1
          title: Max Credits
          description: Maximum credits to spend
          default: 1
      type: object
      required:
        - object
        - candidates
        - rules
      title: MatchRequest
      description: Request model for match API.
    MatchResponse:
      properties:
        success:
          type: boolean
          title: Success
          description: Boolean indicating request success
        results:
          items:
            $ref: '#/components/schemas/MatchCandidateResult'
          type: array
          title: Results
          description: List of candidate results
        confidence:
          anyOf:
            - type: number
              maximum: 1
              minimum: 0
            - type: 'null'
          title: Confidence
          description: Confidence score (0.0-1.0) or null if disabled/not found
        credits_consumed:
          type: integer
          title: Credits Consumed
          description: Number of credits used for this request
        credits_remaining:
          type: integer
          title: Credits Remaining
          description: Credits remaining in your account after this request
        processing_time_ms:
          type: integer
          title: Processing Time Ms
          description: Time taken to process the request in milliseconds
        cached:
          type: boolean
          title: Cached
          description: Boolean indicating if this result was returned from cache
      type: object
      required:
        - success
        - results
        - credits_consumed
        - credits_remaining
        - processing_time_ms
        - cached
      title: MatchResponse
      description: Response model for match API.
    MatchResult:
      properties:
        sf_id:
          type: string
          title: Sf Id
          description: Salesforce ID of the matched record
        object:
          type: string
          title: Object
          description: >-
            Object type of the matched record (e.g., 'Account', 'Contact',
            'Lead')
        confidence:
          type: number
          maximum: 1
          minimum: 0
          title: Confidence
          description: Overall confidence score
        explanations:
          items:
            type: string
          type: array
          title: Explanations
          description: List of match explanations (e.g., ['domain eq', 'name fuzzy 0.86'])
        fields:
          additionalProperties: true
          type: object
          title: Fields
          description: >-
            Matched record fields (e.g., {'Name': 'Company Name', 'Website':
            'example.com'})
      type: object
      required:
        - sf_id
        - object
        - confidence
        - explanations
        - fields
      title: MatchResult
      description: Individual match result.
    MatchRules:
      properties:
        mode:
          type: string
          enum:
            - simple
            - grouped
            - ai
          title: Mode
          description: Matching mode
        groups:
          anyOf:
            - items:
                $ref: '#/components/schemas/MatchGroup'
              type: array
            - type: 'null'
          title: Groups
          description: Match groups (for grouped mode)
        any:
          type: boolean
          title: Any
          description: Match if any group is true
          default: true
        threshold:
          type: number
          maximum: 1
          minimum: 0
          title: Threshold
          description: Overall confidence cutoff
        effort:
          anyOf:
            - type: string
              enum:
                - low
                - medium
                - high
            - type: 'null'
          title: Effort
          description: Enrichment effort level (for AI mode)
          examples:
            - low
            - medium
            - high
      type: object
      required:
        - mode
        - threshold
      title: MatchRules
      description: Match rules configuration.
    MergePolicy:
      properties:
        on_contact_match:
          type: string
          title: On Contact Match
          description: Action when contact match is found
        on_account_match:
          type: string
          title: On Account Match
          description: Action when account match is found
      type: object
      required:
        - on_contact_match
        - on_account_match
      title: MergePolicy
      description: Merge policy configuration.
    PersonEnrichmentData:
      properties:
        full_name:
          anyOf:
            - type: string
            - type: 'null'
          title: Full Name
          description: Person's full name
        email:
          anyOf:
            - type: string
            - type: 'null'
          title: Email
          description: Person's email address
        email_confidence:
          anyOf:
            - type: number
              maximum: 1
              minimum: 0
            - type: 'null'
          title: Email Confidence
          description: Email confidence score (0.0-1.0)
        email_status:
          $ref: '#/components/schemas/EmailStatus'
          description: >-
            Email verification status: valid, accept_all, risky, invalid,
            unknown
          default: unknown
        phone:
          anyOf:
            - type: string
            - type: 'null'
          title: Phone
          description: Direct phone number
        title:
          anyOf:
            - type: string
            - type: 'null'
          title: Title
          description: Job title
        linkedin_url:
          anyOf:
            - type: string
            - type: 'null'
          title: Linkedin Url
          description: LinkedIn profile URL
        job_last_seen_at:
          anyOf:
            - type: string
            - type: 'null'
          title: Job Last Seen At
          description: ISO timestamp when job information was last verified
      type: object
      title: PersonEnrichmentData
      description: Person enrichment data response.
    PersonEnrichmentRequest:
      properties:
        record_id:
          type: string
          title: Record Id
          description: Unique identifier for this enrichment request
        first_name:
          type: string
          title: First Name
          description: Person's first name
        last_name:
          type: string
          title: Last Name
          description: Person's last name
        company_domain:
          type: string
          title: Company Domain
          description: Company domain where the person works
        email:
          anyOf:
            - type: string
            - type: 'null'
          title: Email
          description: Person's email address
        linkedin_id:
          anyOf:
            - type: string
            - type: 'null'
          title: Linkedin Id
          description: LinkedIn ID or profile URL
        effort:
          $ref: '#/components/schemas/EnrichmentEffortType'
          description: Enrichment effort type
          default: low
          examples:
            - low
            - medium
            - high
        max_credits:
          type: integer
          maximum: 100
          minimum: 1
          title: Max Credits
          description: Maximum credits to spend on this request
          default: 1
      type: object
      required:
        - record_id
        - first_name
        - last_name
        - company_domain
      title: PersonEnrichmentRequest
      description: Request model for person enrichment.
    PersonEnrichmentResponse:
      properties:
        success:
          type: boolean
          title: Success
          description: Boolean indicating request success
        record_id:
          type: string
          title: Record Id
          description: Unique identifier for this enrichment request
        person:
          anyOf:
            - $ref: '#/components/schemas/PersonEnrichmentData'
            - type: 'null'
          description: Enriched person data
        confidence:
          anyOf:
            - type: number
              maximum: 1
              minimum: 0
            - type: 'null'
          title: Confidence
          description: Confidence score (0.0-1.0) or null if disabled/not found
        credits_consumed:
          type: integer
          title: Credits Consumed
          description: Number of credits used for this request
        credits_remaining:
          type: integer
          title: Credits Remaining
          description: Credits remaining in your account after this request
        processing_time_ms:
          type: integer
          title: Processing Time Ms
          description: Time taken to process the request in milliseconds
        cached:
          type: boolean
          title: Cached
          description: Boolean indicating if this result was returned from cache
      type: object
      required:
        - success
        - record_id
        - credits_consumed
        - credits_remaining
        - processing_time_ms
        - cached
      title: PersonEnrichmentResponse
      description: Response model for person enrichment.
    PhoneEnrichBatchRequest:
      properties:
        ids:
          anyOf:
            - items:
                type: string
              type: array
              maxItems: 1000
              minItems: 1
            - type: 'null'
          title: Ids
          description: List of IDs to process for phone enrichment
        records:
          anyOf:
            - items:
                $ref: '#/components/schemas/PhoneEnrichmentRecord'
              type: array
              maxItems: 1000
              minItems: 1
            - type: 'null'
          title: Records
          description: List of record objects to process for phone enrichment
        entity_type:
          type: string
          const: person
          title: Entity Type
          description: >-
            Type of entity being processed (must be 'person' for phone
            enrichment)
          default: person
        max_credits:
          type: integer
          exclusiveMinimum: 0
          title: Max Credits
          description: Maximum credits this request is allowed to consume
      type: object
      required:
        - max_credits
      title: PhoneEnrichBatchRequest
      description: Request model for phone enrichment batch operations.
      examples:
        - entity_type: person
          ids:
            - 550e8400-e29b-41d4-a716-446655440001
            - 550e8400-e29b-41d4-a716-446655440002
            - 550e8400-e29b-41d4-a716-446655440003
          max_credits: 100
    PhoneEnrichmentRecord:
      properties:
        id:
          type: string
          title: Id
          description: Unique identifier for the record
        first_name:
          anyOf:
            - type: string
            - type: 'null'
          title: First Name
          description: Person's first name
        last_name:
          anyOf:
            - type: string
            - type: 'null'
          title: Last Name
          description: Person's last name
        company:
          anyOf:
            - type: string
            - type: 'null'
          title: Company
          description: Company name or website URL
        email:
          anyOf:
            - type: string
            - type: 'null'
          title: Email
          description: Person's email address
        linkedin:
          anyOf:
            - type: string
            - type: 'null'
          title: Linkedin
          description: LinkedIn profile URL or identifier
      type: object
      required:
        - id
      title: PhoneEnrichmentRecord
      description: Record model for phone enrichment batch operations.
    PhoneEnrichmentRequest:
      properties:
        record_id:
          type: string
          title: Record Id
          description: Your unique identifier for this record
        first_name:
          anyOf:
            - type: string
            - type: 'null'
          title: First Name
          description: Contact's first name (required for name-based enrichment)
        last_name:
          anyOf:
            - type: string
            - type: 'null'
          title: Last Name
          description: Contact's last name (required for name-based enrichment)
        company:
          anyOf:
            - type: string
            - type: 'null'
          title: Company
          description: Company name or website URL (required for name-based enrichment)
        email:
          anyOf:
            - type: string
            - type: 'null'
          title: Email
          description: Contact's email address (optional)
        linkedin_id:
          anyOf:
            - type: string
            - type: 'null'
          title: Linkedin Id
          description: LinkedIn profile identifier/slug (e.g., 'john-doe-123456')
          examples:
            - john-doe-123456
            - jane-smith-789
        domain:
          anyOf:
            - type: string
            - type: 'null'
          title: Domain
          description: Company domain (optional) - improves accuracy when provided
      type: object
      required:
        - record_id
      title: PhoneEnrichmentRequest
      description: Request model for phone enrichment.
    PhoneEnrichmentResponse:
      properties:
        success:
          type: boolean
          title: Success
          description: Boolean indicating request success
        record_id:
          type: string
          title: Record Id
          description: Echo of the input record ID
        first_name:
          anyOf:
            - type: string
            - type: 'null'
          title: First Name
          description: Echo of input first name
        last_name:
          anyOf:
            - type: string
            - type: 'null'
          title: Last Name
          description: Echo of input last name
        company:
          anyOf:
            - type: string
            - type: 'null'
          title: Company
          description: Echo of input company
        email:
          anyOf:
            - type: string
            - type: 'null'
          title: Email
          description: Echo of input email or email found during enrichment
        linkedin_id:
          anyOf:
            - type: string
            - type: 'null'
          title: Linkedin Id
          description: >-
            Echo of input LinkedIn ID or LinkedIn profile found during
            enrichment
        phone:
          anyOf:
            - type: string
            - type: 'null'
          title: Phone
          description: International format phone number (E.164) or null if not found
        processing_time_ms:
          type: integer
          title: Processing Time Ms
          description: Time taken to process the request in milliseconds
      type: object
      required:
        - success
        - record_id
        - processing_time_ms
      title: PhoneEnrichmentResponse
      description: Response model for phone enrichment.
    PollingStatus:
      properties:
        last_poll_time:
          type: string
          title: Last Poll Time
          description: ISO timestamp of last poll
        records_processed:
          type: integer
          title: Records Processed
          description: Number of records processed in last poll
        watermark_value:
          type: string
          title: Watermark Value
          description: Current watermark value
        next_poll_time:
          type: string
          title: Next Poll Time
          description: ISO timestamp of next scheduled poll
      type: object
      required:
        - last_poll_time
        - records_processed
        - watermark_value
        - next_poll_time
      title: PollingStatus
      description: Status of polling-based enrichment.
    RemainingCreditsResponse:
      properties:
        success:
          type: boolean
          title: Success
          description: Boolean indicating request success
        tenant_id:
          type: integer
          title: Tenant Id
          description: Tenant ID
        remaining_credits:
          type: number
          title: Remaining Credits
          description: Remaining credits for the tenant
        total_credits:
          type: number
          title: Total Credits
          description: Total credits for the tenant
      type: object
      required:
        - success
        - tenant_id
        - remaining_credits
        - total_credits
      title: RemainingCreditsResponse
      description: Response model for remaining credits.
    ResetRules:
      properties:
        reason:
          type: string
          title: Reason
          description: Reason for reset (e.g., 'bad_fit', 'user_request')
        place_user_at_top:
          anyOf:
            - type: string
            - type: 'null'
          title: Place User At Top
          description: User ID to place at top of rotation (optional)
      type: object
      required:
        - reason
      title: ResetRules
      description: Reset rules for round-robin assignment.
    RouteLog:
      properties:
        timestamp:
          type: string
          format: date-time
          title: Timestamp
          description: ISO timestamp of the action
        object:
          type: string
          enum:
            - Lead
            - Contact
            - Account
            - Opportunity
          title: Object
          description: Salesforce object type
        object_id:
          type: string
          title: Object Id
          description: Salesforce ID of the object
        action:
          type: string
          enum:
            - assign
            - convert
            - merge
            - enrich
          title: Action
          description: Action performed on the object
        pool:
          anyOf:
            - type: string
            - type: 'null'
          title: Pool
          description: Round-robin pool name (for assign actions)
        assigned_to:
          anyOf:
            - type: string
            - type: 'null'
          title: Assigned To
          description: Salesforce ID of assigned user (for assign actions)
        prev_owner:
          anyOf:
            - type: string
            - type: 'null'
          title: Prev Owner
          description: Previous owner ID (for assign/convert actions)
        sequence:
          anyOf:
            - type: integer
            - type: 'null'
          title: Sequence
          description: Round-robin sequence number (for assign actions)
        reason:
          anyOf:
            - type: string
            - type: 'null'
          title: Reason
          description: Reason for the action (e.g., 'round_robin', 'manual_override')
        request_id:
          anyOf:
            - type: string
            - type: 'null'
          title: Request Id
          description: Request ID for tracking
        idempotency_key:
          anyOf:
            - type: string
            - type: 'null'
          title: Idempotency Key
          description: Idempotency key for duplicate prevention
        diff:
          anyOf:
            - additionalProperties:
                additionalProperties: true
                type: object
              type: object
            - type: 'null'
          title: Diff
          description: Field changes for enrichment/merge actions
      type: object
      required:
        - timestamp
        - object
        - object_id
        - action
      title: RouteLog
      description: Route log entry for audit and reporting.
    RunErrorResponse:
      properties:
        success:
          type: boolean
          title: Success
          description: Always false for error responses
          default: false
        error:
          type: string
          title: Error
          description: Error message
        details:
          anyOf:
            - type: string
            - type: 'null'
          title: Details
          description: Additional error details
        request_id:
          anyOf:
            - type: string
            - type: 'null'
          title: Request Id
          description: Request ID for tracking
      type: object
      required:
        - error
      title: RunErrorResponse
      description: Error response model for run operations.
    RunStatus:
      type: string
      enum:
        - queued
        - queued
        - failed
        - completed
        - failed
      title: RunStatus
    RunStatusResponse:
      properties:
        run_id:
          type: string
          format: uuid
          title: Run Id
          description: Unique identifier for the run
        status:
          $ref: '#/components/schemas/RunStatus'
          description: Current status of the run
      type: object
      required:
        - run_id
        - status
      title: RunStatusResponse
      description: Response model for run status.
      example:
        run_id: 123e4567-e89b-12d3-a456-426614174000
        status: queued
    TokenUsage:
      properties:
        prompt_tokens:
          type: integer
          title: Prompt Tokens
          description: Tokens used in the input
        completion_tokens:
          type: integer
          title: Completion Tokens
          description: Tokens used in the response
        total_tokens:
          type: integer
          title: Total Tokens
          description: Total tokens consumed
      type: object
      required:
        - prompt_tokens
        - completion_tokens
        - total_tokens
      title: TokenUsage
      description: Token usage information for AI enrichment.
    TriggerRequest:
      properties:
        object:
          type: string
          enum:
            - lead
            - contact
            - account
            - opportunity
          title: Object
          description: Salesforce object type that triggered the event
        ids:
          items:
            type: string
          type: array
          title: Ids
          description: List of Salesforce record IDs that changed
        event:
          type: string
          enum:
            - after_insert
            - after_update
            - after_undelete
          title: Event
          description: Salesforce trigger event type
        org_id:
          type: string
          title: Org Id
          description: Salesforce organization ID
      type: object
      required:
        - object
        - ids
        - event
        - org_id
      title: TriggerRequest
      description: Request model for Salesforce trigger webhook.
    TriggerResponse:
      properties:
        success:
          type: boolean
          title: Success
          description: Boolean indicating request success
        processed_count:
          type: integer
          title: Processed Count
          description: Number of records processed
        enrichment_jobs:
          items:
            type: string
          type: array
          title: Enrichment Jobs
          description: List of enrichment job IDs created
        workflow_status:
          type: string
          enum:
            - started
            - queued
            - failed
          title: Workflow Status
          description: Status of the enrichment workflow
        credits_consumed:
          type: integer
          title: Credits Consumed
          description: Number of credits used for this request
        credits_remaining:
          type: integer
          title: Credits Remaining
          description: Credits remaining in your account after this request
        processing_time_ms:
          type: integer
          title: Processing Time Ms
          description: Time taken to process the request in milliseconds
        cached:
          type: boolean
          title: Cached
          description: Boolean indicating if this result was returned from cache
      type: object
      required:
        - success
        - processed_count
        - enrichment_jobs
        - workflow_status
        - credits_consumed
        - credits_remaining
        - processing_time_ms
        - cached
      title: TriggerResponse
      description: Response model for Salesforce trigger webhook.
    ValidationError:
      properties:
        loc:
          items:
            anyOf:
              - type: string
              - type: integer
          type: array
          title: Location
        msg:
          type: string
          title: Message
        type:
          type: string
          title: Error Type
      type: object
      required:
        - loc
        - msg
        - type
      title: ValidationError
    WorkflowErrorResponse:
      properties:
        success:
          type: boolean
          title: Success
          description: Always false for error responses
          default: false
        error:
          type: string
          title: Error
          description: Error message
        details:
          anyOf:
            - type: string
            - type: 'null'
          title: Details
          description: Additional error details
        request_id:
          anyOf:
            - type: string
            - type: 'null'
          title: Request Id
          description: Request ID for tracking
        workflow_id:
          anyOf:
            - type: string
            - type: 'null'
          title: Workflow Id
          description: Workflow ID that failed
        credits_required:
          anyOf:
            - type: integer
            - type: 'null'
          title: Credits Required
          description: Credits required for insufficient credit errors
        credits_remaining:
          anyOf:
            - type: integer
            - type: 'null'
          title: Credits Remaining
          description: Credits remaining for insufficient credit errors
        retry_after:
          anyOf:
            - type: integer
            - type: 'null'
          title: Retry After
          description: Seconds to wait before retrying for rate limit errors
      type: object
      required:
        - error
      title: WorkflowErrorResponse
      description: Error response model for Workflow Trigger API.
    WorkflowTriggerRequest:
      properties:
        record_data:
          additionalProperties: true
          type: object
          title: Record Data
          description: >-
            Generic record payload containing fields for Lead, Contact,
            Opportunity, or other custom objects
        source_system:
          anyOf:
            - type: string
            - type: 'null'
          title: Source System
          description: Source system identifier (e.g., 'eloqua', 'cdp', 'data_lake')
        enrichment_preferences:
          anyOf:
            - additionalProperties: true
              type: object
            - type: 'null'
          title: Enrichment Preferences
          description: Optional enrichment preferences and configuration
      type: object
      required:
        - record_data
      title: WorkflowTriggerRequest
      description: Request model for Workflow Trigger API.
    WorkflowTriggerResponse:
      properties:
        success:
          type: boolean
          title: Success
          description: Boolean indicating request success
        status:
          type: string
          enum:
            - triggered
            - queued
            - failed
          title: Status
          description: Status of the workflow trigger
        request_id:
          type: string
          title: Request Id
          description: Unique request ID for tracking
        workflow_id:
          type: string
          title: Workflow Id
          description: ID of the triggered workflow
        processing_time_ms:
          type: integer
          title: Processing Time Ms
          description: Time taken to process the request in milliseconds
        enrichment_job_id:
          anyOf:
            - type: string
            - type: 'null'
          title: Enrichment Job Id
          description: ID of the enrichment job created (if applicable)
        credits_consumed:
          type: integer
          title: Credits Consumed
          description: Number of credits used for this request
        credits_remaining:
          type: integer
          title: Credits Remaining
          description: Credits remaining in your account after this request
        cached:
          type: boolean
          title: Cached
          description: Boolean indicating if this result was returned from cache
          default: false
      type: object
      required:
        - success
        - status
        - request_id
        - workflow_id
        - processing_time_ms
        - credits_consumed
        - credits_remaining
      title: WorkflowTriggerResponse
      description: Response model for Workflow Trigger API.
    api_gateway__models__credits__ErrorResponse:
      properties:
        success:
          type: boolean
          title: Success
          description: Boolean indicating request success
          default: false
        error:
          type: string
          title: Error
          description: Error message
        details:
          anyOf:
            - type: string
            - type: 'null'
          title: Details
          description: Additional error details
      type: object
      required:
        - error
      title: ErrorResponse
      description: Error response model.
    api_gateway__models__enrichment__ErrorResponse:
      properties:
        success:
          type: boolean
          title: Success
          description: Always false for error responses
          default: false
        error:
          type: string
          title: Error
          description: Error message
        details:
          anyOf:
            - type: string
            - type: 'null'
          title: Details
          description: Additional error details
        request_id:
          anyOf:
            - type: string
            - type: 'null'
          title: Request Id
          description: Request ID for tracking
        credits_required:
          anyOf:
            - type: integer
            - type: 'null'
          title: Credits Required
          description: Credits required for insufficient credit errors
        credits_remaining:
          anyOf:
            - type: integer
            - type: 'null'
          title: Credits Remaining
          description: Credits remaining for insufficient credit errors
        retry_after:
          anyOf:
            - type: integer
            - type: 'null'
          title: Retry After
          description: Seconds to wait before retrying for rate limit errors
      type: object
      required:
        - error
      title: ErrorResponse
      description: Standard error response model.
    api_gateway__models__logs__ErrorResponse:
      properties:
        success:
          type: boolean
          title: Success
          description: Always false for error responses
          default: false
        error:
          type: string
          title: Error
          description: Error message
        details:
          anyOf:
            - type: string
            - type: 'null'
          title: Details
          description: Additional error details
        request_id:
          anyOf:
            - type: string
            - type: 'null'
          title: Request Id
          description: Request ID for tracking
        retry_after:
          anyOf:
            - type: integer
            - type: 'null'
          title: Retry After
          description: Seconds to wait before retrying for rate limit errors
      type: object
      required:
        - error
      title: ErrorResponse
      description: Standard error response model.
    api_gateway__models__match__ErrorResponse:
      properties:
        success:
          type: boolean
          title: Success
          description: Always false for error responses
          default: false
        error:
          type: string
          title: Error
          description: Error message
        details:
          anyOf:
            - type: string
            - type: 'null'
          title: Details
          description: Additional error details
        request_id:
          anyOf:
            - type: string
            - type: 'null'
          title: Request Id
          description: Request ID for tracking
        credits_required:
          anyOf:
            - type: integer
            - type: 'null'
          title: Credits Required
          description: Credits required for insufficient credit errors
        credits_remaining:
          anyOf:
            - type: integer
            - type: 'null'
          title: Credits Remaining
          description: Credits remaining for insufficient credit errors
        retry_after:
          anyOf:
            - type: integer
            - type: 'null'
          title: Retry After
          description: Seconds to wait before retrying for rate limit errors
      type: object
      required:
        - error
      title: ErrorResponse
      description: Standard error response model.
    api_gateway__models__routing__ErrorResponse:
      properties:
        success:
          type: boolean
          title: Success
          description: Always false for error responses
          default: false
        error:
          type: string
          title: Error
          description: Error message
        details:
          anyOf:
            - type: string
            - type: 'null'
          title: Details
          description: Additional error details
        request_id:
          anyOf:
            - type: string
            - type: 'null'
          title: Request Id
          description: Request ID for tracking
        retry_after:
          anyOf:
            - type: integer
            - type: 'null'
          title: Retry After
          description: Seconds to wait before retrying for rate limit errors
      type: object
      required:
        - error
      title: ErrorResponse
      description: Standard error response model.
    api_gateway__models__salesforce__ErrorResponse:
      properties:
        success:
          type: boolean
          title: Success
          description: Always false for error responses
          default: false
        error:
          type: string
          title: Error
          description: Error message
        details:
          anyOf:
            - type: string
            - type: 'null'
          title: Details
          description: Additional error details
        request_id:
          anyOf:
            - type: string
            - type: 'null'
          title: Request Id
          description: Request ID for tracking
        retry_after:
          anyOf:
            - type: integer
            - type: 'null'
          title: Retry After
          description: Seconds to wait before retrying for rate limit errors
      type: object
      required:
        - error
      title: ErrorResponse
      description: Standard error response model.
    api_gateway__models__triggers__ErrorResponse:
      properties:
        success:
          type: boolean
          title: Success
          description: Always false for error responses
          default: false
        error:
          type: string
          title: Error
          description: Error message
        details:
          anyOf:
            - type: string
            - type: 'null'
          title: Details
          description: Additional error details
        request_id:
          anyOf:
            - type: string
            - type: 'null'
          title: Request Id
          description: Request ID for tracking
        credits_required:
          anyOf:
            - type: integer
            - type: 'null'
          title: Credits Required
          description: Credits required for insufficient credit errors
        credits_remaining:
          anyOf:
            - type: integer
            - type: 'null'
          title: Credits Remaining
          description: Credits remaining for insufficient credit errors
        retry_after:
          anyOf:
            - type: integer
            - type: 'null'
          title: Retry After
          description: Seconds to wait before retrying for rate limit errors
      type: object
      required:
        - error
      title: ErrorResponse
      description: Standard error response model.
  securitySchemes:
    BearerAuth:
      type: http
      scheme: bearer
      bearerFormat: ApiToken
servers:
  - url: https://api-gateway.agenthq.withlantern.com
    description: Lantern API server
  - url: http://localhost:8000
    description: Local API server
security:
  - BearerAuth: []
