Contact Search

Look up location filter values

Search the location vocabulary for the exact values a location filter will match.

Location filters are matched against a fixed vocabulary of place names, spelled the way the underlying data spells them. A value outside that vocabulary matches no contacts, and because search returns 200 with an empty data array either way, a misspelling is indistinguishable from a genuinely empty market. This endpoint is how you tell the two apart: look a place up, then send the returned location string verbatim.

The vocabulary is too large to enumerate — roughly 170,000 cities and 727,000 postal codes — so there is no full list to download. Query it instead. Results are ordered by contact volume, so the first result is usually the place you meant.

US state names and abbreviations, and the country aliases US, USA and United States of America, are resolved by the location filters directly and need no lookup.

This endpoint consumes no search credits.

GET

locations

Look up location filter values

curl --request GET \
  --url https://api.seamless.ai/api/client/v1/search/locations \
  --header 'Authorization: Bearer <token>'

const options = {method: 'GET', headers: {Authorization: 'Bearer <token>'}};

fetch('https://api.seamless.ai/api/client/v1/search/locations', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://api.seamless.ai/api/client/v1/search/locations",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "GET",
  CURLOPT_HTTPHEADER => [
    "Authorization: Bearer <token>"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"net/http"
	"io"
)

func main() {

	url := "https://api.seamless.ai/api/client/v1/search/locations"

	req, _ := http.NewRequest("GET", url, nil)

	req.Header.Add("Authorization", "Bearer <token>")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

require 'uri'
require 'net/http'

url = URI("https://api.seamless.ai/api/client/v1/search/locations")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Get.new(url)
request["Authorization"] = 'Bearer <token>'

response = http.request(request)
puts response.read_body

{
  "data": [
    {
      "location": "Austin, Texas, United States",
      "type": "city-state-country",
      "count": 166378
    }
  ]
}

{
  "message": "<string>"
}

{
  "message": "<string>"
}

{
  "message": "<string>"
}

Authorizations

Authorization

string

header

required

The access token received from the authorization server in the OAuth 2.0 flow.

Query Parameters

string

required

A partial place name, matched at the start of any word — york finds New York. Search one place name at a time rather than a whole comma-separated tag.

Example:

"austin"

limit

integer

default:10

Maximum results to return, 1-100.

Required range: 1 <= x <= 100

types

enum<string>[]

Restrict results to these tiers of the vocabulary. Repeat the parameter or pass a comma-separated list. Omit for all tiers.

Use state-country or country to find a value for contactState / companyState or contactCountry / companyCountry, city-state-country for a free-form locations tag, and postcode for contactZipCode / companyZipCode.

Available options:

city-state-country,

state-country,

city-country,

country,

postcode

Response

Matching locations, most common first

data

object[]

Matching locations, ordered by contact volume. An empty array means the vocabulary holds nothing resembling the query.

Show child attributes

Look up location filter values

curl --request GET \
  --url https://api.seamless.ai/api/client/v1/search/locations \
  --header 'Authorization: Bearer <token>'

const options = {method: 'GET', headers: {Authorization: 'Bearer <token>'}};

fetch('https://api.seamless.ai/api/client/v1/search/locations', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://api.seamless.ai/api/client/v1/search/locations",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "GET",
  CURLOPT_HTTPHEADER => [
    "Authorization: Bearer <token>"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"net/http"
	"io"
)

func main() {

	url := "https://api.seamless.ai/api/client/v1/search/locations"

	req, _ := http.NewRequest("GET", url, nil)

	req.Header.Add("Authorization", "Bearer <token>")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

require 'uri'
require 'net/http'

url = URI("https://api.seamless.ai/api/client/v1/search/locations")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Get.new(url)
request["Authorization"] = 'Bearer <token>'

response = http.request(request)
puts response.read_body

{
  "data": [
    {
      "location": "Austin, Texas, United States",
      "type": "city-state-country",
      "count": 166378
    }
  ]
}

{
  "message": "<string>"
}

{
  "message": "<string>"
}

{
  "message": "<string>"
}

MCP

API v1

API v2

Look up location filter values

Authorizations

Query Parameters

Response