GoodLeads Lists API

openapi: 3.2.0
info:
  title: Formation GTM Lists API
  description: GoodLeads Formation Data Platform — scored, enriched, campaign-ready leads.
  version: 0.1.0
tags:
- name: Lists
paths:
  /api/v1/leads/summary:
    post:
      tags:
      - Lists
      summary: Inline Summary
      description: 'The same summary for an inline shape — one call per chip edit before a

        list is ever saved (save happens after checkout, never before).'
      operationId: inline_summary_api_v1_leads_summary_post
      security:
      - APIKeyHeader: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/SummaryRequest'
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema: {}
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /api/v1/lists:
    post:
      tags:
      - Lists
      summary: Create List
      description: 'Save a shaped list. Anonymous allowed (rate-limited like browse); the

        response carries the one-time claim_token — the only time it is shown.'
      operationId: create_list_api_v1_lists_post
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/SavedListCreate'
        required: true
      responses:
        '201':
          description: Successful Response
          content:
            application/json:
              schema: {}
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
      security:
      - APIKeyHeader: []
  /api/v1/lists/starters:
    get:
      tags:
      - Lists
      summary: List Starters
      description: 'The starter shelf: every live state × business type we sell, each with

        the summary''s counts (`matching`, `sellable`, `verified_one`,

        `verified_both`), its display label, its from-price and the exact filters

        the card opens with. Computed once and cached in-process (6 h; 5 min when

        a state''s count was partial) — never a live COUNT per page view.


        Declared before `GET /lists/{list_id}` so the path is never read as a list id.'
      operationId: list_starters_api_v1_lists_starters_get
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema: {}
      security:
      - APIKeyHeader: []
  /api/v1/lists/shelf:
    get:
      tags:
      - Lists
      summary: List Shelf
      description: 'The time shelf: sellable counts per industry × live state for businesses

        filed in the last 7 / 30 / 56 / 90 days and everything on file, each

        window''s expected find upgrade per record, today''s prices, and the window

        the run rate of new records is read from. Built at the end of every pipeline

        run and stored (backend/services/list_shelf.py); this reads the stored

        snapshot, so a buyer''s request never computes — a rolled date or a partial

        count is rebuilt in the background.


        Declared before `GET /lists/{list_id}` so the path is never read as a list id.'
      operationId: list_shelf_api_v1_lists_shelf_get
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema: {}
      security:
      - APIKeyHeader: []
  /api/v1/lists/{list_id}:
    get:
      tags:
      - Lists
      summary: Get List
      operationId: get_list_api_v1_lists__list_id__get
      security:
      - APIKeyHeader: []
      parameters:
      - name: list_id
        in: path
        required: true
        schema:
          type: string
          title: List Id
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema: {}
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
    patch:
      tags:
      - Lists
      summary: Patch List
      description: 'Rename. Authorized by the list''s claim token or the owner. Until a

        customer session exists (wave two), the owner path is the admin key.'
      operationId: patch_list_api_v1_lists__list_id__patch
      security:
      - APIKeyHeader: []
      parameters:
      - name: list_id
        in: path
        required: true
        schema:
          type: string
          title: List Id
      - name: X-Claim-Token
        in: header
        required: false
        schema:
          anyOf:
          - type: string
          - type: 'null'
          title: X-Claim-Token
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/SavedListPatch'
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema: {}
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /api/v1/lists/{list_id}/summary:
    get:
      tags:
      - Lists
      summary: List Summary Endpoint
      description: Counts + facets + prices for a saved list; add lane / cap for a quote.
      operationId: list_summary_endpoint_api_v1_lists__list_id__summary_get
      security:
      - APIKeyHeader: []
      parameters:
      - name: list_id
        in: path
        required: true
        schema:
          type: string
          title: List Id
      - name: lane
        in: query
        required: false
        schema:
          anyOf:
          - type: string
          - type: 'null'
          description: all | best | contact
          title: Lane
        description: all | best | contact
      - name: cap_type
        in: query
        required: false
        schema:
          anyOf:
          - type: string
          - type: 'null'
          description: count | budget
          title: Cap Type
        description: count | budget
      - name: cap_value
        in: query
        required: false
        schema:
          anyOf:
          - type: integer
            minimum: 0
          - type: 'null'
          description: records for count, cents for budget
          title: Cap Value
        description: records for count, cents for budget
      - name: channel
        in: query
        required: false
        schema:
          anyOf:
          - type: string
          - type: 'null'
          description: phone | email — the one channel this buyer runs
          title: Channel
        description: phone | email — the one channel this buyer runs
      - name: offer_code
        in: query
        required: false
        schema:
          anyOf:
          - type: string
          - type: 'null'
          description: An offer code the buyer was given (ADR-058)
          title: Offer Code
        description: An offer code the buyer was given (ADR-058)
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema: {}
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /api/v1/crosswalk:
    get:
      tags:
      - Lists
      summary: Crosswalk
      description: 'One classification code in, the other three systems out — with our industry, the filter for each, and a live count.


        We carry NAICS, SIC, the Google Business category and the payment MCC on every

        record, tied together by our own taxonomy. Give any one (a code, or the words)

        and get the equivalents, the ready-to-use filter per system, and how many

        records are in it today. A code we do not carry widens through the crosswalk

        (to its parent group, then to the codes it ties to) and says so in `widened`.

        No key needed.'
      operationId: crosswalk_api_v1_crosswalk_get
      security:
      - APIKeyHeader: []
      parameters:
      - name: q
        in: query
        required: false
        schema:
          anyOf:
          - type: string
          - type: 'null'
          description: 'A code or words: "MCC 5812", "SIC 1711", "NAICS 238220", "google category plumber", "restaurants".'
          title: Q
        description: 'A code or words: "MCC 5812", "SIC 1711", "NAICS 238220", "google category plumber", "restaurants".'
      - name: system
        in: query
        required: false
        schema:
          anyOf:
          - type: string
          - type: 'null'
          description: naics | sic | mcc | google_category — with `code`, instead of `q`.
          title: System
        description: naics | sic | mcc | google_category — with `code`, instead of `q`.
      - name: code
        in: query
        required: false
        schema:
          anyOf:
          - type: string
          - type: 'null'
          description: The code in `system`. A SIC or NAICS prefix (17, 238) is a whole group.
          title: Code
        description: The code in `system`. A SIC or NAICS prefix (17, 238) is a whole group.
      - name: states
        in: query
        required: false
        schema:
          type: string
          description: Comma-separated state codes for the live count; empty = every live state.
          default: ''
          title: States
        description: Comma-separated state codes for the live count; empty = every live state.
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema: {}
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /api/v1/counts:
    get:
      tags:
      - Lists
      summary: Counts By Url
      description: 'The summary as one GET — for agents and tools that can fetch a URL but cannot POST.


        Same numbers, same filter contract, same `group_by` as `POST /leads/summary`

        (this is a thin adapter over it); no key needed for counts.'
      operationId: counts_by_url_api_v1_counts_get
      security:
      - APIKeyHeader: []
      parameters:
      - name: states
        in: query
        required: false
        schema:
          type: string
          description: Comma-separated state codes; empty = every live state.
          default: ''
          title: States
        description: Comma-separated state codes; empty = every live state.
      - name: filters
        in: query
        required: false
        schema:
          anyOf:
          - type: string
          - type: 'null'
          description: JSON-encoded filter array — the same contract as POST /leads/summary.
          title: Filters
        description: JSON-encoded filter array — the same contract as POST /leads/summary.
      - name: group_by
        in: query
        required: false
        schema:
          type: string
          description: Comma-separated fields (max 2) to cross-tab by, e.g. property_classification,naics_2_digit.
          default: ''
          title: Group By
        description: Comma-separated fields (max 2) to cross-tab by, e.g. property_classification,naics_2_digit.
      - name: include_existing
        in: query
        required: false
        schema:
          type: boolean
          default: false
          title: Include Existing
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema: {}
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /api/v1/lists/interpret:
    post:
      tags:
      - Lists
      summary: Interpret List
      description: Translate one typed line into a list shape the page can open.
      operationId: interpret_list_api_v1_lists_interpret_post
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/InterpretRequest'
        required: true
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema: {}
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
      security:
      - APIKeyHeader: []
components:
  schemas:
    SavedListPatch:
      properties:
        name:
          anyOf:
          - type: string
            maxLength: 120
          - type: 'null'
          title: Name
      additionalProperties: false
      type: object
      title: SavedListPatch
    SummaryRequest:
      properties:
        states:
          items:
            type: string
          type: array
          title: States
        filters:
          items:
            additionalProperties: true
            type: object
          type: array
          title: Filters
        include_held:
          type: boolean
          title: Include Held
          default: false
        include_existing:
          type: boolean
          title: Include Existing
          description: Widen past the Just-started default to existing businesses with a new filing (Browse's checkbox).
          default: false
        lane:
          anyOf:
          - type: string
          - type: 'null'
          title: Lane
          description: all | best | contact
        cap:
          anyOf:
          - additionalProperties: true
            type: object
          - type: 'null'
          title: Cap
          description: '{"type": "count"|"budget", "value": int}'
        offer_code:
          anyOf:
          - type: string
          - type: 'null'
          title: Offer Code
        channel:
          anyOf:
          - type: string
          - type: 'null'
          title: Channel
          description: phone | email — the one channel this buyer runs
        group_by:
          items:
            type: string
          type: array
          title: Group By
          description: Up to two fields to cross-tab the count by (e.g. ["property_classification", "naics_2_digit"]); adds a `groups` block with the four counts per group. Groupable fields are listed in the 422 for an unknown one.
      additionalProperties: false
      type: object
      title: SummaryRequest
    CurrentShape:
      properties:
        states:
          items:
            type: string
          type: array
          title: States
        filters:
          items:
            additionalProperties: true
            type: object
          type: array
          title: Filters
        lane:
          anyOf:
          - type: string
          - type: 'null'
          title: Lane
        cap:
          anyOf:
          - additionalProperties: true
            type: object
          - type: 'null'
          title: Cap
      type: object
      title: CurrentShape
    InterpretRequest:
      properties:
        text:
          type: string
          maxLength: 500
          minLength: 1
          title: Text
          description: What the buyer typed
        state:
          anyOf:
          - type: string
            maxLength: 2
          - type: 'null'
          title: State
          description: Optional state hint (two-letter code)
        current:
          anyOf:
          - $ref: '#/components/schemas/CurrentShape'
          - type: 'null'
          description: The buyer's current shape, merged into the answer
      additionalProperties: false
      type: object
      required:
      - text
      title: InterpretRequest
    SavedListCreate:
      properties:
        states:
          items:
            type: string
          type: array
          title: States
          description: State codes; empty = every live state
        filters:
          items:
            additionalProperties: true
            type: object
          type: array
          title: Filters
          description: Browse filter contract [{field, op, value}] with groups
        sort:
          anyOf:
          - items:
              additionalProperties: true
              type: object
            type: array
          - type: 'null'
          title: Sort
          description: '[{field, dir}]'
        name:
          anyOf:
          - type: string
            maxLength: 120
          - type: 'null'
          title: Name
        include_held:
          type: boolean
          title: Include Held
          default: false
        include_existing:
          type: boolean
          title: Include Existing
          default: false
      additionalProperties: false
      type: object
      title: SavedListCreate
    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
    HTTPValidationError:
      properties:
        detail:
          items:
            $ref: '#/components/schemas/ValidationError'
          type: array
          title: Detail
      type: object
      title: HTTPValidationError
  securitySchemes:
    APIKeyHeader:
      type: apiKey
      in: header
      name: X-API-Key