# Company Employees API
> Retrieve public employee profiles associated with a company using a company name, domain, or company social media URL.
**Base URL:** `https://api.nyne.ai`
**Endpoint:** `https://api.nyne.ai/company/employees`

---

## Overview
The Company Employees API lets you retrieve public employee profiles associated with a company by supplying a company name, company domain, or company social media URL. The request is queued asynchronously, then returned as a structured array of people with names, headlines, locations, current organization data, and profile links.
### What You Get
- **Flexible Company Input:** Start from a company name, company domain, or company social media URL- **Flexible Limits:** Request between 1 and 1000 associated profiles per job- **Async Delivery:** Receive a request_id immediately, then poll or register a callback- **Structured People Output:** Results return as person-shaped JSON objects with profile links, headlines, and locations- **Per-Result Billing:** Credits are charged only for the number of profiles returned- **Cached Retrieval:** Raw and formatted results are cached for follow-up requests
## 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 Employees:** 3 credits per person returned
> Credits are charged only for the number of profiles actually returned.
---

## POST /company/employeesQueue a company employee lookup request using a company name, company domain, or company social media URL.
### Parameters

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `social_media_url` | string | No | Company social media URL. Query strings, fragments, and trailing cruft are removed automatically. |
| `company_name` | string | No | Company name. |
| `domain` | string | No | Company domain or website hostname. |
| `max_employees` | integer | No | Maximum number of profiles to return (1–1000). Defaults to 10. |
| `callback_url` | string | No | HTTP or HTTPS endpoint that receives the completed payload. |

> **Required:** Supply at least one of <code>social_media_url</code>, <code>company_name</code>, or <code>domain</code>.
### Request Examples

**Basic Request:**

```json
{
  "company_name": "Acme",
  "domain": "acme.com",
  "max_employees": 25
}
```

### Code Examples

**cURL:**

```bash
curl -X POST https://api.nyne.ai/company/employees \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "X-API-Secret: YOUR_API_SECRET" \
  -H "Content-Type: application/json" \
  -d '{
    "company_name": "Acme",
    "domain": "acme.com",
    "max_employees": 25
  }'
```

**Python:**

```python
import requests

url = "https://api.nyne.ai/company/employees"
headers = {
    "X-API-Key": "YOUR_API_KEY",
    "X-API-Secret": "YOUR_API_SECRET",
    "Content-Type": "application/json"
}
payload = {
    "company_name": "Acme",
    "domain": "acme.com",
    "max_employees": 25
}

response = requests.post(url, headers=headers, json=payload)
print(response.json())
```

**JavaScript:**

```javascript
const url = "https://api.nyne.ai/company/employees";
const headers = {
  "X-API-Key": "YOUR_API_KEY",
  "X-API-Secret": "YOUR_API_SECRET",
  "Content-Type": "application/json"
};
const payload = {
  company_name: "Acme",
  domain: "acme.com",
  max_employees: 25
};

const response = await fetch(url, {
  method: "POST",
  headers,
  body: JSON.stringify(payload)
});

console.log(await response.json());
```

**PHP:**

```php
<?php
$url = "https://api.nyne.ai/company/employees";
$headers = [
    "X-API-Key: YOUR_API_KEY",
    "X-API-Secret: YOUR_API_SECRET",
    "Content-Type: application/json"
];
$payload = json_encode([
    "company_name" => "Acme",
    "domain" => "acme.com",
    "max_employees" => 25
]);

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

$result = curl_exec($ch);
curl_close($ch);

echo $result;
```

### Response Codes

| Code | Description |
|------|-------------|
| 202 | 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": "94f1bf8a0d1a1f065a9b4e7fbc3df6aabbb6d828ce64fe780a5496f43b61fc73",
    "status": "queued",
    "message": "Company employees request queued. Poll this endpoint with GET request_id to retrieve results.",
    "company_name": "Acme",
    "domain": "acme.com",
    "max_employees": 25
  },
  "timestamp": "2026-04-20T21:15:03Z"
}
```

---

## GET /company/employees
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/employees?request_id=94f1bf8a0d1a1f065a9b4e7fbc3df6aabbb6d828ce64fe780a5496f43b61fc73
```

### 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": "94f1bf8a0d1a1f065a9b4e7fbc3df6aabbb6d828ce64fe780a5496f43b61fc73",
    "status": "completed",
    "company_name": "Acme",
    "domain": "acme.com",
    "max_employees": 25,
    "results": [
      {
        "profile_id": "profile_jane_doe",
        "displayname": "Jane Doe",
        "headline": "VP of Sales at Acme",
        "bio": "VP of Sales at Acme",
        "address": {
          "city": "San Francisco",
          "state": "California",
          "country": "United States"
        },
        "organizations": [
          {
            "name": "Acme",
            "is_current": true
          }
        ],
        "websites": [
          "https://janedoe.example"
        ]
      }
    ],
    "total_results": 1,
    "created_on": "2026-04-20T21:15:03",
    "completed_on": "2026-04-20T21:15:19"
  },
  "timestamp": "2026-04-20T21:15:19Z"
}
```

---

## 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 results array contains person-shaped objects- Minimal rows are preserved even when only a profile URL is available- The current organization is mapped into organizations[0] with is_current = true- The request payload echoes back whichever company identifiers were supplied along with the requested max_employees
---

## Error Codes

| HTTP Code | Error Code | Description |
|-----------|------------|-------------|
| 400 | `missing_parameters` | None of <code>social_media_url</code>, <code>company_name</code>, or <code>domain</code> was supplied |
| 400 | `invalid_url` | The supplied company social media URL could not be processed |
| 400 | `invalid_domain` | The supplied company domain could not be processed |
| 400 | `invalid_limit` | <code>max_employees</code> outside 1&ndash;1000 |
| 400 | `invalid_callback_url` | Callback URL is not a valid HTTP or HTTPS URL |
| 403 | `subscription_required` | This API is not enabled on the 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 https://example.com/webhook/company-employees
Content-Type: application/json

{
  "request_id": "94f1bf8a0d1a1f065a9b4e7fbc3df6aabbb6d828ce64fe780a5496f43b61fc73",
  "status": "completed",
  "completed": true,
  "completed_on": "2026-04-20T21:15:19Z",
  "timestamp": "2026-04-20T21:15:19Z",
  "success": true,
  "data": {
    "company_name": "Acme",
    "domain": "acme.com",
    "max_employees": 25,
    "page": 1,
    "limit": 25,
    "total_results": 1,
    "results": [
      {
        "displayname": "Jane Doe",
        "headline": "VP of Sales at Acme"
      }
    ]
  }
}
```

---

## Best Practices

Prioritize inputs in this order for best match rates:
1. **Use the strongest identifier you have** (Best) — A clean company domain or social media URL tends to be more specific than a name by itself.2. **Start with a smaller limit** (Good) — Use a smaller <code>max_employees</code> for interactive workflows, then increase it for batch jobs.3. **Use callbacks in production** (Good) — Register a <code>callback_url</code> instead of polling for larger or longer-running requests.4. **Chain selectively** (Good) — Use the returned profile list to decide which people should be enriched further instead of enriching everyone.
---

## Note for AI Agents
When integrating Company Employees into automated pipelines, register a callback_url and treat the result as a lightweight profile list. Use the returned people objects to decide whether to call Person Enrichment for any individual profile.
---

## Related APIs
- **Company Enrichment API** — Get firmographic company data → `https://api.nyne.ai/documentation/company/enrichment`
- **Company Search API** — Find target companies first → `https://api.nyne.ai/documentation/company/search`
- **Person Enrichment API** — Enrich selected people profiles → `https://api.nyne.ai/documentation/person/enrichment`