> ## Documentation Index
> Fetch the complete documentation index at: https://technologychecker.io/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Create lead list API

> Build a targeted domain list from technology and company filters. Runs as a background job; billed 1 credit per delivered row after completion.

## Frequently asked questions

<AccordionGroup>
  <Accordion title="How does the async flow work?">
    The request returns immediately with a `list_id` and `status: "processing"`. A background job assembles the rows. Poll [the list detail endpoint](/docs/api-reference/lead-lists/get-lead-list-api) until `status` is `ready`, then preview or export it.
  </Accordion>

  <Accordion title="When am I charged?">
    After the job completes, on the actual number of rows delivered — 1 credit each. Nothing is charged upfront, and a failed job charges nothing at all. At create time we only check that your balance covers `list_size`, the maximum the job could deliver. If your balance is lower than `list_size`, the list is capped to your balance rather than rejected.
  </Accordion>

  <Accordion title="What does the technology logic field do?">
    `or` matches domains running any of the listed technologies. `and` requires all of them. `and_not` requires the first and excludes the rest — the way to build "running Shopify but not Klaviyo".
  </Accordion>

  <Accordion title="How do I get contact data in the list?">
    Set `has_email: true` or `has_phone: true` to restrict the list to domains where the crawler found contact details. Either way, every export carries the contact columns — emails, phones and five social profile URLs — so you do not have to filter on them to receive them.
  </Accordion>

  <Accordion title="Can I export a saved audience as a list?">
    Yes. Pass `segment_id` instead of technology filters and the list is built from that audience's membership, with all the company and contact columns attached.
  </Accordion>

  <Accordion title="How many lists can I build at once?">
    Concurrency is capped per plan: 1 on Free, 3 on Pro, 5 on Scale and 10 on Enterprise. Lists are between 1,000 and 100,000 rows and their results are deleted 60 days after creation.
  </Accordion>
</AccordionGroup>


## OpenAPI

````yaml POST /v1/leads/create
openapi: 3.1.0
info:
  title: TechnologyChecker API
  description: >-
    Discover technology stacks, track market trends, and enrich data with
    company intelligence.
  version: 1.0.0
  contact:
    name: TechnologyChecker Support
    email: support@technologychecker.io
    url: https://technologychecker.io
servers:
  - url: https://api.technologychecker.io
    description: Production
security:
  - bearerAuth: []
tags:
  - name: Domain technologies
    description: Look up technologies detected on any domain
  - name: Technology data
    description: Search, look up, and get details on tracked technologies
  - name: Market intelligence
    description: Technology stats, trends, and market share
  - name: Company data
    description: Firmographic and company intelligence
  - name: Live detection
    description: Real-time technology detection with browser rendering
  - name: Signals
    description: >-
      Intent signals derived from technology state transitions: who adopted, who
      churned, who switched, and who has a gap in their stack.
  - name: Alerts
    description: >-
      Saved signal queries delivered to your webhook. Every signal you can
      query, you can subscribe to.
  - name: Audiences
    description: >-
      Saved groups of domains — uploaded lists or computed recipes — that you
      can profile, slice and monitor.
  - name: Lead lists
    description: >-
      Build and export targeted domain lists combining technology detection with
      company data.
paths:
  /v1/leads/create:
    post:
      tags:
        - Lead lists
      summary: Create lead list API
      description: >-
        Build a lead list from a filter set. The request returns immediately
        with `status: "processing"` and a background job assembles the rows —
        poll the list detail endpoint until it is `ready`.


        **Billing is 1 credit per delivered row, charged after the job
        completes.** Nothing is charged upfront and a failed job charges
        nothing, so there is no refund path to worry about. At create time we
        only check that your balance covers `list_size`, the maximum the job
        could deliver; if your balance is lower the list is capped to it.


        Lists expire after 60 days. Concurrency is capped per plan: 1 on Free, 3
        on Pro, 5 on Scale, 10 on Enterprise.
      operationId: createLeadList
      requestBody:
        required: true
        content:
          application/json:
            schema:
              allOf:
                - $ref: '#/components/schemas/LeadListFilters'
                - type: object
                  required:
                    - name
                    - list_size
                  properties:
                    name:
                      type: string
                      example: US SaaS Companies using Cloudflare
                    list_size:
                      type: integer
                      minimum: 1000
                      maximum: 100000
                      description: >-
                        Maximum rows to deliver, and therefore the maximum
                        charge.
                      example: 10000
                    segment_id:
                      type: string
                      description: >-
                        Export a saved audience as a lead list instead of
                        specifying technology filters.
                      example: seg_8f3a2c1b
                    selected_columns:
                      type: array
                      items:
                        type: string
                      example:
                        - domain
                        - company_name
                        - linkedin_url
              example:
                name: US SaaS Companies using Cloudflare
                technologies:
                  ids:
                    - 2
                  logic: or
                countries:
                  - United States
                industries:
                  - Software Development
                employees:
                  - 51-200
                  - 201-500
                has_email: true
                list_size: 10000
      responses:
        '200':
          description: The list was accepted and is being built
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                    example: true
                  data:
                    type: object
                    properties:
                      list_id:
                        type: string
                        format: uuid
                        example: f6ab2d94-c34f-47b7-9d1a-228e71488cd2
                      status:
                        type: string
                        example: processing
                      estimated_count:
                        type: integer
                        example: 10000
                      credits_charged:
                        type: integer
                        description: Charged after completion, on the actual row count.
                        example: 10000
                      created_at:
                        type: string
                        example: '2026-01-15T19:19:21.179Z'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '402':
          $ref: '#/components/responses/PaymentRequired'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
        '429':
          $ref: '#/components/responses/RateLimited'
components:
  schemas:
    LeadListFilters:
      type: object
      description: >-
        The filter set that defines a lead list. Technology filters and company
        filters combine with AND.
      properties:
        technologies:
          type: object
          properties:
            ids:
              type: array
              items:
                type: integer
              example:
                - 2
                - 7
            logic:
              type: string
              enum:
                - or
                - and
                - and_not
              default: or
              description: >-
                `or` matches domains running any listed technology. `and`
                requires all of them. `and_not` requires the first and excludes
                the rest.
        keywords:
          type: object
          properties:
            include:
              type: array
              items:
                type: string
              example:
                - shop
            exclude:
              type: array
              items:
                type: string
              example:
                - health
        website_type:
          type: string
          example: company_only
        countries:
          type: array
          items:
            type: string
          example:
            - United States
            - Germany
        industries:
          type: array
          items:
            type: string
          example:
            - Software Development
        employees:
          type: array
          items:
            type: string
          example:
            - 51-200
            - 201-500
        has_email:
          type: boolean
          description: Only domains where the crawler found an email address.
        has_phone:
          type: boolean
          description: Only domains where the crawler found a phone number.
        languages:
          type: array
          items:
            type: string
          example:
            - en
        web_countries:
          type: array
          items:
            type: string
          description: >-
            ISO-2 codes or English names. Unresolvable values are rejected at
            create time.
          example:
            - USA
    ApiError:
      type: object
      properties:
        success:
          type: boolean
          example: false
        error:
          type: object
          properties:
            code:
              type: string
              example: UNAUTHORIZED
            message:
              type: string
              example: Missing or invalid API key
  responses:
    BadRequest:
      description: Invalid or missing parameters
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ApiError'
          example:
            success: false
            error:
              code: VALIDATION_ERROR
              message: >-
                Provide exactly one scope: technology_id, technology or
                category_id.
    Unauthorized:
      description: Missing or invalid API key
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ApiError'
    PaymentRequired:
      description: Not enough credits, or the plan does not include this feature
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ApiError'
          example:
            success: false
            error:
              code: INSUFFICIENT_CREDITS
              message: Insufficient credits for this request.
              details:
                required: 1
                available: 0
    Forbidden:
      description: The plan does not allow this action, or a plan limit was reached
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ApiError'
          example:
            success: false
            error:
              code: PLAN_LIMIT
              message: >-
                Your plan allows up to 2 saved audiences. Delete one to create
                another.
    NotFound:
      description: Resource not found
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ApiError'
    RateLimited:
      description: Rate limit exceeded
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ApiError'
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      description: >-
        API key in format `tapi_live_[32-char]` (live) or `tapi_test_[32-char]`
        (test)

````