# Company Enrichment API
> Get comprehensive company data including firmographics, locations, funding, and employee insights using an email, phone number, or LinkedIn company URL
**Base URL:** `https://api.nyne.ai`
**Endpoint:** `https://api.nyne.ai/company/enrichment`

---

## Overview
The Company Enrichment API retrieves detailed information about companies using their website domain, LinkedIn company URL, email address, or phone number. It provides comprehensive company data including size, locations, funding information, industry classifications, and more. The endpoint is asynchronous — queue a request and poll or receive a webhook when processing completes.
### What You Get
- **Company Profile:** Official name, website, description, and industry classification- **Size & Headcount:** Headcount range, estimated employee count, and growth indicators- **Locations:** Headquarters and office locations with city, region, and country- **Funding Details:** Last funding round, total disclosed funding, and investor information- **Industry & Specialties:** Primary industry, SIC codes, NAICS codes, and specialty tags- **Web & Social Presence:** Known domains, social media profiles, email addresses, and phone numbers
## 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 Enrichment:** 1 credit per successful enrichment (includes firmographics, locations, funding, and employee data)
> Credits are only charged when the enrichment returns data. If a company cannot be found, no credits are charged.
---

## POST /company/enrichmentSubmit a company identifier and receive a comprehensive company profile once processing completes.
### Parameters

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `email` | string | No | Company email address to enrich |
| `phone` | string | No | Company phone number to enrich |
| `social_media_url` | string | No | LinkedIn company profile URL |
| `domain` | string | No | Company website domain. Protocols and paths are stripped automatically. |
| `callback_url` | string | No | HTTPS endpoint that will receive the completed enrichment payload |

> **Required:** At least one of email, phone, social_media_url, or domain must be provided. Results are delivered asynchronously via polling or optional webhook callback.
### Request Examples

**With Advanced Features:**

```json
{
  "social_media_url": "https://www.linkedin.com/company/tesla-motors/",
  "callback_url": "https://example.com/webhooks/company-enrichment"
}
```

**Basic Request:**

```json
{
  "social_media_url": "https://www.linkedin.com/company/tesla-motors/"
}
```

### Code Examples

**cURL:**

```bash
curl -X POST https://api.nyne.ai/company/enrichment \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "X-API-Secret: YOUR_API_SECRET" \
  -H "Content-Type: application/json" \
  -d '{
    "social_media_url": "https://www.linkedin.com/company/tesla-motors/"
  }'
```

**Python:**

```python
import requests
import json

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

data = {
    "social_media_url": "https://www.linkedin.com/company/tesla-motors/"
}

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/enrichment";
const headers = {
    "X-API-Key": "YOUR_API_KEY",
    "X-API-Secret": "YOUR_API_SECRET",
    "Content-Type": "application/json"
};

const data = {
    social_media_url: "https://www.linkedin.com/company/tesla-motors/"
};

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/enrichment";
$headers = [
    "X-API-Key: YOUR_API_KEY",
    "X-API-Secret: YOUR_API_SECRET",
    "Content-Type: application/json"
];

$data = [
    "social_media_url" => "https://www.linkedin.com/company/tesla-motors/"
];

$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 | Enrichment completed successfully |
| 400 | Invalid request parameters |
| 401 | Invalid API credentials |
| 402 | Insufficient credits |
| 429 | Rate limit exceeded |

### Response Example

```json
{
  "success": true,
  "data": {
    "request_id": "coenrich_dfd84d2d_1700000123",
    "status": "completed",
    "company": {
      "company_name": "Tesla, Inc.",
      "website": "https://www.tesla.com",
      "linkedin_url": "https://www.linkedin.com/company/tesla-motors/",
      "industry": "Automotive",
      "headcount_range": "10,001+",
      "hq_location": "Austin, TX",
      "funding": {
        "last_round": "Post-IPO",
        "funding_total": "6.1B"
      }
    }
  },
  "timestamp": "2025-11-10T21:45:09Z"
}
```

---

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

### Parameters

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

### Request Example

```
GET /company/enrichment?request_id=coenrich_dfd84d2d_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": "coenrich_dfd84d2d_1700000123",
    "status": "completed",
    "company": {
      "company_name": "Tesla, Inc.",
      "website": "https://www.tesla.com",
      "description": "Tesla designs and manufactures electric vehicles, battery storage, and solar products.",
      "linkedin_url": "https://www.linkedin.com/company/tesla-motors/",
      "industry": "Automotive",
      "specialties": [
        "Electric Vehicles",
        "Energy Storage",
        "Solar"
      ],
      "size": {
        "headcount_range": "10,001+",
        "employees": 127000
      },
      "locations": [
        { "city": "Austin", "region": "Texas", "country": "United States" },
        { "city": "Fremont", "region": "California", "country": "United States" }
      ],
      "funding": {
        "last_round": "Post-IPO",
        "funding_total": "6.1B"
      }
    }
  },
  "timestamp": "2025-11-10T21:45:09Z"
}
```

---

## Response Format

All API responses follow a consistent JSON format. All fields in enrichment results are **optional** and only included when data is available:
- If a field has no data, it will be omitted from the response (not included as null or empty string)- Arrays are only included if they contain at least one item- Objects are only included if they contain at least one field- The locations array contains objects with city, region, and country fields- Funding fields (last_round, funding_total) are only included when funding data is available- Industry classification codes (sic_codes, naics_codes) are arrays of strings when present
---

## Error Codes

| HTTP Code | Error Code | Description |
|-----------|------------|-------------|
| 400 | `missing_parameters` | None of domain, email, phone, or social_media_url were provided |
| 400 | `invalid_callback_url` | Callback URL is not HTTPS |
| 401 | `invalid_credentials` | API key or secret is incorrect |
| 402 | `insufficient_credits` | Not enough credits available |
| 403 | `subscription_required` | Company enrichment product is not enabled on this account |
| 404 | `not_found` | Unable to find a company matching the provided identifiers |
| 429 | `rate_limit_exceeded` | Rate limit exceeded |
| 429 | `monthly_limit_exceeded` | Monthly usage limit exceeded |
| 500 | `internal_error` | Internal server error |

---

## 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
{
  "request_id": "coenrich_dfd84d2d_1700000123",
  "status": "completed",
  "success": true,
  "completed": true,
  "data": {
    "company": {
      "company_name": "Tesla, Inc.",
      "website": "https://www.tesla.com",
      "industry": "Automotive",
      "headcount_range": "10,001+",
      "funding": {
        "last_round": "Post-IPO",
        "funding_total": "6.1B"
      }
    }
  },
  "completed_on": "2025-11-10T21:45:09Z",
  "timestamp": "2025-11-10T21:45:09Z"
}
```

---

## Best Practices

Prioritize inputs in this order for best match rates:
1. **LinkedIn Company URL** (Best) — Provides the highest match rate and most complete company profiles. The LinkedIn URL serves as a reliable anchor for company identity resolution.2. **Company Domain** (Good) — Direct lookup by website domain. Provides comprehensive firmographic data, funding details, and employee insights.3. **Email Address** (Good) — Company domain is extracted from the email to match against known company records. Work emails from corporate domains perform best.4. **Phone Number** (Lowest) — Generally has the lowest match rate. Use only when LinkedIn URL, domain, or email is unavailable.
**Recommendation:** Whenever possible, use a LinkedIn company URL as your primary input for the most complete and accurate results. A company domain is also a strong alternative.
---

## Note for AI Agents
The Company Enrichment API is asynchronous. Provide a company domain, LinkedIn URL, email, or phone. AI agents and automated systems should poll using the GET endpoint with the returned request_id until status is completed, or register a callback_url to receive results automatically. Do not assume the response from the POST call contains the enriched data — it returns a request ID for tracking.
---

## Related APIs
- **Company Search API** — Find companies to enrich → `https://api.nyne.ai/documentation/company/search`
- **Company Funding API** — Get detailed funding data → `https://api.nyne.ai/documentation/company/funding`
- **Company Needs API** — Discover business challenges → `https://api.nyne.ai/documentation/company/needs`