Anymail Finder Geo Lead API

openapi: 3.2.0
info:
  title: Anymail finder Geo Lead API
  description: ''
  version: '5.1'
  contact: {}
servers:
- url: https://api.anymailfinder.com
tags:
- name: geo-lead
paths:
  /v5.1/geo-lead:
    post:
      description: Creates a bulk search that will generate leads from a specific geographic area. The search will find businesses or locations matching the provided query within the specified radius from the given coordinates. This is useful for location-based lead generation and market research.
      operationId: searchBulkGeoLeadCreate
      parameters:
      - name: x-webhook-url
        in: header
        description: If provided, the result will be POSTed to this URL instead of waiting for the response.
        required: false
        schema:
          type: string
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/Api51GeoLeadCreateBodyDto'
      responses:
        '200':
          description: Created.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Api5GeoLeadDto'
        '400':
          description: Bad Request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Api51ErrorResponseDto'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Api51ErrorResponseDto'
      security:
      - api_key: []
      summary: Create a new GeoLead search based on geographic coordinates and search query
      tags:
      - geo-lead
  /v5.1/geo-lead/{searchId}:
    get:
      operationId: get
      parameters:
      - name: searchId
        required: true
        in: path
        schema:
          type: string
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Api5GeoLeadDto'
        '400':
          description: Bad Request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Api51ErrorResponseDto'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Api51ErrorResponseDto'
        '404':
          description: Not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Api51ErrorResponseDto'
      security:
      - api_key: []
      summary: Retrieve the details of a GeoLead search
      tags:
      - geo-lead
  /v5.1/geo-lead/{searchId}/download:
    get:
      operationId: download
      parameters:
      - name: searchId
        required: true
        in: path
        description: The ID of the GeoLead search
        schema:
          example: blk_xxxxxxxx
          type: string
      - name: preview_only
        required: false
        in: query
        description: When true, downloads a preview version of the results without charging credits. Preview files exclude all paid information (such as emails or other data depending on the bulk search type). Defaults to false.
        schema:
          enum:
          - 'true'
          - 'false'
          type: string
          example: 'true'
      - name: partially_verified
        required: false
        in: query
        description: Deprecated - searches no longer return risky emails, so this has no effect. Still accepted so existing callers keep working.
        schema:
          enum:
          - '0'
          - '1'
          type: string
          example: '1'
      - name: not_found
        required: false
        in: query
        description: 'Include rows where the email was not found in the download. Default: 1 (enabled).'
        schema:
          enum:
          - '0'
          - '1'
          type: string
          example: '1'
      - name: fully_verified
        required: false
        in: query
        description: 'Include rows with valid emails in the download. Default: 1 (enabled).'
        schema:
          enum:
          - '0'
          - '1'
          type: string
          example: '1'
      - name: file_name_column_name
        required: false
        in: query
        description: If specified, appends a column containing the file name to the downloaded file.
        schema:
          example: file_name
      - name: download_as
        required: false
        in: query
        description: Output file format ("csv", "json_arr", "json_obj" or "xlsx", defaults to "csv").
        schema:
          example: csv
      responses:
        '200':
          content:
            text/csv: {}
          description: Success
        '400':
          description: Bad Request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Api51ErrorResponseDto'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Api51ErrorResponseDto'
        '402':
          description: Upgrade needed
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Api51ErrorResponseDto'
        '404':
          description: Not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Api51ErrorResponseDto'
      security:
      - api_key: []
      summary: Download a CSV file containing the results of a GeoLead search
      tags:
      - geo-lead
components:
  schemas:
    Api51GeoLeadCreateBodyDto:
      type: object
      properties:
        file_name:
          type: string
          description: A label to identify the geo lead search.
          example: my_geo_lead_search
        find_company_emails:
          type: boolean
          description: Whether to search for company emails. If false, only decision maker emails will be searched. Defaults to true.
          example: true
        find_decision_maker_categories:
          description: 'Decision maker categories to search for. If not provided, defaults to ["ceo"]. If empty array [], no decision maker search will be performed. Valid categories: "ceo", "engineering", "finance", "hr", "it", "logistics", "marketing", "operations", "buyer", "sales".'
          example:
          - ceo
          type: array
          items:
            type: string
        latitude:
          type: number
          minimum: -90
          maximum: 90
          description: The latitude coordinate for the search center point.
          example: 40.7127753
        longitude:
          type: number
          minimum: -180
          maximum: 180
          description: The longitude coordinate for the search center point.
          example: -74.0059728
        query:
          type: string
          description: The search query to find businesses or locations within the specified radius.
          example: restaurants
        radius_km:
          type: number
          minimum: 1
          maximum: 25
          description: The search radius in km from the center point.
          example: 1
        result_limit:
          type:
          - number
          - 'null'
          minimum: 1
          description: Optional limit on the number of leads to extract. If specified, the extraction will stop once this limit is reached.
          example: 100
      required:
      - find_company_emails
      - find_decision_maker_categories
      - latitude
      - longitude
      - query
      - radius_km
    Api51ErrorResponseDto:
      type: object
      properties:
        error:
          type: string
          description: Error code
          example: no_result
        message:
          type: string
          description: Detailed explanation of the error
          example: We could not find an email for this person. Sorry.
      required:
      - error
      - message
    Api5GeoLeadDto:
      type: object
      properties:
        status:
          enum:
          - on_deck
          - queued
          - running
          - paused
          - completed
          - deleted
          - extraction_queued
          - extraction_running
          type: string
          description: "The current status of the GeoLead search:<br />\n    - \"extraction_queued\": The search for companies matching the specified criteria is queued and will start soon.<br />\n    - \"extraction_running\": The search for companies is in progress.<br />\n    - \"queued\": The search for emails of the found companies is queued and will start soon.<br />\n    - \"running\": The search for emails of the found companies is in progress.<br />\n    - \"paused\": The GeoLead search has been temporarily paused.<br />\n    - \"completed\": The GeoLead search has finished successfully.<br />\n    - \"failed\": The GeoLead search has failed. This indicates that an error occurred during processing and the operation could not complete."
        counts:
          type: object
          properties:
            failed:
              type: number
            found_unknown:
              type: number
            found_valid:
              type: number
            not_found:
              type: number
            total:
              type: number
          required:
          - failed
          - found_unknown
          - found_valid
          - not_found
          - total
        created_at:
          format: date-time
          type: string
        credits_needed:
          type: number
        file_name:
          type: string
        find_company_emails:
          type: boolean
        find_decision_maker_categories:
          type: array
          items:
            type: string
        id:
          type: string
        latitude:
          type: number
        longitude:
          type: number
        paid:
          type: boolean
        query:
          type: string
        radius_km:
          type: number
        result_limit:
          type:
          - number
          - 'null'
        started_running_at:
          format: date-time
          type:
          - string
          - 'null'
      required:
      - status
      - counts
      - created_at
      - credits_needed
      - file_name
      - find_company_emails
      - find_decision_maker_categories
      - id
      - latitude
      - longitude
      - paid
      - query
      - radius_km
      - started_running_at
  securitySchemes:
    api_key:
      type: apiKey
      in: header
      name: Authorization