openapi: 3.2.0
info:
  title: LastDatabase Lead Search Leads API
  version: 1.0.0
  description: 'Official API specification for the LastDatabase Lead Search API.


    Search supported email, phone, and fax lead inventory using

    country, city, industry, keyword, and result-limit parameters.


    Authentication uses an active LastDatabase API key supplied

    as a Bearer token.'
  contact:
    name: LastDatabase
    url: https://lastdatabase.com/docs/api
servers:
- url: https://lastdatabase.com
  description: Production
tags:
- name: Leads
  description: Search supported LastDatabase lead inventory.
paths:
  /api/leads/search:
    get:
      tags:
      - Leads
      summary: Search leads
      description: 'Search email, phone, or fax lead inventory.


        The default lead type is email.


        For phone searches, the public industry parameter maps

        to the phone category field.


        The current endpoint does not expose page, offset, or

        cursor pagination.'
      operationId: searchLeads
      security:
      - bearerAuth: []
      parameters:
      - name: type
        in: query
        required: false
        description: 'Lead inventory type. Defaults to email.


          The current implementation falls back to email when

          an unrecognized type value is supplied.

          '
        schema:
          type: string
          enum:
          - email
          - phone
          - fax
          default: email
      - name: country
        in: query
        required: false
        description: Filter results by country.
        schema:
          type: string
        example: usa
      - name: city
        in: query
        required: false
        description: Filter results by city.
        schema:
          type: string
        example: New York
      - name: industry
        in: query
        required: false
        description: 'Filter by industry. For phone inventory, this

          parameter maps to the phone category field.

          '
        schema:
          type: string
        example: healthcare
      - name: keyword
        in: query
        required: false
        description: 'Keyword filter.


          Email keyword matching covers country, city,

          industry, and company name.


          Phone keyword matching covers country, city,

          and category.


          Fax keyword matching covers country, city,

          industry, and company name.

          '
        schema:
          type: string
      - name: limit
        in: query
        required: false
        description: Number of records to return.
        schema:
          type: integer
          minimum: 1
          maximum: 100
          default: 25
        example: 10
      responses:
        '200':
          description: Lead search completed successfully.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/LeadSearchResponse'
              examples:
                success:
                  summary: Successful search
                  value:
                    status: true
                    type: email
                    count: 1
                    data:
                    - id: 12345
                      first_name: Example
                      last_name: Contact
                      company_name: Example Company
                      industry: Healthcare
                      country: USA
                      city: New York
        '401':
          description: Missing or invalid API token.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              examples:
                missingToken:
                  summary: Missing API token
                  value:
                    status: false
                    message: Missing API token.
                invalidToken:
                  summary: Invalid API token
                  value:
                    status: false
                    message: Invalid API token.
        '429':
          description: Daily API request limit exceeded.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              example:
                status: false
                message: Daily API limit exceeded.
components:
  schemas:
    ErrorResponse:
      type: object
      required:
      - status
      - message
      properties:
        status:
          type: boolean
          const: false
        message:
          type: string
    PhoneLead:
      type: object
      description: 'Phone lead record. Additional fields may be returned

        by the underlying phone inventory.

        '
      additionalProperties: true
      properties:
        id:
          type:
          - integer
          - string
        package_id:
          type:
          - integer
          - string
          - 'null'
        first_name:
          type:
          - string
          - 'null'
        last_name:
          type:
          - string
          - 'null'
        phone_number:
          type:
          - string
          - 'null'
        country_code:
          type:
          - string
          - 'null'
        country:
          type:
          - string
          - 'null'
        state:
          type:
          - string
          - 'null'
        postal_code:
          type:
          - string
          - 'null'
        city:
          type:
          - string
          - 'null'
        carrier:
          type:
          - string
          - 'null'
        category:
          type:
          - string
          - 'null'
        company_website:
          type:
          - string
          - 'null'
        linkedin_url:
          type:
          - string
          - 'null'
        employee_size:
          type:
          - string
          - 'null'
        revenue:
          type:
          - string
          - 'null'
        seniority:
          type:
          - string
          - 'null'
        technology:
          type:
          - string
          - 'null'
        source:
          type:
          - string
          - 'null'
        optin_status:
          type:
          - boolean
          - integer
          - string
          - 'null'
        created_at:
          type:
          - string
          - 'null'
        updated_at:
          type:
          - string
          - 'null'
    EmailLead:
      type: object
      description: 'Email lead record. Additional fields may be returned

        by the underlying email inventory.

        '
      additionalProperties: true
      properties:
        id:
          type:
          - integer
          - string
        package_id:
          type:
          - integer
          - string
          - 'null'
        first_name:
          type:
          - string
          - 'null'
        last_name:
          type:
          - string
          - 'null'
        email:
          type:
          - string
          - 'null'
        company_name:
          type:
          - string
          - 'null'
        company_website:
          type:
          - string
          - 'null'
        linkedin_url:
          type:
          - string
          - 'null'
        employee_size:
          type:
          - string
          - 'null'
        revenue:
          type:
          - string
          - 'null'
        seniority:
          type:
          - string
          - 'null'
        technology:
          type:
          - string
          - 'null'
        job_title:
          type:
          - string
          - 'null'
        industry:
          type:
          - string
          - 'null'
        country:
          type:
          - string
          - 'null'
        state:
          type:
          - string
          - 'null'
        postal_code:
          type:
          - string
          - 'null'
        city:
          type:
          - string
          - 'null'
        source:
          type:
          - string
          - 'null'
        created_at:
          type:
          - string
          - 'null'
    LeadSearchResponse:
      type: object
      required:
      - status
      - type
      - count
      - data
      properties:
        status:
          type: boolean
          const: true
        type:
          type: string
          enum:
          - email
          - phone
          - fax
        count:
          type: integer
          minimum: 0
        data:
          type: array
          description: 'Lead records. Available fields depend on the

            requested inventory type and source data.

            '
          items:
            oneOf:
            - $ref: '#/components/schemas/EmailLead'
            - $ref: '#/components/schemas/PhoneLead'
            - $ref: '#/components/schemas/FaxLead'
    FaxLead:
      type: object
      additionalProperties: true
      properties:
        id:
          type:
          - integer
          - string
        package_id:
          type:
          - integer
          - string
          - 'null'
        company_name:
          type:
          - string
          - 'null'
        fax_number:
          type:
          - string
          - 'null'
        industry:
          type:
          - string
          - 'null'
        country:
          type:
          - string
          - 'null'
        city:
          type:
          - string
          - 'null'
        source:
          type:
          - string
          - 'null'
        optin_status:
          type:
          - boolean
          - integer
          - string
          - 'null'
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      description: 'Active LastDatabase API key.


        Send the key in the Authorization header:


        Authorization: Bearer YOUR_API_KEY

        '