Company Intent API - Ranked ICP Intent Leads

Overview

API Endpoint

POST https://api.nyne.ai/company/intent

Input: An interest company domain used to identify similar-product interest and an ICP company domain used for fit ranking.
Intent candidates: Returned people have demonstrated interest in products similar to the interest company.
Limits: max_results defaults to 25. Allowed values are 1–1000.
Delivery: Always asynchronous. Receive a request_id immediately, then poll or register a callback.
Output: A highest-to-lowest ranked results array with score, reason, person details, available profile URL, and sanitized intent-signal counts.

Authentication

Authenticate every request with your API key and secret:

Headers

X-API-Key: your_api_key_hereX-API-Secret: your_api_secret_here

Rate Limits

Company intent requests count against the following limits for your account:

Per Minute: 60 requests
Per Hour: 1000 requests
Monthly: Varies by plan

Credit Usage

Credits are charged based on the number of ranked people returned:

Standard lookup: 10 credits per person returned
Lite lookup: 5 credits per person returned when lite_lookup is enabled
Response format: Standard and lite lookups return the same response fields and nested result structure.

Per-Result Billing

If a standard request returns 12 ranked people, the request consumes 120 credits. If it returns no people, no per-result credits are charged.

POST /company/intent

Queue a company intent request.

POST /company/intent

Request Body

Field	Type	Required	Description
`interest_company_domain`	string	required	Domain for the company or product category used to find people with demonstrated interest in similar products.
`icp_company_domain`	string	required	Domain for the company used to rank candidate ICP fit.
`max_results`	integer	optional	Maximum ranked people to return. Allowed range is 1–1000. Defaults to 25.
`lite_lookup`	boolean	optional	Use a faster, lower-cost lookup path for broader demonstrated-interest signals. Defaults to `false`.
`callback_url`	string	optional	Public HTTP or HTTPS endpoint that receives the completed payload automatically. Localhost and private-network targets are rejected.

Example Request

{ "interest_company_domain": "gong.io", "icp_company_domain": "salesforce.com", "max_results": 25 }

cURL Example

Queue Company Intent Request

curl -X POST https://api.nyne.ai/company/intent \
  -H "X-API-Key: your_api_key_here" \
  -H "X-API-Secret: your_api_secret_here" \
  -H "Content-Type: application/json" \
  -d '{
    "interest_company_domain": "gong.io",
    "icp_company_domain": "salesforce.com",
    "max_results": 25
  }'

Immediate Response

{ "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, "lite_lookup": false }, "timestamp": "2026-04-20T21:15:03Z" }

GET /company/intent?request_id=...

Poll for completion and retrieve results.

GET /company/intent

Query Parameters

request_id (string, required) – the value returned by POST /company/intent.

cURL Example

Poll for Results

curl -X GET "https://api.nyne.ai/company/intent?request_id=65f6d9f92799d3c2a24123f4f13a7d7a3af6ac13f1d8d0695dce03b98a4e5220" \
  -H "X-API-Key: your_api_key_here" \
  -H "X-API-Secret: your_api_secret_here"

Queued or Processing Response

{ "success": true, "data": { "request_id": "65f6d9f92799d3c2a24123f4f13a7d7a3af6ac13f1d8d0695dce03b98a4e5220", "status": "processing", "created_on": "2026-04-20T21:15:03", "completed_on": null, "interest_company_domain": "gong.io", "icp_company_domain": "salesforce.com", "max_results": 25, "max_results_mode": "finite", "effective_output_cap": 25, "lite_lookup": false, "message": "Company intent request is being processed" }, "timestamp": "2026-04-20T21:15:09Z" }

Completed Response

{ "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, "lite_lookup": false, "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", "lite_lookup": false, "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" }

Failed Response

{ "success": true, "data": { "request_id": "65f6d9f92799d3c2a24123f4f13a7d7a3af6ac13f1d8d0695dce03b98a4e5220", "status": "failed", "created_on": "2026-04-20T21:15:03", "completed_on": "2026-04-20T21:16:10", "interest_company_domain": "gong.io", "icp_company_domain": "salesforce.com", "max_results": 25, "max_results_mode": "finite", "effective_output_cap": 25, "lite_lookup": false, "error": "Company intent request failed. Please try again later." }, "timestamp": "2026-04-20T21:16:10Z" }

Response Format

All responses use the standard Nyne API wrapper. Completed company intent payloads include these endpoint-specific fields:

request_id                          // Stable ID used for polling
status                              // pending, processing, completed, or failed
created_on                          // Request creation timestamp
completed_on                        // Completion timestamp, null until finished
interest_company_domain             // Normalized interest company domain
icp_company_domain                  // Normalized ICP company domain
max_results                         // Requested limit
max_results_mode                    // finite
effective_output_cap                // Actual output cap applied to the request
lite_lookup                         // true when the lower-cost lookup path was requested
results[]                           // Ranked people, highest score first
results[].score                     // ICP fit score from 0 to 100
results[].score_reason              // Short explanation for the score
results[].organizations[0]          // Current organization details when available
results[].social_profiles.linkedin  // Public profile URL when available
results[].latest_interest_date      // Most recent observed interest date when available
results[].intent_signals            // Sanitized intent signal counts
total_results                       // Number of people returned
credits_charged                     // Total credits deducted for returned people
metadata                            // Sanitized request metadata

Callbacks

If you provide a callback_url, the completed or failed payload is sent to your endpoint automatically.

Delivery

Callback delivery is best effort for this endpoint. Keep the returned request_id and use GET /company/intent as the source of truth if your receiver is unavailable.

Completed Callback Example

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"
  }
}

Failed Callback Example

POST https://example.com/webhook/company-intent
Content-Type: application/json

{
  "request_id": "65f6d9f92799d3c2a24123f4f13a7d7a3af6ac13f1d8d0695dce03b98a4e5220",
  "status": "failed",
  "error": "Company intent processing failed. Please try again later."
}

Error Codes

HTTP	Error Code	When It Happens
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`, `invalid_credentials`, `api_key_expired`	POST authentication failed.
401	`authentication_failed`	GET status authentication failed.
403	`ip_not_allowed`	The API key is locked to a different IP address.
403	`subscription_required`, `no_active_subscription`	The account cannot access this API.
403	`insufficient_credits`	The account does not have enough credits.
404	`request_not_found`	The request ID does not exist or belongs to another API key.
429	`rate_limit_exceeded`	Per-minute or per-hour request limits were exceeded.
429	`monthly_limit_exceeded`	The monthly usage limit was exceeded.
500	`internal_error`	The request could not be processed. Try again later.

Error Response Format

{ "success": false, "error": { "code": "invalid_limit", "message": "max_results must be between 1 and 1000" }, "timestamp": "2026-04-20T21:15:03Z" }

Best Practices

Use clean domains: Send only hostnames when you have them. Full URLs are normalized, but domains produce clearer request logs.
Start finite: Use max_results between 10 and 50 while tuning your ICP comparison, then increase it for batch jobs.
Prefer callbacks for larger jobs: Larger requests can take longer than simple lookups.
Rank by ICP fit: Choose the ICP company domain as the company whose ideal customers the returned people should resemble.