Nyne.ai API Login
Company APIs

Buyer Intent API

Find people who have demonstrated interest in products similar to an interest_company_domain, then rank them as ICP candidates for an icp_company_domain. Both domains are required. The request is queued asynchronously and returns a request_id; poll or supply a callback_url. Results come back highest-score-first with a relevance reason, person details, and intent-signal counts. Credits are charged per ranked person returned; set lite_lookup for the faster, lower-cost lookup path. Callback delivery is best effort for this endpoint - keep the returned request_id and use GET /company/intent for the final result.

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

Manual credentials take precedence over your account key.

Try it needs these required parameters:

Overview

The Company Intent API ranks companies by fit and demonstrated buying-intent signals so sales and growth teams can prioritize accounts with stronger timing.

Best for

  • Prioritizing target accounts
  • Finding ICP-fit companies
  • Ranking companies by intent signals

Returns

  • Ranked company candidates
  • Intent and fit context
  • Company identifiers for enrichment

Parameters

interest_company_domain string required
Domain for the company / product category used to find people with demonstrated interest in similar products. Max 255 chars.
icp_company_domain string required
Domain for the company used to rank candidate ICP fit. Max 255 chars.
max_results integer optional
Maximum ranked people to return. Range 1-1000, default 25.
lite_lookup boolean optional
Use the lower-cost lite lookup option for broader demonstrated-interest signals. Defaults to false. Returns the same response shape.
e.g. false
callback_url string optional
Public http(s) endpoint that receives the completed or failed payload. Localhost / private-network targets are rejected.

Polling for the result

This endpoint is asynchronous. A successful submit returns a request_id while the job runs in the background. Poll the same path with a GET request - same authentication headers - passing the request_id as a query parameter:

Loading your API credentials...

Each poll returns the job's current status; once it is completed the payload carries the result shown under Responses. Polling an unknown or expired request_id returns 404 request_not_found.

Status Meaning
queued · processing · pending The job is still running - keep polling.
completed The job finished; the payload carries the result and completed: true.
failed Terminal - the job could not complete; the error field explains why.

Poll every few seconds at first, backing off for long-running jobs. Polling is free - status checks never burn credits.

Prefer push delivery?
Supply the optional callback_url parameter and the completed payload is POSTed to your endpoint when the job finishes - no polling required. Delivery is retried up to 5 times with exponential backoff (1s, 5s, 15s, 1m, 5m) and a 30-second timeout per attempt; respond with a 2xx status to acknowledge receipt.

Credit usage

Credits are charged based on the matched configuration. The listed cost is the per-result unit price.

Feature Credits Notes
Standard lookup 10 Charged per ranked person returned
Lite lookup 5 lite_lookup: true - fewer credits per ranked person returned
No results 0 No ranked people never burns per-result credits
Heads up
Empty results do not burn credits.

Responses

202 Request queued - poll the status endpoint with the returned request_id
400 missing_parameters / invalid_domain / invalid_limit / invalid_lite_lookup / invalid_callback_url / invalid_json
401 missing_credentials / invalid_credentials / api_key_expired
402 insufficient_credits
403 ip_not_allowed, subscription_required, or no_active_subscription
404 request_not_found (on status poll)
429 rate_limit_exceeded / monthly_limit_exceeded
500 internal_error

A successful response wraps the payload in the { success, data, timestamp } envelope (also shown live in the panel on the right):

{
  "success": true,
  "data": {
    "request_id": "65f6d9f92799d3c2a24123f4f13a7d7a_1700000123_5520",
    "status": "completed",
    "completed": true,
    "result": {
      "results": [
        {
          "score": 92,
          "score_reason": "Senior revenue leader with strong intent signals.",
          "displayname": "Jane Doe",
          "location": "San Francisco, CA",
          "organizations": [
            {
              "name": "Acme",
              "title": "VP Sales",
              "is_current": true
            }
          ],
          "social_profiles": {
            "linkedin": {
              "url": "https://linkedin.com/in/janedoe"
            }
          },
          "latest_interest_date": "2026-01-09",
          "intent_signals": {
            "signal_count": 3
          }
        }
      ],
      "total_results": 1
    },
    "completed_on": "2026-01-15T10:35:00Z"
  },
  "timestamp": "2026-01-01T00:00:00"
}