> ## Documentation Index
> Fetch the complete documentation index at: https://docs.seamless.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Search

> search_contacts, search_companies, and lookup_locations MCP tools.

Search the Seamless.AI database for contacts and companies. These tools do not consume credits. `POST /search/contacts` and `POST /search/companies` do — see [Rate limits and credits](/rate-limits-and-credits).

| Tool | Description | Risk | Schema |
| - | - | - | - |
| `search_contacts` | Search contacts by company, title, seniority, location, timezone, industry, SIC/NAICS code, company type, funding, and more. Returns a paginated table. | `read` | [#search\_contacts](#search_contacts) |
| `search_companies` | Search companies by name, domain, location, industry, SIC/NAICS code, size, revenue, company type, funding, and more. Returns a paginated table. | `read` | [#search\_companies](#search_companies) |
| `lookup_locations` | Find the exact spellings a location filter will match, with the contact count behind each. The only way to find a city or postal code. | `read` | [#lookup\_locations](#lookup_locations) |

## Location filters

Location filters match a fixed vocabulary of place names, spelled the way the data spells them (Germany's state is `Bavaria`, not `Bayern`). A value the vocabulary does not hold is rejected with the nearest real spellings. Call `lookup_locations` before setting a location filter you are unsure of, or whenever a filter returns fewer results than expected.

`locationRadius` and `zipCodesRadius` widen a location to everything within a radius in miles — `25`, `50`, `100`, or `250`. Only geocodable values (cities, zip codes) get a radius. Read `seamless://search/radius` for which filter each one widens.

## search\_contacts

<ParamField path="companyName" type="string[]">
  Filter by company names.
</ParamField>

<ParamField path="jobTitle" type="string[]">
  Filter by job title (not `title`). Set `titlesExactMatch: true` to require an exact match.
</ParamField>

<ParamField path="fullname" type="string[]">
  Filter by contact full name (not `contactName`).
</ParamField>

<ParamField path="locations" type="string[]">
  City, state/region, or country tags (max 10). The only filter that reaches city level; comma-separate to disambiguate (`Austin, Texas`). Prefix with `-` to exclude.
</ParamField>

<ParamField path="locationRadius" type="string | number">
  Widen `locations` to everything within this many miles: `25`, `50`, `100`, or `250`.
</ParamField>

<ParamField path="limit" default="50" type="integer">
  Results per page.
</ParamField>

### Example

```json theme={null}
{
  "jsonrpc": "2.0",
  "method": "tools/call",
  "params": {
    "name": "search_contacts",
    "arguments": {
      "companyName": ["Acme Corp"],
      "jobTitle": ["VP Sales"],
      "seniority": ["VP", "Director"],
      "limit": 10
    }
  },
  "id": 1
}
```

## search\_companies

<ParamField path="companyName" type="string[]">
  Filter by company names.
</ParamField>

<ParamField path="locations" type="string[]">
  City, state/region, or country tags (max 10). Prefix with `-` to exclude.
</ParamField>

### Example

```json theme={null}
{
  "jsonrpc": "2.0",
  "method": "tools/call",
  "params": {
    "name": "search_companies",
    "arguments": {
      "companyName": ["Acme Corp"],
      "limit": 10
    }
  },
  "id": 1
}
```

## lookup\_locations

Search one place name at a time. Results come back most common first, each with the contact `count` behind it and a `type` naming which filter the value belongs on. US state abbreviations and country aliases like `TX` and `USA` are accepted by the filters directly and need no lookup.

<ParamField path="q" type="string" required>
  Partial location name, matched at the start of any word — `york` finds `New York`.
</ParamField>

<ParamField path="types" type="string[]">
  Restrict to these tiers: `city-state-country`, `state-country`, `city-country`, `country`, `postcode`. Use `state-country` or `country` for `contactState`/`contactCountry`, `city-state-country` for a `locations` tag, and `postcode` for `contactZipCode`.
</ParamField>

<ParamField path="limit" default="10" type="integer">
  Maximum results, up to 100.
</ParamField>

### Example

```json theme={null}
{
  "jsonrpc": "2.0",
  "method": "tools/call",
  "params": {
    "name": "lookup_locations",
    "arguments": {
      "q": "ontario",
      "types": ["city-state-country", "state-country"]
    }
  },
  "id": 1
}
```


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.