Nyne.ai API Login
Company APIs

Company Discovery API

Find companies from the open web using a natural-language query. The API evaluates each candidate against your requirements with evidence-based matching, extracts the extract fields you request, and ranks the matches best first. Every evaluation is backed by source citations with confidence levels (high/medium/low) and excerpt quotes; fields with no data are omitted. Jobs progress through pending → searching → completed (or failed) and typically take 1-3 minutes; poll about every 5 seconds or supply a callback_url.

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

Manual credentials take precedence over your account key.

Try it needs this required parameter:

Overview

The Company Discovery API finds companies from natural-language criteria and match conditions, supporting research-backed company list building beyond basic firmographic filters.

Best for

  • Open-web company discovery
  • Finding companies by nuanced requirements
  • Building research-backed account lists

Returns

  • Discovered companies
  • Match evidence and context
  • Company identifiers for enrichment

Parameters

query string required
Natural-language query describing the companies to find. Max 2000 characters.
requirements array optional
Match conditions, each with name and description (max 20). Each is evaluated independently per company with evidence.
0 / 20
extract array optional
Enrichment fields to extract per matched company, each with name and description (max 10).
0 / 10
limit integer optional
Maximum results to return. Range 5-100, default 10.
quality string optional
Quality tier - basic (fastest) · standard (default) · premium (most thorough).
exclude array optional
Entities to exclude from results, each with name and url (max 100).
0 / 100
metadata object optional
Pass-through metadata returned with the results. Values must be string, number, or boolean.
number and true/false values are sent as numbers and booleans
callback_url string optional
HTTPS URL that receives a webhook notification when processing completes.

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
Discovery Request 10 Fixed per request, regardless of the number of results returned
Heads up
Empty results do not burn credits.

Responses

202 Discovery request accepted and queued for processing
400 INVALID_PARAMETERS / MISSING_PARAMETER (e.g. query)
401 AUTHENTICATION_FAILED - invalid or missing API credentials
402 INSUFFICIENT_CREDITS - requires 10 credits per request
403 NO_ACTIVE_SUBSCRIPTION / PRODUCT_NOT_AVAILABLE / ACCESS_DENIED
404 NOT_FOUND - unknown request_id (on status poll)
429 RATE_LIMIT_EXCEEDED
500 QUEUE_ERROR - the request could not be queued

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": "64f2d8e4dc1f065a9b4e7fbc3df6aabb_1700000123_9910",
    "status": "completed",
    "completed": true,
    "result": {
      "entity_type": "companies",
      "query": "AI startups in healthcare that have raised Series A funding",
      "results_count": 1,
      "results": [
        {
          "name": "HealthAI Labs",
          "url": "healthailabs.com",
          "description": "AI-powered diagnostics platform for early disease detection",
          "match_status": "matched",
          "evaluations": {
            "series_a_funded": {
              "value": "yes",
              "matched": true
            }
          },
          "extractions": {
            "ceo_name": "Maria Chen"
          },
          "sources": [
            {
              "field": "series_a_funded",
              "reasoning": "Announced a $14M Series A led by a major healthcare fund",
              "confidence": "high",
              "citations": [
                {
                  "title": "HealthAI Labs raises Series A",
                  "url": "https://example.com/news/healthai-series-a",
                  "excerpts": [
                    "HealthAI Labs today announced a $14M Series A round…"
                  ]
                }
              ]
            }
          ]
        }
      ],
      "metrics": {
        "candidates_evaluated": 40,
        "candidates_matched": 10
      }
    },
    "completed_on": "2026-01-15T10:35:00Z"
  },
  "timestamp": "2026-01-01T00:00:00"
}