How to Use a Websearch API for Lead Research (and Where It Stops)

A websearch API takes a search query over HTTPS and returns the results as JSON. You get titles, URLs, snippets and positions instead of HTML you would have to scrape. It answers "what is on the web about this", not "who works there".

That gap decides how you use it. This guide shows the request and response, then adds a B2B people search so a result becomes a named contact. Websearch providers differ, so those steps use a placeholder host. The LeadOcean steps are real calls to https://api.leadocean.io.

TL;DR

• A websearch API fetches live search results and normalizes them to JSON. It is good for signals (a launch, a funding post, a hire) and bad for contact data.
• The full flow takes about 15 minutes and spends 6 LeadOcean records of the 1,000 free ones. Counts cost nothing.
• Use websearch for the trigger. Use a people API for the person behind it.

Prerequisites

• A websearch API key from any provider. Read its docs for the endpoint, auth header and rate limit.
• A LeadOcean key from the free plan (1,000 records, no card): register here.
• curl and jq.

export SEARCH_API_KEY="your-search-provider-key"
export LEADOCEAN_API_KEY="your-leadocean-key"

Step 1: Send the query

A websearch API call is one request with a query and a few filters. Most providers take a keyword, a location, a language and a result type (web, news, images).

The host below is a placeholder. Swap in your provider's endpoint and header name.

curl -s "https://search.example.com/v1/search" \
  -H "Authorization: Bearer $SEARCH_API_KEY" \
  -G --data-urlencode "q=Acme Corp raises Series A" \
  --data-urlencode "country=us" \
  --data-urlencode "type=news" \
  --data-urlencode "num=5"

Behind that call the provider queries a search engine in real time, handles proxies and geo-targeting, and parses the page (Crustdata blog, October 2026). You skip the scraper and the CAPTCHA problem. That is the whole value.

Step 2: Read the response

A websearch response is a ranked list of results. The exact field names depend on the provider, but the shape is stable: title, URL, snippet and position, per Crustdata's own description of its output (Crustdata blog, October 2026).

This is a typical shape with placeholder values, not any one vendor's schema.

{
  "query": "Acme Corp raises Series A",
  "results": [
    {
      "position": 1,
      "title": "Acme Corp announces $12M Series A",
      "url": "https://news.example.com/acme-series-a",
      "snippet": "Acme Corp, maker of workflow tools, closed a $12M round led by..."
    }
  ]
}

Notice what is missing. There is no person, no job title and no email. The hit tells you Acme just raised. It does not tell you who to write to.

Pick the tool by the question you are asking.

The two answer different questions. Treat them as a pair, not as rivals.

Step 3: Turn the hit into people

To go from "Acme raised" to a contact list, query a B2B people index. In LeadOcean, POST /v1/people/search takes a flat JSON body. Filters are arrays of strings, limit runs 1 to 100, and paging uses cursor.

Start by sizing the list for free. Send count=true as a query parameter, not in the body, with limit 1. It returns meta.total and no rows.

curl -s -X POST "https://api.leadocean.io/v1/people/search?count=true" \
  -H "x-api-key: $LEADOCEAN_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "jobLevel": ["VP"],
    "jobFunction": ["Sales & Business Development"],
    "country": ["CA"],
    "limit": 1
  }' | jq '.meta'

Then pull a small page. Five rows spend five records.

curl -s -X POST "https://api.leadocean.io/v1/people/search" \
  -H "x-api-key: $LEADOCEAN_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "jobLevel": ["VP"],
    "jobFunction": ["Sales & Business Development"],
    "country": ["CA"],
    "limit": 5
  }' | jq '.data[0] | {profile_data, person_id: .meta.source_ids.person_id}'

If you already know the company from the search hit, GET /v1/companies/{domain}/people lists the people at that domain instead. Use acme.com as the placeholder.

Step 4: Enrich one person

Search returns a thin profile with no contact points. Enrichment adds the contact data. POST /v1/people/enrich takes exactly one of linkedin_url, email, phone or person_id. Pass the person_id from the search row (meta.source_ids.person_id).

curl -s -X POST "https://api.leadocean.io/v1/people/enrich" \
  -H "x-api-key: $LEADOCEAN_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"person_id": "PERSON_ID_FROM_STEP_3", "reveal_email": true}'

reveal_email returns the address and costs no extra record. A person we hold nothing for returns a 404 and costs nothing.

Step 5: Do it from an agent

If an AI agent runs the flow, give it both tools. The websearch tool finds the trigger. The LeadOcean MCP server at https://api.leadocean.io/mcp handles the people step with OAuth sign-in, so no key is pasted. It has 13 tools, and leadocean_count_leads, leadocean_list_filters, leadocean_list_enum_values and leadocean_count_companies are free.

Use a prompt that keeps the cost down.

Search the web for companies that announced a Series A this month.
For each, count VPs of Sales at that company with leadocean_count_leads.
Report counts only. Do not search or enrich until I pick one.

The agent now spends zero records until a human chooses a company. That one rule matters more than any prompt tuning. Agents loop, and a loop over paid calls is how a free allowance disappears in an afternoon.

Step 6: Keep the cost and the pace under control

A websearch call and a people call are metered differently, so check both before you loop.

• Websearch providers usually bill per query or per result. Read your provider's pricing page for the unit.
• LeadOcean counts one record per person or company returned. A count, a 404 and an empty page cost nothing.
• Size first with a free count, then pull rows. If the count says 40,000 and you wanted 200, tighten the filters before you spend anything.
• Keep the loop under your plan's rate limit: 5 requests a second on Free, 50 on Solo, 200 on Agency.

A simple guard in a script is to stop when the count passes your ceiling.

TOTAL=$(curl -s -X POST "https://api.leadocean.io/v1/people/search?count=true" \
  -H "x-api-key: $LEADOCEAN_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"jobLevel":["VP"],"country":["CA"],"limit":1}' | jq '.meta.total')
[ "$TOTAL" -gt 500 ] && echo "Too broad: $TOTAL. Narrow the filters." && exit 1

Run the count in the same script before every pull. It costs nothing and it saves the free records.

What you get

Here is a free leadocean_count_leads call on 21 October 2026 for the Step 3 filters (jobLevel VP, jobFunction Sales & Business Development, country CA). It spent 0 records.

{
  "total": 5574,
  "totalIsExact": true,
  "totalAll": 18800,
  "distinctCompanies": 3873,
  "credits": 0
}

The 5,574 counts only addresses worth sending to: emailStatus verified, catch_all_valid or catch_all. Without an email filter the same filters match 18,800 people. That is the difference between "people" and "mailable people", and a websearch API cannot show you either.

The valid values for jobLevel come from leadocean_list_enum_values (checked 21 October 2026): C-Team, Director, Manager, Other, Staff, VP. Enum values are exact strings.

A person row from search looks like this. This is the response shape from the API reference, with placeholder values:

{
  "success": true,
  "data": [
    {
      "profile_data": { "profile_full_name": "Jane Doe", "profile_headline": "VP Sales at Acme" },
      "contact_data": {
        "has_email": true,
        "has_phone": false,
        "email_status": "verified",
        "email_type": "work",
        "contact_current_experiences": [
          { "job_title": "VP Sales", "company_name": "Acme", "company_domain": "acme.com" }
        ]
      },
      "meta": { "source_ids": { "person_id": "123456789" } }
    }
  ],
  "meta": { "count": 1, "nextCursor": "opaque-string" }
}

Search returns flags such as has_email and email_status, not the address. Contact points arrive in Step 4.

Troubleshooting

FAQ