# Company Intent API > Find people who have demonstrated interest in similar products and rank them by ICP fit. **Base URL:** `https://api.nyne.ai` **Endpoint:** `https://api.nyne.ai/company/intent` --- ## Overview The Company Intent API finds people who have demonstrated interest in products similar to an interest company, then ranks them by likely ICP fit for an ICP company domain. It is designed for async sales-intelligence jobs where you want a scored list of people rather than raw activity records. ### What You Get - **Intent Discovery:** Finds people who have demonstrated interest in products similar to the interest company- **Candidate Ranking:** Ranks people by likely ICP fit for the ICP company domain- **Person Details:** Returns person details such as name, current organization, location, and available profile URL- **ICP Ranking:** Scores candidates by likely ICP fit for the ICP company domain- **Async Delivery:** Receives a request_id immediately, then supports polling or callback delivery- **Per-Result Billing:** Charges credits only for ranked people returned ## 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 Intent:** 10 credits per person returned - **Company Intent Lite:** 5 credits per person returned when lite_lookup is enabled > Credits are charged only for ranked people returned. Example: if a standard request returns 12 people, the request consumes 120 credits. Lite lookup is billed at 5 credits per person returned. If no people are returned, no per-result credits are charged. --- ## POST /company/intentQueue a company intent lookup using an interest company domain for similar-product intent and an ICP company domain for fit ranking. ### Parameters | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `interest_company_domain` | string | Yes | Domain for the company or product category used to find people with demonstrated interest in similar products. | | `icp_company_domain` | string | Yes | Domain for the company used to rank candidate ICP fit. | | `max_results` | integer | No | Maximum ranked people to return. Allowed range is 1–1000. Defaults to 25. (default: `25`) | | `lite_lookup` | boolean | No | Use a faster, lower-cost lookup path for broader demonstrated-interest signals. Defaults to false. (default: `false`) | | `callback_url` | string | No | Public HTTP or HTTPS endpoint that receives the completed or failed payload. Localhost and private-network targets are rejected. | > **Required:** Supply both interest_company_domain and icp_company_domain. ### Request Examples **Lite Enrichment:** ```json { "interest_company_domain": "gong.io", "icp_company_domain": "salesforce.com", "max_results": 25, "lite_lookup": true } ``` **Basic Request:** ```json { "interest_company_domain": "gong.io", "icp_company_domain": "salesforce.com", "max_results": 25 } ``` ### Code Examples **cURL:** ```bash curl -X POST https://api.nyne.ai/company/intent \ -H "X-API-Key: YOUR_API_KEY" \ -H "X-API-Secret: YOUR_API_SECRET" \ -H "Content-Type: application/json" \ -d '{ "interest_company_domain": "gong.io", "icp_company_domain": "salesforce.com", "max_results": 25 }' ``` **Python:** ```python import requests url = "https://api.nyne.ai/company/intent" headers = { "X-API-Key": "YOUR_API_KEY", "X-API-Secret": "YOUR_API_SECRET", "Content-Type": "application/json" } payload = { "interest_company_domain": "gong.io", "icp_company_domain": "salesforce.com", "max_results": 25 } response = requests.post(url, headers=headers, json=payload) print(response.json()) ``` **JavaScript:** ```javascript const url = "https://api.nyne.ai/company/intent"; const headers = { "X-API-Key": "YOUR_API_KEY", "X-API-Secret": "YOUR_API_SECRET", "Content-Type": "application/json" }; const payload = { interest_company_domain: "gong.io", icp_company_domain: "salesforce.com", max_results: 25 }; const response = await fetch(url, { method: "POST", headers, body: JSON.stringify(payload) }); console.log(await response.json()); ``` **PHP:** ```php "gong.io", "icp_company_domain" => "salesforce.com", "max_results" => 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 | Missing or invalid request parameters | | 401 | Invalid, missing, or expired API credentials | | 403 | IP, subscription, or credit access denied | | 429 | Rate limit or monthly limit exceeded | | 500 | The request could not be queued | ### Response Example ```json { "success": true, "data": { "request_id": "65f6d9f92799d3c2a24123f4f13a7d7a3af6ac13f1d8d0695dce03b98a4e5220", "status": "queued", "message": "Company intent request queued. Poll this endpoint with GET request_id to retrieve results.", "interest_company_domain": "gong.io", "icp_company_domain": "salesforce.com", "max_results": 25, "max_results_mode": "finite", "effective_output_cap": 25 }, "timestamp": "2026-04-20T21:15:03Z" } ``` --- ## GET /company/intent 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/intent?request_id=65f6d9f92799d3c2a24123f4f13a7d7a3af6ac13f1d8d0695dce03b98a4e5220 ``` ### Response Codes | Code | Description | |------|-------------| | 200 | Status retrieved successfully. Payload status can be pending, processing, completed, or failed. | | 400 | request_id is missing | | 401 | Authentication failed | | 404 | Request ID not found or not owned by this API key | | 500 | The request status could not be retrieved | ### Response Example ```json { "success": true, "data": { "request_id": "65f6d9f92799d3c2a24123f4f13a7d7a3af6ac13f1d8d0695dce03b98a4e5220", "status": "completed", "created_on": "2026-04-20T21:15:03", "completed_on": "2026-04-20T21:18:41", "interest_company_domain": "gong.io", "icp_company_domain": "salesforce.com", "max_results": 25, "max_results_mode": "finite", "effective_output_cap": 25, "results": [ { "score": 92, "score_reason": "Senior revenue leader at a B2B software company with strong demonstrated interest signals.", "displayname": "Jane Doe", "organizations": [ { "name": "Example Software", "title": "VP Sales", "is_current": true } ], "social_profiles": { "linkedin": { "url": "https://www.linkedin.com/in/janedoe" } }, "location": "San Francisco, California, United States", "latest_interest_date": "2026-04-19", "intent_signals": { "signal_count": 3, "latest_interest_date": "2026-04-19" } } ], "total_results": 1, "credits_charged": 10, "metadata": { "interest_company_domain": "gong.io", "icp_company_domain": "salesforce.com", "max_results_mode": "finite", "requested_max_results": 25, "effective_output_cap": 25, "returned_results": 1, "processed_at": "2026-04-20T21:18:41Z" } }, "timestamp": "2026-04-20T21:18:41Z" } ``` --- ## 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 immediate POST response has status queued and includes request_id- GET status responses return pending, processing, completed, or failed- Completed responses include results, total_results, credits_charged, and metadata- Failed responses still use HTTP 200 when the request record exists; inspect data.status and data.error- Validation, authentication, access, rate-limit, and service errors use the standard success = false wrapper with error.code and error.message- Each result is a person object with score, score_reason, organizations, social_profiles.linkedin, and sanitized intent_signals- Responses include lite_lookup so clients can distinguish standard and lite requests- Standard and lite requests return the same response fields and nested result structure --- ## Error Codes | HTTP Code | Error Code | Description | |-----------|------------|-------------| | 400 | `missing_parameters` | interest_company_domain or icp_company_domain is missing | | 400 | `invalid_domain` | A supplied company domain could not be normalized to a valid domain | | 400 | `invalid_limit` | max_results is not 1–1000 | | 400 | `invalid_lite_lookup` | lite_lookup is not a boolean value | | 400 | `invalid_callback_url` | Callback URL is not a valid public HTTP or HTTPS URL | | 400 | `invalid_json` | The request body could not be parsed as JSON | | 400 | `missing_request_id` | GET status request omitted request_id | | 401 | `missing_credentials` | POST request did not include API credentials | | 401 | `invalid_credentials` | POST request credentials are invalid | | 401 | `api_key_expired` | The API key has expired | | 401 | `authentication_failed` | GET status authentication failed | | 403 | `ip_not_allowed` | The API key is locked to a different IP address | | 403 | `subscription_required` | This API is not enabled on the account | | 403 | `no_active_subscription` | No active subscription is available for the account | | 403 | `insufficient_credits` | The account does not have enough credits | | 404 | `request_not_found` | The request ID does not exist or does not belong to the authenticated API key | | 429 | `rate_limit_exceeded` | Per-minute or per-hour usage limits were exceeded | | 429 | `monthly_limit_exceeded` | Monthly usage limit exceeded | | 500 | `internal_error` | The request could not be processed. Try again later. | --- ## Callbacks When you provide a `callback_url`, the API sends results to your endpoint via HTTP POST. ### Delivery- The API sends one HTTP POST to your callback URL when the request completes or fails- The callback body is JSON with request_id and status- Your endpoint should return HTTP 2xx for successCallback delivery is best effort for this endpoint. Continue to treat GET /company/intent with the returned request_id as the source of truth if your receiver is unavailable. ### Callback Payload Example ```json POST https://example.com/webhook/company-intent Content-Type: application/json { "request_id": "65f6d9f92799d3c2a24123f4f13a7d7a3af6ac13f1d8d0695dce03b98a4e5220", "status": "completed", "total_results": 1, "credits_charged": 10, "results": [ { "score": 92, "displayname": "Jane Doe", "social_profiles": { "linkedin": { "url": "https://www.linkedin.com/in/janedoe" } } } ], "metadata": { "returned_results": 1, "processed_at": "2026-04-20T21:18:41Z" } } ``` --- ## Best Practices Prioritize inputs in this order for best match rates: 1. **Use clean domains** (Best) — Send hostnames such as gong.io and salesforce.com when possible.2. **Start finite** (Good) — Use max_results between 10 and 50 while tuning the ICP comparison.3. **Use callbacks for larger jobs** (Good) — Larger requests can take longer than simple lookups, so callbacks are better than frequent polling for production jobs.4. **Choose the ICP domain carefully** (Best) — The ICP company domain defines the fit context used by the ranking model. --- ## Note for AI Agents Company Intent is an async orchestration endpoint. Queue with POST, store the returned request_id, then poll GET /company/intent or wait for the callback. Treat status as authoritative: pending and processing are not terminal, completed includes results and credits_charged, and failed includes error.