> ## 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. # 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. ## OpenAPI ````yaml https://gist.githubusercontent.com/JustinAlia/6ff38a671f5f79895444b77c57f3afff/raw/v2-openapi.json get /search/locations openapi: 3.0.0 info: title: Seamless API description: >- [Privacy Policy](https://seamless.ai/policies/privacy-policy) In order to dramatically improve our offerings to customers, Seamless will be introducing a Public API which can be used to search Companies & Contacts, Enrich Lists, and offer integrations as an Endpoint for our customers. The API is build using [RESTful](https://en.wikipedia.org/wiki/REST) principles and is secured using OAuth 2.0 with the implicit grant flow. # Authentication ## API Key ### 1. **Register Your Application** To use the Seamless API, you need to register your application to obtain an API key. To create a new API key, go to [Seamless.AI | Settings](https://login.seamless.ai/settings/public-api) > API Key and click the *Create New Connection* button. Note: The Public API Connections menu will only appear if your account has access to the Public API. ### 2. **Use the Access Token** For all authenticated API requests, include the API key in the header: ``` Token: API_KEY ``` ## OAuth 2.0 ### 1. **Register Your Application** Before integrating, you have to setup your client credentials. To create a new API client, go to [Seamless.AI | Settings](https://login.seamless.ai/settings/public-api) > OAuth Connections, and click the *Create New Connection* button. Note: The Public API Connections menu will only appear if your account has access to the Public API. - `client_id` - `client_secret` - `redirect_uri` You’ll use these to authenticate and obtain tokens. --- ### 2. **Obtain Authorization Code** Redirect the user to Seamless.AI's OAuth authorization endpoint: ``` GET https://login.seamless.ai/oauth/authorize ``` ### Query Parameters: | Name | Description | | --- | --- | | `client_id` | Your client ID | | `redirect_uri` | The URL users are redirected to | | `state` | (Optional) CSRF protection string | **Example URL**: ``` GET https://login.seamless.ai/oauth/authorize?client_id=YOUR_CLIENT_ID&redirect_uri=https://yourapp.com/callback ``` Once the user authenticates, they will be redirected to your `redirect_uri` with a `code` parameter. If your `redirect_uri` contains any query parameters (such as `?foo=bar`), you must URL encode your `redirect_uri` for this step. --- ### 3. **Exchange Code for Access Token** ``` POST https://api.seamless.ai/api/client/v2/oauth/accessToken ``` ### Request Body (JSON): ```json { "client_id": "YOUR_CLIENT_ID", "client_secret": "YOUR_CLIENT_SECRET", "redirect_uri": "https://yourapp.com/callback", "grant_type": "authorization_code", "code": "AUTHORIZATION_CODE_FROM_STEP_2" } ``` ### Response: ```json { "token_type": "Bearer", "access_token": "ACCESS_TOKEN", "refresh_token": "REFRESH_TOKEN", "expires_in": 10800, "expires_at": "2026-06-25T12:00:00.000Z", "refresh_token_expires_in": 604800, "refresh_token_expires_at": "2026-07-02T12:00:00.000Z" } ``` Access tokens expire after **180 minutes** by default. Integrations must use the `refresh_token` grant before expiry to obtain a new token pair. Existing long-lived tokens issued before this change remain valid until their original expiry. --- ### 4. **Use the Access Token** For all authenticated API requests, include the token in the header: ``` Authorization: Bearer ACCESS_TOKEN ``` --- ### 5. **Refreshing the Token** To refresh the access token: ``` POST https://api.seamless.ai/api/client/v2/oauth/accessToken ``` ### Request Body: ```json { "client_id": "YOUR_CLIENT_ID", "client_secret": "YOUR_CLIENT_SECRET", "redirect_uri": "https://yourapp.com/callback", "grant_type": "refresh_token", "refresh_token": "YOUR_REFRESH_TOKEN" } ``` ### Response: ```json { "token_type": "Bearer", "access_token": "NEW_ACCESS_TOKEN", "refresh_token": "NEW_REFRESH_TOKEN", "expires_in": 10800, "expires_at": "2026-06-25T12:00:00.000Z", "refresh_token_expires_in": 604800, "refresh_token_expires_at": "2026-07-02T12:00:00.000Z" } ``` Each refresh rotates both the access and refresh tokens. Store the new `refresh_token` from every response. # Rate Limiting Rate limits are enforced at the **organization** level. All API usage for your Seamless organization counts against the same quota for each endpoint—limits are not applied separately per API key or per user. The default limit is **60 requests per minute** per endpoint. If you exceed the limit, the API responds with **429 Too Many Requests** and a JSON error body. Some endpoints may use different limits (for example, OAuth routes). Your organization may also have custom limits. The `X-RateLimit-Limit` header on each response always reflects the maximum number of requests allowed for that endpoint in the current rate limit window. Rate limit and remaining credits information will be returned in the response header of each request. The parameters are: | Name | Example | Description | | --- | --- | --- | | `X-RateLimit-Limit` | 60 | The maximum number of requests you're permitted to make in the current rate limit window for this endpoint. | | `X-RateLimit-Remaining` | 42 | The number of requests remaining in the current rate limit window. | | `X-RateLimit-Reset` | 1745587198 | The time at which the current rate limit window resets in epoch seconds. | | `X-PublicAPI-Credits` | 1000 | The number of credits remaining that can be used in requests. | version: 1.0.0 x-logo: url: https://s3.amazonaws.com/seamless.ai-public/logos/logo-full-dark.svg altText: Seamless logo href: https://login.seamless.ai termsOfService: https://seamless.ai/policies/terms-of-use servers: - url: https://api.seamless.ai/api/client/v2 description: Seamless API security: - OAuth2: [] - ApiKeyAuth: [] tags: - name: OAuth description: >- Exchange client credentials for an access token and inspect the authenticated caller. - name: Contact Search description: >- Search the Seamless.AI contact database. Searching does not consume credits; researching a result does. - name: Company Search description: >- Search the Seamless.AI company database. Searching does not consume credits; researching a result does. - name: Contact Research description: >- Resolve a contact's emails and phone numbers. Research is asynchronous: submit a request, then poll for results or receive them by webhook. - name: Company Research description: >- Resolve company firmographics and contact details. Research is asynchronous: submit a request, then poll for results or receive them by webhook. - name: Org Contacts description: >- Read and update the contacts already saved to your organization. These are the records research writes to, and the IDs other endpoints expect. - name: Org Companies description: Read and update the companies already saved to your organization. - name: Campaigns description: >- Create and run multi-step outbound campaigns, manage their steps, and enroll or remove contacts. - name: Emails description: Compose, preview, send, and track emails, individually or in bulk. - name: Tasks description: Read and act on the tasks a campaign generates for its assigned user. - name: Lists description: Group saved contacts and companies into named lists. - name: Templates description: Reusable email templates available to campaigns and one-off sends. - name: Saved Searches description: Persist search filters so a search can be re-run or shared later. - name: Calls description: >- Log call outcomes against saved contacts, and read the disposition and sentiment vocabularies. - name: Activity description: A chronological feed of engagement activity across your organization. - name: Credits description: Remaining research credits for the authenticated organization. - name: Features description: Feature access flags for the authenticated organization. - name: Reference description: >- Static lookup data — locations, statuses, and other vocabularies other endpoints accept. paths: /search/locations: get: tags: - Contact Search - Company Search summary: Look up location filter values description: > 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. operationId: lookupLocations parameters: - in: query name: q required: true description: > 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. schema: type: string example: austin - in: query name: limit required: false description: Maximum results to return, 1-100. schema: type: integer minimum: 1 maximum: 100 default: 10 - in: query name: types required: false description: > 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`. schema: type: array items: type: string enum: - city-state-country - state-country - city-country - country - postcode responses: '200': description: Matching locations, most common first content: application/json: schema: type: object properties: data: description: > Matching locations, ordered by contact volume. An empty array means the vocabulary holds nothing resembling the query. type: array items: type: object description: > One entry of the location filter vocabulary — a value the search index will actually match, spelled the way the index spells it. properties: location: description: > The exact string to send on a location filter. Pass it verbatim; a partial or re-spelled form may match nothing. type: string example: Austin, Texas, United States type: description: > Which tier of the vocabulary this entry belongs to, and so which filter it belongs on. A `postcode` goes on `contactZipCode` or `companyZipCode`; every other tier goes on a location filter, and only `city-state-country` and `city-country` reach city level. type: string enum: - city-state-country - state-country - city-country - country - postcode example: city-state-country count: description: > Contacts in the index at this location. This is what disambiguates a name that means several places — "Ontario" is a Canadian province and five US cities, and the largest of them is "Ontario, California, United States". type: integer example: 166378 '400': description: >- Missing `q`, a `limit` out of range, or an unrecognized `types` value content: application/json: schema: type: object required: - message properties: message: description: A human readable error message type: string '401': description: Unauthorized content: application/json: schema: type: object required: - message properties: message: description: A human readable error message type: string '500': description: Unexpected error content: application/json: schema: type: object required: - message properties: message: description: A human readable error message type: string security: - OAuth2: [] - ApiKeyAuth: [] components: securitySchemes: OAuth2: type: oauth2 flows: authorizationCode: authorizationUrl: https://login.seamless.ai/oauth/authorize tokenUrl: https://api.seamless.ai/api/client/v2/oauth/accessToken scopes: {} ApiKeyAuth: type: apiKey name: Token in: header description: API key passed via the Token header. ````