Get Lead Finder search results

Changed on Nov 3, 2026

Retrieve the results of a Lead Finder search.

Answers 202 with no leads while the search is still running, and 200 with status: "terminated" once it is done. Branch on status, never on the HTTP code alone. See Request statuses.

get/lead_finder/async/{request_id}

Request

Base URL
https://app.bettercontact.rocks/api/v2
URL
https://app.bettercontact.rocks/api/v2/lead_finder/async/{request_id}
Auth
API key in header X-API-Key

Path parameters

request_idstring required

Response

Search finished. status is terminated (leads present, possibly empty) or on_hold (top up credits to resume).

idstring

The request_id of this search.

status'not_started' | 'processing' | 'on_hold' | 'terminated'

See Request statuses. A search that matched nothing is reported as terminated with an empty leads array.

messagestring

Human readable hint. Only present while the search is not terminated.

credits_consumedinteger

Credits spent by this search. Zero unless enrich_email_address or enrich_phone_number was requested.

credits_leftinteger

Credits remaining on the account.

Example response

{
  "id": "bc39ffbfc24cf043b748",
  "status": "terminated",
  "message": "Lead finder request is not terminated yet. Please try later",
  "credits_left": 331,
  "summary": {
    "leads_found": 350,
    "limit": 100,
    "offset": 100,
    "total": 100,
    "valid": 62,
    "catch_all": 18,
    "catch_all_not_safe": 5,
    "undeliverable": 3,
    "not_found": 17,
    "found": 41
  },
  "leads": [
    {
      "contact_id": 128374651,
      "contact_first_name": "Elon",
      "contact_last_name": "Musk",
      "contact_full_name": "Elon Musk",
      "contact_job_title": "Ceo",
      "contact_seniority": "Cxo",
      "contact_industry": "Automotive",
      "contact_gender": "male",
      "contact_linkedin_profile_url": "https://www.linkedin.com/in/elonmusk",
      "contact_location_continent": "North america",
      "contact_location_country": "United states",
      "contact_location_state": "Texas",
      "contact_location_city": "Austin",
      "contact_email_address": "elon@tesla.com",
      "contact_email_address_status": "deliverable",
      "contact_email_address_provider": "Secret Provider",
      "contact_phone_number": "+14155550101",
      "company_name": "Tesla",
      "company_domain": "tesla.com",
      "company_industry": "Automotive",
      "company_type": "Public Company",
      "company_keywords": [
        "wine industry",
        "wine"
      ],
      "company_founded_year": 2003,
      "company_employees_range_start": 10001,
      "company_employees_range_end": 50000,
      "company_head_quarters_city": "Austin",
      "company_head_quarters_country": "United states",
      "custom_fields": []
    }
  ]
}

Changes

Nov 3, 2026cd9044a26697 Revision changes
- breaking
  the response's property type changed from string to integer for status
- breaking
  the response's property type changed from string to integer for status
- breaking
  the /// response's property type changed from no type to object for status
- warning
  removed the optional property // from the response with the status
- warning
  removed the optional property // from the response with the status
- warning
  removed the optional property // from the response with the status
- warning
  removed the optional property // from the response with the status
- warning
  removed the optional property // from the response with the status
- warning
  removed the optional property // from the response with the status
- warning
  removed the optional property // from the response with the status
- warning
  removed the optional property // from the response with the status
- warning
  removed the optional property // from the response with the status
- warning
  removed the optional property // from the response with the status
- warning
  removed the optional property // from the response with the status
- warning
  removed the optional property // from the response with the status
- warning
  removed the optional property // from the response with the status
- warning
  removed the optional property // from the response with the status
- warning
  removed the optional property // from the response with the status
- warning
  removed the optional property // from the response with the status
- warning
  removed the optional property // from the response with the status
- warning
  removed the optional property // from the response with the status
- warning
  removed the optional property // from the response with the status
- warning
  removed the optional property // from the response with the status
- warning
  removed the optional property // from the response with the status
- warning
  removed the optional property // from the response with the status
- warning
  removed the optional property // from the response with the status
- warning
  removed the optional property // from the response with the status
- warning
  removed the optional property // from the response with the status
- warning
  removed the optional property // from the response with the status
- warning
  removed the optional property // from the response with the status
- warning
  removed the optional property // from the response with the status
- warning
  removed the optional property // from the response with the status
- warning
  removed the optional property // from the response with the status
- warning
  removed the optional property // from the response with the status
- warning
  removed the optional property // from the response with the status
- warning
  removed the optional property // from the response with the status
- warning
  removed the optional property // from the response with the status
- warning
  removed the optional property // from the response with the status
- warning
  removed the optional property // from the response with the status
- warning
  removed the optional property // from the response with the status
- warning
  removed the optional property // from the response with the status
- warning
  removed the optional property // from the response with the status
- warning
  removed the optional property // from the response with the status
- warning
  removed the optional property // from the response with the status
- warning
  removed the optional property // from the response with the status
- warning
  removed the optional property // from the response with the status
- warning
  removed the optional property // from the response with the status
- warning
  removed the optional property // from the response with the status
- warning
  removed the optional property // from the response with the status
- warning
  removed the optional property // from the response with the status
- warning
  added the new catch_all enum value to the // response property for the response status
- warning
  added the new catch_all_not_safe enum value to the // response property for the response status
- warning
  added the new catch_all_safe enum value to the // response property for the response status
- warning
  added the new deliverable enum value to the // response property for the response status
- warning
  added the new not_found enum value to the // response property for the response status
- warning
  added the new not_started enum value to the response property for the response status
- warning
  added the new on_hold enum value to the response property for the response status
- warning
  added the new processing enum value to the response property for the response status
- warning
  added the new terminated enum value to the response property for the response status
- warning
  added the new undeliverable enum value to the // response property for the response status
- info
  api operation id getLeadFinderSearch was added
- info
  added the non-success response with the status
- info
  removed the non-success response with the status
- info
  added the optional property // to the response with the status
- info
  added the optional property //// to the response with the status
- info
  added the optional property //// to the response with the status
- info
  added the optional property //// to the response with the status
- info
  added the optional property to the response with the status
- info
  added the optional property to the response with the status
- info
  added the optional property / to the response with the status
- info
  added the optional property / to the response with the status
- info
  added the optional property / to the response with the status
- info
  added the optional property / to the response with the status
- info
  added the optional property / to the response with the status
- info
  added the optional property / to the response with the status
- info
  added the optional property / to the response with the status
- info
  added the optional property / to the response with the status
- info
  added the optional property / to the response with the status
- info
  added the success response with the status

Operation history