# Company Search API
> Discover relevant companies using location, industry, and keyword filters. Results are generated asynchronously with structured JSON output.
**Base URL:** `https://api.nyne.ai`
**Endpoint:** `https://api.nyne.ai/company/search`

---

## Overview
The Company Search API lets you discover companies matching specific industry, keyword, and location criteria. Submit a search request asynchronously, receive a request_id, then poll or register a callback to retrieve structured results. Each result includes the company name and website URL, ready to feed into the Company Enrichment API for full profiles.
### What You Get
- **Industry Filtering:** Search by industry focus such as SaaS, Healthcare, or FinTech- **Keyword Validation:** Optionally verify that a keyword appears on each company's website- **Location Targeting:** Filter results by city, region, or country- **Flexible Result Limits:** Control how many companies are returned (1–50)- **Async Delivery:** Receive a request_id immediately, then poll or use a callback- **Structured Output:** Results returned as clean JSON with company name and URL
## Authentication

All requests require header authentication:

```
X-API-Key: YOUR_API_KEY
X-API-Secret: YOUR_API_SECRET
```

## Rate Limits

| Limit | Value |
|-------|-------|
| Per Minute | 60 requests |
| Per Hour | 1000 requests |
| Monthly | Varies by plan |

### Response Headers

Responses from endpoints that perform rate-limit checks include both legacy and standard rate-limit headers:

| Header | Description |
|--------|-------------|
| `X-RateLimit-Limit` | Active per-minute or per-hour limit |
| `X-RateLimit-Remaining` | Remaining requests in the active window |
| `X-RateLimit-Reset` | Unix timestamp when the active window resets |
| `RateLimit-Limit` | Active per-minute or per-hour limit |
| `RateLimit-Remaining` | Remaining requests in the active window |
| `RateLimit-Reset` | Seconds until the active window resets |
| `Retry-After` | Seconds to wait before retrying; present on HTTP `429` rate-limit responses |

Monthly quota responses include quota-specific headers when available:

| Header | Description |
|--------|-------------|
| `X-Quota-Limit` | Monthly request or credit limit |
| `X-Quota-Used` | Amount used in the current billing cycle |
| `X-Quota-Remaining` | Amount remaining in the current billing cycle |
| `X-Quota-Reset` | Unix timestamp when the current billing cycle resets |

## Credit Usage

- **Company Search:** 5 credits per completed search request
> Credits are charged upon successful completion. The cost applies per search request, regardless of the number of companies returned.
---

## POST /company/searchQueue a company search request using industry, keyword, and location filters.
### Parameters

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `industry` | string | No | Industry focus (e.g. "Healthcare SaaS"). Required if website_keyword is not supplied. |
| `website_keyword` | string | No | Keyword that should appear on company sites (e.g. "SOC 2"). Required if industry is omitted. |
| `location` | string | No | Geographic filter (city, region, or country). |
| `max_results` | integer | No | Maximum results to return (1–50). Defaults to 25. |
| `validate_keyword` | boolean | No | Fetch each website and retain only companies whose HTML includes website_keyword. |
| `callback_url` | string | No | HTTPS endpoint that receives the completed payload. |

> **Required:** At least one of <code>industry</code> or <code>website_keyword</code> must be provided.
### Request Examples

**Basic Request:**

```json
{
  "industry": "SaaS",
  "website_keyword": "SOC 2",
  "location": "San Francisco Bay Area",
  "max_results": 20,
  "validate_keyword": true
}
```

### Code Examples

**cURL:**

```bash
curl -X POST https://api.nyne.ai/company/search \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "X-API-Secret: YOUR_API_SECRET" \
  -H "Content-Type: application/json" \
  -d '{
    "industry": "SaaS",
    "website_keyword": "SOC 2",
    "location": "San Francisco",
    "max_results": 5
  }'
```

**Python:**

```python
import requests
import json

url = "https://api.nyne.ai/company/search"
headers = {
    "X-API-Key": "YOUR_API_KEY",
    "X-API-Secret": "YOUR_API_SECRET",
    "Content-Type": "application/json"
}

data = {
    "industry": "SaaS",
    "website_keyword": "SOC 2",
    "location": "San Francisco",
    "max_results": 5
}

response = requests.post(url, headers=headers, json=data)
result = response.json()
print(json.dumps(result, indent=2))
```

**JavaScript:**

```javascript
const url = "https://api.nyne.ai/company/search";
const headers = {
    "X-API-Key": "YOUR_API_KEY",
    "X-API-Secret": "YOUR_API_SECRET",
    "Content-Type": "application/json"
};

const data = {
    industry: "SaaS",
    website_keyword: "SOC 2",
    location: "San Francisco",
    max_results: 5
};

fetch(url, {
    method: "POST",
    headers: headers,
    body: JSON.stringify(data)
})
.then(response => response.json())
.then(result => console.log(result))
.catch(error => console.error("Error:", error));
```

**PHP:**

```php
<?php
$url = "https://api.nyne.ai/company/search";
$headers = [
    "X-API-Key: YOUR_API_KEY",
    "X-API-Secret: YOUR_API_SECRET",
    "Content-Type: application/json"
];

$data = [
    "industry" => "SaaS",
    "website_keyword" => "SOC 2",
    "location" => "San Francisco",
    "max_results" => 5
];

$ch = curl_init();
curl_setopt($ch, CURLOPT_URL, $url);
curl_setopt($ch, CURLOPT_POST, true);
curl_setopt($ch, CURLOPT_POSTFIELDS, json_encode($data));
curl_setopt($ch, CURLOPT_HTTPHEADER, $headers);
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);

$response = curl_exec($ch);
$result = json_decode($response, true);
curl_close($ch);

echo json_encode($result, JSON_PRETTY_PRINT);
?>
```

### Response Codes

| Code | Description |
|------|-------------|
| 200 | Search request queued successfully |
| 400 | Invalid request parameters |
| 401 | Invalid API credentials |
| 402 | Insufficient credits |
| 429 | Rate limit exceeded |

### Response Example

```json
{
  "success": true,
  "data": {
    "request_id": "cosearch_64f2d8e4_1700000123",
    "status": "queued",
    "message": "Company search request queued. Poll this endpoint with GET request_id to retrieve results.",
    "max_results": 20
  },
  "timestamp": "2025-11-10T22:15:03Z"
}
```

---

## GET /company/search
Check the status of a request.

### Parameters

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `request_id` | string | Yes | The request ID returned from the POST call |

### Request Example

```
GET /company/search?request_id=cosearch_64f2d8e4_1700000123
```

### Response Codes

| Code | Description |
|------|-------------|
| 200 | Status retrieved successfully |
| 400 | Invalid request parameters |
| 401 | Invalid API credentials |
| 404 | Request ID not found |

### Response Example

```json
{
  "success": true,
  "data": {
    "request_id": "cosearch_64f2d8e4_1700000123",
    "status": "completed",
    "companies": [
      { "name": "SecureOps Cloud", "url": "https://secureopscloud.com" },
      { "name": "CompliantStack", "url": "https://compliantstack.io" }
    ],
    "results": [
      { "name": "SecureOps Cloud", "url": "https://secureopscloud.com" },
      { "name": "CompliantStack", "url": "https://compliantstack.io" }
    ],
    "total_results": 2,
    "created_on": "2025-11-10T22:15:03Z",
    "completed_on": "2025-11-10T22:15:18Z"
  }
}
```

---

## Response Format

All API responses follow a consistent JSON format. All fields in enrichment results are **optional** and only included when data is available:
- The companies and results arrays contain the same data for backward compatibility- Each company object includes name and url fields- The total_results field reflects the actual number of companies returned, which may be less than max_results- If no companies match the criteria, results will be an empty array and total_results will be 0
---

## Error Codes

| HTTP Code | Error Code | Description |
|-----------|------------|-------------|
| 400 | `missing_parameters` | Both <code>industry</code> and <code>website_keyword</code> were omitted |
| 400 | `invalid_limit` | <code>max_results</code> outside 1&ndash;50 |
| 400 | `invalid_callback_url` | Callback URL is not HTTPS |
| 403 | `subscription_required` | Search product is not enabled on this account |
| 402 | `insufficient_credits` | Not enough credits available |
| 429 | `rate_limit_exceeded` | Usage limits exceeded |
| 429 | `monthly_limit_exceeded` | Monthly usage limit exceeded |

---

## Callbacks

When you provide a `callback_url`, the API sends results to your endpoint via HTTP POST.

### Retry Policy- Maximum 5 retry attempts- Exponential backoff: 1s, 5s, 15s, 1m, 5m- 30-second timeout per request- Your endpoint should return HTTP 2xx for success
Your callback endpoint should respond with HTTP 200-299. Any other code triggers a retry.

### Callback Payload Example

```json
POST &lt;callback_url&gt;
Content-Type: application/json

{
  "request_id": "cosearch_64f2d8e4_1700000123",
  "status": "completed",
  "success": true,
  "data": {
    "success": true,
    "results": [
      { "name": "SecureOps Cloud", "url": "https://secureopscloud.com" }
    ],
    "total_results": 1,
    "page": 1,
    "limit": 50,
    "enrichments_count": 1,
    "has_more_results": false
  },
  "completed_on": "2025-11-10T22:15:18Z",
  "timestamp": "2025-11-10T22:15:18Z"
}
```

---

## Best Practices

Prioritize inputs in this order for best match rates:
1. **Combine Filters** (Best) — Provide both <code>industry</code> and <code>website_keyword</code> together for the most targeted results. Adding a <code>location</code> further narrows the set.2. **Validate Keywords** (Good) — Set <code>validate_keyword</code> to <code>true</code> when precision matters. The API will fetch each site and confirm the keyword appears, eliminating false positives.3. **Use Callbacks** (Good) — For production workflows, register a <code>callback_url</code> instead of polling. This reduces unnecessary GET requests and delivers results as soon as they are ready.
---

## Note for AI Agents
When integrating Company Search into automated pipelines, always register a callback_url rather than polling, as search times vary depending on max_results and validate_keyword settings. Chain results into the Company Enrichment API to get full company profiles for each discovered company.
---

## Related APIs
- **Company Enrichment API** — Enrich companies you find → `https://api.nyne.ai/documentation/company/enrichment`
- **CheckSeller API** — Verify what companies sell → `https://api.nyne.ai/documentation/company/checkseller`
- **Company Needs API** — Surface business pain points → `https://api.nyne.ai/documentation/company/needs`