> ## 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.

# Location → Contacts

> Free-form city, state, or country targeting, and the only filter that matches at city level. One filter of the Seamless.AI Contact Search API.

> [!NOTE]
>
> `POST /search/contacts` · Credits charged per results returned · v1, v2 · Part of the [Contact Search API](/api-catalog/contact-search)

## Introduction

Free-form city, state, or country targeting, and the only filter that matches at city level. Widen any city with a 25-250 mile radius. Combine it with any other filter in the same request (AND logic).

## AI agent prompt

```text theme={null}
Read https://docs.seamless.ai/api-catalog/contact-filters/location. Using SEAMLESS_API_KEY, call POST https://api.seamless.ai/api/client/v1/search/contacts with the `locations` filter to find contacts matching: <your target>. Page with nextToken and keep each searchResultId.
```

## Example

```bash cURL theme={null}
curl -X POST https://api.seamless.ai/api/client/v1/search/contacts \
  -H "Token: $SEAMLESS_API_KEY" -H "Content-Type: application/json" \
  -d '{"locations": ["Austin, Texas", "-Dallas, Texas"], "locationRadius": "50", "limit": 25}'
```

```python Python theme={null}
import os, requests
rows = requests.post("https://api.seamless.ai/api/client/v1/search/contacts",
    headers={"Token": os.environ["SEAMLESS_API_KEY"]},
    json={"locations": ["Austin, Texas", "-Dallas, Texas"], "locationRadius": "50", "limit": 25}).json()["data"]
```

## Reference

| Parameter | Type | Required | Description |
| - | - | - | - |
| `locations` | string\[] | Yes | Free-form location filter — city, state/region, or country — and the only filter that reaches city-level matching. Values may be a single place (`"Austin"`) or comma-separated to disambiguate (`"Austin, Texas"`, `"Ontario, Canada"`). Prefix a value with `-` to exclude it. Behavior depends on the `locationType` parameter, and values are combined with `contactCountry` rather than replacing it. Cities are the largest part of the vocabulary and the part no list can enumerate — use `GET /search/locations` to find one, and pass the returned `location` string verbatim. Its `count` is what separates a name meaning several places: `"Ontario"` is a Canadian province and a larger California city. Up to 10 values. |
| `locationRadius` | string | No | Widen `locations` (and `contactCountry`) to everything within a radius of each value. The value is the radius in miles, sent as a string or a number. Only geocodable values get a radius — a city or zip code resolves to coordinates, a country does not. Use `zipCodesRadius` for `contactZipCode`. The spelled-out label (`25 miles`) is accepted too, as are the legacy options `1`, `2`, `3`, and `4`, which mean 25, 50, 100, and 250 miles. |
| `locationType` | string | No | Determines how location filters (`locations`, `contactState`, `contactCountry`, `contactZipCode`) are applied. `contact` matches the contact's personal location only. `company` matches the company's headquarters location only. `bothOR` matches if either the contact or the company location matches (default). `bothAND` matches only when both match. Default `"bothOR"`. |
| `limit` | integer | No | Results per page, up to 500. Default `50`. |
| `nextToken` | string | No | Cursor from `supplementalData.nextToken` to fetch the next page. |

**Allowed values for `locationRadius`:** `25`, `50`, `100`, `250`

**Allowed values for `locationType`:** `bothOR`, `bothAND`, `company`, `contact`

> [!TIP]
>
> Resolve city spellings first with the [Location Lookup API](/api-catalog/location-lookup).

## Response

Rows are contact previews with `searchResultId`, name, title, seniority, company, location, and LinkedIn URL, but no emails or phones. Send `searchResultId` to [Contact Research](/api-catalog/contact-enrichment) to get them. Fields: [Contact Search](/api-catalog/contact-search).

Auth: `Token` header ([API keys](/authentication/api-keys)) · Errors: [status codes](/api-http-status-codes) · Billing: [rate limits and credits](/rate-limits-and-credits)


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