> ## 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 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/v1/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 { "access_token": "ACCESS_TOKEN", "refresh_token": "REFRESH_TOKEN", "expires_at": 1712000000 } ``` --- ### 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/v1/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" } ``` # 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/v1 description: Seamless API security: - OAuth2: [] - ApiKeyAuth: [] tags: [] 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. type: integer default: 50 example: 50 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 enum: - NY - Texas - Florida - VA - CA maxItems: 10 description: >- Company location state filters. Combined with country/zip filters as part of location matching. example: - CA companyCountry: type: array items: type: string enum: - United States - Canada - United Kingdom - Germany - Australia maxItems: 10 description: >- Company location country filters. Combined with state/zip filters as part of location matching. example: - United States companyZipCode: type: array items: type: string enum: - '10001' - '30301' - '33101' - '60601' - '94105' maxItems: 10 description: Company postal/zip code filters for location-based matching. example: - '94105' 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 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 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 properties: searchResultId: type: string description: >- Stable identifier for this search result item, used by enrichment/research endpoints. example: cmp_sr_01J8YQ4FXZQ6N5G2T3A7BC9D1E name: type: string description: Canonical company name. example: Seamless.AI street1: type: string description: Primary street line for the company location. example: 800 W El Camino Real street2: type: string description: Secondary street line for the company location. example: Suite 180 street3: type: string description: Additional street/location line when provided. example: Building B city: type: string description: City of the company location. example: Mountain View state: type: string description: State or region of the company location. example: CA postCode: type: string description: Postal/zip code of the company location. example: '94040' country: type: string description: Country of the company location. example: United States domain: type: string description: Primary website domain for the company. example: seamless.ai description: type: string description: Short company profile/summary text. example: >- Seamless.AI is a sales intelligence platform for finding and engaging prospects. liUrl: type: string description: Public LinkedIn company profile URL when available. example: https://www.linkedin.com/company/seamless-ai/ sicCode: type: string description: >- Standard Industrial Classification (SIC) code associated with the company. example: '7372' industries: type: array description: Industry categories associated with the company. example: - Information Technology and Services - Computer Software items: type: string revenueRange: type: string description: Revenue band bucket assigned to the company. example: $20M - $50M annualRevenue: type: string description: Estimated annual revenue value, when available. example: '35000000' staffCountRange: type: string description: Employee headcount band for the company. example: 51 - 200 employeeCount: type: string description: Estimated employee count. example: '125' numContacts: type: string description: >- Number of contacts currently associated with this company in indexed results. example: '487' technologies: type: array description: Technologies detected for the company. example: - Salesforce - HubSpot - Marketo items: type: string linkedInId: type: string description: LinkedIn company ID when available. example: '1234567' companyLIURL: type: string description: >- Alternate LinkedIn company URL source returned from social metadata when available. example: https://www.linkedin.com/company/seamless-ai/ foundedOn: type: string format: date description: Company founding date. example: '2015-01-01' newsAndEvents: type: array description: Recent news articles related to the company. items: type: object properties: title: description: The headline of the news article. type: string url: description: The URL to the full news article. type: string date: description: The date the news article was published. type: string format: date-time type: description: >- The type of news article (e.g., "Acquisition"). type: string fundingTotal: type: string description: Most recent total funding amount for the company. example: '135000000' latestFundingDate: type: string format: date description: >- The date of the most recent funding round for the company. example: '2018-01-01' latestFundingClassifications: type: array 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. type: integer example: 5 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/v1/oauth/accessToken scopes: {} ApiKeyAuth: type: apiKey name: Token in: header description: API key passed via the Token header. ````