Anymail Finder Bulk API

openapi: 3.2.0
info:
  title: Anymail finder Bulk API
  description: ''
  version: '5.1'
  contact: {}
servers:
- url: https://api.anymailfinder.com
tags:
- name: Bulk
paths:
  /v5.1/bulk/json:
    post:
      operationId: createWithJson
      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/Api51BulkCreateWithJsonBodyDto'
      responses:
        '200':
          description: Created.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Api5SearchBulkDto'
        '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 bulk search by sending a CSV file in the request body
      tags:
      - Bulk
  /v5.1/bulk/multipart:
    post:
      operationId: createWithMultipart
      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:
          multipart/form-data:
            schema:
              type: object
              properties:
                file:
                  type: string
                  format: binary
                  description: File to be uploaded
                company_name_field_index:
                  type: number
                  description: The zero-based index of the column containing the company name in the uploaded file.
                  minimum: 0
                domain_field_index:
                  type: number
                  description: The zero-based index of the column containing the company website (domain) in the uploaded file.
                  minimum: 0
                email_field_index:
                  type: number
                  description: The zero-based index of the column containing the emails to validate in the uploaded file.
                  minimum: 0
                file_name:
                  type: string
                  description: A label to identify the bulk search.
                has_header:
                  type: boolean
                  description: Whether the first row of the file contains headers. Defaults to true. Set to false if the first row is data.
                first_name_field_index:
                  type: number
                  description: The zero-based index of the column containing the first name in the uploaded file.
                  minimum: 0
                full_name_field_index:
                  type: number
                  description: The zero-based index of the column containing the full name in the uploaded file.
                  minimum: 0
                decision_maker_category:
                  type: array
                  items:
                    type: string
                  description: 'One or more categories of the decision maker(s) to search for. If multiple are provided, they are treated in order of importance and the result will use the first category that resolves to a valid email. One or more of the following: "ceo", "engineering", "finance", "hr", "it", "logistics", "marketing", "operations", "buyer", "sales".'
                last_name_field_index:
                  type: number
                  description: The zero-based index of the column containing the last name in the uploaded file.
                  minimum: 0
                linkedin_url_field_index:
                  type: number
                  description: The zero-based index of the column containing the Linkedin URL in the uploaded file.
                  minimum: 0
                webhook_url:
                  type: string
                  description: URL where we should send a webhook when the file processing has completed.
      responses:
        '200':
          description: Created.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Api5SearchBulkDto'
        '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 bulk search by uploading an Excel or CSV file
      tags:
      - Bulk
  /v5.1/bulk/{searchId}/download:
    get:
      operationId: download
      parameters:
      - name: searchId
        required: true
        in: path
        description: The ID of the 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: 'Include rows with risky emails in the download. Verify bulks only - searches no longer return risky emails. Default: 1 (enabled).'
        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: format
        required: false
        in: query
        description: Setting to specify how the output file should be formatted.
        schema:
          enum:
          - default
          - company-one-email-per-line
          type: string
          example: default
      - 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 bulk search
      tags:
      - Bulk
  /v5.1/bulk/{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/Api5SearchBulkDto'
        '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 bulk search
      tags:
      - Bulk
components:
  schemas:
    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
    Api5SearchBulkDto:
      type: object
      properties:
        status:
          enum:
          - on_deck
          - queued
          - running
          - paused
          - completed
          - deleted
          - extraction_queued
          - extraction_running
          type: string
          description: "The current status of the bulk operation. Each status represents a specific stage in the bulk operation lifecycle:<br />\n    - \"on_deck\": Indicates the bulk file has been uploaded through the UI, but the columns have not been mapped yet. This status is internal and typically not encountered by API users.<br />\n    - \"queued\": The bulk operation is queued and will be processed soon. This status implies that the operation is in the waiting list and will be picked up by the processing system.<br />\n    - \"running\": The bulk operation is currently in progress. This status indicates that the processing of the bulk file is actively ongoing.<br />\n    - \"paused\": The operation has been temporarily paused.<br />\n    - \"completed\": The bulk operation has been completed successfully. All records in the bulk file have been processed as intended.<br />\n    - \"failed\": The bulk operation has failed. This status indicates that there was an error during the processing which prevented the operation from completing successfully.<br />\n    Note: The status flow typically progresses from \"queued\" to \"running\", and then to either \"completed\" or \"failed\", but can also include \"paused\"."
        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
        decision_maker_category:
          type:
          - string
          - 'null'
        file_name:
          type: string
        id:
          type: string
        paid:
          type: boolean
        started_running_at:
          format: date-time
          type:
          - string
          - 'null'
      required:
      - status
      - counts
      - created_at
      - credits_needed
      - decision_maker_category
      - file_name
      - id
      - paid
      - started_running_at
    Api51BulkCreateWithJsonBodyDto:
      type: object
      properties:
        company_name_field_index:
          type: number
          minimum: 0
          description: The zero-based index of the column containing the company name in the uploaded file.
          example: 0
        data:
          type: array
          items:
            required: true
            description: A multidimensional array containing rows and columns. The first row is expected to contain headers unless has_header is set to false.
            example:
            - - company
              - name
            - - Tesla
              - Elon Musk
            type: array
            items:
              type: object
        decision_maker_category:
          maxItems: 5
          description: 'One or more categories of the decision maker(s) to search for. If multiple are provided, they are treated in order of importance and the result will use the first category that resolves to a valid email. One or more of the following: "ceo", "engineering", "finance", "hr", "it", "logistics", "marketing", "operations", "buyer", "sales".'
          example: ceo
          type: array
          items:
            type: string
        domain_field_index:
          type: number
          minimum: 0
          description: The zero-based index of the column containing the company website (domain) in the uploaded file.
          example: null
        email_field_index:
          type: number
          minimum: 0
          description: The zero-based index of the column containing the emails to validate in the uploaded file.
          example: null
        file_name:
          type: string
          description: A label to identify the bulk search.
          example: my_search_name
        first_name_field_index:
          type: number
          minimum: 0
          description: The zero-based index of the column containing the first name in the uploaded file.
          example: null
        full_name_field_index:
          type: number
          minimum: 0
          description: The zero-based index of the column containing the full name in the uploaded file.
          example: 1
        has_header:
          type: boolean
          description: Whether the first row of the data array contains headers. Defaults to true. Set to false if the first row is data.
          example: true
        last_name_field_index:
          type: number
          minimum: 0
          description: The zero-based index of the column containing the last name in the uploaded file.
          example: null
        linkedin_url_field_index:
          type: number
          minimum: 0
          description: The zero-based index of the column containing the Linkedin URL in the uploaded file.
          example: null
        webhook_url:
          type: string
          description: URL where we should send a webhook when the file processing has completed.
          example: null
      required:
      - data
  securitySchemes:
    api_key:
      type: apiKey
      in: header
      name: Authorization