Find leads in the Directory

WhyCopy Anchor Link

The Directory is ReplySparrow's pool of B2B leads. Searching it is free and shows you who matches before you spend anything; you pay only for the leads you reveal. That makes it the fastest way to build a targeted list for a campaign, an account-based play, or a one-off export.

Send Authorization: Bearer YOUR_API_KEY. The base URL is https://app.replysparrow.com/api/v1. The key needs the contacts:read scope to search, and contacts:write to reveal.

1. Pick filter values (optional)

GET /directory/industries and GET /directory/locations return the industry and location values the Directory uses, such as "Financial Services" or "England, United Kingdom". Other values are accepted, but these give the best matches, and a source agent's target_industries and target_locations understand them too. Both calls are free.

curl --header "Authorization: Bearer YOUR_API_KEY" \
  "https://app.replysparrow.com/api/v1/directory/locations"

2. Search, for free

POST /directory/leads/search returns a page of matching leads. At least one filter is required.

curl --request POST \
  --header "Authorization: Bearer YOUR_API_KEY" \
  --header "Content-Type: application/json" \
  --data '{
    "job_title": ["Head of Sales", "VP Sales"],
    "location": ["France"],
    "company_size": ["51-200"],
    "is_company_hiring": true,
    "limit": 25,
    "page": 1
  }' \
  "https://app.replysparrow.com/api/v1/directory/leads/search"

{
  "leads": [
    {
      "id": "dl_3f9a0c2b7d1e4f5a6b7c8d9e",
      "first_name": "Jane",
      "last_name": "",
      "full_name": "",
      "job_title": "Head of Sales",
      "headline": "",
      "location": "Paris, France",
      "industry": "Software Development",
      "company": "",
      "company_size": "",
      "linkedin_url": ""
    }
  ],
  "total": 1840,
  "page": 1,
  "limit": 25,
  "has_more": true
}

The preview fills only id, first_name, job_title, location, and industry; the other fields stay empty until you reveal. Results are cached for 7 days per filter set, so the same filters and page return the same leads. limit goes up to 100, and total is capped at 10,000. Read pages in order: a page far past the ones you read can return 400 page_too_deep.

Other filters: industry, name, company, company_identifier (website domains or exact company names), and the signal has_recently_changed_job (started at their current company in the last 3 months). is_company_hiring means the company's headcount grew 20% or more in 6 months. company_url, has_recent_funding_round, company_last_funding_round_since, and has_recent_activity are not supported yet and return 400 filter_not_supported.

3. Reveal the leads you want

POST /directory/leads/reveal returns the full leads for the ids you pick: last name, company, LinkedIn profile URL, company website, and more. Pass list_id to also save them as contacts in that list, at no extra cost.

curl --request POST \
  --header "Authorization: Bearer YOUR_API_KEY" \
  --header "Content-Type: application/json" \
  --data '{
    "ids": ["dl_3f9a0c2b7d1e4f5a6b7c8d9e", "dl_7c2e9b1a0f3d4e5c6b7a8d9f"],
    "list_id": "9f8e7d6c-0000-4000-8000-000000000002"
  }' \
  "https://app.replysparrow.com/api/v1/directory/leads/reveal"

{
  "leads": [
    {
      "id": "dl_3f9a0c2b7d1e4f5a6b7c8d9e",
      "first_name": "Jane",
      "last_name": "Doe",
      "full_name": "Jane Doe",
      "job_title": "Head of Sales",
      "company": "Acme",
      "linkedin_url": "https://www.linkedin.com/in/janedoe",
      "company_website": "acme.com"
    }
  ],
  "requested": 2,
  "revealed": 2,
  "credits_used": 2,
  "not_found_ids": [],
  "not_revealed_ids": [],
  "saved_to_list": 2,
  "skipped_existing": 0,
  "skipped_excluded": 0,
  "skipped_missing_name": 0
}

Each revealed lead costs 1 credit the first time; revealing the same lead again is free. Send up to 100 ids per call. If your credits don't cover every id, only the first ones are revealed and charged, and the rest are listed in not_revealed_ids. not_found_ids lists ids that did not come from one of your searches.

With list_id, leads already in your workspace, excluded, or without a first and last name are skipped (skipped_existing, skipped_excluded, skipped_missing_name), so saved_to_list can be lower than revealed. The save happens during the call: allow a longer HTTP timeout for large reveals.

To start from companies instead, Search companies and Reveal companies work the same way, at 1 credit per company.

4. Reach out

Revealed leads have no email or phone. Get them per contact with POST /contacts/{id}/enrich/email (1 credit) and POST /contacts/{id}/enrich/phone (10 credits), charged only when something is found. id is the ReplySparrow contact id: read the saved contacts with GET /contacts?list_id=.... Both calls can take minutes; the -async variants return a job to poll instead. In an assistant, lead_action with find_email or find_phone does the same.

To contact the list, attach it to a campaign: see A full outbound play from one prompt.

Every field is listed on Search leads, Reveal leads, Industries, and Locations.