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

# Start bulk phone find

> Start an asynchronous bulk phone finder job. Billed only for phone numbers found.

## Use Case:

Start an asynchronous bulk phone finder job (up to 50 leads per request).

## Pricing

This is a billable endpoint — you are charged only for each phone number found. If no phone is found, the request is free.

<Tip>Your price decreases automatically as your lifetime spend grows. [Check your current tier and pricing →](https://beta.generect.com/settings/billing)</Tip>


## OpenAPI

````yaml post /api/v1/phone/find/bulk/
openapi: 3.0.3
info:
  title: Generect API
  description: >-
    Welcome to the Generect API documentation. Here we will help you integrate
    and use our API.


    API base url: `https://api.generect.com` — every path below is relative to
    this host. Newer endpoints live under `/api/v1/...`, legacy endpoints under
    `/api/...`; use each path exactly as documented.

    Protocol: `HTTPS`


    # Authentication


    Get your API token from the Generect app settings and send it in the
    `Authorization` header with the required `Token` prefix.


    Example: `Authorization: Token xxxxxxxxx`


    # Rate limits


    You can request data depending on your data plan and account balance
    (default: 10000/month). Pricing depends on the operation and the number of
    results returned, and may increase with additional data flags. For exact
    pricing, see each endpoint's Pricing section or your billing settings:
    https://beta.generect.com/settings/billing


    # Note


    _Every endpoint must include the trailing `/`. Requests without the trailing
    slash may fail._
  version: 1.0.0
  contact: {}
servers:
  - url: https://api.generect.com
security:
  - apiKey: []
tags:
  - name: 1. Auth
    description: Login and get user info
  - name: 2. Transactions
    description: List of latest transactions in your account
  - name: 3. Leads
    description: Fetch information about leads by _link/name/ICP_.
  - name: 4. Companies
    description: Fetch information about companies by link/name/ICP.
  - name: 5. Preview
    description: Search masked database leads for preview and reveal workflows.
  - name: 6. Enrich
    description: Enrich leads and companies by internal or external identifiers.
  - name: 7. Email
    description: Find and validate email addresses.
  - name: 8. Accounts
    description: Account profile, usage, and transactions.
  - name: 9. Search
    description: Database and realtime lead, company, and company-lead search.
  - name: 10. Phone
    description: Find phone numbers for leads.
  - name: 11. Webhooks
    description: Register and manage async job notifications.
paths:
  /api/v1/phone/find/bulk/:
    post:
      tags:
        - 10. Phone
      summary: Start bulk phone find
      description: >-
        Start an asynchronous bulk phone finder job. Billed only for phone
        numbers found.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - leads
              properties:
                leads:
                  type: array
                  maxItems: 50
                  description: >-
                    List of leads to find phones for (max 50 per request). Each
                    entry is either a lead_id, linkedin_url, or name+company.
                  items:
                    oneOf:
                      - title: By Lead ID
                        type: object
                        required:
                          - lead_id
                        properties:
                          lead_id:
                            type: string
                            description: Generect lead identifier.
                      - title: By LinkedIn URL
                        type: object
                        required:
                          - linkedin_url
                        properties:
                          linkedin_url:
                            type: string
                            example: https://www.linkedin.com/in/jordan-ellis
                      - $ref: '#/components/schemas/PhoneFindByNameRequest'
            examples:
              Bulk phone find:
                value:
                  leads:
                    - lead_id: ACwAAAE9bk0BxY7Qf2mN4pR8sT1vW3zA5cE6gH9
                    - first_name: Jordan
                      last_name: Ellis
                      company: microsoft.com
      responses:
        '202':
          description: Bulk phone job accepted
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BulkSubmitResponse'
              example:
                data: null
                meta:
                  job_id: 7c9e6679-7425-40de-944b-e07fc1f90ae7
                  status: pending
                  total: 2
                  processed: 0
                  amount_charged: 0
                  error: null
        '400':
          description: Validation error or insufficient balance.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
              examples:
                Validation error:
                  value:
                    status: error
                    status_code: 400
                    detail:
                      leads:
                        - This field is required.
                Insufficient funds:
                  value:
                    status: error
                    status_code: 400
                    detail: Insufficient funds in the account.
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
components:
  schemas:
    PhoneFindByNameRequest:
      title: By Name and Company
      type: object
      required:
        - first_name
        - last_name
        - company
      properties:
        first_name:
          type: string
          description: Lead's first name.
          example: John
        last_name:
          type: string
          description: Lead's last name.
          example: Doe
        company:
          type: string
          description: Company name or domain where the lead works.
          example: microsoft.com
        linkedin_url:
          type: string
          description: Optional LinkedIn profile URL to improve match accuracy.
          example: https://www.linkedin.com/in/jordan-ellis
    BulkSubmitResponse:
      type: object
      properties:
        data:
          type: object
          nullable: true
          description: Always null — results arrive via the bulk status endpoint.
        meta:
          $ref: '#/components/schemas/BulkJobMeta'
    Error:
      type: object
      description: Standard error envelope returned for 4xx/5xx responses.
      properties:
        status:
          type: string
          example: error
        status_code:
          type: integer
          example: 400
        detail:
          description: >-
            Human-readable message (string) for most errors, or a field-level
            validation map ({ field: [messages] }) for 400 validation errors.
          example: Insufficient funds in the account.
    BulkJobMeta:
      type: object
      description: >-
        Bulk job state. Poll the bulk status endpoint with job_id or subscribe
        to the completion webhook.
      required:
        - job_id
        - status
        - total
        - processed
        - amount_charged
      properties:
        job_id:
          type: string
          description: Job identifier — pass it to the bulk status endpoint.
        status:
          type: string
          enum:
            - pending
            - processing
            - completed
            - error
        total:
          type: integer
          description: Number of submitted items.
        processed:
          type: integer
          description: Items processed so far.
        found:
          type: integer
          description: >-
            Items that resolved to a result (present on status/webhook once
            completed).
        not_found:
          type: integer
          description: Items with no result — not charged (No Data, No Charge).
        amount_charged:
          type: number
          description: USD charged for found results; final when status is completed.
        error:
          type: string
          nullable: true
          description: Failure reason when status is error.
  responses:
    Unauthorized:
      description: Missing or invalid API token.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
          example:
            status: error
            status_code: 401
            detail: Authentication credentials were not provided.
    Forbidden:
      description: Authenticated, but the account/plan is not allowed to use this endpoint.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
          example:
            status: error
            status_code: 403
            detail: You do not have permission to perform this action.
  securitySchemes:
    apiKey:
      type: apiKey
      in: header
      name: Authorization
      description: 'Use the required Token prefix. Example: Authorization: Token xxxxxxxxx'

````