Generect 10. Phone API

openapi: 3.2.0
info:
  title: Generect 10. Phone 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


    There is no monthly request quota. What you can run is bounded by your account balance and by the parallel-request caps on the Limits page. 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://app.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: 10. Phone
  description: Find phone numbers for leads.
paths:
  /api/v1/phone/find/:
    post:
      tags:
      - 10. Phone
      summary: Find phone
      description: Find a phone number by lead ID, LinkedIn URL, or by name and company. Billed only when a phone number is found.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              oneOf:
              - title: By Lead ID
                type: object
                required:
                - lead_id
                properties:
                  lead_id:
                    type: string
                    description: Generect lead identifier from Search, Preview, or Enrich.
                    example: ACwAAAE9bk0BxY7Qf2mN4pR8sT1vW3zA5cE6gH9
              - title: By LinkedIn URL
                type: object
                required:
                - linkedin_url
                properties:
                  linkedin_url:
                    type: string
                    description: LinkedIn profile URL.
                    example: https://www.linkedin.com/in/jordan-ellis
              - $ref: '#/components/schemas/PhoneFindByNameRequest'
      responses:
        '400':
          description: Validation error.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
              examples:
                Validation error:
                  value:
                    status: error
                    status_code: 400
                    detail:
                      non_field_errors:
                      - 'Provide one of: lead_id, linkedin_url, or first_name+last_name+company.'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '402':
          $ref: '#/components/responses/PaymentRequired'
        '403':
          $ref: '#/components/responses/Forbidden'
        '200':
          description: Phone finder result
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PhoneFindResponse'
              examples:
                Found:
                  value:
                    data:
                      lead_id: ACwAAAE9bk0BxY7Qf2mN4pR8sT1vW3zA5cE6gH9
                      phone:
                        number: '+14155550123'
                        status: FOUND
                        type: mobile
                        country: US
                    meta:
                      amount_charged: 0.4
                Not found:
                  value:
                    data:
                      lead_id: ACwAAAE9bk0BxY7Qf2mN4pR8sT1vW3zA5cE6gH9
                      phone:
                        number: null
                        status: NOT_FOUND
                    meta:
                      amount_charged: 0
      operationId: postApiV1PhoneFind
      x-operation-id-source: derived
  /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:
        '400':
          description: Validation error.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
              examples:
                Validation error:
                  value:
                    status: error
                    status_code: 400
                    detail:
                      leads:
                      - This field is required.
        '401':
          $ref: '#/components/responses/Unauthorized'
        '402':
          $ref: '#/components/responses/PaymentRequired'
        '403':
          $ref: '#/components/responses/Forbidden'
        '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
      operationId: postApiV1PhoneFindBulk
      x-operation-id-source: derived
  /api/v1/phone/find/bulk/{job_id}/:
    get:
      tags:
      - 10. Phone
      summary: Get bulk phone find job
      description: Retrieve the status and results of a bulk phone finder job.
      parameters:
      - name: job_id
        in: path
        required: true
        schema:
          type: string
        example: 7c9e6679-7425-40de-944b-e07fc1f90ae7
      responses:
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          description: Job not found.
          content:
            application/json:
              schema:
                type: object
                properties:
                  detail:
                    type: string
              example:
                detail: Job not found
        '200':
          description: Bulk phone job status and results
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BulkStatusResponse'
              example:
                data:
                - lead_id: ACwAAAE9bk0BxY7Qf2mN4pR8sT1vW3zA5cE6gH9
                  phone:
                    number: '+14155550123'
                    status: FOUND
                    type: mobile
                    country: US
                - lead_id: ACwAAAFp2r4Bd1eF3gH5iJ7kL9mN0pQ2rS4tU6v
                  phone:
                    number: null
                    status: NOT_FOUND
                meta:
                  job_id: 7c9e6679-7425-40de-944b-e07fc1f90ae7
                  status: completed
                  total: 2
                  processed: 2
                  amount_charged: 0.4
                  error: null
      operationId: getApiV1PhoneFindBulkByJobId
      x-operation-id-source: derived
components:
  responses:
    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.
    PaymentRequired:
      description: Not enough balance to run a billable request. Top up in your billing settings; requests already accepted run to completion.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
          example:
            status: error
            status_code: 402
            detail: Insufficient funds in the account.
    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.
  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
    BulkStatusResponse:
      type: object
      properties:
        data:
          type:
          - array
          - 'null'
          description: Result items once status is completed; null until then.
          items:
            type: object
        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: Person does not exist
    BulkSubmitResponse:
      type: object
      properties:
        data:
          type:
          - object
          - 'null'
          description: Always null — results arrive via the bulk status endpoint.
        meta:
          $ref: '#/components/schemas/BulkJobMeta'
    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
          - 'null'
          description: Failure reason when status is error.
    Meta:
      type: object
      description: Operation metadata returned in every data/meta response.
      required:
      - amount_charged
      properties:
        amount_charged:
          type: number
          description: Actual amount charged for this request in USD, computed from your pricing tier. 0 for free operations and for not-found results (No Data — No Charge).
        status:
          type: string
          description: Set to "error" when the operation finished with an error.
        error:
          type: string
          description: Error details; present only when the operation failed.
        time_cached:
          type: string
          format: date-time
          description: When the cached result set was originally collected (returned by database company search when results are served from a previous identical search).
        free_tier:
          type: object
          description: 'Present only on a database lead or company search sent with `"detail": "thin"`: where your account stands against today''s free row quota. The quota resets at 00:00 UTC.'
          properties:
            detail:
              type: string
              enum:
              - thin
            daily_rows:
              type: integer
              description: Free thin rows per account per UTC day.
            rows_used_today:
              type: integer
              description: Thin rows returned to your account today, this page included.
            rows_left_today:
              type: integer
              description: Thin rows your account can still take today.
    PhoneFindResponse:
      type: object
      properties:
        data:
          type: object
          properties:
            lead_id:
              type:
              - string
              - 'null'
              description: Resolved lead identifier, when the input matched a lead.
            phone:
              type: object
              properties:
                number:
                  type:
                  - string
                  - 'null'
                  description: Phone number in E.164 format; null when not found.
                status:
                  type: string
                  enum:
                  - FOUND
                  - NOT_FOUND
                type:
                  type: string
                  description: Number type (mobile, fixed_line, voip, ...). Present when found.
                country:
                  type: string
                  description: ISO country code. Present when found.
        meta:
          $ref: '#/components/schemas/Meta'
  securitySchemes:
    apiKey:
      type: apiKey
      in: header
      name: Authorization
      description: 'Use the required Token prefix. Example: Authorization: Token xxxxxxxxx'