# CheckSeller API
> Verify whether a company sells or provides a specific product or service. Responses are generated asynchronously with structured output.
**Base URL:** `https://api.nyne.ai`
**Endpoint:** `https://api.nyne.ai/company/checkseller`

---

## Overview
The CheckSeller API verifies whether a company sells or provides a specific product or service. Submit a company name and product/service description, receive a request_id, then poll for completion or register a callback URL. The response includes a boolean verdict, a confidence score, and a brief evidence summary.
### What You Get
- **Seller Verdict:** Yes/no/unknown answer on whether the company sells the specified product or service- **Confidence Scoring:** Low, medium, or high confidence rating for the verdict- **Evidence Summary:** Human-readable explanation of how the verdict was determined- **Async Delivery:** Queue a check, then poll or receive a callback when the result is ready
## 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

- **CheckSeller Verification:** 2 credits per completed verification (verdict produced)
> Credits are charged when a verdict (yes/no/unknown) is produced. If the request fails or times out, no credits are charged.
---

## POST /company/checksellerQueue a seller check for the specified company/product pair.
### Parameters

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `company_name` | string | Yes | Legal or commonly used company name. |
| `product_service` | string | Yes | Product or service to test (e.g. "SOC 2 automation platform"). |
| `callback_url` | string | No | HTTPS URL to receive the completed payload automatically. |

> **Required:** Both company_name and product_service are required.
### Request Examples

**Basic Request:**

```json
{
  "company_name": "Acme Cloud",
  "product_service": "SOC 2 compliance automation",
  "callback_url": "https://example.com/webhooks/checkseller"
}
```

### Code Examples

**cURL:**

```bash
curl -X POST https://api.nyne.ai/company/checkseller \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "X-API-Secret: YOUR_API_SECRET" \
  -H "Content-Type: application/json" \
  -d '{
    "company_name": "Acme Cloud",
    "product_service": "SOC 2 compliance automation"
  }'
```

**Python:**

```python
import requests
import json

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

data = {
    "company_name": "Acme Cloud",
    "product_service": "SOC 2 compliance automation"
}

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

const data = {
    company_name: "Acme Cloud",
    product_service: "SOC 2 compliance automation"
};

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

$data = [
    "company_name" => "Acme Cloud",
    "product_service" => "SOC 2 compliance automation"
];

$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 | 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": "cocs_64f2d8e4_1700000123",
    "status": "queued",
    "message": "Company seller check queued. Use GET /company/checkseller?request_id=... to check status.",
    "callback_url": "https://example.com/webhooks/checkseller"
  },
  "timestamp": "2025-11-10T22:20:03Z"
}
```

---

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

### Parameters

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `request_id` | string | Yes | Identifier returned by the POST call |

### Request Example

```
GET /company/checkseller?request_id=cocs_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": "cocs_64f2d8e4_1700000123",
    "status": "completed",
    "result": {
      "company": "Acme Cloud",
      "product_service": "SOC 2 compliance automation",
      "sells": true,
      "confidence": "medium",
      "evidence": "Acme Cloud lists SOC 2 automation on its compliance solutions page."
    },
    "created_on": "2025-11-10T22:20:03Z",
    "completed_on": "2025-11-10T22:20:17Z"
  },
  "timestamp": "2025-11-10T22:20:17Z"
}
```

---

## 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 sells field is a boolean (true or false) when a verdict can be determined, or null when unknown- The confidence field is one of "high", "medium", or "low"- The evidence field contains a brief human-readable explanation of the verdict- If the request is still processing, the result object will not be present
---

## Error Codes

| HTTP Code | Error Code | Description |
|-----------|------------|-------------|
| 400 | `missing_parameters` | company_name or product_service omitted |
| 400 | `invalid_callback_url` | Callback URL must be HTTPS |
| 403 | `subscription_required` | Account lacks enrichment access |
| 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/webhooks/checkseller
Content-Type: application/json

{
  "request_id": "cocs_64f2d8e4_1700000123",
  "status": "completed",
  "result": {
    "company": "Acme Cloud",
    "product_service": "SOC 2 compliance automation",
    "sells": true,
    "confidence": "medium",
    "evidence": "Acme Cloud lists SOC 2 automation on its compliance solutions page."
  },
  "created_at": "2025-11-10T22:20:03Z",
  "completed_at": "2025-11-10T22:20:17Z"
}
```

---

## Best Practices

Prioritize inputs in this order for best match rates:
1. **Specific Products** (Best) — Be as specific as possible with the product_service field. "SOC 2 compliance automation" will yield more accurate results than "security".2. **Official Names** (Good) — Use the company's legal or commonly known name. Avoid abbreviations or nicknames that might be ambiguous.3. **Broad Categories** (Lowest) — Overly broad terms like "software" or "consulting" will produce low-confidence results. Narrow down to a specific offering.
---

## Note for AI Agents
The CheckSeller API is well-suited for automated workflows. AI agents can use the sells boolean and confidence field to make routing decisions. For high-stakes decisions, consider only acting on "high" confidence verdicts and flagging "medium" or "low" for human review.
---

## Related APIs
- **Feature Checker API** — Detect technology stack → `https://api.nyne.ai/documentation/company/checkfeature`
- **Company Enrichment API** — Full company profile → `https://api.nyne.ai/documentation/company/enrichment`
- **Company Search API** — Find companies by criteria → `https://api.nyne.ai/documentation/company/search`
- **Company Needs API** — Business pain points from filings → `https://api.nyne.ai/documentation/company/needs`