> ## 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. # Research companies > Research companies by search result IDs from `/search/companies` and/or direct company identifiers (`domain`, `companyName`). ## OpenAPI ````yaml POST /companies/research 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: /companies/research: post: tags: - Company Research summary: Research companies description: >- Research companies by search result IDs from `/search/companies` and/or direct company identifiers (`domain`, `companyName`). operationId: researchCompanies requestBody: required: true content: application/json: examples: requestPayload: summary: Research companies request payload value: searchResultIds: - cmp_sr_01J8YQ4FXZQ6N5G2T3A7BC9D1E - cmp_sr_01J8YQ5F95Y0M4R7J8N1P2Q3R4 companies: - domain: seamless.ai companyName: Seamless.AI - domain: openai.com searchResultIdsOnly: summary: Research companies from company search results only value: searchResultIds: - cmp_sr_01J8YQ4FXZQ6N5G2T3A7BC9D1E companiesOnly: summary: Research companies directly by domain/name only value: companies: - domain: seamless.ai companyName: Seamless.AI schema: type: object properties: searchResultIds: description: >- Company search result IDs returned from `/search/companies` that you want to enrich. type: array maxItems: 100 example: - cmp_sr_01J8YQ4FXZQ6N5G2T3A7BC9D1E items: type: string companies: description: | Companies to enrich directly without running search first. Each item must include at least one identifier: - `domain` - `companyName` type: array maxItems: 100 example: - domain: seamless.ai companyName: Seamless.AI items: type: object properties: domain: type: string description: Company website domain used to identify the company. example: seamless.ai companyName: type: string description: >- Company legal or common name used to identify the company. example: Seamless.AI skipDeduplicationCheck: type: boolean description: >- When true, research will not check for duplicate records that you already researched recently, and perform a research (which can result in credit usage) default: false responses: '202': description: The request IDs for research content: application/json: examples: accepted: summary: Accepted research request description: >- Response returned immediately after request is queued for async research. value: success: true requestIds: - 8T7LmzqW2Q6hA19 - Ka2nQ9L3pR4vD1F schema: type: object properties: success: type: boolean description: Indicates whether the request was accepted successfully. example: true requestIds: description: >- Request identifiers for each submitted company research job. type: array example: - 8T7LmzqW2Q6hA19 - Ka2nQ9L3pR4vD1F items: type: string '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. ````