GoodLeads Enrichment API

openapi: 3.2.0
info:
  title: Formation GTM Enrichment API
  description: GoodLeads Formation Data Platform — scored, enriched, campaign-ready leads.
  version: 0.1.0
tags:
- name: Enrichment
paths:
  /api/v1/enrichment/preview:
    post:
      tags:
      - Enrichment
      summary: Enrichment Preview
      description: 'Analyze selected leads for enrichment eligibility.


        Returns segment breakdown, contact coverage, eligible count, and cost estimate.

        Use this before committing to enrichment to understand the cost and value.


        Still consumed by the State GM agents (`get_enrichment_preview` tool) — read-only.'
      operationId: enrichment_preview_api_v1_enrichment_preview_post
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/EnrichmentRequest'
        required: true
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema: {}
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /api/v1/enrichment/build:
    post:
      tags:
      - Enrichment
      summary: Build Enrichment Batch Removed
      description: 'DEPRECATED — removed in favor of POST /api/v1/pipeline/trigger.


        The old implementation built a Tracerfy batch and ran the enrichment pipeline

        (skip_trace → gapfill → validate → score → reload) as a local background thread

        inside the API container. That container is not provisioned to run paid

        enrichment stages, so the path failed in production (TX job 5ac78544:

        `skip_trace` "exit code 1" after ~90s).


        The Browse selection bar and Lead Detail "Send to Pipeline…" actions now call

        POST /api/v1/pipeline/trigger (PR #536), which runs stages as isolated ECS tasks

        with a Run Manifest for per-entity COGS attribution. This endpoint returns 410

        Gone; there are no remaining callers in the frontend or the agent layer.'
      operationId: build_enrichment_batch_removed_api_v1_enrichment_build_post
      responses:
        '410':
          description: Successful Response
          content:
            application/json:
              schema: {}
      deprecated: true
components:
  schemas:
    HTTPValidationError:
      properties:
        detail:
          items:
            $ref: '#/components/schemas/ValidationError'
          type: array
          title: Detail
      type: object
      title: HTTPValidationError
    EnrichmentRequest:
      properties:
        state:
          type: string
          title: State
        entity_ids:
          anyOf:
          - items:
              type: string
            type: array
          - type: 'null'
          title: Entity Ids
        include_all_matching:
          type: boolean
          title: Include All Matching
          default: false
        filters:
          items:
            additionalProperties: true
            type: object
          type: array
          title: Filters
          default: []
      type: object
      required:
      - state
      title: EnrichmentRequest
    ValidationError:
      properties:
        loc:
          items:
            anyOf:
            - type: string
            - type: integer
          type: array
          title: Location
        msg:
          type: string
          title: Message
        type:
          type: string
          title: Error Type
        input:
          title: Input
        ctx:
          type: object
          title: Context
      type: object
      required:
      - loc
      - msg
      - type
      title: ValidationError
  securitySchemes:
    APIKeyHeader:
      type: apiKey
      in: header
      name: X-API-Key