> ## 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 companies ## OpenAPI ````yaml https://gist.githubusercontent.com/JustinAlia/6ff38a671f5f79895444b77c57f3afff/raw/v2-openapi.json post /search/companies 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/companies: post: tags: - Company Search summary: Search companies operationId: searchCompanies requestBody: required: true content: application/json: schema: type: object properties: nextToken: description: >- Opaque cursor token from a previous `/search/companies` response. Use this to fetch the next page of results. type: string default: null example: eyJwYWdlIjoyLCJzZWFyY2hJZCI6IjEyMzQ1In0= limit: description: > Number of companies to return per page before credit-based trimming is applied. A larger value is reduced to 500 rather than rejected. type: integer default: 50 maximum: 500 example: 50 page: description: > Page number for offset-based pagination, starting at 1. `nextToken` is the preferred way to page through results and takes precedence when both are sent. type: integer default: 1 example: 2 savedSearchId: description: >- Run the filters held by a saved search instead of sending them. Get the id from `GET /saved-searches`. The saved search must be a company search. Cannot be combined with any other filter; doing so returns a validation error. `limit`, `page` and `nextToken` are still accepted. type: integer example: 1234 companyName: type: array items: type: string maxItems: 100 description: >- Company names to match. Use this when you know full company names or key name fragments. example: - Seamless AI companyNameSearchType: description: >- Matching strategy for `companyName` (`default` = standard matching, `related` = include aliases/related names, `exact` = exact company name only). type: string enum: - default - related - exact default: default example: related companyDomain: type: array items: type: string maxItems: 100 description: >- Company website domains to match (for example root domains without protocol). example: - seamless.ai companyState: type: array items: type: string maxItems: 10 description: > Company location state filters. Accepts a US state name or abbreviation and non-US subdivisions alike (`"CA"`, `"California"`, `"Ontario"`). A company matches if it is in any of these states, narrowed by `companyCountry` when that is supplied too. Prefix a value with `-` to exclude it; an excluded state stands alone, since exclusions narrow on their own. Values match a fixed vocabulary of place names spelled the way our data spells them, which is usually the English exonym — Germany's state is `"Bavaria"`, not `"Bayern"`. US state names and abbreviations are both resolved, so neither needs a lookup. Use `GET /search/locations` to find the spelling for anything else; a value the vocabulary does not hold matches no companies and comes back under `warnings`, with suggestions, rather than as an error. example: - CA companyCountry: type: array items: type: string maxItems: 10 description: > Company location country filters. Narrows `companyState` rather than widening it, so `companyState: ["Virginia"]` with `companyCountry: ["United States"]` returns Virginia companies only. A state and country that do not belong together narrow to nothing: `companyState: ["Texas"]` with `companyCountry: ["Germany"]` matches no companies, since no company is in both — that pair comes back under `warnings` too, suggesting the state's real country. Use `locations` when you mean either place rather than both. It does not narrow `locations` — put the country inside the tag itself (`"Austin, Texas, United States"`) to scope a free-form value. Prefix a value with `-` to exclude it; an excluded country stands alone and narrows nothing. `"US"`, `"USA"` and `"United States of America"` all resolve to the United States. Use `GET /search/locations?types=country` to find any other country's spelling; a value the vocabulary does not hold matches no companies and comes back under `warnings`, with suggestions, rather than as an error. example: - United States companyZipCode: type: array items: type: string maxItems: 10 description: > Company postal/zip code filters. Widens the other location filters rather than narrowing them: a company matches if it is in any of these zip codes, or in anything `locations` / `companyState` ask for. Send it as the only location filter to match zip codes alone. Prefix a value with `-` to exclude it. example: - '94105' locations: description: > 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. A company matches if it is in any of these places, or in any `companyState`. 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. type: array items: type: string maxItems: 10 example: - Austin, Texas - '-Dallas, Texas' locationRadius: description: > Widen the company location filters to everything within a radius of each value. Applies to `locations`, `companyState`, and `companyZipCode` alike — there is a single radius for every company location filter. 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. This is the form `GET /saved-searches` reads a radius back in, so those values can be sent straight through here. The spelled-out label (`25 miles`) is accepted too, as are the options `1`, `2`, `3`, and `4` this filter originally took, which mean 25, 50, 100, and 250 miles respectively. type: string enum: - '25' - '50' - '100' - '250' default: null nullable: true example: '50' industry: type: array items: type: string enum: - Accounting - Airlines/Aviation - Alternative Dispute Resolution - Alternative Medicine - Animation - Apparel & Fashion - Architecture & Planning - Arts and Crafts - Automotive - Aviation & Aerospace - Banking - Biotechnology - Broadcast Media - Building Materials - Business Supplies and Equipment - Capital Markets - Chemicals - Civic & Social Organization - Civil Engineering - Commercial Real Estate - Computer & Network Security - Computer Games - Computer Hardware - Computer Networking - Computer Software - Construction - Consumer Electronics - Consumer Goods - Consumer Services - Cosmetics - Dairy - Defense & Space - Design - E-Learning - Education Management - Electrical/Electronic Manufacturing - Entertainment - Environmental Services - Events Services - Executive Office - Facilities Services - Farming - Financial Services - Fine Art - Fishery - Food & Beverages - Food Production - Fund-Raising - Furniture - Gambling & Casinos - Glass, Ceramics & Concrete - Government Administration - Government Relations - Graphic Design - Health, Wellness and Fitness - Higher Education - Hospital & Health Care - Hospitality - Human Resources - Import and Export - Individual & Family Services - Industrial Automation - Information Services - Information Technology and Services - Insurance - International Affairs - International Trade and Development - Internet - Investment Banking - Investment Management - Judiciary - Law Enforcement - Law Practice - Legal Services - Legislative Office - Leisure, Travel & Tourism - Libraries - Logistics and Supply Chain - Luxury Goods & Jewelry - Machinery - Management Consulting - Maritime - Market Research - Marketing and Advertising - Mechanical or Industrial Engineering - Media Production - Medical Devices - Medical Practice - Mental Health Care - Military - Mining & Metals - Motion Pictures and Film - Museums and Institutions - Music - Nanotechnology - Newspapers - Non-Profit Organization Management - Oil & Energy - Online Media - Outsourcing/Offshoring - Package/Freight Delivery - Packaging and Containers - Paper & Forest Products - Performing Arts - Pharmaceuticals - Philanthropy - Photography - Plastics - Political Organization - Primary/Secondary Education - Printing - Professional Training & Coaching - Program Development - Public Policy - Public Relations and Communications - Public Safety - Publishing - Railroad Manufacture - Ranching - Real Estate - Recreational Facilities and Services - Religious Institutions - Renewables & Environment - Research - Restaurants - Retail - Security and Investigations - Semiconductors - Shipbuilding - Sporting Goods - Sports - Staffing and Recruiting - Supermarkets - Telecommunications - Textiles - Think Tanks - Tobacco - Translation and Localization - Transportation/Trucking/Railroad - Utilities - Venture Capital & Private Equity - Veterinary - Warehousing - Wholesale - Wine and Spirits - Wireless - Writing and Editing maxItems: 5 description: >- Industry categories to include in results. Valid values are the fixed industry list below. example: - Information Technology and Services industrySicCodes: description: > Filter by SIC code. Applied independently of `industry`, so the two can be combined or used on their own. Prefix a value with `-` to exclude it. Up to 5 codes can be specified. type: array items: type: string maxItems: 5 example: - '7372' industryNaicsCodes: description: > Filter by NAICS code. Applied independently of `industry`, so the two can be combined or used on their own. Prefix a value with `-` to exclude it. Up to 5 codes can be specified. On API v2, unrecognized codes are rejected with a validation error. Matching is against the company's own `naicsCode`. A company that has no `naicsCode` of its own also matches when its SIC code maps to a requested code. type: array items: type: string maxItems: 5 example: - '511210' companyKeyword: type: array items: type: string maxItems: 10 description: >- Free-text keywords used to match company profile text (name, description, and related indexed company data). example: - sales intelligence - B2B SaaS keywordsIsOr: description: > Controls how multiple `companyKeyword` values are combined. When `false` (default), a company must match all of the keywords (AND logic). When `true`, matching any one of them is enough (OR logic). type: boolean default: false example: false companySize: type: array items: type: string enum: - 0 - 1 (Self-employed) - 2 - 10 - 11 - 50 - 51 - 200 - 201 - 500 - 501 - 1,000 - 1,001 - 5,000 - 5,001 - 10,000 - 10,001+ maxItems: 10 description: >- Employee size bands to match against company headcount ranges. example: - 51 - 200 - 201 - 500 companyRevenue: type: array items: type: string enum: - $0 - $100K - $100K - $1M - $1M - $5M - $5M - $20M - $20M - $50M - $50M - $100M - $100M - $500M - $500M - $1B - $1B+ maxItems: 10 description: Revenue range bands to match estimated company revenue. example: - $20M - $50M technologies: type: array items: type: string enum: - Salesforce - HubSpot - Marketo - Outreach - Apollo maxItems: 10 description: >- Technologies used by the company. Sample enum values for documentation only (not exhaustive; actual values come from API/typeahead). example: - Salesforce - HubSpot technologiesIsOr: type: boolean description: >- If true, matches companies using any of the specified technologies (OR). If false, matches only companies using all specified technologies (AND). example: true companyType: type: string description: > Filter by company type. `Public` = companies with a known stock ticker/exchange, `Private` = all others. enum: - Public - Private default: null nullable: true example: Public foundedOn: type: array items: type: string enum: - Less than 1 Year - Last 1-3 Years - Last 4-10 Years - 10+ Years description: Company age buckets based on founding date. maxItems: 4 example: - Less than 1 Year - Last 1-3 Years newsTypes: type: array items: type: string enum: - Acquisition - Corporate Challenges - Cost Cutting - Expansion - Investment - Leadership - Partnership - Recognition maxItems: 8 description: Filter companies by news/event classification type. example: - Acquisition - Expansion newsTypeDates: type: array items: type: string enum: - '60' - '90' - '180' - '365' maxItems: 1 description: >- Limit news/event results to a rolling day window (60, 90, 180, or 365 days). Only the first value is applied. example: - '60' latestFundingDates: type: array items: type: string enum: - '90' - '180' - '365' - '1095' description: >- Filter companies based on the date of their latest funding round (90, 180, 365 days or 3 years). example: - '90' maxItems: 1 latestFundingClassifications: type: array items: type: string enum: - Angel - Pre-Seed - Seed - Series A - Series B - Series C - Series D - Series E - Series F - Series G - Series H - Series I - Series J - Other description: >- Filter companies based on the classifications of their latest funding round. example: - Series A - Seed maxItems: 14 latestFundingTotals: type: array items: type: string enum: - $0 - $100K - $100K - $1M - $1M - $5M - $5M - $20M - $20M - $50M - $50M - $100M - $100M - $500M - $500M - $1B - $1B+ description: >- Filter companies based on the total funding amount they have raised. example: - $0 - $100K - $100K - $1M maxItems: 9 responses: '200': description: Company Search Results content: application/json: schema: type: object properties: data: description: A list of companies type: array items: type: object description: >- A company search result. Any field may be `null` when the underlying record lacks that attribute — search and research results are sparse, so treat every field below as optional and nullable. properties: searchResultId: type: string description: >- Stable identifier for this search result item, used by enrichment/research endpoints. example: cmp_sr_01J8YQ4FXZQ6N5G2T3A7BC9D1E companyName: type: string nullable: true description: >- Canonical company name. Same vocabulary as the `companyName` search filter. example: Seamless.AI name: deprecated: true type: string nullable: true description: >- Deprecated alias for `companyName`. Prefer `companyName`, which matches the search filter of the same name. example: Seamless.AI street1: type: string nullable: true description: Primary street line for the company location. example: 800 W El Camino Real street2: type: string nullable: true description: Secondary street line for the company location. example: Suite 180 street3: type: string nullable: true description: Additional street/location line when provided. example: Building B city: type: string nullable: true description: City of the company location. example: Mountain View state: type: string nullable: true description: State or region of the company location. example: CA postCode: type: string nullable: true description: Postal/zip code of the company location. example: '94040' country: type: string nullable: true description: Country of the company location. example: United States domain: type: string nullable: true description: Primary website domain for the company. example: seamless.ai description: type: string nullable: true description: Short company profile/summary text. example: >- Seamless.AI is a sales intelligence platform for finding and engaging prospects. liUrl: type: string nullable: true description: Public LinkedIn company profile URL when available. example: https://www.linkedin.com/company/seamless-ai/ sicCode: type: string nullable: true description: >- Standard Industrial Classification (SIC) code associated with the company. example: '7372' naicsCode: type: string nullable: true description: >- North American Industry Classification System (NAICS) code associated with the company. example: '541512' industries: type: array nullable: true description: Industry categories associated with the company. example: - Information Technology and Services - Computer Software items: type: string companyRevenue: type: string nullable: true description: >- Revenue band bucket assigned to the company. Same vocabulary as the `companyRevenue` search filter. example: $20M - $50M revenueRange: deprecated: true type: string nullable: true description: >- Deprecated alias for `companyRevenue`. Prefer `companyRevenue`, which matches the search filter of the same name. example: $20M - $50M annualRevenue: type: string nullable: true description: Estimated annual revenue value, when available. example: '35000000' companySize: type: string nullable: true description: >- Employee headcount band for the company. Same vocabulary as the `companySize` search filter. example: 51 - 200 staffCountRange: deprecated: true type: string nullable: true description: >- Deprecated alias for `companySize`. Prefer `companySize`, which matches the search filter of the same name. This alias keeps the historical label (`51 - 200 employees`); `companySize` is the filter apiValue (`51 - 200`). example: 51 - 200 employees employeeCount: type: string nullable: true description: Estimated employee count. example: '125' numContacts: type: string nullable: true description: >- Number of contacts currently associated with this company in indexed results. example: '487' technologies: type: array nullable: true description: Technologies detected for the company. example: - Salesforce - HubSpot - Marketo items: type: string linkedInId: type: string nullable: true description: LinkedIn company ID when available. example: '1234567' companyLIURL: type: string nullable: true description: >- Alternate LinkedIn company URL source returned from social metadata when available. example: https://www.linkedin.com/company/seamless-ai/ foundedOn: type: string nullable: true format: date description: Company founding date. example: '2015-01-01' newsAndEvents: type: array nullable: true description: Recent news articles related to the company. items: type: object properties: title: description: The headline of the news article. type: string nullable: true url: description: The URL to the full news article. type: string nullable: true date: description: The date the news article was published. type: string nullable: true format: date-time type: description: >- The type of news article (e.g., "Acquisition"). type: string nullable: true fundingTotal: type: string nullable: true description: Most recent total funding amount for the company. example: '135000000' latestFundingDate: type: string nullable: true description: >- The date of the most recent funding round for the company. format: date example: '2018-01-01' latestFundingClassifications: type: array nullable: true description: >- The classifications of the most recent funding round for the company. example: - Series D items: type: string companyType: type: string nullable: true description: >- Company type — "Public" or "Private" when determined. enum: - Public - Private example: Public stockTicker: type: string nullable: true description: >- Stock ticker symbol of the company, if publicly traded. example: AAPL supplementalData: type: object description: Pagination metadata for the current search result set. properties: isMore: description: >- Indicates whether additional pages of results are available beyond the current page. type: boolean example: true total: description: >- The total number of contacts matching the search criteria. type: integer example: 150 perPage: description: >- The number of results returned per page for this search request. Returned by contact search only — company search omits this field, so read the page size from the length of `data` rather than relying on it. type: integer example: 50 nextToken: description: >- An opaque pagination token. Pass this value in the `nextToken` field of your next request body to retrieve the next page of results. Null or absent when no more pages are available. type: string nullable: true example: eyJwYWdlIjoyLCJzZWFyY2hJZCI6ImFiYzEyMyJ9 '401': description: Unauthorized content: application/json: schema: type: object required: - message properties: message: description: A human readable error message type: string '422': description: Insufficient credits or missing license content: application/json: schema: description: Insufficient credits or missing license type: object properties: msg: type: string code: type: string data: type: object properties: productCategory: type: string additionalCreditsNeeded: type: integer '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. ````