Skip to main content

​
Summary

The Prospecting API group contains the POST /v1/prospect/companies endpoint and its interactive playground.Use POST /v1/prospect/companies to discover matching companies from external sources using either a freeform search query or structured filters.For example, you can send a request like “find manufacturing companies in Tokyo with more than 200 employees” and get back a ranked list of matching company candidates.

​
Authentication

  • External integrations use Authorization: Bearer <access_token>
  • OAuth callers need companies:read
  • Sanka internal tooling can also authenticate with X-Workspace-Code

​
When to use it

Use prospecting when you want to:
  • discover new company candidates that match a sales profile
  • pass a natural-language request directly into the API
  • filter by location, industry, and employee-count range in the same request
Main request fields:
  • query: freeform search criteria
  • location: city, region, or country
  • industry: industry label or vertical
  • min_employee_count and max_employee_count: employee range filters
  • limit: number of results to return, from 1 to 20
  • sources: external providers to request; defaults to ["exa"]

​
Coverage

  • v1 supports company prospecting
  • either query or at least one structured filter is required
  • responses include parsed_filters so you can inspect how the request was interpreted
  • this is a read-oriented API: it returns candidates but does not create or update Sanka company records

​
Send the request

curl -X POST "https://api.sanka.com/v1/prospect/companies" \
  -H "Authorization: Bearer <access_token>" \
  -H "Content-Type: application/json" \
  -d '{
    "query": "find manufacturing companies in Tokyo with more than 200 employees",
    "limit": 10,
    "sources": ["exa"]
  }'
You can also skip the freeform query and use structured filters only:
{
  "location": "Tokyo",
  "industry": "manufacturing",
  "min_employee_count": 200,
  "limit": 10
}
Use the interactive playground in the OpenAPI reference on this page to test the same request.

​
Review the response

The response includes:
  • query: the search text used for the run
  • parsed_filters: the normalized location, industry, and employee filters
  • results: the discovered company candidates
  • count: the number of returned candidates
  • provider_meta: source usage and extraction metadata
Each result can include company name, URL, domain, industry, employee count, description, source URLs, and match_reasons.
{
  "data": {
    "query": "find manufacturing companies in Tokyo with more than 200 employees",
    "parsed_filters": {
      "location": "Tokyo",
      "industry": "manufacturing",
      "min_employee_count": 200
    },
    "results": [
      {
        "name": "Acme Manufacturing",
        "domain": "acme.example",
        "employee_count": 350,
        "source_urls": ["https://acme.example/about"],
        "match_reasons": ["industry match", "employee count match"]
      }
    ],
    "count": 1,
    "provider_meta": {}
  },
  "message": "Company prospecting completed",
  "ctx_id": "<ctx_id>"
}

​
Supported sources

  • v1 executes prospect discovery through exa
  • you can pass multiple provider names in sources, but unsupported names are not executed
  • if you include a name such as google_maps, it is reported under provider_meta.unsupported_sources
  • check provider_meta.requested_sources, provider_meta.supported_sources, and provider_meta.unsupported_sources to see what happened in a run