# Nyne.ai API Documentation - full corpus

> Every page from https://api.nyne.ai/llms.txt concatenated into one file. Each page starts with a `Source:` line giving its canonical Markdown URL; pages are separated by `---` rules.

---

Source: https://api.nyne.ai/documentation.md

# Nyne.ai API Reference

> Programmatic access to person & company enrichment and search. Every endpoint is documented with parameters, responses, credit costs, and code samples in cURL, Python, Node, and PHP.

This is the Markdown version of https://api.nyne.ai/documentation, geared toward agents and developer tooling. Every page below is also available as Markdown by appending `.md` to its URL. Flat index: https://api.nyne.ai/llms.txt

## Get started

- [Quick Start](https://api.nyne.ai/documentation/quickstart.md) - zero to an enriched profile in three steps.
- [Your First Request](https://api.nyne.ai/documentation/first-request.md) - the one pattern every data endpoint shares.
- [Authentication](https://api.nyne.ai/documentation/authentication.md) - API keys, headers, rate limits.
- [Async requests, polling & webhooks](https://api.nyne.ai/documentation/async.md) - submit, 202, poll, or callback webhook.
- [Constructing effective requests](https://api.nyne.ai/documentation/effective-requests.md) - identifiers, fields, and search filters.
- [Choosing request depth](https://api.nyne.ai/documentation/request-depth.md) - lookup_mode and search type tradeoffs.
- [Interpreting responses](https://api.nyne.ai/documentation/responses.md) - the envelope, confidence, and data provenance.
- [Credits, billing & usage](https://api.nyne.ai/documentation/credits.md) - fixed vs dynamic pricing, quotas, and tracking.
- [Rate limits & error handling](https://api.nyne.ai/documentation/rate-limits.md) - throttling, headers, and backoff.
- [Evaluating the APIs](https://api.nyne.ai/documentation/evaluating.md) - benchmark accuracy, latency, and cost fairly.

## Person APIs

Resolve anyone from any identifier - then enrich, monitor, and analyze them. Search, verified contact data, social intelligence, and AI research over the same person graph. Overview: https://api.nyne.ai/documentation/person.md

- **[Person Search](https://api.nyne.ai/documentation/person/search.md)** - `POST /person/search` - Find people by natural-language query with structured filters.
- **[Person Enrichment](https://api.nyne.ai/documentation/person/enrichment.md)** - `POST /person/enrichment` - Resolve a full person profile from one or more identifiers.
- **[Deep Research](https://api.nyne.ai/documentation/person/deep-research.md)** - `POST /person/deep-research` - Run an in-depth autonomous research pass on a person.
- **[OSINT Deep Search](https://api.nyne.ai/documentation/person/osint.md)** - `POST /person/osint` - Run an agentic OSINT investigation on a person. Disabled by default - access on request.
- **[Personal Interests](https://api.nyne.ai/documentation/person/interests.md)** - `POST /person/interests` - Infer a person’s interests and affinities.
- **[Article Search](https://api.nyne.ai/documentation/person/articlesearch.md)** - `POST /person/articlesearch` - Find articles and press mentions for a person.
- **[Social Newsfeed](https://api.nyne.ai/documentation/person/newsfeed.md)** - `POST /person/newsfeed` - Pull recent social posts from a person’s resolved profiles.
- **[Social Interactions](https://api.nyne.ai/documentation/person/interactions.md)** - `POST /person/interactions` - Surface a person’s social interactions and engagement.
- **[Competitor Engagements](https://api.nyne.ai/documentation/person/competitor-engagements.md)** - `POST /person/competitor-engagements` - Detect a person’s engagement with competitor content.
- **[Person Events](https://api.nyne.ai/documentation/person/events.md)** - `POST /person/events` - Retrieve notable life/career events for a person.
- **[Ask](https://api.nyne.ai/documentation/person/ask.md)** - `POST /person/ask` - Ask a natural-language question about a person.
- **[Leads](https://api.nyne.ai/documentation/person/leads.md)** - `POST /person/leads` - Generate qualified lead candidates from a natural-language description.
- **[Discover](https://api.nyne.ai/documentation/person/discover.md)** - `POST /person/discover` - Discover matching people from keywords and location.
- **[Discovery](https://api.nyne.ai/documentation/person/discovery.md)** - `POST /person/discovery` - Discover people from the open web with natural-language queries and match conditions.
- **[Simulation](https://api.nyne.ai/documentation/person/simulation.md)** - `POST /person/simulation` - Predict how a person would respond to a question.
- **[Lookup Fields](https://api.nyne.ai/documentation/person/lookup-fields.md)** - `POST /person/lookup-fields` - Request specific fields for a person from any identifier.
- **[Email Finder](https://api.nyne.ai/documentation/person/email.md)** - `POST /person/email` - Find a verified business email for a person.
- **[Phone Finder](https://api.nyne.ai/documentation/person/phone.md)** - `POST /person/phone` - Find a phone number for a person.
- **[Social Lookup](https://api.nyne.ai/documentation/person/social-lookup.md)** - `POST /person/social-lookup` - Resolve a profile on a target platform from another identifier.
- **[Single Social Lookup](https://api.nyne.ai/documentation/person/single-social-lookup.md)** - `POST /person/single-social-lookup` - Resolve a single social profile (alias of social-lookup).
- **[Social Account Validator](https://api.nyne.ai/documentation/person/social-account-validator.md)** - `POST /person/social-account-validator` - Validate a public social profile or post and capture a screenshot.
- **[Social Profiles](https://api.nyne.ai/documentation/person/social-profiles.md)** - `POST /person/social-profiles` - Find all social media accounts for a person.

## Company APIs

Company intelligence resolved from a domain - firmographics, employees, funding history, buying intent, and product signals. Overview: https://api.nyne.ai/documentation/company.md

- **[Company Search](https://api.nyne.ai/documentation/company/search.md)** - `POST /company/search` - Find companies from a natural-language query.
- **[Company Discovery](https://api.nyne.ai/documentation/company/discovery.md)** - `POST /company/discovery` - Discover companies from the open web with natural-language queries and match conditions.
- **[Company Enrichment](https://api.nyne.ai/documentation/company/enrichment.md)** - `POST /company/enrichment` - Resolve a full company profile from a domain, email, phone, or company social URL.
- **[Company Employees](https://api.nyne.ai/documentation/company/employees.md)** - `POST /company/employees` - Retrieve public employee profiles for a company.
- **[Company Intent](https://api.nyne.ai/documentation/company/intent.md)** - `POST /company/intent` - Find and rank ICP candidates from demonstrated buying-intent signals.
- **[CheckSeller](https://api.nyne.ai/documentation/company/checkseller.md)** - `POST /company/checkseller` - Verify whether a company sells a given product or service.
- **[CheckFeature](https://api.nyne.ai/documentation/company/checkfeature.md)** - `POST /company/checkfeature` - Detect whether a company’s site has a given feature, technology, or capability.
- **[Company Funding](https://api.nyne.ai/documentation/company/funding.md)** - `POST /company/funding` - Retrieve verified funding-round and acquisition history for a company.
- **[Company Funders](https://api.nyne.ai/documentation/company/funders.md)** - `POST /company/funders` - Look up an investor / fund profile (partners, thesis, check size, recent deals).
- **[Company Needs](https://api.nyne.ai/documentation/company/needs.md)** - `POST /company/needs` - Summarize pain points / challenges from a company’s official filings.
- **[Competitor Engagements](https://api.nyne.ai/documentation/company/competitor-engagements.md)** - `POST /company/competitor-engagements` - Find people who engaged with a company page, with profile URLs and post context.

## Account APIs

Account-level monitoring - track credit consumption, monthly allocation, and per-API usage breakdowns. Overview: https://api.nyne.ai/documentation/account.md

- **[Usage](https://api.nyne.ai/documentation/account/usage.md)** - `GET /usage` - Monitor credit consumption, allocation, and per-API breakdown (synchronous, 200).

## MCP / agents

- [MCP Server](https://api.nyne.ai/documentation/mcp.md) - connect AI assistants over the Model Context Protocol.
- [MCP Quick Start](https://api.nyne.ai/documentation/mcp/quickstart.md) - per-client setup (Claude, ChatGPT, Cursor, VS Code, …).
- [llms.txt](https://api.nyne.ai/llms.txt) - flat machine-readable index of every page.
- [llms-full.txt](https://api.nyne.ai/llms-full.txt) - every docs page concatenated into one file.
- [Agent manifest](https://api.nyne.ai/agent-manifest.json) - structured tool definitions.

## Authentication

All `/person/*` and `/company/*` endpoints authenticate with an API key and secret sent as HTTP headers on every request: `X-API-Key` and `X-API-Secret`. Create keys from your Nyne.ai dashboard and keep the secret server-side. Rate limits: 100 requests/minute, 1,000 requests/hour. Full guide: https://api.nyne.ai/documentation/authentication.md

## Async pattern

Most enrichment and search endpoints are asynchronous. Submit a request and receive `202 Accepted` with a `request_id`, then poll the same path until the job is `completed` - or provide a `callback_url` to receive the result via webhook. Credits are charged on results: empty results never burn credits.

```bash
# 1. Submit - returns 202 + a request_id
curl -X POST https://api.nyne.ai/person/enrichment \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "X-API-Secret: YOUR_API_SECRET" \
  -d '{ "email": "jane.doe@acme.com" }'
# => { "request_id": "…", "status": "queued" }

# 2. Poll the same path - until status is "completed"
curl "https://api.nyne.ai/person/enrichment?request_id=…" \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "X-API-Secret: YOUR_API_SECRET"
```

---

Source: https://api.nyne.ai/documentation/quickstart.md

# Quick Start

> Go from zero to a full, enriched person profile in three steps - create an API key, call the endpoint, and poll for the result. The whole round trip usually takes under a second.

HTML version: https://api.nyne.ai/documentation/quickstart

## 1. Create an API key

Sign in and open API keys in your dashboard, then click **Create key**. You'll get a key and a secret - copy the secret now, it's shown only once:

```
API Key:     YOUR_API_KEY
API Secret:  YOUR_API_SECRET
```

**Keep the secret server-side.** Send `X-API-Key` and `X-API-Secret` on every request, and call the API from your backend - never ship the secret to the browser. Rate limits: 100/min, 1,000/hour. See the [Authentication guide](https://api.nyne.ai/documentation/authentication.md) for more.

## 2. Call the endpoint

Submit one or more identifiers - here, an email plus a couple of social sources to pull - to `POST /person/enrichment`:

```bash
curl -X POST https://api.nyne.ai/person/enrichment \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "X-API-Secret: YOUR_API_SECRET" \
  -H "Content-Type: application/json" \
  -d '{ "email": "jane.doe@acme.com", "newsfeed": ["linkedin", "github"] }'
```

The call returns `202 Accepted` right away with a `request_id` - hold onto it for the next step:

```json
{
  "request_id": "a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4_1717000000_4271",
  "status": "queued"
}
```

## 3. Poll for the result

Poll the same path with the `request_id` until `status` is `completed`:

```bash
curl "https://api.nyne.ai/person/enrichment?request_id=a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4_1717000000_4271" \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "X-API-Secret: YOUR_API_SECRET"
```

Enrichment typically finishes in well under a second, so your first poll often already returns the completed result. Poll roughly once a second until `status` is `completed` - or pass a `callback_url` on the submit to get the result by webhook and skip polling entirely.

When it's done, you get back a merged, sanitized profile - name and headline, location, business and alternate emails, phones, social profiles with follower counts, and a full work history:

```json
{
  "request_id": "a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4_1717000000_4271",
  "status": "completed",
  "completed": true,
  "result": {
    "displayname": "Jane Doe",
    "firstname": "Jane",
    "lastname": "Doe",
    "headline": "VP of Product at Acme",
    "location": "San Francisco, CA",
    "best_business_email": "jane.doe@acme.com",
    "altemails": ["jane.doe@acme.com", "jane@example.com"],
    "fullphone": [{ "fullphone": "+1-555-123-4567", "phone_type": "mobile" }],
    "social_profiles": {
      "linkedin": { "url": "https://linkedin.com/in/janedoe", "followers": 2847 },
      "twitter": { "url": "https://x.com/janedoe", "followers": 1234 }
    },
    "organizations": [
      { "name": "Acme", "title": "VP of Product", "is_current": true },
      { "name": "StartupXYZ", "title": "Product Manager", "is_current": false }
    ],
    "total_experience_years": 12
  },
  "completed_on": "2026-01-15T10:35:00Z"
}
```

**You only pay for results.** Credits are charged only on a meaningful match. Empty results never burn credits.

## What's next

- [Person Enrichment](https://api.nyne.ai/documentation/person/enrichment.md) - every parameter, response code, and field in the profile you just saw.
- [Person Search](https://api.nyne.ai/documentation/person/search.md) - find people by natural-language query instead of a known identifier.
- [Authentication](https://api.nyne.ai/documentation/authentication.md) - the full guide to keys, secrets, and rate limits.
- [MCP Quick Start](https://api.nyne.ai/documentation/mcp/quickstart.md) - wire Nyne.ai into Claude, ChatGPT, Cursor, and other AI clients.

---

Source: https://api.nyne.ai/documentation/first-request.md

# Your first request

> Every Nyne.ai data endpoint speaks the same language: authenticate with a key and secret, submit a request, and read the result out of one uniform envelope. Learn the pattern once here with person enrichment, and the rest of the API works exactly the same way.

HTML version: https://api.nyne.ai/documentation/first-request

The lifecycle every data endpoint follows: `POST /person/enrichment` -> `202 request_id` -> `GET ?request_id=` (poll) -> `200 result`.

## Before you start

You need two things: a **key and secret**, and the **base URL**.

- Sign in and open API keys in your dashboard, then click **Create key**. Copy the secret right away - it is shown only once. The full walkthrough is in the [Authentication guide](https://api.nyne.ai/documentation/authentication.md).
- Every request goes to `https://api.nyne.ai`. Send the key and secret as the `X-API-Key` and `X-API-Secret` headers, and always call from your backend so the secret never reaches a browser.

## Make a request

Submit one or more identifiers - here, just an email - to `POST /person/enrichment`:

```bash
curl -X POST https://api.nyne.ai/person/enrichment \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "X-API-Secret: YOUR_API_SECRET" \
  -H "Content-Type: application/json" \
  -d '{ "email": "jane.doe@acme.com" }'
```

It returns `202 Accepted` right away. The work is not done - you get a `request_id` to poll with next:

```json
{
  "success": true,
  "data": {
    "request_id": "a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4_1717000000_4271",
    "status": "queued",
    "message": "Enrichment request queued. Use GET /person/enrichment?request_id=... to check status."
  },
  "timestamp": "2026-05-28T18:04:11"
}
```

## Poll for the result

Send a `GET` to the **same path** with the `request_id` until you get a `200` with `status` of `completed`. Enrichment typically finishes in well under a second, so your first poll often already returns the result - or pass a `callback_url` on the submit to get it by webhook and skip polling entirely.

```bash
curl "https://api.nyne.ai/person/enrichment?request_id=a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4_1717000000_4271" \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "X-API-Secret: YOUR_API_SECRET"
```

The completed poll returns the merged, sanitized profile, wrapped in the same envelope:

```json
{
  "success": true,
  "data": {
    "request_id": "a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4_1717000000_4271",
    "status": "completed",
    "completed": true,
    "result": {
      "displayname": "Jane Doe",
      "headline": "VP of Product at Acme",
      "location": "San Francisco, CA",
      "best_business_email": "jane.doe@acme.com",
      "social_profiles": {
        "linkedin": { "url": "https://linkedin.com/in/janedoe", "followers": 2847 }
      },
      "organizations": [
        { "name": "Acme", "title": "VP of Product", "is_current": true }
      ],
      "total_experience_years": 12
    },
    "error": null,
    "created_on": "2026-05-28T18:04:11",
    "completed_on": "2026-05-28T18:04:39"
  },
  "timestamp": "2026-05-28T18:04:45"
}
```

## The response envelope

Every reply from the API - from any endpoint, success or failure - is wrapped in the same three keys: `success`, `data`, and `timestamp`. The envelope never changes; only what sits inside `data` does.

When something goes wrong, `success` is `false` and the detail moves under `error`. Branch on `error.code`, not on the human-readable `message` - the codes are stable, the messages are not:

```json
{
  "success": false,
  "error": {
    "code": "insufficient_credits",
    "message": "Not enough credits to complete this request."
  },
  "timestamp": "2026-05-28T18:04:45"
}
```

Each `error.code` maps to an HTTP status you can also switch on:

| error.code | HTTP | Meaning |
| --- | --- | --- |
| missing_credentials | 401 | No key or secret was sent. |
| invalid_credentials | 401 | The key or secret is wrong or expired. |
| access_denied | 403 | The key lacks access to this product. |
| ip_not_allowed | 403 | The request came from an unlisted IP. |
| insufficient_credits | 402 | The workspace is out of credits. |
| rate_limit_exceeded | 429 | Too many requests. Back off and retry. |
| request_not_found | 404 | No request matches that request_id. |

## What you won't see

Responses contain the documented Nyne.ai fields only. Operational metadata and source attribution are not part of the public response contract. Parse only the fields documented for the endpoint, and do not use undocumented metadata for application logic.

## What's next

- [Authentication](https://api.nyne.ai/documentation/authentication.md) - keys, secrets, IP locking, and rate limits in full.
- [Person Enrichment](https://api.nyne.ai/documentation/person/enrichment.md) - every parameter, response code, and field in the profile you just saw.
- [Person Search](https://api.nyne.ai/documentation/person/search.md) - find people by natural-language query instead of a known identifier.
- [MCP Quick Start](https://api.nyne.ai/documentation/mcp/quickstart.md) - wire Nyne.ai into Claude, ChatGPT, Cursor, and other AI clients.

---

Source: https://api.nyne.ai/documentation/authentication.md

# Authentication

> Authenticate to the Nyne.ai Person and Company APIs with an API key and secret sent as X-API-Key / X-API-Secret headers. Covers key management, product access, IP-locking, auth error codes, and key hygiene.

HTML version: https://api.nyne.ai/documentation/authentication

The Person and Company APIs (`/person/*` and `/company/*`) authenticate with an API key and secret. This is a key/secret pair, not a bearer token. Send both values as the `X-API-Key` and `X-API-Secret` headers on every request.

## API key and secret

Send the key and secret as HTTP headers (recommended):

```bash
curl -X POST https://api.nyne.ai/person/enrichment \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "X-API-Secret: YOUR_API_SECRET" \
  -H "Content-Type: application/json" \
  -d '{ "email": "ada@example.com" }'
```

As a fallback, the same credentials also work as the `api_key` and `api_secret` request params (form fields or query string). Headers are preferred - query strings can land in server logs and browser history:

```bash
curl "https://api.nyne.ai/person/enrichment?api_key=YOUR_API_KEY&api_secret=YOUR_API_SECRET&email=ada@example.com"
```

**Always call from your backend.** The secret is a credential - never ship it to a browser, mobile bundle, or any client you do not control. Rate limits apply per key: 100/min, 1,000/hour.

## Get and manage keys

Create and manage keys on the API keys surface in your account. Click **Create key** to mint a key and secret pair. Keys are **workspace-scoped**: a key belongs to the workspace it was created in and inherits that workspace's subscription, credits, and rate limits. Programmatic management lives under the `/v1/api-keys/*` path family.

## Product access

A key is authorized per **product**: `enrichment`, `search`, and `newsfeed`. Each endpoint requires one of them, and authenticating successfully does not by itself grant access to every endpoint.

Calling an endpoint your key is not entitled to returns `403` with `subscription_required` and a message like *"Your subscription does not include access to the Search API."* If your credentials are correct but one endpoint keeps returning that code while others work, the key is missing that product - the fix is to add the product to your plan, not to rotate the key.

## IP-locking (optional)

A key can optionally be locked to an **allow-list of IPs**. Each entry can be an exact IP, a CIDR range (v4 or v6), or an IPv4 wildcard like `203.0.113.*`. Requests from any other address are rejected with `403 ip_not_allowed`. Allow-list the public address that actually originates the API request.

Locking is off until you add entries, and you enable and manage the allow-list from the API keys surface. A key locked with an **empty** allow-list **fails closed**: it blocks every request. Allow-list the address your backend calls from, not your browser's IP.

## Auth error codes

When authentication or access fails, `success` is `false` and the detail moves under `error`. Branch on the stable `error.code`, not the human-readable `message`:

```json
{
  "success": false,
  "error": {
    "code": "invalid_credentials",
    "message": "The API key or secret is invalid."
  },
  "timestamp": "2026-05-28T18:04:45"
}
```

Each `error.code` maps to an HTTP status you can also switch on:

| error.code | HTTP | Meaning |
| --- | --- | --- |
| missing_credentials | 401 | No key or secret was sent. |
| invalid_credentials | 401 | The key or secret is wrong or the key is disabled. |
| api_key_expired | 401 | The key is past its expiry date. |
| subscription_inactive | 403 | The subscription behind the key is not active. |
| subscription_required | 403 | The key or plan does not include this product. |
| ip_not_allowed | 403 | The request IP is not in the key's allow-list. |
| access_denied | 403 | The request does not belong to this key. |
| service_unavailable | 503 | Transient backend outage. Retry - do not rotate keys. |

**Retry vs fix.** `503 service_unavailable` is transient - back off and retry the same request; do not rotate keys. A `401` means the credentials are wrong or expired, so fix or reissue them. A `403` means the credentials are valid but access is not granted - add the product, adjust the IP allow-list, or check the subscription. Retrying a 401 or 403 unchanged will keep failing.

## Key hygiene and rotation

The secret is stored **hashed** and shown in full **only once**, at creation. Copy it immediately into your secret manager or environment - it cannot be retrieved again, only replaced. Treat the secret like a password: never commit it, log it, or embed it in client code.

To rotate a key with no downtime: create a new key, roll your traffic over to it, confirm the old key is idle, then delete the old key. If a secret is ever exposed, delete that key right away and issue a new one.

**MCP authenticates differently.** The Nyne.ai MCP server (`mcp__nyne__*` tools, hosted at `/mcp`) authenticates over OAuth (well-known metadata plus JWKS), separate from this data-API key and secret model. See the [MCP Quick Start](https://api.nyne.ai/documentation/mcp/quickstart.md) for that flow.

## What's next

- [Rate limits](https://api.nyne.ai/documentation/rate-limits.md) - per-key request ceilings and how to handle 429 responses.
- [Credits](https://api.nyne.ai/documentation/credits.md) - how usage is metered and when a request consumes a credit.
- [Your first request](https://api.nyne.ai/documentation/first-request.md) - the submit-and-poll pattern every data endpoint shares.
- [MCP Quick Start](https://api.nyne.ai/documentation/mcp/quickstart.md) - wire Nyne.ai into Claude, ChatGPT, Cursor, and other AI clients over OAuth.

---

Source: https://api.nyne.ai/documentation/async.md

# Async requests, polling & webhooks

> Most Nyne.ai data endpoints are asynchronous: a POST returns 202 with a request_id, then you poll the same path until it returns a terminal response - or hand over a callback_url and let a webhook deliver the result. This guide covers the request lifecycle, correct polling, terminal errors, and callback webhooks.

HTML version: https://api.nyne.ai/documentation/async

The common success lifecycle is: `POST /person/enrichment` -> `202` with a `request_id` -> `GET ?request_id=` (poll) -> `200` with `status: "completed"`. Some endpoints use `queued`, others use `processing`, and a terminal failure may be returned as a non-2xx error instead of a `200 failed` envelope.

## Submit, 202, poll

A `POST` to a data endpoint validates your input, checks account access and available credits when applicable, and enqueues background work. It returns `202 Accepted` with a `request_id` - the durable identifier for this one job (for example `a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4_1717000000_4271`). The result is NOT in that response; the acknowledgement carries a non-terminal status such as `queued` or `processing`.

```bash
curl -X POST https://api.nyne.ai/person/enrichment \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "X-API-Secret: YOUR_API_SECRET" \
  -H "Content-Type: application/json" \
  -d '{ "email": "jane.doe@acme.com" }'
```

The `202` body hands you the `request_id` to poll with next:

```json
{
  "success": true,
  "data": {
    "request_id": "a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4_1717000000_4271",
    "status": "queued",
    "message": "Enrichment request queued. Use GET /person/enrichment?request_id=... to check status."
  },
  "timestamp": "2026-05-28T18:04:11"
}
```

## The lifecycle statuses

The submit/queue reply contains a non-terminal status such as `queued` or `processing`. From then on, the status endpoint commonly returns `pending`, `processing`, `completed`, or `failed`. A representative progression is `queued -> processing -> completed`.

- Most endpoints use `completed` for terminal success (never `"done"`). Some endpoint pages document additional successful terminal values. For example, People Search can return `exhausted` or `stale` with `completed: true`.
- A successful poll may use HTTP `200` or `202` while work is still in flight. When a successful payload includes `completed`, `false` means keep polling and `true` means stop; otherwise use the endpoint's status table. HTTP `200` alone does not prove completion. A terminal error envelope or non-retriable non-2xx processing/billing response also stops that request; transient transport/status-infrastructure responses may be retried using the endpoint's documented backoff policy.

Treat the status values listed here and on each endpoint page as the complete public contract. Do not infer additional intermediate states. See [Interpreting responses](https://api.nyne.ai/documentation/responses.md) for the full status model.

## Poll for the result

Poll by sending a `GET` to the **same path you POSTed to**, with `?request_id=...` and any additional page values required by that endpoint. A successful poll may use HTTP `200` or `202` before completion. When `completed` is present on a successful response, continue while it is false and stop when it is true. Otherwise follow the endpoint's status table. Any terminal error envelope or non-retriable non-2xx job response also stops that request; retry transient transport/status-infrastructure responses only as documented by the endpoint.

```bash
curl "https://api.nyne.ai/person/enrichment?request_id=a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4_1717000000_4271" \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "X-API-Secret: YOUR_API_SECRET"
```

Enrichment usually finishes in well under a second, so the first poll often already returns the result. Poll roughly once per second with a sensible max-wait; do not hammer the endpoint. Polls count toward your throttles, so see the [Rate limits](https://api.nyne.ai/documentation/rate-limits.md) guide before tightening the loop.

A successful terminal payload carries the merged, sanitized result inside the same envelope, with `status: "completed"` and `completed: true`:

```json
{
  "success": true,
  "data": {
    "request_id": "a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4_1717000000_4271",
    "status": "completed",
    "completed": true,
    "result": {
      "displayname": "Jane Doe",
      "headline": "VP of Product at Acme",
      "location": "San Francisco, CA",
      "best_business_email": "jane.doe@acme.com"
    },
    "error": null,
    "created_on": "2026-05-28T18:04:11",
    "completed_on": "2026-05-28T18:04:39"
  },
  "timestamp": "2026-05-28T18:04:45"
}
```

A status lookup itself can fail. The request must belong to the authenticating key, the `request_id` must be known, and the lookup store must be reachable. Treat authentication, authorization, unknown-request, insufficient-credit, and terminal processing errors as settled. Retry a `429` poll only when the poll itself was throttled; a `429` stored as the job's terminal status ends that request. Back off and retry transient service-unavailable responses:

| error.code | HTTP | Meaning |
| --- | --- | --- |
| invalid_credentials | 401 | Authentication failed. Fix credentials before retrying. |
| insufficient_credits | 402 | The job cannot continue until the account has enough credits. |
| access_denied / ip_not_allowed | 403 | The authenticated account or request IP is not allowed to use the endpoint. |
| request_not_found | 404 | No request matches that request_id, including request IDs owned by another API key. |
| rate_limit_exceeded | 429 | If the poll itself was throttled, honor Retry-After and retry it. If this is the job's stored terminal status, stop polling that request_id and submit a new request after the limit resets. |
| search_error / internal_error | 500 | Terminal processing failure for that request_id unless the endpoint says otherwise. |
| service_unavailable | 503 | A transient lookup issue. Back off and retry. |

## Webhooks with callback_url

Instead of polling, supply a `callback_url` on the submit. When the job completes, Nyne.ai POSTs the same result envelope to your URL:

```bash
curl -X POST https://api.nyne.ai/person/enrichment \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "X-API-Secret: YOUR_API_SECRET" \
  -H "Content-Type: application/json" \
  -d '{
        "email": "jane.doe@acme.com",
        "callback_url": "https://hooks.example.com/nyne"
      }'
```

The callback URL is validated before the request is accepted. It must be `http(s)://`, at most 1024 characters, and carry no userinfo (no `user:pass@` in the URL). It is also checked against an allowed-hosts policy that rejects localhost, private, and reserved addresses, along with `.local`, `.internal`, `.lan`, `.home`, `.corp`, `.test`, `.invalid`, and `.example` hosts. An invalid target is rejected at submit time with `400 invalid_callback_url`.

For endpoints using the common callback envelope, the delivered payload matches what a poll would have returned: `success`, `data` (with the terminal `status` and `result`), and `timestamp`. Verify and process it idempotently, keyed on the `request_id`, so a retried delivery is safe.

Person Search has endpoint-specific pagination behavior. Its callback can report queued session work, but it is not a per-page pagination mechanism: after a successful callback it is not re-emitted for every later page, and an immediately cached page POST does not enqueue one. The exact `GET /person/search` request with that page's `request_id`, `offset`, and `limit` remains the authoritative retrieval path. See [Person Search](https://api.nyne.ai/documentation/person/search.md).

## Which calls are synchronous

Not everything is async. A few calls return `200` directly, with no `request_id` and nothing to poll:

- `POST /person/enrichment/feedback` is a single insert that returns `200` immediately.
- The status-lookup `GET`s themselves are synchronous, and they are not credit-gated - polling never costs credits.

## Idempotency and durability

The `request_id` is the durable handle to one job. Re-polling it with the documented status GET is safe and does NOT re-charge credits. A poll loop, a retried GET poll, or a redelivered webhook does not create another charge. People Search is the pagination exception: multiple page POSTs reuse one `request_id`, and each successfully fulfilled page POST is billable; use GET, not POST, for status checks and stored-page reads.

## What's next

- [Rate limits](https://api.nyne.ai/documentation/rate-limits.md) - how throttles work so your poll loop stays under them.
- [Interpreting responses](https://api.nyne.ai/documentation/responses.md) - the envelope, the status model, and how normalized statuses are derived.
- [Credits](https://api.nyne.ai/documentation/credits.md) - when a request is charged and what counts as a meaningful result.
- [Your first request](https://api.nyne.ai/documentation/first-request.md) - the end-to-end walkthrough this guide builds on.

---

Source: https://api.nyne.ai/documentation/effective-requests.md

# Constructing effective requests

> Every Nyne.ai request falls into one of two shapes. Enrichment and lookup identify one person from the identifiers you already hold; search takes a natural-language string and/or structured filters and returns the people who match. Getting the JSON shape right is what drives hit rate, latency, and credit cost.

HTML version: https://api.nyne.ai/documentation/effective-requests

The two request shapes: **enrichment / lookup** (`POST /person/enrichment`, `POST /person/lookup-fields`) identify one person, while **search** (`POST /person/search`) describes a population and returns everyone who matches.

## Person-search JSON contract

Send one JSON object. The `query` field is always a natural-language **string**, never an object or array. Put exact fields under `custom_filters`.

Valid natural-language request:

```json
{ "query": "People currently working at acme.com", "limit": 1 }
```

Valid structured request (`companies` matches current employers and accepts a company name, domain, or company profile URL):

```json
{
  "custom_filters": {
    "companies": ["acme.com"],
    "titles": ["Product Manager"]
  },
  "limit": 25
}
```

Do **not** send this shape:

```json
{ "query": { "company_domain": "acme.com" }, "limit": 1 }
```

That request confuses a natural-language field with structured filters. Use `POST /company/employees` for a broad roster at one company. Use `POST /person/search` when title, role, location, experience, or other person criteria matter.

### Agent-safe search lifecycle

1. Send each `POST /person/search` page exactly once. A new search returns `202`, `status: "processing"`, a `request_id`, and that page's `offset`/`limit`; an already-cached page can return `200` with `completed: true` immediately. POST prepares the page but does not return its result rows, and replaying a completed/cached page can charge that page again.
2. Poll and retrieve that exact page with `GET /person/search?request_id=<request_id>&offset=<offset>&limit=<limit>` using the same API credentials about every two seconds. If POST returned `completed: true`, do this GET once to read the rows without entering a polling loop. A bare GET with only `request_id` always reads offset 0; it does not remember the most recently submitted cursor.
3. Continue only while the poll returns `202` with `data.completed: false`. Stop whenever `data.completed` is `true`, regardless of whether People Search reports `status: "completed"`, `"exhausted"`, or `"stale"`. `exhausted` can coexist with `has_more: true` when later rows are already cached, so use `has_more` alone to decide whether another page exists.
4. To fetch another page, submit exactly one new POST with the prior response's `next_cursor` (recommended), or with the same `request_id` plus a higher `offset`. Record the POST response's `offset`/`limit`, then use those same values on every GET for that page. Do not use GET to launch a page fetch.
5. Stop on any error envelope or terminal `400`, `401`, `402`, `403`, `404`, `429`, or `500`. A transport-level `429` that throttles the polling call itself may be retried after `Retry-After`; a `429` stored as this search's terminal status ends that request. Retry transient `503` responses with backoff.
6. Polling is free. A POST page is billed per result returned. The base search cost and enabled options such as structured filters, contact data, insights, and scoring are additive per result. The dollar value of a credit depends on the account's subscription or credit-purchase tier.
7. An HTTPS `callback_url` can report queued session work, but it is not a per-page pagination mechanism. After a successful callback it is not re-emitted for every later page, and an immediately cached POST response does not enqueue one. Handle webhook deliveries idempotently using `request_id`, and retain the exact `request_id`/`offset`/`limit` GET for recovery and authoritative page retrieval.

## Identifiers for enrichment and lookup

Enrichment and lookup identify a single person. Send at least one of `email`, `phone`, `social_media_url`, or `name`. The more specific the identifier, the better the match: `email` and `social_media_url` resolve to exactly one person, while `name` works best when you also pass `company` and a location to disambiguate.

| key | What it is |
| --- | --- |
| email | A work or personal email address. The strongest single identifier. |
| phone | A phone number in any common format. |
| social_media_url | A profile URL, e.g. a LinkedIn page. |
| name | Full name. Works best paired with company + location to disambiguate. |
| company | Employer name. Strip legal suffixes first (see below). |
| city | City the person is in, to narrow a name match. |
| state | State or region, alongside city. |
| company_domain | Employer domain (lookup-fields), e.g. acme.com. |
| location | A free-form location string (lookup-fields). |
| postal_code | Postal or ZIP code (lookup-fields). |
| profile_url / url | A profile URL alias accepted by lookup-fields. |

Extra identifiers never hurt: each one narrows the candidate set and raises your chance of a clean, single-person match.

## Ask for only what you need: the fields array

Lookup requests take a `fields` array. Request only the fields you actually use - a narrower request is cheaper and faster, because each field can pull from a different source. Common contact fields are `best_work_email`, `best_personal_email`, and `mobile`. If you already hold specific profile URLs you want resolved, pass them in `profile_urls`.

```bash
curl -X POST https://api.nyne.ai/person/lookup-fields \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "X-API-Secret: YOUR_API_SECRET" \
  -H "Content-Type: application/json" \
  -d '{
    "email": "jane.doe@acme.com",
    "fields": ["best_work_email", "mobile"]
  }'
```

## The email and phone shortcuts

When you need exactly one contact field, skip the `fields` array. `POST /person/email` and `POST /person/phone` are thin wrappers over lookup-fields that force the field set for you: `/person/email` forces `fields=["best_work_email"]` and `/person/phone` forces `fields=["mobile"]`, and both clear `profile_urls`. They take the same person identifiers - the simplest possible request when you only want that one value.

```bash
curl -X POST https://api.nyne.ai/person/email \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "X-API-Secret: YOUR_API_SECRET" \
  -H "Content-Type: application/json" \
  -d '{ "name": "Jane Doe", "company": "acme" }'
```

```bash
curl -X POST https://api.nyne.ai/person/phone \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "X-API-Secret: YOUR_API_SECRET" \
  -H "Content-Type: application/json" \
  -d '{ "social_media_url": "https://linkedin.com/in/janedoe" }'
```

Under the hood, `/person/email` is a lookup-fields call with this body forced on top of your identifiers:

```json
{
  "fields": ["best_work_email"],
  "profile_urls": []
}
```

## Start from what you know, expand outward

A hard identifier resolves to a single person on its own: an `email`, a `phone`, or a LinkedIn or other `social_media_url`. Once you have one, submit it back to enrichment to expand the record - filling out title, company, socials, and work history from that single anchor. You do not need to send anything else:

```bash
curl -X POST https://api.nyne.ai/person/enrichment \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "X-API-Secret: YOUR_API_SECRET" \
  -H "Content-Type: application/json" \
  -d '{ "social_media_url": "https://linkedin.com/in/janedoe" }'
```

This "known key in, full record out" flow is the backbone of most integrations: capture whatever strong identifier a user gives you, then let enrichment fill in the rest.

## Company-name hygiene

Legal and entity suffixes throw off company matching. Before you send a `company` value, lowercase it and strip trailing suffix tokens repeatedly until none remain. So `"Acme Corp Inc"` becomes `"acme"`. Copy-paste this suffix list:

```
inc, llc, ltd, co, corp, corporation, company, gmbh, sa, ag,
plc, llp, lp, pllc, pty, group, holdings, holding, the
```

Match tokens case-insensitively and remove them one at a time from the end, so a doubled suffix like `Corp Inc` is fully cleaned. Do this to any name you send as `company` - in enrichment, lookup, the shortcuts, and the search `companies` filter alike.

## Search filters and requirements

Search does not identify one person. It takes a natural-language `query` string, a `custom_filters` object, or both, and returns everyone who matches. Most fields in `custom_filters` are arrays you can combine, alongside numeric ranges and bounded structured objects:

| custom_filters field | Matches on |
| --- | --- |
| locations | Regions, metros, or countries. |
| languages | Languages the person uses. |
| titles | Job titles or role names. |
| industries | Industry categories. |
| companies | Current employers; accepts names, domains, and company profile URLs. |
| universities | Schools attended. |
| keywords | Free-text terms matched across the profile. |
| degrees | Degree types held. |
| specialization_categories | Areas of specialization. |
| company_funding_stages | Funding stage of the employer. |
| company_latest_funding_stages | Most recent funding stage. |
| company_investor_names | Investors backing the employer. |
| company_funding_round_filters | Same-event employer funding constraints. Each object may contain `stages`, `investor_names`, `min_amount`, `max_amount`, `funded_after_date`, `funded_before_date`, and `funded_within_days`. |

Use `company_funding_round_filters` when facts must come from one round. For example, `{"stages":["series a"],"min_amount":3000000,"funded_within_days":30}` requires a Series A round of at least $3 million within the inclusive last 30 days; it does not allow the stage, amount, and date to come from separate rounds.

Alongside the filters, contact-requirement toggles narrow the result set to people who have the contact data you care about, and `profile_scoring` ranks each result against the query:

| parameter | Effect |
| --- | --- |
| require_emails | Keep only results that have an email. |
| require_phone_numbers | Keep only results that have a phone. |
| require_phones_or_emails | Keep only results with a phone or an email. |
| profile_scoring | Attach a query-fit score to each result. |

```bash
curl -X POST https://api.nyne.ai/person/search \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "X-API-Secret: YOUR_API_SECRET" \
  -H "Content-Type: application/json" \
  -d '{
    "custom_filters": {
      "titles": ["VP of Engineering", "CTO"],
      "locations": ["San Francisco Bay Area"],
      "industries": ["Software"],
      "min_linkedin_followers": 1000
    },
    "require_phones_or_emails": true,
    "profile_scoring": true,
    "limit": 10
  }'
```

Each requirement you add filters more people out and can raise the cost per result, because guaranteeing a phone or email means resolving more data. See [Credits](https://api.nyne.ai/documentation/credits.md) and [Request depth](https://api.nyne.ai/documentation/request-depth.md) for how the trade-off is priced.

## Async delivery with callback_url

Any submit can carry a `callback_url`. When the result is ready, Nyne POSTs it there instead of making you poll. The URL is validated against an allowed-hosts list, so register your host first. See [Async and webhooks](https://api.nyne.ai/documentation/async.md) for the full setup.

## What's next

- [Request depth](https://api.nyne.ai/documentation/request-depth.md) - how far Nyne digs for a result, and what that costs.
- [Credits](https://api.nyne.ai/documentation/credits.md) - what each request type charges, and when.
- [Async and webhooks](https://api.nyne.ai/documentation/async.md) - polling versus `callback_url` delivery.
- [Responses](https://api.nyne.ai/documentation/responses.md) - the envelope and the fields you get back.

---

Source: https://api.nyne.ai/documentation/request-depth.md

# Choosing request depth

> Pick the right depth for latency, coverage, and cost: lookup_mode (fast / balanced / deep), search type (light / medium / premium), the person_enrich tier, and the search feature toggles that change the price.

HTML version: https://api.nyne.ai/documentation/request-depth

Every request trades latency, coverage, and cost against each other. Four dials set that balance: `lookup_mode` on enrichment, the search `type`, the higher-tier `person_enrich` mode, and the search feature toggles that change the price. Deeper is not always better - the right depth is the shallowest one that still answers your question. The ladder runs shallow to deep: `fast` / `light` -> `balanced` / `medium` -> `deep` / `premium`.

## Enrichment depth: lookup_mode

On `/person/enrichment`, the `lookup_mode` field controls the latency and coverage tradeoff. It takes one of three values, and the default is `deep`:

| lookup_mode | Behavior | Latency | Coverage |
| --- | --- | --- | --- |
| fast (shortest processing) | Prioritizes response time with the shortest enrichment path. Lowest latency, lower coverage. | Lowest | Lower |
| balanced (balanced processing) | Allows more enrichment work than fast mode. A middle ground for latency and coverage. | Medium | Medium |
| deep (most thorough processing, default) | Uses the most thorough enrichment path. Highest coverage, highest latency. | Highest | Highest |

Pass it in the JSON body. Here is the middle-ground `balanced` mode:

```bash
curl -X POST https://api.nyne.ai/person/enrichment \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "X-API-Secret: YOUR_API_SECRET" \
  -H "Content-Type: application/json" \
  -d '{ "email": "jane.doe@acme.com", "lookup_mode": "balanced" }'
```

**Deep is the default.** If you send no `lookup_mode`, you get `deep` for the best coverage and highest latency. Drop to `balanced` or `fast` when a caller is waiting on the response.

## Search tier: type

On `/person/search`, the `type` field picks the search tier. Result quality and coverage rise with the tier, and so does cost. `light` is the fastest and `premium` is the most thorough. The default is `premium`:

| type | Search tier | Quality | Notes |
| --- | --- | --- | --- |
| light | Fastest search tier | Lower | Lowest cost and latency. For light, insights and high_freshness are force-disabled. |
| medium | Balanced search tier | Medium | A balance of result quality and cost. |
| premium (default) | Most thorough search tier | Highest | Highest result quality and coverage, and the highest cost. |

```bash
curl -X POST https://api.nyne.ai/person/search \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "X-API-Secret: YOUR_API_SECRET" \
  -H "Content-Type: application/json" \
  -d '{ "query": "VP of Product in San Francisco", "type": "premium", "show_emails": true }'
```

**type also affects processing priority.** A higher search tier receives higher processing priority and can start sooner. Note that for `light`, `insights` and `high_freshness` are force-disabled - they do not apply at the fastest tier.

## The person_enrich tier

Standard `person_enrichment` is the right call most of the time. When it is not enough, the higher-tier `person_enrich` mode forces all newsfeed sources (force-newsfeed) to pull a fuller, fresher record - the complete social activity, not just the merged profile.

It is worth the upgrade for hard-to-find people the standard enrichment misses, or when you specifically need full social activity rather than a static profile. It also costs more: `person_enrich` cross-links additional credit-bearing sources, so reach for it deliberately, not by default. Start standard, escalate when it falls short.

## Search feature toggles that change the price

Several search flags each change the credit price when you turn them on. Broadly, turning more on means better and richer results, a higher cost, and often higher latency. See [Credits & pricing](https://api.nyne.ai/documentation/credits.md) for the exact per-feature costs.

| Toggle | Tradeoff |
| --- | --- |
| show_emails | Return matched email addresses. Adds to the credit price. |
| show_phone_numbers | Return matched phone numbers. Adds to the credit price. |
| insights | Attach AI-derived insights to each result. Richer, higher cost and latency. |
| profile_scoring | Score and rank results against your query. Higher cost. |
| high_freshness | Prefer fresher records over cached ones. Higher cost and latency. |
| require_emails | Drop results without an email. Fewer but better-qualified results. |
| require_phone_numbers | Drop results without a phone. Fewer but better-qualified results. |
| require_phones_or_emails | Drop results without a phone or an email. Fewer but contactable results. |

The `require_*` toggles narrow results rather than enrich them - use them to trim what you never wanted, not to widen coverage. Every added signal has a price; leave off the ones you will not read.

## Picking a depth

Stated plainly: a deeper `lookup_mode`, a higher search `type`, and more toggles all buy you better coverage at a higher cost and higher latency. There is no universally right setting - only the right one for a given call. Start from the use case:

| Use case | lookup_mode | search type | Notes |
| --- | --- | --- | --- |
| Interactive / autocomplete / low latency | fast | light | Answer while the user waits. |
| General enrichment / balanced | balanced | medium | The default-ish middle ground. |
| Hard-to-find / maximum recall / batch | deep | premium | Add person_enrich when the standard record is not enough. |

**Measure on your own data.** These are starting points, not verdicts. Coverage and latency depend on the identifiers and audience you send, so run each candidate depth against a sample of your real inputs before you commit. The [Evaluating the API](https://api.nyne.ai/documentation/evaluating.md) guide walks through how to compare depths fairly.

## What's next

- [Credits & pricing](https://api.nyne.ai/documentation/credits.md) - how each mode, tier, and toggle maps to credits.
- [Writing effective requests](https://api.nyne.ai/documentation/effective-requests.md) - the identifiers and query shapes that raise coverage before you pay for more depth.
- [Evaluating the API](https://api.nyne.ai/documentation/evaluating.md) - measure coverage, latency, and cost on your own data before committing.
- [Async & polling](https://api.nyne.ai/documentation/async.md) - why deeper modes take longer and how to poll for the result.

---

Source: https://api.nyne.ai/documentation/responses.md

# Interpreting API responses

> Every reply from the Nyne.ai API arrives in the same envelope, so reading one correctly means reading them all. Branch on `success` first, tell a finished result from a still-running one, read confidence scores where they exist, and build against the documented public fields.

HTML version: https://api.nyne.ai/documentation/responses

The shape is always the same: `success` (true or false), then `data` or `error` (one, never both), then `timestamp` (server UTC, ISO-8601). Branch on `success` first; on failure switch on `error.code`, not the message.

## The uniform envelope

Success or failure, from any endpoint, the response is wrapped in the same keys. On success you get `success: true` and the payload under `data`:

```json
{
  "success": true,
  "data": {
    "request_id": "a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4_1717000000_4271",
    "status": "completed",
    "completed": true,
    "result": {
      "displayname": "Jane Doe",
      "headline": "VP of Product at Acme",
      "best_business_email": "jane.doe@acme.com"
    }
  },
  "timestamp": "2026-05-28T18:04:45"
}
```

When something goes wrong, `success` is `false`, there is no `data`, and the detail sits under `error`:

```json
{
  "success": false,
  "error": {
    "code": "insufficient_credits",
    "message": "Not enough credits to complete this request."
  },
  "timestamp": "2026-05-28T18:04:45"
}
```

Always branch on `success` first, then read `error.code` for the failure branch. The `error.code` is a stable, machine-readable identifier; the human `message` is for logs and can change wording at any time, so never parse it. The `timestamp` is the server's UTC time in ISO-8601 - useful for correlating logs, not for logic.

## Async status: done or not done

Most data endpoints answer asynchronously. A `202` means the request was accepted but is **not finished**. While it runs, `data.status` reads `pending`, `queued`, or `processing`, and `data.completed` is `false`:

```json
{
  "success": true,
  "data": { "request_id": "a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4_1717000000_4271", "status": "processing", "completed": false },
  "timestamp": "2026-05-28T18:04:12"
}
```

A successful result is final when `data.completed` is `true`. Most endpoints pair that with `status: "completed"`; an endpoint may document other successful terminal values, such as People Search's `exhausted` and `stale`. When a successful payload includes `data.completed`, `false` means keep polling and `true` means stop, regardless of whether the HTTP status is `200` or `202`. Terminal failures may instead arrive as an error envelope or non-retriable non-2xx response without a true completed flag; those also stop the request. Transient transport/status-infrastructure responses remain retryable when the endpoint documents a retry policy. Interpret `data.status` using that endpoint's status table. See [Async requests](https://api.nyne.ai/documentation/async.md) for the full lifecycle, poll cadence, and webhook callbacks.

## Confidence and scoring

Search can rank its matches. Opt in with `profile_scoring` to attach a query-fit score to each result:

```bash
curl -X POST https://api.nyne.ai/person/search \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "X-API-Secret: YOUR_API_SECRET" \
  -H "Content-Type: application/json" \
  -d '{ "query": "VP of Product at Acme", "profile_scoring": true }'
```

```json
{
  "success": true,
  "data": {
    "request_id": "a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4_1717000000_4271",
    "status": "completed",
    "completed": true,
    "results": [
      { "displayname": "Jane Doe", "headline": "VP of Product at Acme", "probability": 0.94 },
      { "displayname": "Jane Doe", "headline": "Analyst at Globex", "probability": 0.42 }
    ]
  },
  "timestamp": "2026-05-28T18:04:39"
}
```

Pick a confidence bar that fits your use case and threshold on `probability` rather than blindly trusting the top match - a high bar for automated writes, a lower one for human review. Be aware of the limit: `probability` is the only confidence number the API exposes. There are no per-field confidence values, so a returned field is present or it is not.

## Public response contract

Treat the fields and status values documented for each endpoint as the complete response contract. Operational metadata and source attribution are not part of that contract and must not be required by client code.

Use stable `error.code` values for branching and documented response fields for data access. Human messages are for display or logs and can change wording, so do not parse implementation details from a `message`.

## Partial and failed results

A match can be partial. Fields that could not be resolved simply do not appear, or come back `null` - a profile with a name and company but no phone is a normal, useful result. Do not assume any single field will be present.

When a request finds nothing at all it presents as a terminal failure: `status: "failed"` with `completed: true`. A clean no-match commonly reads as a `404` on the underlying request:

```json
{
  "success": true,
  "data": {
    "request_id": "a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4_1717000000_4271",
    "status": "failed",
    "completed": true,
    "error": "No match found for the supplied identifiers."
  },
  "timestamp": "2026-05-28T18:04:39"
}
```

Accept partial matches that clear your confidence bar. A transient `failed` or a `503` is retryable with backoff; a clean no-match (nothing exists for those identifiers) is not - retrying just burns calls. See [Rate limits](https://api.nyne.ai/documentation/rate-limits.md) for the full retryable error taxonomy.

## Report bad data

Found something wrong or stale in a result? Close the loop with `POST /person/enrichment/feedback`. It is synchronous and returns `200` right away - pass the `request_id` from the result you are correcting and a non-empty `comments` string:

```bash
curl -X POST https://api.nyne.ai/person/enrichment/feedback \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "X-API-Secret: YOUR_API_SECRET" \
  -H "Content-Type: application/json" \
  -d '{
    "request_id": "a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4_1717000000_4271",
    "comments": "The current company is out of date; she left Acme in early 2026."
  }'
```

## What's next

- [Async requests](https://api.nyne.ai/documentation/async.md) - the full submit, poll, and callback lifecycle behind every 202.
- [Rate limits](https://api.nyne.ai/documentation/rate-limits.md) - which errors are retryable, and how to back off cleanly.
- [Effective requests](https://api.nyne.ai/documentation/effective-requests.md) - send stronger identifiers to get fuller, higher-confidence matches.
- [Your first request](https://api.nyne.ai/documentation/first-request.md) - the end-to-end walkthrough this page's rules apply to.

---

Source: https://api.nyne.ai/documentation/credits.md

# Credits, billing & usage tracking

> How the Nyne.ai API charges credits: fixed per-call vs dynamic per-result pricing, feature surcharges, pre-flight checks and deduction, the monthly quota, and how to track usage without double-counting.

HTML version: https://api.nyne.ai/documentation/credits

Every call to the Nyne.ai API is priced in credits. Most endpoints charge a fixed amount per call; a few price dynamically by the number of results returned.

## The credit model

Most endpoints cost a **fixed** number of credits per call. **Search** and company **employees** are **dynamic**: the pre-flight check uses `credits x requested_limit` as the maximum, while the final charge is `credits x results_returned`. These are the documented default costs - your workspace may have negotiated overrides, and the live figures load from your account into the endpoint pages.

### Person

| Action | Credits | Notes |
| --- | --- | --- |
| person_search | 1 (per result) | Dynamic: per result returned. |
| person_enrichment | 2 | Standard full-profile enrichment. |
| person_lookup_fields | 1 | Only the fields you ask for. |
| person_email | 1 | Single best work email. |
| person_phone | 1 | Single best phone. |
| person_newsfeed | 1 | ceil(limit / 10) units; by-URL lookup bills 1. |
| person_ask | 10 | AI-powered profile Q&A. |
| person_interests | 5 | Interest analysis. |
| person_leads | 1 | Lead search. |
| person_discover | 10 | Discovery. |
| person_deep_research | 100 | Long-running deep research. |
| social_account_validation | 10 | Validate a social account. |

### Company

| Action | Credits | Notes |
| --- | --- | --- |
| company_search | 1 (per result) | Dynamic: per result returned. |
| company_enrichment | 1 | Full company profile. |
| company_employees | 1 (per result) | Dynamic: per result returned. |
| company_intent | 10 | Buyer-intent signals. |
| company_competitor_engagements | 5 | Per engagement result. |
| company_needs | 1 | Company needs. |
| company_funding | 1 | Funding history. |

A few specifics worth knowing:

- `person_ask` costs 10 credits per call - it runs an AI analysis over the profile.
- Newsfeed quantity is `ceil(limit / 10)` units, so a larger feed costs more units; a single by-URL newsfeed lookup bills 1.
- Standard `person_enrichment` is the everyday tier. The higher-tier `person_enrich` forces a full newsfeed and costs more - see [Request depth](https://api.nyne.ai/documentation/request-depth.md) for when to reach for it.

## Feature surcharges

On search endpoints, feature toggles change the price. The more you turn on, the more each result costs: `show_emails`, `show_phone_numbers`, `insights`, `profile_scoring`, `high_freshness`, `require_emails`, `require_phone_numbers`, `require_phones_or_emails`.

The billing action key is a function of the feature **combination** - deduped and canonically ordered - so the same set of toggles always maps to the same key. For example, a search with emails and phones on bills under `person_search:show_emails:show_phone_numbers`. See [Request depth](https://api.nyne.ai/documentation/request-depth.md).

## Pre-flight checks & deduction

Credits are handled in two moments. Before any work starts, the request runs a **pre-flight allowance check**: if the workspace cannot cover the estimated cost, the call fails immediately with `402 insufficient_credits` and nothing is spent. Credits are only **deducted on completion**, after a meaningful result. Async endpoints check the estimated cost at submission. Dynamic search and employee endpoints deduct credits for the actual completed result count. Every charge carries a `billing_action_key` naming exactly what was billed:

```json
{
  "success": true,
  "data": {
    "request_id": "a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4_1717000000_4271",
    "status": "completed",
    "billing_action_key": "person_search:show_emails:show_phone_numbers",
    "credits_charged": 20,
    "requested_limit": 10
  },
  "timestamp": "2026-05-28T18:04:45"
}
```

**Empty results do not burn credits.** A no-match or empty result is not billed. You pay only when the API returns a meaningful result.

When the pre-flight check fails, the shape is the standard error envelope - branch on `error.code`:

```json
{
  "success": false,
  "error": {
    "code": "insufficient_credits",
    "message": "Not enough credits to complete this request."
  },
  "timestamp": "2026-05-28T18:04:45"
}
```

## The monthly quota

On **top** of per-request credits, your plan has a monthly request quota - a cap on how many calls you can make in a billing month, independent of credit balance. Exceeding it returns `monthly_limit_exceeded` with HTTP `429`:

```json
{
  "success": false,
  "error": {
    "code": "monthly_limit_exceeded",
    "message": "Monthly request quota exceeded."
  },
  "timestamp": "2026-05-28T18:04:45"
}
```

Every response carries the quota state in headers:

| Header | Meaning |
| --- | --- |
| X-Quota-Limit | Requests allowed this month. |
| X-Quota-Used | Requests already spent this month. |
| X-Quota-Remaining | Requests left before the cap. |
| X-Quota-Reset | When the quota window resets. |

The quota is distinct from per-minute and per-hour throttling. For those, see [Rate limits](https://api.nyne.ai/documentation/rate-limits.md).

## Usage tracking & analytics

You can see per-call spend and history through the Usage Analytics API, which reports credits grouped by `billing_action_key`:

```json
{
  "success": true,
  "data": {
    "period": "2026-05",
    "total_credits": 142,
    "by_action": [
      { "billing_action_key": "person_search", "credits": 40, "calls": 40 },
      { "billing_action_key": "person_search:show_emails", "credits": 60, "calls": 30 },
      { "billing_action_key": "person_enrichment", "credits": 42, "calls": 21 }
    ]
  },
  "timestamp": "2026-05-28T18:04:45"
}
```

**Use reported credit totals.** Request counts and credit usage are different measurements. A request can finish without a billable result, and dynamic operations can charge by the number of results returned. Reconcile spend from `total_credits` and `by_action`, not by adding up request counts.

## Computed cost versus charged usage

An estimate or computed cost is not itself a charge. Treat `total_credits` and `by_action` from Usage Analytics as the authoritative record of deducted credits.

## What's next

- [Rate limits](https://api.nyne.ai/documentation/rate-limits.md) - per-minute and per-hour throttling, and how the monthly quota fits in.
- [Request depth](https://api.nyne.ai/documentation/request-depth.md) - the feature toggles and enrichment tiers that move the price.
- [Effective requests](https://api.nyne.ai/documentation/effective-requests.md) - shaping calls to get the results you need for the fewest credits.
- [Responses](https://api.nyne.ai/documentation/responses.md) - the envelope, error codes, and status fields you branch on.

---

Source: https://api.nyne.ai/documentation/rate-limits.md

# Rate limits, quotas & error handling

> Every API key is throttled by a three-tier rate limiter and a monthly quota. When you push past either, the API answers with a structured error and headers that tell you exactly how long to wait. This page covers the tiers, the headers to read, the error taxonomy, and how to back off.

HTML version: https://api.nyne.ai/documentation/rate-limits

## The three-tier rate limiter

Requests are counted **per API key** across three windows at once. All three are enforced together, and the **first tier you exceed wins** - a fast burst can trip the burst tier even while you are well under the hourly cap. The caps scale from the key's `rate_limit_per_minute` and `rate_limit_per_hour` (defaults 100/min and 1,000/hour).

| Tier | Window | Default cap | Derived from |
| --- | --- | --- | --- |
| Burst | 10-second window | 49 requests / 10s | int(perMinute x 10/60 x 3) |
| Sustained | 5-minute rolling window | 500 requests / 5min | perMinute x 5 |
| Hourly | 1-hour window | 1,000 requests / hour | perHour |

The burst cap is about 3x your per-minute rate spread across a 10-second slice, then floored: at the default 100/min the float math (100 x 10/60 x 3 = 49.9...) truncates down to `49`, not 50. If you fan out requests in parallel, pace them: hitting the burst tier returns `429` even when your minute and hour budgets are untouched.

## The monthly quota

On top of the per-second and per-hour rate limits, each key has a **monthly request quota** - a ceiling on how many requests it can make in a billing month. The rate limiter smooths traffic over short windows; the quota caps total volume over the month. You can exhaust the quota without ever tripping a rate tier, and when you do, requests fail with `monthly_limit_exceeded` until the quota resets or you raise it.

The quota counts *requests*; credits meter *results*. A key can have quota left but be out of credits, or the reverse. See the [Credits guide](https://api.nyne.ai/documentation/credits.md).

## Response headers to read

Every response carries the live rate-limit and quota counters. Read them proactively - warn or slow down as `Remaining` approaches zero, rather than waiting for the first `429`. Note the two `Reset` conventions: `X-RateLimit-Reset` is an **absolute Unix timestamp**, while `RateLimit-Reset` is **relative seconds from now**.

| Header | Meaning |
| --- | --- |
| X-RateLimit-Limit | Requests allowed in the current window. |
| X-RateLimit-Remaining | Requests left in the current window. |
| X-RateLimit-Reset | When the window resets, as an absolute Unix timestamp. |
| RateLimit-Limit | Same limit, standard-header spelling. |
| RateLimit-Remaining | Same remaining count, standard-header spelling. |
| RateLimit-Reset | Seconds from now until the window resets (relative). |
| Retry-After | Seconds to wait before retrying. Present only after you have been throttled. |
| X-Quota-Limit | Total requests allowed this month. |
| X-Quota-Used | Requests already spent this month. |
| X-Quota-Remaining | Requests left before the monthly quota is exhausted. |
| X-Quota-Reset | When the monthly quota rolls over. |

`Retry-After` appears only when you have been throttled, and it is the server telling you exactly how many seconds to wait. When it is present, use it verbatim - it beats any backoff you compute yourself.

## Error taxonomy

Throttling and access failures use the same uniform envelope as every other reply: `success` is `false`, the detail moves under `error`, and a `timestamp` is always present. Branch on the stable `error.code`, never the human-readable `message`:

```json
{
  "success": false,
  "error": {
    "code": "rate_limit_exceeded",
    "message": "Rate limit exceeded. Retry after the period in the Retry-After header."
  },
  "timestamp": "2026-05-28T18:04:45"
}
```

Each `error.code` maps to an HTTP status, and tells you whether to retry or to fix something first:

| error.code | HTTP | Handling | What to do |
| --- | --- | --- | --- |
| rate_limit_exceeded | 429 | Retryable | Back off and retry; honor Retry-After when present. |
| monthly_limit_exceeded | 429 / 403 | Needs action | Monthly quota exhausted. Wait for the reset or raise the quota. |
| insufficient_credits | 402 | Needs action | Top up credits before retrying. |
| missing_credentials | 401 | Needs action | Send the X-API-Key and X-API-Secret headers. |
| invalid_credentials | 401 | Needs action | Fix or reissue the key and secret. |
| subscription_inactive | 403 | Needs action | Reactivate the subscription behind the key. |
| ip_not_allowed | 403 | Needs action | Allow-list the IP your backend calls from. |
| access_denied | 403 | Needs action | Grant the key access to this product. |
| service_unavailable | 503 | Retryable | Transient outage. Back off and retry the same request. |

Only `429` and `503` are safe to retry unchanged. `monthly_limit_exceeded` can surface as `429` or, on some paths, `403` - either way it means the quota is spent, not that a short wait will help. For the credentials and access codes (`401`/`403`) see the [Authentication guide](https://api.nyne.ai/documentation/authentication.md); for `insufficient_credits` see [Credits](https://api.nyne.ai/documentation/credits.md).

## Recommended client behavior

Build one retry policy and apply it everywhere:

- Retry **only** `429` and `503`, with **exponential backoff** (1s, 2s, 4s, ...) and a capped number of attempts.
- **Always honor `Retry-After`** when it is present - use its value instead of your computed delay.
- **Surface the quota headers**: warn before you hit the wall using `X-RateLimit-Remaining` and `X-Quota-Remaining`.
- Do **not** retry `402`, `401`, or `403` - they need an action (credits, credentials, or access), not another call.

```bash
# Retry 429/503 with backoff; honor Retry-After when the server sends it.
attempt=0
while :; do
  code=$(curl -sS -D headers.txt -o body.json -w '%{http_code}' \
    "https://api.nyne.ai/person/enrichment?request_id=$RID" \
    -H "X-API-Key: $KEY" -H "X-API-Secret: $SECRET")

  case "$code" in
    2*) break ;;                      # done
    429|503)
      retry=$(grep -i '^Retry-After:' headers.txt | tr -d '\r' | awk '{print $2}')
      # Prefer Retry-After; otherwise exponential backoff (1s, 2s, 4s, ...).
      sleep "${retry:-$(( 2 ** attempt ))}"
      attempt=$(( attempt + 1 )) ;;
    401|402|403) echo "not retryable - fix creds/credits/access"; break ;;
    *) echo "unexpected $code"; break ;;
  esac
done
```

Every poll for an async result is a request, so the same tiers and quota apply while you wait. Space your polls (roughly once a second) and honor `Retry-After` there too. See [Async requests](https://api.nyne.ai/documentation/async.md).

## What's next

- [Credits](https://api.nyne.ai/documentation/credits.md) - how usage is metered and when a request consumes a credit.
- [Authentication](https://api.nyne.ai/documentation/authentication.md) - keys, secrets, IP-locking, and the auth error codes.
- [Async requests](https://api.nyne.ai/documentation/async.md) - the submit-and-poll lifecycle that must respect these limits.
- [Responses](https://api.nyne.ai/documentation/responses.md) - the uniform envelope every reply shares.

---

Source: https://api.nyne.ai/documentation/evaluating.md

# How to evaluate the Nyne enrichment APIs

> A practical, honest-tradeoffs guide to benchmarking the Nyne.ai person and company enrichment, lookup-fields, and search APIs before you trust them in production: fair ground truth, the dimensions that matter (accuracy, coverage, latency, freshness, cost), and a repeatable workflow that changes one knob at a time.

HTML version: https://api.nyne.ai/documentation/evaluating

## Start simple, stay fair

The golden rule of evaluation: **baseline one endpoint at one depth against a fixed dataset before you touch a single feature toggle.** Get a clean, boring number first. Then, and only then, start changing things - one knob per run.

The most common way to get a misleading result is to compare depths on unequal footing: pitting `fast` latency against `deep` coverage, for example. Those are two different questions. Hold everything else constant and change one variable at a time, or you will not be able to say which change caused which shift in the numbers.

```bash
curl -X POST https://api.nyne.ai/person/enrichment \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "X-API-Secret: YOUR_API_SECRET" \
  -H "Content-Type: application/json" \
  -d '{ "email": "jane.doe@acme.com", "lookup_mode": "fast" }'
```

**One knob at a time.** A run is only comparable to the run before it if exactly one thing changed. Move `lookup_mode` from `fast` to `balanced`, or flip `high_freshness` on - but never both in the same step, and never against a different dataset.

## The dimensions that matter

"Is it any good?" is not measurable. These four dimensions are. Track each one separately - a single blended score hides the tradeoffs you are trying to see.

| Dimension | What to measure | Nyne specifics |
| --- | --- | --- |
| Accuracy & coverage | Per-field hit rate (email, phone, LinkedIn/social, title, company, location); recall vs precision. | Recall and precision shift with depth: deeper modes surface more fields but can admit lower-confidence ones. Set a confidence bar per field. |
| Latency | End-to-end time, including the async submit and poll round trip - not just server time. | Varies by lookup_mode (fast / balanced / deep) and search type (light / medium / premium). Measure the whole submit-then-poll loop. |
| Freshness | How recent the returned data is, and where coverage thins out. | The search high_freshness toggle trades speed for recency. Report coverage gaps honestly rather than averaging them away. |
| Cost | Credits per call: per-call fixed vs per-result, and how toggles move the bill. | Search and employees preflight against credits x limit, then charge credits x results returned; result options change the per-result unit cost. |

On **latency**, measure the whole round trip. Real endpoints are asynchronous: you submit, get a `request_id`, and poll until the result is ready. Server compute time is only part of what your users feel - the submit-then-poll loop is the number that matters. See [Async requests](https://api.nyne.ai/documentation/async.md) and [Request depth](https://api.nyne.ai/documentation/request-depth.md) for how `lookup_mode` and search `type` move both coverage and time.

On **cost**, remember there are two shapes. Enrichment is largely per-call; search and employees are per-result. The preflight ceiling is `credits x limit`, while the final charge is `credits x results returned`. Feature toggles like `show_emails`, `show_phone_numbers`, and `insights` change the per-result cost, so record cost per run alongside accuracy. The full rules are in [Credits](https://api.nyne.ai/documentation/credits.md).

## Build fair ground truth

A benchmark is only as honest as the answer key behind it. Use a **labeled test set** of known-correct contacts you already trust - records verified independently of the API you are grading. Measure the API's output against that fixed set, and keep the set unchanged across runs so every result is comparable.

**Do not grade the API against its own output.** The classic trap: you enrich a list, then treat those results as "truth" and re-score the same API against them. That measures consistency, not correctness - the API will always agree with itself. Ground truth has to come from outside the system under test, and the test set must not be one the API was seeded from.

The output of a run is a **scorecard you compute**, not something the API hands back. Keep per-field hit rate, recall, precision, latency, and cost together so no single number gets read in isolation:

```json
{
  "depth": "fast",
  "sample_size": 500,
  "field_hit_rate": {
    "best_business_email": 0.91,
    "fullphone": 0.62,
    "linkedin": 0.88,
    "title": 0.79,
    "location": 0.83
  },
  "precision": 0.94,
  "recall": 0.71,
  "median_latency_ms": 840,
  "credits_per_match": 1
}
```

**Use a repeatable methodology.** The API does not return a benchmark scorecard. Build one from a fair labeled set, then measure one request option at a time. That is what makes any number you report defensible.

## A repeatable workflow

Run these six steps in order. Step 5 loops back through the middle: change one knob, re-read the metrics, record the cost and latency, repeat.

1. **Define scope** - decide what good means for your use case and which fields matter.
2. **Fix the dataset** - pick a labeled test set the API was not seeded from.
3. **Baseline one depth** - run ONE endpoint at ONE depth, toggles off.
4. **Read per-field metrics** - hit rate, recall, precision, by field, not one blended score.
5. **Iterate one knob** - change a single knob, hold everything else constant.
6. **Record all three** - log cost and latency next to accuracy, every run.

## Anti-patterns to avoid

Most bad benchmarks fail the same handful of ways. Each of these quietly inflates or muddies your numbers:

- **Counting ambiguous results as matches.** A low-confidence guess is not a hit. Set a `probability` or confidence bar and score anything below it as a miss. The scoring field is documented in [Responses](https://api.nyne.ai/documentation/responses.md).
- **Comparing depths at different settings.** If `deep` has more toggles on than `fast`, you are comparing two products, not two depths. Change one thing per run.
- **Treating cached responses as fresh trials.** Re-running the exact same input may be served from cache, so it is not an independent sample. Vary the inputs across your test set instead of hammering one record.
- **Conflating the two usage ledgers.** Per-call and per-result charges are metered differently; tallying them as one number will misstate cost. See [Credits](https://api.nyne.ai/documentation/credits.md) for how each is counted.

**A flattering benchmark is a broken one.** If your evaluation always makes the API look great, suspect the evaluation. Fair ground truth and a confidence bar exist precisely to let real gaps show up in the numbers.

## Production-readiness checklist

Once the numbers hold up, lock in the decisions before you ship:

- [ ] Pick a **depth and toggle set** - the `lookup_mode` / search `type` and feature flags your metrics justify.
- [ ] Set a **confidence bar** and enforce it in code, so low-probability results never reach downstream systems as facts.
- [ ] Wire **usage-analytics monitoring** so per-field hit rate and cost stay visible in production, not just in the benchmark.
- [ ] Watch **failure and timeout rates**, and alert when they drift from your baseline.
- [ ] Set a **max-wait and backoff** for polling, so a slow request degrades gracefully instead of hanging your pipeline.

Enforcing the confidence bar in code is a one-liner - do it at the seam where results enter your system:

```python
# Only count matches at or above your confidence bar.
# A low-probability result is a "maybe", not a hit.
match = result.get("probability", 0) >= 0.85
```

## What's next

- [Request depth](https://api.nyne.ai/documentation/request-depth.md) - how `lookup_mode` and search `type` trade coverage against latency and cost.
- [Credits](https://api.nyne.ai/documentation/credits.md) - per-call vs per-result metering and how feature toggles change the bill.
- [Responses](https://api.nyne.ai/documentation/responses.md) - the response shape, the scoring field, and how to read a confidence bar.
- [Effective requests](https://api.nyne.ai/documentation/effective-requests.md) - shaping inputs and toggles to get the coverage you measured for.

---

Source: https://api.nyne.ai/documentation/person.md

# Person APIs

> Resolve anyone from any identifier - then enrich, monitor, and analyze them. Search, verified contact data, social intelligence, and AI research over the same person graph.

- **Auth:** `X-API-Key` + `X-API-Secret` headers
- **Mode:** Most operations are asynchronous - submit returns a `request_id`, normally with `202 Accepted`; poll using that endpoint's documented status path or use a `callback_url` webhook.
- **HTML version:** https://api.nyne.ai/documentation/person

Every Person API starts from the same idea: give us whatever you have - an email address, a phone number, a social profile URL, or just a name and company - and Nyne.ai resolves it to a real person. From there each endpoint returns a different slice of that person: a full merged profile, a verified work email or mobile number, their social accounts and recent posts, or an AI-generated dossier.

Most Person endpoints are asynchronous `POST` requests: the submit returns a `request_id`, normally with `202 Accepted`, and you poll using the status path and page parameters documented for that endpoint. Where supported, a `callback_url` can notify you when queued work finishes; follow the endpoint's retrieval notes. Follow the endpoint's polling table: when `completed` is present on a successful response, `true` is terminal even if the endpoint uses a more specific status such as `exhausted`.

Credits are charged only on meaningful results - an empty result never burns credits. Per-result options (verified emails, phone numbers, AI scoring) carry their own line items, listed on each endpoint's page.

## Endpoints

### Find people

Start from intent instead of an identifier - a natural-language query, keywords, or a triggering event.

- **[Person Search](https://api.nyne.ai/documentation/person/search.md)** - `POST /person/search` - Find people by natural-language query with structured filters.
- **[Discover](https://api.nyne.ai/documentation/person/discover.md)** - `POST /person/discover` - Discover matching people from keywords and location.
- **[Discovery](https://api.nyne.ai/documentation/person/discovery.md)** - `POST /person/discovery` - Discover people from the open web with natural-language queries and match conditions.
- **[Leads](https://api.nyne.ai/documentation/person/leads.md)** - `POST /person/leads` - Generate qualified lead candidates from a natural-language description.
- **[Person Events](https://api.nyne.ai/documentation/person/events.md)** - `POST /person/events` - Retrieve notable life/career events for a person.

### Enrichment & contact data

Turn an identifier into a full profile - or exactly the fields you need, like a verified email or mobile.

- **[Person Enrichment](https://api.nyne.ai/documentation/person/enrichment.md)** - `POST /person/enrichment` - Resolve a full person profile from one or more identifiers.
- **[Lookup Fields](https://api.nyne.ai/documentation/person/lookup-fields.md)** - `POST /person/lookup-fields` - Request specific fields for a person from any identifier.
- **[Email Finder](https://api.nyne.ai/documentation/person/email.md)** - `POST /person/email` - Find a verified business email for a person.
- **[Phone Finder](https://api.nyne.ai/documentation/person/phone.md)** - `POST /person/phone` - Find a phone number for a person.

### Social intelligence

Map a person's social presence: every account, recent posts, who they engage with, and whether an account is real.

- **[Social Profiles](https://api.nyne.ai/documentation/person/social-profiles.md)** - `POST /person/social-profiles` - Find all social media accounts for a person.
- **[Social Lookup](https://api.nyne.ai/documentation/person/social-lookup.md)** - `POST /person/social-lookup` - Resolve a profile on a target platform from another identifier.
- **[Single Social Lookup](https://api.nyne.ai/documentation/person/single-social-lookup.md)** - `POST /person/single-social-lookup` - Resolve a single social profile (alias of social-lookup).
- **[Social Newsfeed](https://api.nyne.ai/documentation/person/newsfeed.md)** - `POST /person/newsfeed` - Pull recent social posts from a person’s resolved profiles.
- **[Social Interactions](https://api.nyne.ai/documentation/person/interactions.md)** - `POST /person/interactions` - Surface a person’s social interactions and engagement.
- **[Competitor Engagements](https://api.nyne.ai/documentation/person/competitor-engagements.md)** - `POST /person/competitor-engagements` - Detect a person’s engagement with competitor content.
- **[Social Account Validator](https://api.nyne.ai/documentation/person/social-account-validator.md)** - `POST /person/social-account-validator` - Validate a public social profile or post and capture a screenshot.

### AI research & analysis

Let the platform read everything for you - research dossiers, interest graphs, press coverage, AI Q&A, and persona simulation.

- **[Deep Research](https://api.nyne.ai/documentation/person/deep-research.md)** - `POST /person/deep-research` - Run an in-depth autonomous research pass on a person.
- **[OSINT Deep Search](https://api.nyne.ai/documentation/person/osint.md)** - `POST /person/osint` - Run an agentic OSINT investigation on a person. Disabled by default - access on request.
- **[Personal Interests](https://api.nyne.ai/documentation/person/interests.md)** - `POST /person/interests` - Infer a person’s interests and affinities.
- **[Article Search](https://api.nyne.ai/documentation/person/articlesearch.md)** - `POST /person/articlesearch` - Find articles and press mentions for a person.
- **[Ask](https://api.nyne.ai/documentation/person/ask.md)** - `POST /person/ask` - Ask a natural-language question about a person.
- **[Simulation](https://api.nyne.ai/documentation/person/simulation.md)** - `POST /person/simulation` - Predict how a person would respond to a question.

## Worked example

The flagship endpoint, [Person Enrichment](https://api.nyne.ai/documentation/person/enrichment), shows the request/poll shape every async Person API shares. Submit any identifier, get a `request_id` back immediately, then poll the same path for the merged profile - usually ready in under a second.

### 1. Submit - `POST /person/enrichment`

```bash
curl -X POST https://api.nyne.ai/person/enrichment \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "X-API-Secret: YOUR_API_SECRET" \
  -H "Content-Type: application/json" \
  -d '{
    "email": "jane.doe@acme.com",
    "name": "Jane Doe",
    "company": "Acme",
    "newsfeed": [
      "linkedin",
      "github"
    ],
    "ai_enhanced_search": true
  }'
```

The call returns `202 Accepted` immediately:

```json
{
  "request_id": "a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4_1717000000_4271",
  "status": "queued"
}
```

### 2. Poll until completed

```bash
curl "https://api.nyne.ai/person/enrichment?request_id=<request_id>" \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "X-API-Secret: YOUR_API_SECRET"
```

When `status` is `completed`, the same response carries the result:

```json
{
  "request_id": "a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4_1717000000_4271",
  "status": "completed",
  "completed": true,
  "result": {
    "displayname": "Jane Doe",
    "firstname": "Jane",
    "lastname": "Doe",
    "headline": "VP of Product at Acme",
    "location": "San Francisco, CA",
    "best_business_email": "jane.doe@acme.com",
    "best_work_email": "jane.doe@acme.com",
    "best_personal_email": "jane@gmail.com",
    "altemails": [
      "jane.doe@acme.com",
      "jane@example.com"
    ],
    "fullphone": [
      {
        "fullphone": "+1-555-123-4567",
        "phone_type": "mobile"
      }
    ],
    "social_profiles": {
      "linkedin": {
        "url": "https://linkedin.com/in/janedoe",
        "followers": 2847
      },
      "twitter": {
        "url": "https://x.com/janedoe",
        "followers": 1234
      }
    },
    "organizations": [
      {
        "name": "Acme",
        "title": "VP of Product",
        "is_current": true
      },
      {
        "name": "StartupXYZ",
        "title": "Product Manager",
        "is_current": false
      }
    ],
    "classifications": {
      "seniority": [
        "vp"
      ],
      "job_functions": [
        "product_management"
      ],
      "employment_types": [
        "full_time"
      ]
    },
    "total_experience_years": 12
  },
  "error": null,
  "created_on": "2026-01-15T10:34:21",
  "completed_on": "2026-01-15T10:35:00"
}
```

## Authentication & credits

All `/person/*` and `/company/*` endpoints authenticate with an API key and secret sent as HTTP headers on every request: `X-API-Key` and `X-API-Secret`. Create keys from your Nyne.ai dashboard and keep the secret server-side. Rate limits: 100 requests/minute, 1,000 requests/hour. Full guide: https://api.nyne.ai/documentation/authentication.md

Credits are charged only on meaningful results - empty results never burn credits. Each endpoint page lists its exact credit costs.

## FAQ

### Which Person API should I start with?

Use Person Enrichment when you already have an identifier, People Search when you need to find people from criteria, and Lookup Fields when you only want selected fields such as emails, phones, work history, or social profiles.

### Can the Person APIs return contact data?

Yes. Person Enrichment, Lookup Fields, Work Email Lookup, and Phone Number Lookup can return contact fields when the data is available and permitted for your use case.

### How do async Person API requests work?

Submit a POST request and store the returned request_id, then poll the endpoint's documented status path with that request_id and any required page parameters. Where supported, callback_url can notify you when queued work finishes, but retain the endpoint's documented GET for recovery and retrieval.

---

All documentation pages are available as Markdown by appending `.md` to their URL. Index: https://api.nyne.ai/llms.txt

---

Source: https://api.nyne.ai/documentation/person/search.md

# Person Search

> Find people by natural-language query with structured filters.

- **Endpoint:** `POST https://api.nyne.ai/person/search`
- **Group:** Person APIs (https://api.nyne.ai/documentation/person.md)
- **Auth:** `X-API-Key` + `X-API-Secret` headers
- **Mode:** Asynchronous - submit returns a `request_id` (normally with `202 Accepted`); poll `GET /person/search?request_id=<request_id>&offset=<offset>&limit=<limit>` with the same auth headers until the endpoint reports a terminal response. Where supported, a `callback_url` can notify you when queued work finishes; follow this endpoint's retrieval notes.
- **HTML version:** https://api.nyne.ai/documentation/person/search

Send one JSON object. `query`, when present, must be a natural-language JSON string, never an object or array. Put exact fields under `custom_filters`. For example, send `{"query":"People currently working at acme.com","limit":1}`, or a filter-only request such as `{"custom_filters":{"companies":["acme.com"]},"limit":25}`. Do not send `{"query":{"company_domain":"acme.com"}}`. Submit each page once. A new search returns `202` plus a `request_id`; a page already cached for that request can return `200` immediately. The POST prepares the page but does not return its result rows. Read the page with `GET /person/search` using that `request_id` and the page's `offset`/`limit`; if POST returned `200`, issue that GET once without entering a polling loop. A processing poll is `202` with `data.completed: false`; a successful terminal poll is `200` with `data.completed: true`. Stop polling whenever `completed` is true, regardless of whether `status` is `completed`, `exhausted`, or `stale`. A bare GET with only `request_id` always reads offset 0; it does not remember the most recently submitted cursor. Polling is free. `callback_url` can notify you after queued session work, but it is not a per-page pagination mechanism: a successful callback is not re-emitted for every later page, and an immediate cached `200` does not enqueue one. Always retain the exact GET retrieval path. Use `/company/employees` for a broad company roster and `/person/search` when role, title, location, or other person criteria matter.

## Authentication

All `/person/*` and `/company/*` endpoints authenticate with an API key and secret sent as HTTP headers on every request: `X-API-Key` and `X-API-Secret`. Create keys from your Nyne.ai dashboard and keep the secret server-side. Rate limits: 100 requests/minute, 1,000 requests/hour. Full guide: https://api.nyne.ai/documentation/authentication.md

## Parameters

| Name | Type | Required | Description | Example |
| --- | --- | --- | --- | --- |
| `query` | string | no | Natural-language JSON string describing who you're looking for (max 1000 chars). It must not be an object, array, or search DSL. Provide a `query` and/or structured `custom_filters` - at least one is required unless paginating with `cursor` or `request_id`. With no `query`, the search runs purely on `custom_filters`. | "Marketing directors at fintech startups in Austin" |
| `limit` | integer | no | Results per page. Default 10; valid values are 1-100. Larger result sets are retrieved by paginating (see Pagination). Values outside the range return HTTP 400. | 10 |
| `show_emails` | boolean | no | Include verified email addresses in each result. | true |
| `show_phone_numbers` | boolean | no | Include phone numbers in each result. | true |
| `require_emails` | boolean | no | Only return people for whom a verified email could be found. | true |
| `require_phone_numbers` | boolean | no | Only return people for whom a phone number could be found. | true |
| `require_phones_or_emails` | boolean | no | Only return people with at least one contact method (email or phone). | true |
| `insights` | boolean | no | Attach AI-generated relevance insights per result. When present, `insights.why_matched` contains concise evidence chips showing the criterion, evidence type, confidence, and a safe short matched phrase when available. Most useful when a `query` is supplied. | true |
| `profile_scoring` | boolean | no | Return a query-fit `score` (integer 1-5) ranking how well each profile matches the query. Most useful when a `query` is supplied. | true |
| `custom_filters` | object | no | Structured filters - `locations`, `titles`, `companies`, `universities`, `degrees`, `specialization_categories`, plus the array filters `industries` (industry names, lowercase; common taxonomy synonyms accepted, e.g. `["fintech","financial services"]`), `keywords` (free-text terms that must each appear in the profile text/skills/interests; multiple keywords are ANDed), and `languages` (spoken languages, 2-3 common forms each, e.g. `["spanish","espanol"]` or `["chinese","mandarin","中文"]`). `companies` matches current employers and accepts company names, domains such as `acme.com`, or company profile URLs. Employer-company filters include `min_company_employee_count`/`max_company_employee_count`, `company_employee_count_scope`, `min_company_total_funding_raised`/`max_company_total_funding_raised`, `company_funding_stages`, `company_latest_funding_stages`, `company_investor_names`, `company_last_funding_after_date`/`company_last_funding_before_date`, `company_funding_round_filters`, and `company_funding_scope`. Each `company_funding_round_filters` item binds its supplied `stages`, `investor_names`, `min_amount`/`max_amount`, `funded_after_date`/`funded_before_date`, and `funded_within_days` to the same funding event. Supports array filters (any-of), numeric ranges, booleans, and exact-match values. | { "locations": ["NYC"], "company_funding_round_filters": [{ "stages": ["series a"], "min_amount": 3000000, "funded_within_days": 30 }], "company_funding_scope": "current" } |
| `cursor` | string | no | Opaque pagination token from a previous response's `next_cursor`. Submit it in a new `POST /person/search` to fetch that page. Preserve the `offset` and `limit` returned by this POST and include them on the GET that polls/retrieves the page. | "eyJvIjo1MCwi…" |
| `offset` | integer | no | Starting position for offset pagination (0-indexed). Default 0; `offset` + `limit` may not exceed 10000. | 0 |
| `request_id` | string | no | ID of an existing search (returned by the first call). Re-send it in a `POST` with a new `offset`/`limit` to fetch another page. Use `GET` with that same `request_id`, `offset`, and `limit` to poll/retrieve the requested page. A bare GET does not launch a page fetch; it reads offset 0. Polling never consumes credits. | "abc12345_1737123456_1234" |
| `callback_url` | string | no | HTTPS URL for a session callback after queued search work. This is not a per-page pagination mechanism: after a successful callback it is not re-emitted for every later page, and an immediately cached page does not enqueue one. Process callbacks idempotently by request_id, and retain the exact request_id/offset/limit GET for recovery and authoritative page retrieval. | "https://example.com/webhooks/nyne" |

## Polling for the result

A newly queued submit normally returns `202 Accepted` with a `request_id`. For People Search, `data.completed` is authoritative for successful responses: keep polling only while it is `false`, and stop whenever it is `true` regardless of the successful `status` value. Any terminal error envelope or non-retriable non-2xx job response also stops that request; transient transport/status-infrastructure responses such as `503` may be retried with backoff. Where supported, pass a `callback_url` on the submit to receive a webhook when queued work finishes; keep the documented GET as a recovery and retrieval path:

```bash
curl "https://api.nyne.ai/person/search?request_id=<request_id>&offset=<offset>&limit=<limit>" \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "X-API-Secret: YOUR_API_SECRET"
```

| Status | Meaning |
| --- | --- |
| processing | HTTP 202 with `completed: false`. The requested page is still being prepared; keep polling. |
| pending / enriching | HTTP 202 with `completed: false`. These non-terminal values can appear only when polling an older request created by the legacy search implementation; keep polling. |
| completed | HTTP 200 with `completed: true`. The requested page is ready. Use `has_more` to decide whether to request another page. |
| exhausted | HTTP 200 with `completed: true`. The search source cannot add more matches. This can still have `has_more: true` when later rows are already stored in the session; `has_more`, not this status word, decides pagination. |
| stale | HTTP 200 with `completed: true`. Cached results are older than 30 days; the response includes a warning and remains a terminal success. |

## Pagination

Each page has two phases: submit exactly one `POST` to fetch/prepare that page, then use `GET` to poll and read that exact slice. POST returns page metadata, not result rows. If POST immediately returns `200` with `completed: true`, skip repeated polling but still issue one GET for the rows. For pages after the first, include the `offset` and `limit` from the page-submit response on every GET. A GET with only `request_id` defaults to offset 0 and therefore re-reads page 1; it neither remembers a cursor POST nor launches a new page fetch. Each successfully fulfilled page POST is billed for results on that page, and replaying an already completed/cached page can charge that page again; GET polling/retrieval is free. `offset + limit` may not exceed 10000.

### Knowing when to paginate

| Response field | Meaning |
| --- | --- |
| completed | The definitive polling signal. `false` means keep polling; `true` means stop polling and consume this page, regardless of whether `status` is `completed`, `exhausted`, or `stale`. |
| status | `processing` is non-terminal. `completed`, `exhausted`, and `stale` are successful terminal states. `exhausted` describes upstream fetchability, not whether the current slice has a cached next page. |
| has_more | `true` means more results are available beyond this page - fetch the next page. `false` means you have reached the end; stop. |
| next_cursor | An opaque token for the next page. Present only when `has_more` is `true` (omitted on the last page). Pass it back as the `cursor` parameter - it already encodes the next `offset`, `limit` and `request_id`. |
| total_estimate | Approximate total number of matches for the query. Use it to size a progress bar or decide how many pages to pull; treat it as an estimate, not an exact count. |
| credits_charged | Credits recorded on this search session's fetch activity. It is not a charge for the current GET, and it is not the authoritative account billing ledger; polling and stored-page reads are free. Use `GET /usage` for account-level consumption. |
| offset / limit | The slice this response represents: results `offset` through `offset + limit - 1`. |

### Fetching the next page

| Method | How |
| --- | --- |
| Cursor (recommended) | Take `next_cursor` from the response and submit `POST /person/search` exactly once with `{"cursor":"..."}` (no other body fields needed). Record the POST response's `request_id`, `offset`, and `limit`. Poll/read that page with `GET /person/search?request_id=...&offset=...&limit=...`. If POST already returned `completed: true`, perform the GET once to read the rows. Repeat the page cycle only while the GET response has `has_more: true`. |
| request_id + offset | Submit the original `request_id` in a new POST with an increasing `offset` and the chosen `limit`. Then poll/read with a GET carrying the same `request_id`, `offset`, and `limit`. |
| Repeat the query + offset | Re-submit the same `query` and identical search options with a higher `offset`. The service matches it to the existing search session. Poll/read with the returned `request_id` and that same `offset`/`limit`. Prefer cursor or request_id when available because they are unambiguous. |

Do not use a bare `GET ?request_id=...` to retrieve a page submitted at a nonzero offset: the GET defaults to offset 0 and will correctly return page 1 with the same first-page cursor. Do not resubmit POST as a status check: an identical POST can become another billable page request. Carry the page's `offset`/`limit` through the complete POST-to-GET lifecycle. Results retain stable positions within the session, and re-reading stored data with GET is free.

## Credit usage

| Item | Credits | Condition |
| --- | --- | --- |
| Person Search | 1 | base credits per result returned |
| Smart Ranking | +1 | per result when profile_scoring: true |
| Candidate Insights | +1 | per result when insights: true |
| Structured Filters | +1 | per result when custom_filters is non-empty |
| Email Data | +6 | per result when show_emails or require_emails is true |
| Phone Data | +6 | per result when show_phone_numbers or require_phone_numbers is true |
| Any Contact Data | +6 | per result when require_phones_or_emails is true and no email/phone add-on is already enabled |

## Responses

| Code | Meaning |
| --- | --- |
| `202` | Search queued or still processing - poll with the returned request_id |
| `200` | Requested page is ready; successful terminal statuses are completed, exhausted, and stale, all with completed: true |
| `400` | Invalid parameters, including an object-valued query or missing search scope |
| `401` | Missing, invalid, or expired API credentials |
| `402` | Insufficient credits |
| `403` | Valid credentials, but the account, plan, product, subscription, or request IP is not allowed |
| `404` | Unknown request_id or a request_id not owned by this API key |
| `429` | Rate or monthly request limit exceeded |
| `500` | The queued search reached a terminal processing error; do not keep polling that request_id |
| `503` | Search or status infrastructure is temporarily unavailable; retry with backoff |

## Example request

### cURL

```bash
curl -X POST https://api.nyne.ai/person/search \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "X-API-Secret: YOUR_API_SECRET" \
  -H "Content-Type: application/json" \
  -d '{
    "query": "Sales managers at Fortune 500 companies in San Francisco",
    "limit": 10,
    "show_emails": true,
    "show_phone_numbers": true,
    "profile_scoring": true,
    "insights": true,
    "custom_filters": {
      "min_company_employee_count": 500,
      "company_investor_names": [
        "Sequoia Capital"
      ],
      "min_company_total_funding_raised": 10000000,
      "company_funding_scope": "current"
    }
  }'
```

### Python

```python
import requests

resp = requests.post(
    "https://api.nyne.ai/person/search",
    headers={
        "X-API-Key": "YOUR_API_KEY",
        "X-API-Secret": "YOUR_API_SECRET",
    },
    json={
        "query": "Sales managers at Fortune 500 companies in San Francisco",
        "limit": 10,
        "show_emails": True,
        "show_phone_numbers": True,
        "profile_scoring": True,
        "insights": True,
        "custom_filters": {
            "min_company_employee_count": 500,
            "company_investor_names": [
                "Sequoia Capital",
            ],
            "min_company_total_funding_raised": 10000000,
            "company_funding_scope": "current",
        },
    },
)
data = resp.json()
print(data)
```

### Node

```javascript
const resp = await fetch("https://api.nyne.ai/person/search", {
  method: "POST",
  headers: {
    "X-API-Key": "YOUR_API_KEY",
    "X-API-Secret": "YOUR_API_SECRET",
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    query: "Sales managers at Fortune 500 companies in San Francisco",
    limit: 10,
    show_emails: true,
    show_phone_numbers: true,
    profile_scoring: true,
    insights: true,
    custom_filters: {
      min_company_employee_count: 500,
      company_investor_names: [
        "Sequoia Capital",
      ],
      min_company_total_funding_raised: 10000000,
      company_funding_scope: "current",
    },
  }),
});
const data = await resp.json();
console.log(data);
```

### PHP

```php
<?php
$ch = curl_init("https://api.nyne.ai/person/search");
curl_setopt_array($ch, [
  CURLOPT_POST => true,
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_HTTPHEADER => [
    "X-API-Key: YOUR_API_KEY",
    "X-API-Secret: YOUR_API_SECRET",
    "Content-Type: application/json",
  ],
  CURLOPT_POSTFIELDS => json_encode([
    "query" => "Sales managers at Fortune 500 companies in San Francisco",
    "limit" => 10,
    "show_emails" => true,
    "show_phone_numbers" => true,
    "profile_scoring" => true,
    "insights" => true,
    "custom_filters" => [
      "min_company_employee_count" => 500,
      "company_investor_names" => [
        "Sequoia Capital",
      ],
      "min_company_total_funding_raised" => 10000000,
      "company_funding_scope" => "current",
    ],
  ]),
]);
$data = json_decode(curl_exec($ch), true);
print_r($data);
```

## Initial 202 response

```json
{
  "request_id": "abc12345_1737123456_1234",
  "status": "processing",
  "completed": false,
  "message": "Search request is being processed. Poll GET /person/search with request_id to check status.",
  "offset": 0,
  "limit": 10
}
```

## Completed poll response

```json
{
  "request_id": "abc12345_1737123456_1234",
  "status": "completed",
  "completed": true,
  "results": [
    {
      "profile_id": "johnsmith",
      "displayname": "John Smith",
      "firstname": "John",
      "middlename": "A",
      "lastname": "Smith",
      "gender": "male",
      "headline": "Senior Sales Manager at Tech Corp",
      "bio": "Enterprise sales leader with 15 years closing Fortune 500 accounts.",
      "location": "San Francisco, CA",
      "altemails": [
        "john.smith@techcorp.com",
        "john.smith@gmail.com"
      ],
      "fullphone": [
        {
          "fullphone": "+1-555-123-4567",
          "phone_type": "mobile"
        }
      ],
      "social_profiles": {
        "linkedin": {
          "url": "https://linkedin.com/in/johnsmith",
          "username": "johnsmith",
          "followers": 1200,
          "connections": 500
        }
      },
      "organizations": [
        {
          "name": "Tech Corp",
          "company_domain": "techcorp.com",
          "company_employee_count": 1200,
          "company_employee_count_range_start": 1001,
          "company_employee_count_range_end": 5000,
          "company_total_funding_raised": 25000000,
          "company_latest_funding_stage": "series b",
          "company_funding_stages": [
            "seed",
            "series a",
            "series b"
          ],
          "company_funding_rounds": [
            {
              "stage": "series b",
              "date": "2025-10-03",
              "amount": 15000000,
              "investor_names": [
                "sequoia capital"
              ]
            }
          ],
          "company_last_funding_date": "2025-10-03",
          "company_investor_names": [
            "sequoia capital"
          ],
          "title": "Senior Sales Manager",
          "startDate": "2020-03",
          "endDate": null
        }
      ],
      "schools_info": [
        {
          "name": "University of California, Berkeley",
          "degree": "BS",
          "specialization_category": "Business",
          "startDate": "2001",
          "endDate": "2005"
        }
      ],
      "skills": [
        "enterprise sales",
        "negotiation"
      ],
      "languages": [
        "english"
      ],
      "estimated_age": 42,
      "score": 5,
      "insights": {
        "overall_summary": "Strong match: senior sales leadership at a large enterprise in the target metro.",
        "why_matched": [
          {
            "criterion": "Sales managers at Fortune 500 companies",
            "evidence_type": "work_experience",
            "confidence": "strong",
            "display_text": "Current role shows senior sales management at Tech Corp.",
            "matched_phrase": "Senior Sales Manager at Tech Corp"
          },
          {
            "criterion": "San Francisco",
            "evidence_type": "location",
            "confidence": "strong",
            "display_text": "Profile location is in the requested metro."
          }
        ],
        "query_insights": [
          {
            "subquery_idx": 0,
            "subquery": "Sales managers at Fortune 500 companies",
            "priority": "Essential",
            "match_level": "Meets Expectations",
            "short_rationale": "Senior Sales Manager at a Fortune 500 company.",
            "rationale": "Currently Senior Sales Manager at Tech Corp, a Fortune 500 enterprise.",
            "short_quotes": [
              "Senior Sales Manager at Tech Corp"
            ]
          }
        ]
      }
    }
  ],
  "offset": 0,
  "limit": 10,
  "total_estimate": 500,
  "has_more": true,
  "next_cursor": "eyJvIjoxMCwiciI6ImFiYzEyMzQ1…",
  "credits_charged": 160
}
```

---

All documentation pages are available as Markdown by appending `.md` to their URL. Index: https://api.nyne.ai/llms.txt

---

Source: https://api.nyne.ai/documentation/person/enrichment.md

# Person Enrichment

> Resolve a full person profile from one or more identifiers.

- **Endpoint:** `POST https://api.nyne.ai/person/enrichment`
- **Group:** Person APIs (https://api.nyne.ai/documentation/person.md)
- **Auth:** `X-API-Key` + `X-API-Secret` headers
- **Mode:** Asynchronous - submit returns a `request_id` (normally with `202 Accepted`); poll `GET /person/enrichment?request_id=<request_id>` with the same auth headers until the endpoint reports a terminal response. Where supported, a `callback_url` can notify you when queued work finishes; follow this endpoint's retrieval notes.
- **HTML version:** https://api.nyne.ai/documentation/person/enrichment

Submit one or more identifiers for a person (email, phone, social profile URL, or name) and receive enriched person data such as contact details, work history, social profiles, education, and location when available. At least one of `email`, `phone`, `social_media_url`, or `name` is required. The request is queued asynchronously and returns a `request_id`; poll the status endpoint or supply a `callback_url`. The completed `result` may include derived `classifications` and, when requested, a `probability` match-confidence field.

## Authentication

All `/person/*` and `/company/*` endpoints authenticate with an API key and secret sent as HTTP headers on every request: `X-API-Key` and `X-API-Secret`. Create keys from your Nyne.ai dashboard and keep the secret server-side. Rate limits: 100 requests/minute, 1,000 requests/hour. Full guide: https://api.nyne.ai/documentation/authentication.md

## Parameters

| Name | Type | Required | Description | Example |
| --- | --- | --- | --- | --- |
| `email` | string | no | Validated for format. | "jane.doe@acme.com" |
| `phone` | string | no | Must normalize to a US 10-digit number or an international E.164 number. | "+1-555-123-4567" |
| `social_media_url` | string | no | Profile URL. | "https://linkedin.com/in/janedoe" |
| `name` | string | no | Person's full name. At least one identifier (email/phone/url/name) is required. | "Jane Doe" |
| `company` | string | no | Employer; aids matching. | "Acme" |
| `city` | string | no | Location-based disambiguation for name lookups (max 100 chars). Common city abbreviations are understood. | "Austin" |
| `callback_url` | string | no | If set, results are POSTed here. Must be a valid HTTP(S) URL on an allowed host when a callback allow-list is configured. | "https://hooks.example.com/enrichment" |
| `newsfeed` | array \| string | no | Social sources to also pull. Choose one or more supported source literals, or the literal `"all"` (cannot be mixed with named sources). | ["linkedin", "github"] |
| `ai_enhanced_search` | boolean | no | Enable AI-assisted search expansion. | true |
| `strict_email_check` | boolean | no | Require stricter email-to-identity confirmation. | false |
| `lite_enrich` | boolean | no | Use the lower-cost lite enrichment option and return a reduced field set. | false |
| `probability_score` | boolean | no | Opt in to match-probability scoring. When available, the result includes a `probability` field (`high`/`medium`/`low`). Use this score as context, not as the sole decision signal. | false |
| `force_organization_refresh` | boolean | no | Force a live refresh of the person's organization (employment) data. By default recently validated organization data is reused to keep responses fast; set this to `true` to re-validate it live and return the most up-to-date company and title. Live validation adds processing time, so enable it only when you specifically need the freshest organization data. | false |
| `required_fields` | array | no | Field names the result must contain to count as a match (case-insensitive). Use the supported field literals shown below. With `lite_enrich`, only core identity, company/title, and primary profile fields are available. | ["current_title", "linkedin"] |

## Polling for the result

A newly queued submit normally returns `202 Accepted` with a `request_id`. Poll the same path until `status` is `completed` (results stay available afterwards). Where supported, pass a `callback_url` on the submit to receive a webhook when queued work finishes; keep the documented GET as a recovery and retrieval path:

```bash
curl "https://api.nyne.ai/person/enrichment?request_id=<request_id>" \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "X-API-Secret: YOUR_API_SECRET"
```

## Credit usage

| Item | Credits | Condition |
| --- | --- | --- |
| Person Enrichment | 6 | Charged only when usable data is returned |
| Lite Enrichment | 3 | lite_enrich: true - fewer credits for a reduced field set |
| No match | 0 | Empty results never burn credits |

## Responses

| Code | Meaning |
| --- | --- |
| `202` | Enrichment queued - poll /person/enrichment with the returned request_id |
| `400` | Malformed JSON, missing identifiers, or an invalid field (e.g. invalid_newsfeed, invalid_required_fields - a field not available in lite mode) |
| `401` | Missing or invalid API credentials |
| `402` | insufficient_credits - not enough credits to complete the request |
| `403` | subscription_required or ip_not_allowed |
| `429` | rate_limit_exceeded |
| `503` | service_unavailable - the API is temporarily unavailable |

## Example request

### cURL

```bash
curl -X POST https://api.nyne.ai/person/enrichment \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "X-API-Secret: YOUR_API_SECRET" \
  -H "Content-Type: application/json" \
  -d '{
    "email": "jane.doe@acme.com",
    "name": "Jane Doe",
    "company": "Acme",
    "newsfeed": [
      "linkedin",
      "github"
    ],
    "ai_enhanced_search": true
  }'
```

### Python

```python
import requests

resp = requests.post(
    "https://api.nyne.ai/person/enrichment",
    headers={
        "X-API-Key": "YOUR_API_KEY",
        "X-API-Secret": "YOUR_API_SECRET",
    },
    json={
        "email": "jane.doe@acme.com",
        "name": "Jane Doe",
        "company": "Acme",
        "newsfeed": [
            "linkedin",
            "github",
        ],
        "ai_enhanced_search": True,
    },
)
data = resp.json()
print(data)
```

### Node

```javascript
const resp = await fetch("https://api.nyne.ai/person/enrichment", {
  method: "POST",
  headers: {
    "X-API-Key": "YOUR_API_KEY",
    "X-API-Secret": "YOUR_API_SECRET",
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    email: "jane.doe@acme.com",
    name: "Jane Doe",
    company: "Acme",
    newsfeed: [
      "linkedin",
      "github",
    ],
    ai_enhanced_search: true,
  }),
});
const data = await resp.json();
console.log(data);
```

### PHP

```php
<?php
$ch = curl_init("https://api.nyne.ai/person/enrichment");
curl_setopt_array($ch, [
  CURLOPT_POST => true,
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_HTTPHEADER => [
    "X-API-Key: YOUR_API_KEY",
    "X-API-Secret: YOUR_API_SECRET",
    "Content-Type: application/json",
  ],
  CURLOPT_POSTFIELDS => json_encode([
    "email" => "jane.doe@acme.com",
    "name" => "Jane Doe",
    "company" => "Acme",
    "newsfeed" => [
      "linkedin",
      "github",
    ],
    "ai_enhanced_search" => true,
  ]),
]);
$data = json_decode(curl_exec($ch), true);
print_r($data);
```

## Example response

```json
{
  "request_id": "a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4_1717000000_4271",
  "status": "completed",
  "completed": true,
  "result": {
    "displayname": "Jane Doe",
    "firstname": "Jane",
    "lastname": "Doe",
    "headline": "VP of Product at Acme",
    "location": "San Francisco, CA",
    "best_business_email": "jane.doe@acme.com",
    "best_work_email": "jane.doe@acme.com",
    "best_personal_email": "jane@gmail.com",
    "altemails": [
      "jane.doe@acme.com",
      "jane@example.com"
    ],
    "fullphone": [
      {
        "fullphone": "+1-555-123-4567",
        "phone_type": "mobile"
      }
    ],
    "social_profiles": {
      "linkedin": {
        "url": "https://linkedin.com/in/janedoe",
        "followers": 2847
      },
      "twitter": {
        "url": "https://x.com/janedoe",
        "followers": 1234
      }
    },
    "organizations": [
      {
        "name": "Acme",
        "title": "VP of Product",
        "is_current": true
      },
      {
        "name": "StartupXYZ",
        "title": "Product Manager",
        "is_current": false
      }
    ],
    "classifications": {
      "seniority": [
        "vp"
      ],
      "job_functions": [
        "product_management"
      ],
      "employment_types": [
        "full_time"
      ]
    },
    "total_experience_years": 12
  },
  "error": null,
  "created_on": "2026-01-15T10:34:21",
  "completed_on": "2026-01-15T10:35:00"
}
```

---

All documentation pages are available as Markdown by appending `.md` to their URL. Index: https://api.nyne.ai/llms.txt

---

Source: https://api.nyne.ai/documentation/person/deep-research.md

# Deep Research

> Run an in-depth autonomous research pass on a person.

- **Endpoint:** `POST https://api.nyne.ai/person/deep-research`
- **Group:** Person APIs (https://api.nyne.ai/documentation/person.md)
- **Auth:** `X-API-Key` + `X-API-Secret` headers
- **Mode:** Asynchronous - submit returns a `request_id` (normally with `202 Accepted`); poll `GET /person/deep-research?request_id=<request_id>` with the same auth headers until the endpoint reports a terminal response. Where supported, a `callback_url` can notify you when queued work finishes; follow this endpoint's retrieval notes.
- **HTML version:** https://api.nyne.ai/documentation/person/deep-research

Generate a comprehensive person intelligence dossier combining enrichment data, social analysis, article mentions, and AI-powered insights in a single call. Requires at least one direct identifier (`email`, `phone`, or `social_media_url`), *or* a `name` together with a `company` or `city`. Deep research can take several minutes; the POST returns a `request_id` that you can poll about every 5 seconds, or you can supply a `callback_url`.

## Authentication

All `/person/*` and `/company/*` endpoints authenticate with an API key and secret sent as HTTP headers on every request: `X-API-Key` and `X-API-Secret`. Create keys from your Nyne.ai dashboard and keep the secret server-side. Rate limits: 100 requests/minute, 1,000 requests/hour. Full guide: https://api.nyne.ai/documentation/authentication.md

## Parameters

| Name | Type | Required | Description | Example |
| --- | --- | --- | --- | --- |
| `email` | string | no | Email identifier. Validated for format. | "jane.doe@acme.com" |
| `phone` | string | no | Phone identifier. Separators are stripped; 7-15 digits with an optional leading `+`. | "+1-555-123-4567" |
| `social_media_url` | string \| array | no | A profile URL from a supported social media site, or an array of up to 3 profile URLs. | "https://linkedin.com/in/janedoe" |
| `name` | string | no | Full name. Requires `company` or `city` when used without a direct identifier. | "Jane Doe" |
| `company` | string | no | Employer; pairs with `name` for name-based search. | "Acme" |
| `city` | string | no | City; pairs with `name`. Truncated to 100 chars. | "Austin" |
| `probability_score` | boolean | no | Include match-probability scoring in the dossier. | false |
| `callback_url` | string | no | If set, the completed result is POSTed here when the job finishes. Must be a valid HTTP(S) URL on an allowed host when a callback allow-list is configured. | "https://hooks.example.com/result" |

## Polling for the result

A newly queued submit normally returns `202 Accepted` with a `request_id`. Poll the same path until `status` is `completed` (results stay available afterwards). Where supported, pass a `callback_url` on the submit to receive a webhook when queued work finishes; keep the documented GET as a recovery and retrieval path:

```bash
curl "https://api.nyne.ai/person/deep-research?request_id=<request_id>" \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "X-API-Secret: YOUR_API_SECRET"
```

## Credit usage

| Item | Credits | Condition |
| --- | --- | --- |
| Deep Research | - | Charged when the research request is accepted |

## Responses

| Code | Meaning |
| --- | --- |
| `200` | Status poll result - returns the current request status and result/error fields when available |
| `202` | Request queued - poll the status endpoint (or wait for the callback) with the returned request_id |
| `400` | Malformed JSON, missing required parameters, or an invalid field |
| `401` | Missing or invalid API credentials |
| `402` | insufficient_credits - not enough credits to complete the request |
| `403` | subscription_required or ip_not_allowed |
| `404` | request_not_found - no matching request is available for this API key |
| `429` | rate_limit_exceeded |
| `503` | service_unavailable - the API is temporarily unavailable |

## Example request

### cURL

```bash
curl -X POST https://api.nyne.ai/person/deep-research \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "X-API-Secret: YOUR_API_SECRET" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Jane Doe",
    "company": "Acme",
    "social_media_url": "https://linkedin.com/in/janedoe"
  }'
```

### Python

```python
import requests

resp = requests.post(
    "https://api.nyne.ai/person/deep-research",
    headers={
        "X-API-Key": "YOUR_API_KEY",
        "X-API-Secret": "YOUR_API_SECRET",
    },
    json={
        "name": "Jane Doe",
        "company": "Acme",
        "social_media_url": "https://linkedin.com/in/janedoe",
    },
)
data = resp.json()
print(data)
```

### Node

```javascript
const resp = await fetch("https://api.nyne.ai/person/deep-research", {
  method: "POST",
  headers: {
    "X-API-Key": "YOUR_API_KEY",
    "X-API-Secret": "YOUR_API_SECRET",
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    name: "Jane Doe",
    company: "Acme",
    social_media_url: "https://linkedin.com/in/janedoe",
  }),
});
const data = await resp.json();
console.log(data);
```

### PHP

```php
<?php
$ch = curl_init("https://api.nyne.ai/person/deep-research");
curl_setopt_array($ch, [
  CURLOPT_POST => true,
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_HTTPHEADER => [
    "X-API-Key: YOUR_API_KEY",
    "X-API-Secret: YOUR_API_SECRET",
    "Content-Type: application/json",
  ],
  CURLOPT_POSTFIELDS => json_encode([
    "name" => "Jane Doe",
    "company" => "Acme",
    "social_media_url" => "https://linkedin.com/in/janedoe",
  ]),
]);
$data = json_decode(curl_exec($ch), true);
print_r($data);
```

## Example response

```json
{
  "request_id": "a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4_1717000000_4271",
  "status": "completed",
  "completed": true,
  "result": {
    "enrichment": {
      "displayname": "Jane Doe",
      "headline": "VP of Product at Acme",
      "organizations": [
        {
          "name": "Acme",
          "title": "VP of Product",
          "is_current": true
        }
      ]
    },
    "articles": {
      "count": 3,
      "articles": [
        {
          "title": "Jane Doe on AI in Product",
          "url": "https://example.com/article"
        }
      ]
    },
    "dossier": {
      "identity_snapshot": {
        "name": "Jane Doe",
        "role": "VP of Product",
        "company": "Acme"
      },
      "career_dna": {
        "trajectory": "Product Manager → VP of Product",
        "superpower": "user empathy"
      },
      "psychographic_profile": {
        "archetypes": [
          "Builder",
          "Connector"
        ],
        "values": [
          "innovation",
          "craft"
        ]
      },
      "key_relationships": [
        {
          "name": "John Smith",
          "handle": "@johnsmith",
          "nature": "former colleague"
        }
      ]
    }
  },
  "completed_on": "2026-01-15T10:45:00Z"
}
```

---

All documentation pages are available as Markdown by appending `.md` to their URL. Index: https://api.nyne.ai/llms.txt

---

Source: https://api.nyne.ai/documentation/person/osint.md

# OSINT Deep Search

> Run an agentic OSINT investigation on a person. Disabled by default - access on request.

- **Endpoint:** `POST https://api.nyne.ai/person/osint`
- **Group:** Person APIs (https://api.nyne.ai/documentation/person.md)
- **Auth:** `X-API-Key` + `X-API-Secret` headers
- **Mode:** Asynchronous - submit returns a `request_id` (normally with `202 Accepted`); poll `GET /person/osint?request_id=<request_id>` with the same auth headers until the endpoint reports a terminal response. Where supported, a `callback_url` can notify you when queued work finishes; follow this endpoint's retrieval notes.
- **Access:** Access required - this endpoint is disabled by default on every account. Request access: mailto:support@nyne.ai?subject=OSINT%20API%20access%20request
- **HTML version:** https://api.nyne.ai/documentation/person/osint

Runs an autonomous OSINT investigation across public sources and reconciles everything it finds into a single person report: identity, aliases, usernames, emails, phones, social accounts (including when an account was created and last seen active, where that is known), employment and education history, locations, websites, public content, public records, corporate roles, adverse findings, images, and wallets. Sections with no findings are omitted. `images` mixes photographs of the subject with reverse-image matches (`reverse_match: true`), and a reverse-image match is a page containing a *similar* image, which is not always the same person - where the faces could be compared, `face_match` reports `match`, `different` or `inconclusive`, with `face_match_score` (0-1) giving the strength of the correspondence. An `inconclusive` match is still returned - a comparison that could not decide is not evidence against the page - so check `face_match` before presenting any match as the subject; an absent `face_match` means no comparison result is available, not a negative result, and an unconfirmed entry carries no `confidence` so the score says none while `face_match` says why. A comparison that concluded the faces are `different` is withheld, because that is a finding rather than an absence of one. Requires at least one direct identifier (`email`, `phone`, `social_media_url`, `username`, or `domain`), *or* a `name` together with a `company` or `city`. `mode` selects how hard the agent works the search (`shallow`, `medium` by default, or `deep`) and therefore what it costs; the retired `depth` parameter is rejected with `400` rather than silently downgraded. A search keeps running server-side for up to 30 minutes, so poll about every 10 seconds or supply a `callback_url`. If that window closes while the run is still working, whatever it had already assessed is returned and billed like any other result - reaching the limit is how depth is bounded, not a failure - including records it had gathered but not yet judged, which arrive as leads at zero confidence with `UNADJUDICATED_CANDIDATES` raised. A run cut short before it had assessed anything at all returns nothing and is reported as failed, because records no adjudication has looked at are not findings about your subject; those are never returned. A `failed` request returns `result` too whenever the run got far enough to produce diagnostics, holding `report_quality` and `reconciliation_summary` and nothing else - so the error is not all you get. It never carries anything about the person: a run that produced data about the subject is a success, so an error and person data never arrive together. A run cut short before adjudication began has no diagnostics either, and then `result` is absent entirely. `result.report_quality` describes the report you are holding so you can filter it in code rather than by eye: `flags` is a list of stable terms naming what is present (`DISPUTED_RECORDS_PRESENT` when an independent review rejected some returned records, `UNCONFIRMED_RECORDS_PRESENT` when review could not confirm them, `UNADJUDICATED_CANDIDATES` when records were gathered that nobody adjudicated - those are returned at the lowest confidence among `emails`, `phones`, `usernames`, `social_profiles`, `locations`, `wallets` and `images`, so treat them as leads - every adjudicated item carries a confidence above zero and every lead carries exactly zero, so `confidence > 0` reliably keeps only the adjudicated results. An item is never scored down for something we merely could not label: an account on a site we cannot name keeps its confidence and reports `platform: unspecified` instead, `ROLES_DERIVED` when a record's category was inferred from its type, `LOW_CONFIDENCE_RECORDS_PRESENT` when some records scored below the floor the policy considers strong and are returned at their own score rather than withheld), sized by `disputed_count` and `unconfirmed_count`. Records are never withheld to express a flag - a disputed record is returned with its confidence capped at 0.1 and an unconfirmed one at 0.35 instead of being removed, so you can filter by score or by term. Zero - or the field being absent, since a zero double is not transmitted - means one thing only: nobody adjudicated the record. `confidence > 0` therefore keeps just the adjudicated results in any JSON consumer, and a strict typed reader should treat a missing confidence as zero. A confirmed record carries the adjudicating model's own confidence, usually well above those caps but not guaranteed to be, so treat the numbers as a scale to threshold on rather than as ranked tiers. A report with no caveats omits `flags` entirely. `resolution_status` says how the investigation ended. `complete` means records were accepted and the report holds findings - it is reported whenever anything was accepted, *including* when the search was cut short by its time budget or salvaged after a failure, so read `unreviewed_count` and `flags` rather than this field to judge how complete the sweep was. `no_match` means the search ran and concluded none of the candidates was the subject - a finding rather than a failure, and not billed when the report holds nothing but that verdict. `budget_exhausted` and `adjudication_failed` both mean nothing was *accepted*. None of these three is decided by `resolution_status` alone: whether a request succeeds, is billed, and answers `200` depends only on whether the report carries data about the person, so a run that gathered leads before it ran out of budget or failed adjudication still returns them, still bills, and still answers `200` - with the leads at zero confidence and `UNADJUDICATED_CANDIDATES` raised. Only a report with nothing in it at all is reported as failed, and that one is never billed. `degraded` means findings alongside candidates never judged either way, which you see on a partially-complete result rather than a finished search, and `unspecified` means the run had not reached a resolution when the result was stored - you see that on a partial salvaged from a search that failed, was cancelled, or was cut short by the poll window partway, where the findings present are still real. **This endpoint is disabled by default for every account** - see Access below before you integrate it.

## Access

OSINT Deep Search is off by default on every account, so there is nothing to test until it is switched on for yours: submits return `403 PRODUCT_NOT_AVAILABLE` and the playground below stays disabled. Request access and we will enable it for your workspace, then the same API key you already use starts working here.

Request access: mailto:support@nyne.ai?subject=OSINT%20API%20access%20request

## Authentication

All `/person/*` and `/company/*` endpoints authenticate with an API key and secret sent as HTTP headers on every request: `X-API-Key` and `X-API-Secret`. Create keys from your Nyne.ai dashboard and keep the secret server-side. Rate limits: 100 requests/minute, 1,000 requests/hour. Full guide: https://api.nyne.ai/documentation/authentication.md

## Parameters

| Name | Type | Required | Description | Example |
| --- | --- | --- | --- | --- |
| `email` | string | no | Email identifier. Validated for format. | "jane.doe@acme.com" |
| `phone` | string | no | Phone identifier. Separators are stripped; 7-15 digits with an optional leading `+`. | "+1-555-123-4567" |
| `social_media_url` | string \| array | no | A LinkedIn, Twitter/X, Instagram, or Facebook profile URL, or an array of up to 3 such URLs (one per platform). Other hosts are rejected with `400`. | "https://linkedin.com/in/janedoe" |
| `username` | string | no | A handle to pivot from, resolved across platforms. | "janedoe" |
| `domain` | string | no | A domain tied to the subject, e.g. a personal site or an employer domain. | "janedoe.dev" |
| `name` | string | no | Full name. Requires `company` or `city` when used without a direct identifier. | "Jane Doe" |
| `company` | string | no | Employer; pairs with `name` for name-based search. | "Acme" |
| `city` | string | no | City; pairs with `name`. Truncated to 100 chars. | "Austin" |
| `mode` | string | no | Search effort tier, and what the request costs: `shallow`, `medium` (default), or `deep`. Case-insensitive; any other value returns `400`. See Credit usage for the per-tier price. | "medium" |
| `callback_url` | string | no | If set, the completed result is POSTed here when the job finishes. Must be a valid HTTP(S) URL on an allowed host when a callback allow-list is configured. | "https://hooks.example.com/result" |

## Polling for the result

A newly queued submit normally returns `202 Accepted` with a `request_id`. Poll the same path until `status` is `completed` (results stay available afterwards). Where supported, pass a `callback_url` on the submit to receive a webhook when queued work finishes; keep the documented GET as a recovery and retrieval path:

```bash
curl "https://api.nyne.ai/person/osint?request_id=<request_id>" \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "X-API-Secret: YOUR_API_SECRET"
```

## Credit usage

| Item | Credits | Condition |
| --- | --- | --- |
| OSINT Deep Search (medium) | 100 | Default mode - charged once, when a report with data is delivered |
| Shallow mode | 50 | Charged instead of the default when mode is shallow |
| Deep mode | 150 | Charged instead of the default when mode is deep |

## Responses

| Code | Meaning |
| --- | --- |
| `200` | Status poll result - returns the current request status, plus the report or error once terminal |
| `202` | Request queued - poll the status endpoint (or wait for the callback) with the returned request_id |
| `400` | INVALID_PARAMETERS - malformed JSON, no usable identifier, an unsupported social URL, an invalid mode, or the retired depth parameter |
| `401` | Missing or invalid API credentials |
| `402` | insufficient_credits - not enough credits for the requested mode |
| `403` | PRODUCT_NOT_AVAILABLE - OSINT is not enabled for this account (request access), or ACCESS_DENIED when the request_id belongs to another API key |
| `404` | NOT_FOUND - no matching request for this request_id |
| `429` | RATE_LIMIT_EXCEEDED |
| `500` | INTERNAL_ERROR - request failed unexpectedly |
| `502` | UPSTREAM_UNAVAILABLE - the OSINT service could not start or track the search |
| `503` | SERVICE_UNAVAILABLE - the endpoint is temporarily unavailable |

## Example request

### cURL

```bash
curl -X POST https://api.nyne.ai/person/osint \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "X-API-Secret: YOUR_API_SECRET" \
  -H "Content-Type: application/json" \
  -d '{
    "email": "jane.doe@acme.com",
    "social_media_url": "https://linkedin.com/in/janedoe",
    "mode": "medium"
  }'
```

### Python

```python
import requests

resp = requests.post(
    "https://api.nyne.ai/person/osint",
    headers={
        "X-API-Key": "YOUR_API_KEY",
        "X-API-Secret": "YOUR_API_SECRET",
    },
    json={
        "email": "jane.doe@acme.com",
        "social_media_url": "https://linkedin.com/in/janedoe",
        "mode": "medium",
    },
)
data = resp.json()
print(data)
```

### Node

```javascript
const resp = await fetch("https://api.nyne.ai/person/osint", {
  method: "POST",
  headers: {
    "X-API-Key": "YOUR_API_KEY",
    "X-API-Secret": "YOUR_API_SECRET",
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    email: "jane.doe@acme.com",
    social_media_url: "https://linkedin.com/in/janedoe",
    mode: "medium",
  }),
});
const data = await resp.json();
console.log(data);
```

### PHP

```php
<?php
$ch = curl_init("https://api.nyne.ai/person/osint");
curl_setopt_array($ch, [
  CURLOPT_POST => true,
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_HTTPHEADER => [
    "X-API-Key: YOUR_API_KEY",
    "X-API-Secret: YOUR_API_SECRET",
    "Content-Type: application/json",
  ],
  CURLOPT_POSTFIELDS => json_encode([
    "email" => "jane.doe@acme.com",
    "social_media_url" => "https://linkedin.com/in/janedoe",
    "mode" => "medium",
  ]),
]);
$data = json_decode(curl_exec($ch), true);
print_r($data);
```

## Initial 202 response

```json
{
  "request_id": "a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4_1717000000_4271",
  "status": "processing",
  "message": "OSINT deep search request submitted. Use GET with request_id to check status.",
  "created_on": "2026-01-15T10:45:02"
}
```

## Completed poll response

```json
{
  "request_id": "a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4_1717000000_4271",
  "status": "completed",
  "completed": true,
  "created_on": "2026-01-15T10:45:02",
  "completed_on": "2026-01-15T10:52:31",
  "result": {
    "identity": {
      "name": "Jane Doe",
      "kind": "person",
      "labels": [
        "product leadership"
      ],
      "confidence": 0.92,
      "identifiers": [
        {
          "value": "jane.doe@acme.com",
          "confidence": 0.95,
          "best": true
        }
      ]
    },
    "aliases": [
      {
        "value": "Jane A. Doe",
        "kind": "legal",
        "confidence": 0.71
      }
    ],
    "usernames": [
      {
        "value": "janedoe",
        "platform": "github",
        "url": "https://github.com/janedoe",
        "confidence": 0.88
      }
    ],
    "emails": [
      {
        "value": "jane.doe@acme.com",
        "kind": "work",
        "verified": true,
        "confidence": 0.95
      }
    ],
    "phones": [
      {
        "value": "+15551234567",
        "kind": "mobile",
        "verified": false,
        "confidence": 0.62
      }
    ],
    "social_profiles": [
      {
        "platform": "linkedin",
        "url": "https://linkedin.com/in/janedoe",
        "username": "janedoe",
        "display_name": "Jane Doe",
        "follower_count": 4200,
        "confidence": 0.93,
        "first_seen": "2026-01-15T10:47:10Z",
        "last_seen": "2026-01-15T10:47:10Z",
        "usage": {
          "created_at": "2011-03-08T00:00:00Z",
          "last_seen_at": "2026-01-10T00:00:00Z"
        },
        "registered": true,
        "verified": false,
        "platform_variables": {
          "headline": "VP of Product at Acme"
        }
      }
    ],
    "employment_history": [
      {
        "company": "Acme",
        "title": "VP of Product",
        "start_date": "2023-04",
        "current": true,
        "confidence": 0.9
      }
    ],
    "education_history": [
      {
        "institution": "State University",
        "degree": "BSc",
        "field": "Computer Science",
        "confidence": 0.7
      }
    ],
    "locations": [
      {
        "city": "Austin",
        "region": "TX",
        "country": "US",
        "current": true,
        "confidence": 0.81
      }
    ],
    "websites": [
      {
        "url": "https://janedoe.dev",
        "title": "Jane Doe",
        "domain": "janedoe.dev",
        "confidence": 0.76
      }
    ],
    "public_content": [
      {
        "title": "Jane Doe on shipping AI products",
        "url": "https://example.com/interview",
        "description": "Interview covering product strategy at Acme.",
        "published_at": "2025-11-02T00:00:00Z",
        "confidence": 0.65
      }
    ],
    "images": [
      {
        "url": "https://records.example/subject.jpg",
        "confidence": 0.9
      },
      {
        "url": "https://social.example/p/abc",
        "source": "social.example",
        "description": "Matched profile page",
        "reverse_match": true,
        "similarity": 94.5,
        "source_image_url": "https://records.example/subject.jpg",
        "thumbnail_url": "https://thumbs.example/abc.jpg",
        "face_match": "match",
        "face_match_score": 0.87,
        "confidence": 0.93
      },
      {
        "url": "https://blog.example/post",
        "source": "blog.example",
        "reverse_match": true,
        "similarity": 71.2,
        "face_match": "different",
        "face_match_score": 0.04,
        "confidence": 0.4
      }
    ],
    "confidence": 0.88,
    "report_quality": {
      "resolution_status": "complete",
      "confidence_semantics": "heuristic_evidence_strength",
      "accepted_evidence_count": 14,
      "unreviewed_count": 2,
      "flags": [
        "UNADJUDICATED_CANDIDATES",
        "UNCONFIRMED_RECORDS_PRESENT"
      ],
      "disputed_count": 0,
      "unconfirmed_count": 3,
      "retry_count": 0,
      "fallback_count": 0,
      "policy_version": "identity-publication-v1"
    }
  }
}
```

---

All documentation pages are available as Markdown by appending `.md` to their URL. Index: https://api.nyne.ai/llms.txt

---

Source: https://api.nyne.ai/documentation/person/interests.md

# Personal Interests

> Infer a person’s interests and affinities.

- **Endpoint:** `POST https://api.nyne.ai/person/interests`
- **Group:** Person APIs (https://api.nyne.ai/documentation/person.md)
- **Auth:** `X-API-Key` + `X-API-Secret` headers
- **Mode:** Asynchronous - submit returns a `request_id` (normally with `202 Accepted`); poll `GET /person/interests?request_id=<request_id>` with the same auth headers until the endpoint reports a terminal response. Where supported, a `callback_url` can notify you when queued work finishes; follow this endpoint's retrieval notes.
- **HTML version:** https://api.nyne.ai/documentation/person/interests

Resolves a person and returns an inferred interest graph (topics, affinities, psychographic signals). At least one of `email`, `phone`, `social_media_url`, or `name` is required. Name-only lookups can match the wrong person - adding `company` and/or a social profile URL improves disambiguation. Only sections with detected signals are included in the response (possible sections: `core_profile`, `location_intelligence`, `cultural_dna`, `psychographics`, `interest_graph`, `brand_affinities`, `professional_ecosystem`, `social_graph_clusters`); empty sections are omitted, and every insight carries a `supporting_accounts` array naming the accounts that justify it. The request is queued and completes asynchronously - supply a `callback_url` or poll the status endpoint with the returned `request_id`.

## Authentication

All `/person/*` and `/company/*` endpoints authenticate with an API key and secret sent as HTTP headers on every request: `X-API-Key` and `X-API-Secret`. Create keys from your Nyne.ai dashboard and keep the secret server-side. Rate limits: 100 requests/minute, 1,000 requests/hour. Full guide: https://api.nyne.ai/documentation/authentication.md

## Parameters

| Name | Type | Required | Description | Example |
| --- | --- | --- | --- | --- |
| `email` | string | no | Email identifier. Validated for format. | "jane.doe@acme.com" |
| `phone` | string | no | Phone identifier. | "+1-555-123-4567" |
| `social_media_url` | string | no | Profile URL; | "https://linkedin.com/in/janedoe" |
| `name` | string | no | Full name. At least one identifier (email/phone/url/name) is required. | "Jane Doe" |
| `company` | string | no | Current company or workplace - disambiguates a name-based lookup. | "Acme" |
| `callback_url` | string | no | If set, the completed result is POSTed here when the job finishes. Must be a valid HTTP(S) URL on an allowed host when a callback allow-list is configured. | "https://hooks.example.com/result" |

## Polling for the result

A newly queued submit normally returns `202 Accepted` with a `request_id`. Poll the same path until `status` is `completed` (results stay available afterwards). Where supported, pass a `callback_url` on the submit to receive a webhook when queued work finishes; keep the documented GET as a recovery and retrieval path:

```bash
curl "https://api.nyne.ai/person/interests?request_id=<request_id>" \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "X-API-Secret: YOUR_API_SECRET"
```

## Credit usage

| Item | Credits | Condition |
| --- | --- | --- |
| Interest Analysis | 5 | Charged on a completed analysis |
| No match | 0 | Empty results never burn credits |

## Responses

| Code | Meaning |
| --- | --- |
| `200` | Status poll result - returns the current request status and result/error fields when available |
| `202` | Request queued - poll the status endpoint (or wait for the callback) with the returned request_id |
| `400` | Malformed JSON, missing required parameters, or an invalid field |
| `401` | Missing or invalid API credentials |
| `402` | insufficient_credits - not enough credits to complete the request |
| `403` | subscription_required or ip_not_allowed |
| `404` | request_not_found - no matching request is available for this API key |
| `429` | rate_limit_exceeded |
| `503` | service_unavailable - the API is temporarily unavailable |

## Example request

### cURL

```bash
curl -X POST https://api.nyne.ai/person/interests \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "X-API-Secret: YOUR_API_SECRET" \
  -H "Content-Type: application/json" \
  -d '{
    "social_media_url": "https://linkedin.com/in/janedoe"
  }'
```

### Python

```python
import requests

resp = requests.post(
    "https://api.nyne.ai/person/interests",
    headers={
        "X-API-Key": "YOUR_API_KEY",
        "X-API-Secret": "YOUR_API_SECRET",
    },
    json={
        "social_media_url": "https://linkedin.com/in/janedoe",
    },
)
data = resp.json()
print(data)
```

### Node

```javascript
const resp = await fetch("https://api.nyne.ai/person/interests", {
  method: "POST",
  headers: {
    "X-API-Key": "YOUR_API_KEY",
    "X-API-Secret": "YOUR_API_SECRET",
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    social_media_url: "https://linkedin.com/in/janedoe",
  }),
});
const data = await resp.json();
console.log(data);
```

### PHP

```php
<?php
$ch = curl_init("https://api.nyne.ai/person/interests");
curl_setopt_array($ch, [
  CURLOPT_POST => true,
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_HTTPHEADER => [
    "X-API-Key: YOUR_API_KEY",
    "X-API-Secret: YOUR_API_SECRET",
    "Content-Type: application/json",
  ],
  CURLOPT_POSTFIELDS => json_encode([
    "social_media_url" => "https://linkedin.com/in/janedoe",
  ]),
]);
$data = json_decode(curl_exec($ch), true);
print_r($data);
```

## Example response

```json
{
  "request_id": "a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4_1717000000_4271",
  "status": "completed",
  "completed": true,
  "result": {
    "core_profile": {
      "archetypes": [
        "Tech Leader",
        "Thought Leader"
      ],
      "supporting_accounts": [
        "@techcrunch",
        "@ycombinator"
      ]
    },
    "interest_graph": {
      "technology": {
        "interests": [
          {
            "topic": "Machine Learning",
            "supporting_accounts": [
              "@exampleai"
            ]
          }
        ]
      },
      "sports_and_fitness": {
        "interests": [
          {
            "activity": "Running",
            "supporting_accounts": [
              "@strava"
            ]
          }
        ]
      }
    },
    "brand_affinities": [
      {
        "category": "Cloud Platforms",
        "brands": [
          "AWS",
          "Google Cloud"
        ]
      }
    ],
    "professional_ecosystem": {
      "industry_focus": [
        "SaaS",
        "Developer Tools"
      ],
      "supporting_accounts": [
        "@github",
        "@stripe"
      ]
    },
    "following_count": 2847
  },
  "completed_on": "2026-01-15T10:31:00Z"
}
```

---

All documentation pages are available as Markdown by appending `.md` to their URL. Index: https://api.nyne.ai/llms.txt

---

Source: https://api.nyne.ai/documentation/person/articlesearch.md

# Article Search

> Find articles and press mentions for a person.

- **Endpoint:** `POST https://api.nyne.ai/person/articlesearch`
- **Group:** Person APIs (https://api.nyne.ai/documentation/person.md)
- **Auth:** `X-API-Key` + `X-API-Secret` headers
- **Mode:** Asynchronous - submit returns a `request_id` (normally with `202 Accepted`); poll `GET /person/articlesearch?request_id=<request_id>` with the same auth headers until the endpoint reports a terminal response. Where supported, a `callback_url` can notify you when queued work finishes; follow this endpoint's retrieval notes.
- **HTML version:** https://api.nyne.ai/documentation/person/articlesearch

Searches for articles, interviews, publications, and press mentions about a specific person. Both `name` and `company` are required; results can be ordered by recency or popularity. Each result carries a content `type` - `article`, `podcast`, `youtube`, or `research_paper`. The request is queued and returns a `request_id` to poll, or a `callback_url` can receive the completed result.

## Authentication

All `/person/*` and `/company/*` endpoints authenticate with an API key and secret sent as HTTP headers on every request: `X-API-Key` and `X-API-Secret`. Create keys from your Nyne.ai dashboard and keep the secret server-side. Rate limits: 100 requests/minute, 1,000 requests/hour. Full guide: https://api.nyne.ai/documentation/authentication.md

## Parameters

| Name | Type | Required | Description | Example |
| --- | --- | --- | --- | --- |
| `name` | string | **yes** | Full name of the person to search for. | "Jane Doe" |
| `company` | string | **yes** | Company the person is associated with - disambiguates common names. | "Acme" |
| `sort` | string | no | Result ordering - `recent` (default) or `popular`. | "recent" |
| `limit` | integer | no | Max articles to return. Default 5, capped at 20. | 10 |
| `callback_url` | string | no | If set, the completed result is POSTed here when the job finishes. Must be a valid HTTP(S) URL on an allowed host when a callback allow-list is configured. | "https://hooks.example.com/result" |

## Polling for the result

A newly queued submit normally returns `202 Accepted` with a `request_id`. Poll the same path until `status` is `completed` (results stay available afterwards). Where supported, pass a `callback_url` on the submit to receive a webhook when queued work finishes; keep the documented GET as a recovery and retrieval path:

```bash
curl "https://api.nyne.ai/person/articlesearch?request_id=<request_id>" \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "X-API-Secret: YOUR_API_SECRET"
```

## Credit usage

| Item | Credits | Condition |
| --- | --- | --- |
| Article Search | - | Charged on a completed search |
| No match | 0 | Empty results never burn credits |

## Responses

| Code | Meaning |
| --- | --- |
| `200` | Status poll result - returns the current request status and result/error fields when available |
| `202` | Request queued - poll the status endpoint (or wait for the callback) with the returned request_id |
| `400` | Malformed JSON, missing required parameters, or an invalid field |
| `401` | Missing or invalid API credentials |
| `402` | insufficient_credits - not enough credits to complete the request |
| `403` | subscription_required or ip_not_allowed |
| `404` | request_not_found - no matching request is available for this API key |
| `429` | rate_limit_exceeded |
| `503` | service_unavailable - the API is temporarily unavailable |

## Example request

### cURL

```bash
curl -X POST https://api.nyne.ai/person/articlesearch \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "X-API-Secret: YOUR_API_SECRET" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Jane Doe",
    "company": "Acme",
    "sort": "recent",
    "limit": 10
  }'
```

### Python

```python
import requests

resp = requests.post(
    "https://api.nyne.ai/person/articlesearch",
    headers={
        "X-API-Key": "YOUR_API_KEY",
        "X-API-Secret": "YOUR_API_SECRET",
    },
    json={
        "name": "Jane Doe",
        "company": "Acme",
        "sort": "recent",
        "limit": 10,
    },
)
data = resp.json()
print(data)
```

### Node

```javascript
const resp = await fetch("https://api.nyne.ai/person/articlesearch", {
  method: "POST",
  headers: {
    "X-API-Key": "YOUR_API_KEY",
    "X-API-Secret": "YOUR_API_SECRET",
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    name: "Jane Doe",
    company: "Acme",
    sort: "recent",
    limit: 10,
  }),
});
const data = await resp.json();
console.log(data);
```

### PHP

```php
<?php
$ch = curl_init("https://api.nyne.ai/person/articlesearch");
curl_setopt_array($ch, [
  CURLOPT_POST => true,
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_HTTPHEADER => [
    "X-API-Key: YOUR_API_KEY",
    "X-API-Secret: YOUR_API_SECRET",
    "Content-Type: application/json",
  ],
  CURLOPT_POSTFIELDS => json_encode([
    "name" => "Jane Doe",
    "company" => "Acme",
    "sort" => "recent",
    "limit" => 10,
  ]),
]);
$data = json_decode(curl_exec($ch), true);
print_r($data);
```

## Example response

```json
{
  "request_id": "d41d8cd98f00b204e9800998ecf8427e_1717000000_4271",
  "status": "completed",
  "completed": true,
  "result": {
    "articles": [
      {
        "title": "Jane Doe on Product Strategy",
        "link": "https://example.com/articles/product-strategy",
        "summary": "Interview about product strategy trends in 2026.",
        "type": "article",
        "keywords": [
          "product management",
          "strategy",
          "SaaS"
        ],
        "date": {
          "year": 2026,
          "month": 1,
          "day": 10
        },
        "sortrank": 1,
        "ranktype": "recent"
      }
    ],
    "count": 1
  },
  "completed_on": "2026-01-15T10:35:00Z"
}
```

---

All documentation pages are available as Markdown by appending `.md` to their URL. Index: https://api.nyne.ai/llms.txt

---

Source: https://api.nyne.ai/documentation/person/newsfeed.md

# Social Newsfeed

> Pull recent social posts from a person’s resolved profiles.

- **Endpoint:** `POST https://api.nyne.ai/person/newsfeed`
- **Group:** Person APIs (https://api.nyne.ai/documentation/person.md)
- **Auth:** `X-API-Key` + `X-API-Secret` headers
- **Mode:** Asynchronous - submit returns a `request_id` (normally with `202 Accepted`); poll `GET /person/newsfeed?request_id=<request_id>` with the same auth headers until the endpoint reports a terminal response. Where supported, a `callback_url` can notify you when queued work finishes; follow this endpoint's retrieval notes.
- **HTML version:** https://api.nyne.ai/documentation/person/newsfeed

Returns recent social posts and engagement data for a profile URL on a supported social media site. The request is queued and returns a `request_id` (status `processing`, or `pending` when a `callback_url` is supplied); poll the status endpoint or wait for the callback.

## Authentication

All `/person/*` and `/company/*` endpoints authenticate with an API key and secret sent as HTTP headers on every request: `X-API-Key` and `X-API-Secret`. Create keys from your Nyne.ai dashboard and keep the secret server-side. Rate limits: 100 requests/minute, 1,000 requests/hour. Full guide: https://api.nyne.ai/documentation/authentication.md

## Parameters

| Name | Type | Required | Description | Example |
| --- | --- | --- | --- | --- |
| `social_media_url` | string | **yes** | Profile URL on a supported social media site. Required. | "https://linkedin.com/in/janedoe" |
| `limit` | integer | no | Number of posts to return. Default 10, must be 1-1000. | 10 |
| `posts_after` | string | no | Only return posts on/after this date. Must be `YYYY-MM-DD`. Posts without a parseable date are always included. | "2025-01-01" |
| `callback_url` | string | no | If set, the completed result is POSTed here when the job finishes. Must be a valid HTTP(S) URL on an allowed host when a callback allow-list is configured. | "https://hooks.example.com/result" |

## Polling for the result

A newly queued submit normally returns `202 Accepted` with a `request_id`. Poll the same path until `status` is `completed` (results stay available afterwards). Where supported, pass a `callback_url` on the submit to receive a webhook when queued work finishes; keep the documented GET as a recovery and retrieval path:

```bash
curl "https://api.nyne.ai/person/newsfeed?request_id=<request_id>" \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "X-API-Secret: YOUR_API_SECRET"
```

## Credit usage

| Item | Credits | Condition |
| --- | --- | --- |
| Newsfeed | 2 | 2 credits per 10 posts returned, rounded up (e.g. 1-10 → 2, 11-20 → 4, up to ~200) |
| No posts | 0 | Credits scale with posts actually returned, not requested |

## Responses

| Code | Meaning |
| --- | --- |
| `200` | Status poll result - returns the current request status and result/error fields when available |
| `202` | Request queued - poll the status endpoint (or wait for the callback) with the returned request_id |
| `400` | Malformed JSON, missing required parameters, or an invalid field |
| `401` | Missing or invalid API credentials |
| `402` | insufficient_credits - not enough credits to complete the request |
| `403` | subscription_required or ip_not_allowed |
| `404` | request_not_found - no matching request is available for this API key |
| `429` | rate_limit_exceeded |
| `503` | service_unavailable - the API is temporarily unavailable |

## Example request

### cURL

```bash
curl -X POST https://api.nyne.ai/person/newsfeed \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "X-API-Secret: YOUR_API_SECRET" \
  -H "Content-Type: application/json" \
  -d '{
    "social_media_url": "https://linkedin.com/in/janedoe",
    "limit": 10,
    "posts_after": "2025-01-01"
  }'
```

### Python

```python
import requests

resp = requests.post(
    "https://api.nyne.ai/person/newsfeed",
    headers={
        "X-API-Key": "YOUR_API_KEY",
        "X-API-Secret": "YOUR_API_SECRET",
    },
    json={
        "social_media_url": "https://linkedin.com/in/janedoe",
        "limit": 10,
        "posts_after": "2025-01-01",
    },
)
data = resp.json()
print(data)
```

### Node

```javascript
const resp = await fetch("https://api.nyne.ai/person/newsfeed", {
  method: "POST",
  headers: {
    "X-API-Key": "YOUR_API_KEY",
    "X-API-Secret": "YOUR_API_SECRET",
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    social_media_url: "https://linkedin.com/in/janedoe",
    limit: 10,
    posts_after: "2025-01-01",
  }),
});
const data = await resp.json();
console.log(data);
```

### PHP

```php
<?php
$ch = curl_init("https://api.nyne.ai/person/newsfeed");
curl_setopt_array($ch, [
  CURLOPT_POST => true,
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_HTTPHEADER => [
    "X-API-Key: YOUR_API_KEY",
    "X-API-Secret: YOUR_API_SECRET",
    "Content-Type: application/json",
  ],
  CURLOPT_POSTFIELDS => json_encode([
    "social_media_url" => "https://linkedin.com/in/janedoe",
    "limit" => 10,
    "posts_after" => "2025-01-01",
  ]),
]);
$data = json_decode(curl_exec($ch), true);
print_r($data);
```

## Example response

```json
{
  "request_id": "newsfeed_a1b2c3d4e5f6a1b2_1717000000_4271",
  "status": "completed",
  "completed": true,
  "result": {
    "url": "https://linkedin.com/in/janedoe",
    "newsfeed": [
      {
        "id": "post_123456",
        "source": "linkedin",
        "content": "Excited to announce our new AI-powered analytics platform!",
        "timestamp": "2026-01-14T15:30:00Z",
        "url": "https://linkedin.com/feed/update/urn:li:activity:123456",
        "likes": 142,
        "comments": 18,
        "shares": 9
      }
    ]
  },
  "completed_on": "2026-01-15T10:35:00Z"
}
```

---

All documentation pages are available as Markdown by appending `.md` to their URL. Index: https://api.nyne.ai/llms.txt

---

Source: https://api.nyne.ai/documentation/person/interactions.md

# Social Interactions

> Surface a person’s social interactions and engagement.

- **Endpoint:** `POST https://api.nyne.ai/person/interactions`
- **Group:** Person APIs (https://api.nyne.ai/documentation/person.md)
- **Auth:** `X-API-Key` + `X-API-Secret` headers
- **Mode:** Asynchronous - submit returns a `request_id` (normally with `202 Accepted`); poll `GET /person/interactions?request_id=<request_id>` with the same auth headers until the endpoint reports a terminal response. Where supported, a `callback_url` can notify you when queued work finishes; follow this endpoint's retrieval notes.
- **HTML version:** https://api.nyne.ai/documentation/person/interactions

Network-intelligence lookup that maps the people a target interacts with on supported social profiles (repliers, followers, following). The platform is inferred from `social_media_url`; supported interaction types include `replies`, `followers`, `following`, and `followers,following`. The request is queued and returns a `request_id` to poll; for large requests prefer a `callback_url`, which receives the completed result. Returned fields vary by interaction type - replies carry `reply_text`/`reply_date`, follower/following entries carry profile fields like `bio`, `followers_count`, `following_count`, and `verified`.

## Authentication

All `/person/*` and `/company/*` endpoints authenticate with an API key and secret sent as HTTP headers on every request: `X-API-Key` and `X-API-Secret`. Create keys from your Nyne.ai dashboard and keep the secret server-side. Rate limits: 100 requests/minute, 1,000 requests/hour. Full guide: https://api.nyne.ai/documentation/authentication.md

## Parameters

| Name | Type | Required | Description | Example |
| --- | --- | --- | --- | --- |
| `social_media_url` | string | **yes** | Supported profile or status URL. The platform, username, and status id are inferred from it. Aliased as `twitter_url`. | "https://x.com/janedoe" |
| `type` | string | **yes** | Interaction type (aliased as `interaction_type`). Supported values: `replies` · `followers` · `following` · `followers,following`. | "followers" |
| `username` | string | no | Handle (leading `@` stripped). Required for follower/following lookups when no URL is given. | "janedoe" |
| `tweet_id` | string | no | Status id for `replies` (10-25 digits). Extracted from a `/status/` URL when present. | "1234567890123456789" |
| `max_results` | integer | no | Result cap. Default 100, clamped to 10-1000. | 100 |
| `callback_url` | string | no | If set, the completed result is POSTed here when the job finishes. Must be a valid HTTP(S) URL on an allowed host when a callback allow-list is configured. | "https://hooks.example.com/result" |

## Polling for the result

A newly queued submit normally returns `202 Accepted` with a `request_id`. Poll the same path until `status` is `completed` (results stay available afterwards). Where supported, pass a `callback_url` on the submit to receive a webhook when queued work finishes; keep the documented GET as a recovery and retrieval path:

```bash
curl "https://api.nyne.ai/person/interactions?request_id=<request_id>" \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "X-API-Secret: YOUR_API_SECRET"
```

## Credit usage

| Item | Credits | Condition |
| --- | --- | --- |
| Network Intelligence Request | 3 | Charged per request |
| No results | 0 | Empty results never burn credits |

## Responses

| Code | Meaning |
| --- | --- |
| `200` | Status poll result - returns the current request status and result/error fields when available |
| `202` | Request queued - poll the status endpoint (or wait for the callback) with the returned request_id |
| `400` | Malformed JSON, missing required parameters, or an invalid field |
| `401` | Missing or invalid API credentials |
| `402` | insufficient_credits - not enough credits to complete the request |
| `403` | subscription_required or ip_not_allowed |
| `404` | request_not_found - no matching request is available for this API key |
| `429` | rate_limit_exceeded |
| `503` | service_unavailable - the API is temporarily unavailable |

## Example request

### cURL

```bash
curl -X POST https://api.nyne.ai/person/interactions \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "X-API-Secret: YOUR_API_SECRET" \
  -H "Content-Type: application/json" \
  -d '{
    "social_media_url": "https://x.com/janedoe",
    "type": "followers",
    "max_results": 100,
    "callback_url": "https://hooks.example.com/interactions"
  }'
```

### Python

```python
import requests

resp = requests.post(
    "https://api.nyne.ai/person/interactions",
    headers={
        "X-API-Key": "YOUR_API_KEY",
        "X-API-Secret": "YOUR_API_SECRET",
    },
    json={
        "social_media_url": "https://x.com/janedoe",
        "type": "followers",
        "max_results": 100,
        "callback_url": "https://hooks.example.com/interactions",
    },
)
data = resp.json()
print(data)
```

### Node

```javascript
const resp = await fetch("https://api.nyne.ai/person/interactions", {
  method: "POST",
  headers: {
    "X-API-Key": "YOUR_API_KEY",
    "X-API-Secret": "YOUR_API_SECRET",
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    social_media_url: "https://x.com/janedoe",
    type: "followers",
    max_results: 100,
    callback_url: "https://hooks.example.com/interactions",
  }),
});
const data = await resp.json();
console.log(data);
```

### PHP

```php
<?php
$ch = curl_init("https://api.nyne.ai/person/interactions");
curl_setopt_array($ch, [
  CURLOPT_POST => true,
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_HTTPHEADER => [
    "X-API-Key: YOUR_API_KEY",
    "X-API-Secret: YOUR_API_SECRET",
    "Content-Type: application/json",
  ],
  CURLOPT_POSTFIELDS => json_encode([
    "social_media_url" => "https://x.com/janedoe",
    "type" => "followers",
    "max_results" => 100,
    "callback_url" => "https://hooks.example.com/interactions",
  ]),
]);
$data = json_decode(curl_exec($ch), true);
print_r($data);
```

## Example response

```json
{
  "request_id": "interaction_a1b2c3d4e5f6a1b2_1717000000_4271",
  "status": "completed",
  "completed": true,
  "result": {
    "interaction_type": "followers",
    "platform": "twitter",
    "target": {
      "username": "janedoe",
      "profile_url": "https://x.com/janedoe"
    },
    "interactions": [
      {
        "username": "john_smith",
        "display_name": "John Smith",
        "profile_url": "https://x.com/john_smith",
        "followers_count": 2134,
        "verified": false
      },
      {
        "username": "alice_j",
        "display_name": "Alice Johnson",
        "profile_url": "https://x.com/alice_j",
        "followers_count": 5678,
        "verified": true
      }
    ],
    "total_count": 2
  },
  "completed_on": "2026-01-15T10:31:00Z"
}
```

---

All documentation pages are available as Markdown by appending `.md` to their URL. Index: https://api.nyne.ai/llms.txt

---

Source: https://api.nyne.ai/documentation/person/competitor-engagements.md

# Competitor Engagements

> Detect a person’s engagement with competitor content.

- **Endpoint:** `POST https://api.nyne.ai/person/competitor-engagements`
- **Group:** Person APIs (https://api.nyne.ai/documentation/person.md)
- **Auth:** `X-API-Key` + `X-API-Secret` headers
- **Mode:** Asynchronous - submit returns a `request_id` (normally with `202 Accepted`); poll `GET /person/competitor-engagements?request_id=<request_id>` with the same auth headers until the endpoint reports a terminal response. Where supported, a `callback_url` can notify you when queued work finishes; follow this endpoint's retrieval notes.
- **HTML version:** https://api.nyne.ai/documentation/person/competitor-engagements

Tracks the social engagements (comments, reactions, interactions) of one or more supported professional profiles to surface warm-lead signals. Accepts up to 50 profile URLs and returns the engagement results. The request is queued and returns a `request_id` to poll, or a `callback_url` receives the completed result.

## Authentication

All `/person/*` and `/company/*` endpoints authenticate with an API key and secret sent as HTTP headers on every request: `X-API-Key` and `X-API-Secret`. Create keys from your Nyne.ai dashboard and keep the secret server-side. Rate limits: 100 requests/minute, 1,000 requests/hour. Full guide: https://api.nyne.ai/documentation/authentication.md

## Parameters

| Name | Type | Required | Description | Example |
| --- | --- | --- | --- | --- |
| `linkedin_urls` | array | **yes** | Array of supported professional profile URLs (`/in/…` or sales-nav profile URLs). Max 50. `linkedin_url` is accepted as a single-value alias. | ["https://linkedin.com/in/janedoe"] |
| `max_items` | integer | no | Max engagement results to return. Default 20, capped at 100. | 20 |
| `callback_url` | string | no | If set, the completed result is POSTed here when the job finishes. Must be a valid HTTP(S) URL on an allowed host when a callback allow-list is configured. | "https://hooks.example.com/result" |

## Polling for the result

A newly queued submit normally returns `202 Accepted` with a `request_id`. Poll the same path until `status` is `completed` (results stay available afterwards). Where supported, pass a `callback_url` on the submit to receive a webhook when queued work finishes; keep the documented GET as a recovery and retrieval path:

```bash
curl "https://api.nyne.ai/person/competitor-engagements?request_id=<request_id>" \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "X-API-Secret: YOUR_API_SECRET"
```

## Credit usage

| Item | Credits | Condition |
| --- | --- | --- |
| Per Engagement Result | 5 | 5 credits per interaction returned |
| No results | 0 | No engagements returned never burns credits |

## Responses

| Code | Meaning |
| --- | --- |
| `200` | Status poll result - returns the current request status and result/error fields when available |
| `202` | Request queued - poll the status endpoint (or wait for the callback) with the returned request_id |
| `400` | Malformed JSON, missing required parameters, or an invalid field |
| `401` | Missing or invalid API credentials |
| `402` | insufficient_credits - not enough credits to complete the request |
| `403` | subscription_required or ip_not_allowed |
| `404` | request_not_found - no matching request is available for this API key |
| `429` | rate_limit_exceeded |
| `503` | service_unavailable - the API is temporarily unavailable |

## Example request

### cURL

```bash
curl -X POST https://api.nyne.ai/person/competitor-engagements \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "X-API-Secret: YOUR_API_SECRET" \
  -H "Content-Type: application/json" \
  -d '{
    "linkedin_urls": [
      "https://linkedin.com/in/janedoe"
    ],
    "max_items": 20
  }'
```

### Python

```python
import requests

resp = requests.post(
    "https://api.nyne.ai/person/competitor-engagements",
    headers={
        "X-API-Key": "YOUR_API_KEY",
        "X-API-Secret": "YOUR_API_SECRET",
    },
    json={
        "linkedin_urls": [
            "https://linkedin.com/in/janedoe",
        ],
        "max_items": 20,
    },
)
data = resp.json()
print(data)
```

### Node

```javascript
const resp = await fetch("https://api.nyne.ai/person/competitor-engagements", {
  method: "POST",
  headers: {
    "X-API-Key": "YOUR_API_KEY",
    "X-API-Secret": "YOUR_API_SECRET",
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    linkedin_urls: [
      "https://linkedin.com/in/janedoe",
    ],
    max_items: 20,
  }),
});
const data = await resp.json();
console.log(data);
```

### PHP

```php
<?php
$ch = curl_init("https://api.nyne.ai/person/competitor-engagements");
curl_setopt_array($ch, [
  CURLOPT_POST => true,
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_HTTPHEADER => [
    "X-API-Key: YOUR_API_KEY",
    "X-API-Secret: YOUR_API_SECRET",
    "Content-Type: application/json",
  ],
  CURLOPT_POSTFIELDS => json_encode([
    "linkedin_urls" => [
      "https://linkedin.com/in/janedoe",
    ],
    "max_items" => 20,
  ]),
]);
$data = json_decode(curl_exec($ch), true);
print_r($data);
```

## Example response

```json
{
  "request_id": "a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4_1717000000_4271",
  "status": "completed",
  "completed": true,
  "result": [
    {
      "linkedin_profile_url": "https://linkedin.com/in/janedoe",
      "actor": {
        "name": "Jane Doe",
        "profile_url": "https://linkedin.com/in/janedoe"
      },
      "interaction_type": "comment",
      "interaction_url": "https://linkedin.com/feed/update/urn:li:activity:abc123",
      "interaction_date": "2026-01-15T08:30:00Z",
      "content": "Great insight on SaaS pricing models.",
      "engagement": {
        "likes": 5,
        "replies": 2
      }
    }
  ],
  "completed_on": "2026-01-15T10:35:00Z"
}
```

---

All documentation pages are available as Markdown by appending `.md` to their URL. Index: https://api.nyne.ai/llms.txt

---

Source: https://api.nyne.ai/documentation/person/events.md

# Person Events

> Retrieve notable life/career events for a person.

- **Endpoint:** `POST https://api.nyne.ai/person/events`
- **Group:** Person APIs (https://api.nyne.ai/documentation/person.md)
- **Auth:** `X-API-Key` + `X-API-Secret` headers
- **Mode:** Asynchronous - submit returns a `request_id` (normally with `202 Accepted`); poll `GET /person/events?request_id=<request_id>` with the same auth headers until the endpoint reports a terminal response. Where supported, a `callback_url` can notify you when queued work finishes; follow this endpoint's retrieval notes.
- **HTML version:** https://api.nyne.ai/documentation/person/events

Event-based contact discovery - finds people linked to a key event (fundraise, conference, product launch, etc.) for timely outreach. `event` is the only required field; the remaining context fields (`company_name`, `location`, `role`, `industry`) narrow the search. The request is queued and returns a `request_id` to poll, or a `callback_url` receives the result.

## Authentication

All `/person/*` and `/company/*` endpoints authenticate with an API key and secret sent as HTTP headers on every request: `X-API-Key` and `X-API-Secret`. Create keys from your Nyne.ai dashboard and keep the secret server-side. Rate limits: 100 requests/minute, 1,000 requests/hour. Full guide: https://api.nyne.ai/documentation/authentication.md

## Parameters

| Name | Type | Required | Description | Example |
| --- | --- | --- | --- | --- |
| `event` | string | **yes** | The event to discover contacts around (e.g. a fundraise, conference, or announcement). Required. | "Series B fundraise" |
| `company_name` | string | no | Narrow to people at this company. | "Acme" |
| `location` | string | no | Narrow by location. | "San Francisco" |
| `role` | string | no | Narrow by job role/title. | "VP Sales" |
| `industry` | string | no | Narrow by industry. | "Fintech" |
| `callback_url` | string | no | If set, the completed result is POSTed here when the job finishes. Must be a valid HTTP(S) URL on an allowed host when a callback allow-list is configured. | "https://hooks.example.com/result" |

## Polling for the result

A newly queued submit normally returns `202 Accepted` with a `request_id`. Poll the same path until `status` is `completed` (results stay available afterwards). Where supported, pass a `callback_url` on the submit to receive a webhook when queued work finishes; keep the documented GET as a recovery and retrieval path:

```bash
curl "https://api.nyne.ai/person/events?request_id=<request_id>" \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "X-API-Secret: YOUR_API_SECRET"
```

## Credit usage

| Item | Credits | Condition |
| --- | --- | --- |
| Events Search | - | Charged upon successful completion |
| No attendees found | - | The search itself is billed: a completed search with no results still consumes credits |

## Responses

| Code | Meaning |
| --- | --- |
| `200` | Status poll result - returns the current request status and result/error fields when available |
| `202` | Request queued - poll the status endpoint (or wait for the callback) with the returned request_id |
| `400` | Malformed JSON, missing required parameters, or an invalid field |
| `401` | Missing or invalid API credentials |
| `402` | insufficient_credits - not enough credits to complete the request |
| `403` | subscription_required or ip_not_allowed |
| `404` | request_not_found - no matching request is available for this API key |
| `429` | rate_limit_exceeded |
| `503` | service_unavailable - the API is temporarily unavailable |

## Example request

### cURL

```bash
curl -X POST https://api.nyne.ai/person/events \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "X-API-Secret: YOUR_API_SECRET" \
  -H "Content-Type: application/json" \
  -d '{
    "event": "Series B fundraise",
    "company_name": "Acme",
    "industry": "Fintech"
  }'
```

### Python

```python
import requests

resp = requests.post(
    "https://api.nyne.ai/person/events",
    headers={
        "X-API-Key": "YOUR_API_KEY",
        "X-API-Secret": "YOUR_API_SECRET",
    },
    json={
        "event": "Series B fundraise",
        "company_name": "Acme",
        "industry": "Fintech",
    },
)
data = resp.json()
print(data)
```

### Node

```javascript
const resp = await fetch("https://api.nyne.ai/person/events", {
  method: "POST",
  headers: {
    "X-API-Key": "YOUR_API_KEY",
    "X-API-Secret": "YOUR_API_SECRET",
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    event: "Series B fundraise",
    company_name: "Acme",
    industry: "Fintech",
  }),
});
const data = await resp.json();
console.log(data);
```

### PHP

```php
<?php
$ch = curl_init("https://api.nyne.ai/person/events");
curl_setopt_array($ch, [
  CURLOPT_POST => true,
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_HTTPHEADER => [
    "X-API-Key: YOUR_API_KEY",
    "X-API-Secret: YOUR_API_SECRET",
    "Content-Type: application/json",
  ],
  CURLOPT_POSTFIELDS => json_encode([
    "event" => "Series B fundraise",
    "company_name" => "Acme",
    "industry" => "Fintech",
  ]),
]);
$data = json_decode(curl_exec($ch), true);
print_r($data);
```

## Example response

```json
{
  "request_id": "a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4_1717000000_4271",
  "status": "completed",
  "completed": true,
  "result": {
    "people": [
      {
        "name": "Jane Doe",
        "title": "Head of Product",
        "company": "Acme",
        "linkedin_url": "https://linkedin.com/in/janedoe",
        "event": "Series B fundraise"
      },
      {
        "name": "John Smith",
        "title": "VP Engineering",
        "company": "Acme",
        "linkedin_url": "https://linkedin.com/in/johnsmith",
        "event": "Series B fundraise"
      }
    ]
  },
  "completed_on": "2026-01-15T10:35:00Z"
}
```

---

All documentation pages are available as Markdown by appending `.md` to their URL. Index: https://api.nyne.ai/llms.txt

---

Source: https://api.nyne.ai/documentation/person/ask.md

# Ask

> Ask a natural-language question about a person.

- **Endpoint:** `POST https://api.nyne.ai/person/ask`
- **Group:** Person APIs (https://api.nyne.ai/documentation/person.md)
- **Auth:** `X-API-Key` + `X-API-Secret` headers
- **Mode:** Asynchronous - submit returns a `request_id` (normally with `202 Accepted`); poll `GET /person/ask?request_id=<request_id>` with the same auth headers until the endpoint reports a terminal response. Where supported, a `callback_url` can notify you when queued work finishes; follow this endpoint's retrieval notes.
- **HTML version:** https://api.nyne.ai/documentation/person/ask

Ask a natural-language question about a person and receive an AI-powered answer. Requires an identifier - at least one of `email`, `phone`, or `social_media_url` - plus a `question` (max 2000 chars). The request is queued and returns a `request_id`; poll the status endpoint or supply a `callback_url`.

## Authentication

All `/person/*` and `/company/*` endpoints authenticate with an API key and secret sent as HTTP headers on every request: `X-API-Key` and `X-API-Secret`. Create keys from your Nyne.ai dashboard and keep the secret server-side. Rate limits: 100 requests/minute, 1,000 requests/hour. Full guide: https://api.nyne.ai/documentation/authentication.md

## Parameters

| Name | Type | Required | Description | Example |
| --- | --- | --- | --- | --- |
| `question` | string | **yes** | The natural-language question to answer. Required, max 2000 characters. | "What is this person’s current role?" |
| `email` | string | no | Email identifier. Validated for format. | "jane.doe@acme.com" |
| `phone` | string | no | Phone identifier. | "+1-555-123-4567" |
| `social_media_url` | string | no | Profile URL; At least one identifier is required. | "https://linkedin.com/in/janedoe" |
| `callback_url` | string | no | If set, the completed result is POSTed here when the job finishes. Must be a valid HTTP(S) URL on an allowed host when a callback allow-list is configured. | "https://hooks.example.com/result" |

## Polling for the result

A newly queued submit normally returns `202 Accepted` with a `request_id`. Poll the same path until `status` is `completed` (results stay available afterwards). Where supported, pass a `callback_url` on the submit to receive a webhook when queued work finishes; keep the documented GET as a recovery and retrieval path:

```bash
curl "https://api.nyne.ai/person/ask?request_id=<request_id>" \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "X-API-Secret: YOUR_API_SECRET"
```

## Credit usage

| Item | Credits | Condition |
| --- | --- | --- |
| Person Ask | 10 | 10 credits per request |
| No match | 0 | Empty results never burn credits |

## Responses

| Code | Meaning |
| --- | --- |
| `200` | Status poll result - returns the current request status and result/error fields when available |
| `202` | Request queued - poll the status endpoint (or wait for the callback) with the returned request_id |
| `400` | Malformed JSON, missing required parameters, or an invalid field |
| `401` | Missing or invalid API credentials |
| `402` | insufficient_credits - not enough credits to complete the request |
| `403` | subscription_required or ip_not_allowed |
| `404` | request_not_found - no matching request is available for this API key |
| `429` | rate_limit_exceeded |
| `503` | service_unavailable - the API is temporarily unavailable |

## Example request

### cURL

```bash
curl -X POST https://api.nyne.ai/person/ask \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "X-API-Secret: YOUR_API_SECRET" \
  -H "Content-Type: application/json" \
  -d '{
    "social_media_url": "https://linkedin.com/in/janedoe",
    "question": "What is this person’s current role and company?"
  }'
```

### Python

```python
import requests

resp = requests.post(
    "https://api.nyne.ai/person/ask",
    headers={
        "X-API-Key": "YOUR_API_KEY",
        "X-API-Secret": "YOUR_API_SECRET",
    },
    json={
        "social_media_url": "https://linkedin.com/in/janedoe",
        "question": "What is this person’s current role and company?",
    },
)
data = resp.json()
print(data)
```

### Node

```javascript
const resp = await fetch("https://api.nyne.ai/person/ask", {
  method: "POST",
  headers: {
    "X-API-Key": "YOUR_API_KEY",
    "X-API-Secret": "YOUR_API_SECRET",
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    social_media_url: "https://linkedin.com/in/janedoe",
    question: "What is this person’s current role and company?",
  }),
});
const data = await resp.json();
console.log(data);
```

### PHP

```php
<?php
$ch = curl_init("https://api.nyne.ai/person/ask");
curl_setopt_array($ch, [
  CURLOPT_POST => true,
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_HTTPHEADER => [
    "X-API-Key: YOUR_API_KEY",
    "X-API-Secret: YOUR_API_SECRET",
    "Content-Type: application/json",
  ],
  CURLOPT_POSTFIELDS => json_encode([
    "social_media_url" => "https://linkedin.com/in/janedoe",
    "question" => "What is this person’s current role and company?",
  ]),
]);
$data = json_decode(curl_exec($ch), true);
print_r($data);
```

## Example response

```json
{
  "request_id": "a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4_1717000000_4271",
  "status": "completed",
  "completed": true,
  "result": {
    "answer": "Jane Doe is currently VP of Product at Acme, where she has led the product organization since 2021."
  },
  "completed_on": "2026-01-15T10:31:00Z"
}
```

---

All documentation pages are available as Markdown by appending `.md` to their URL. Index: https://api.nyne.ai/llms.txt

---

Source: https://api.nyne.ai/documentation/person/leads.md

# Leads

> Generate qualified lead candidates from a natural-language description.

- **Endpoint:** `POST https://api.nyne.ai/person/leads`
- **Group:** Person APIs (https://api.nyne.ai/documentation/person.md)
- **Auth:** `X-API-Key` + `X-API-Secret` headers
- **Mode:** Asynchronous - submit returns a `request_id` (normally with `202 Accepted`); poll `GET /person/leads?request_id=<request_id>` with the same auth headers until the endpoint reports a terminal response. Where supported, a `callback_url` can notify you when queued work finishes; follow this endpoint's retrieval notes.
- **HTML version:** https://api.nyne.ai/documentation/person/leads

Generate qualified lead/prospect candidates from a natural-language `search_description` (10-2000 chars). The request is queued and returns a `request_id`; poll the status endpoint or supply a `callback_url` for delivery.

## Authentication

All `/person/*` and `/company/*` endpoints authenticate with an API key and secret sent as HTTP headers on every request: `X-API-Key` and `X-API-Secret`. Create keys from your Nyne.ai dashboard and keep the secret server-side. Rate limits: 100 requests/minute, 1,000 requests/hour. Full guide: https://api.nyne.ai/documentation/authentication.md

## Parameters

| Name | Type | Required | Description | Example |
| --- | --- | --- | --- | --- |
| `search_description` | string | **yes** | Natural-language description of the leads you want. Required, 10-2000 characters. | "Heads of marketing at Series A SaaS companies in NYC" |
| `callback_url` | string | no | If set, the completed result is POSTed here when the job finishes. Must be a valid HTTP(S) URL on an allowed host when a callback allow-list is configured. | "https://hooks.example.com/result" |

## Polling for the result

A newly queued submit normally returns `202 Accepted` with a `request_id`. Poll the same path until `status` is `completed` (results stay available afterwards). Where supported, pass a `callback_url` on the submit to receive a webhook when queued work finishes; keep the documented GET as a recovery and retrieval path:

```bash
curl "https://api.nyne.ai/person/leads?request_id=<request_id>" \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "X-API-Secret: YOUR_API_SECRET"
```

## Credit usage

| Item | Credits | Condition |
| --- | --- | --- |
| Lead Search | 1 | Charged on successful lead searches |
| No results | 0 | Empty results never burn credits |

## Responses

| Code | Meaning |
| --- | --- |
| `200` | Status poll result - returns the current request status and result/error fields when available |
| `202` | Request queued - poll the status endpoint (or wait for the callback) with the returned request_id |
| `400` | Malformed JSON, missing required parameters, or an invalid field |
| `401` | Missing or invalid API credentials |
| `402` | insufficient_credits - not enough credits to complete the request |
| `403` | subscription_required or ip_not_allowed |
| `404` | request_not_found - no matching request is available for this API key |
| `429` | rate_limit_exceeded |
| `503` | service_unavailable - the API is temporarily unavailable |

## Example request

### cURL

```bash
curl -X POST https://api.nyne.ai/person/leads \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "X-API-Secret: YOUR_API_SECRET" \
  -H "Content-Type: application/json" \
  -d '{
    "search_description": "Heads of marketing at Series A SaaS companies in NYC"
  }'
```

### Python

```python
import requests

resp = requests.post(
    "https://api.nyne.ai/person/leads",
    headers={
        "X-API-Key": "YOUR_API_KEY",
        "X-API-Secret": "YOUR_API_SECRET",
    },
    json={
        "search_description": "Heads of marketing at Series A SaaS companies in NYC",
    },
)
data = resp.json()
print(data)
```

### Node

```javascript
const resp = await fetch("https://api.nyne.ai/person/leads", {
  method: "POST",
  headers: {
    "X-API-Key": "YOUR_API_KEY",
    "X-API-Secret": "YOUR_API_SECRET",
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    search_description: "Heads of marketing at Series A SaaS companies in NYC",
  }),
});
const data = await resp.json();
console.log(data);
```

### PHP

```php
<?php
$ch = curl_init("https://api.nyne.ai/person/leads");
curl_setopt_array($ch, [
  CURLOPT_POST => true,
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_HTTPHEADER => [
    "X-API-Key: YOUR_API_KEY",
    "X-API-Secret: YOUR_API_SECRET",
    "Content-Type: application/json",
  ],
  CURLOPT_POSTFIELDS => json_encode([
    "search_description" => "Heads of marketing at Series A SaaS companies in NYC",
  ]),
]);
$data = json_decode(curl_exec($ch), true);
print_r($data);
```

## Example response

```json
{
  "request_id": "a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4_1717000000_4271",
  "status": "completed",
  "completed": true,
  "result": [
    {
      "platform": "linkedin",
      "post_url": "https://linkedin.com/feed/update/urn:li:activity:987654",
      "post_content": "Just launched our new onboarding flow - 40% faster time-to-value.",
      "post_date": "2026-01-14T14:22:00Z",
      "author": {
        "name": "Jane Doe",
        "username": "janedoe",
        "profile_url": "https://linkedin.com/in/janedoe",
        "headline": "Head of Marketing at Acme",
        "image_url": "https://cdn.example.com/avatars/janedoe.jpg"
      },
      "engagement": {
        "likes": 245,
        "comments": 18,
        "shares": 12
      }
    }
  ],
  "completed_on": "2026-01-15T10:35:00Z"
}
```

---

All documentation pages are available as Markdown by appending `.md` to their URL. Index: https://api.nyne.ai/llms.txt

---

Source: https://api.nyne.ai/documentation/person/discover.md

# Discover

> Discover matching people from keywords and location.

- **Endpoint:** `POST https://api.nyne.ai/person/discover`
- **Group:** Person APIs (https://api.nyne.ai/documentation/person.md)
- **Auth:** `X-API-Key` + `X-API-Secret` headers
- **Mode:** Asynchronous - submit returns a `request_id` (normally with `202 Accepted`); poll `GET /person/discover?request_id=<request_id>` with the same auth headers until the endpoint reports a terminal response. Where supported, a `callback_url` can notify you when queued work finishes; follow this endpoint's retrieval notes.
- **HTML version:** https://api.nyne.ai/documentation/person/discover

Keyword-based people discovery - finds and enriches people matching a keyword query, optionally narrowed by location. Returns names, bios, social profiles, photos, and contact data. `keywords` is required (3-500 chars); `max_results` defaults to 50 and is clamped to 1-100. The request is queued and returns a `request_id`; poll the status endpoint or supply a `callback_url`.

## Authentication

All `/person/*` and `/company/*` endpoints authenticate with an API key and secret sent as HTTP headers on every request: `X-API-Key` and `X-API-Secret`. Create keys from your Nyne.ai dashboard and keep the secret server-side. Rate limits: 100 requests/minute, 1,000 requests/hour. Full guide: https://api.nyne.ai/documentation/authentication.md

## Parameters

| Name | Type | Required | Description | Example |
| --- | --- | --- | --- | --- |
| `keywords` | string | **yes** | Search keywords. Required, 3-500 characters. Deduplicates to the same job for identical keyword sets. | "growth marketing fintech" |
| `location` | string | no | Optional location filter. | "New York, NY" |
| `max_results` | integer | no | Max profiles to return. Default 50, clamped to 1-100. | 50 |
| `callback_url` | string | no | If set, the completed result is POSTed here when the job finishes. Must be a valid HTTP(S) URL on an allowed host when a callback allow-list is configured. | "https://hooks.example.com/result" |

## Polling for the result

A newly queued submit normally returns `202 Accepted` with a `request_id`. Poll the same path until `status` is `completed` (results stay available afterwards). Where supported, pass a `callback_url` on the submit to receive a webhook when queued work finishes; keep the documented GET as a recovery and retrieval path:

```bash
curl "https://api.nyne.ai/person/discover?request_id=<request_id>" \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "X-API-Secret: YOUR_API_SECRET"
```

## Credit usage

| Item | Credits | Condition |
| --- | --- | --- |
| Discovery | - | Charged as profiles are discovered |
| Enrichment | - | Additional - only charged when contact details are actually found |
| No results | 0 | Empty results never burn credits |

## Responses

| Code | Meaning |
| --- | --- |
| `200` | Status poll result - returns the current request status and result/error fields when available |
| `202` | Request queued - poll the status endpoint (or wait for the callback) with the returned request_id |
| `400` | Malformed JSON, missing required parameters, or an invalid field |
| `401` | Missing or invalid API credentials |
| `402` | insufficient_credits - not enough credits to complete the request |
| `403` | subscription_required or ip_not_allowed |
| `404` | request_not_found - no matching request is available for this API key |
| `429` | rate_limit_exceeded |
| `503` | service_unavailable - the API is temporarily unavailable |

## Example request

### cURL

```bash
curl -X POST https://api.nyne.ai/person/discover \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "X-API-Secret: YOUR_API_SECRET" \
  -H "Content-Type: application/json" \
  -d '{
    "keywords": "growth marketing fintech",
    "location": "New York, NY",
    "max_results": 50
  }'
```

### Python

```python
import requests

resp = requests.post(
    "https://api.nyne.ai/person/discover",
    headers={
        "X-API-Key": "YOUR_API_KEY",
        "X-API-Secret": "YOUR_API_SECRET",
    },
    json={
        "keywords": "growth marketing fintech",
        "location": "New York, NY",
        "max_results": 50,
    },
)
data = resp.json()
print(data)
```

### Node

```javascript
const resp = await fetch("https://api.nyne.ai/person/discover", {
  method: "POST",
  headers: {
    "X-API-Key": "YOUR_API_KEY",
    "X-API-Secret": "YOUR_API_SECRET",
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    keywords: "growth marketing fintech",
    location: "New York, NY",
    max_results: 50,
  }),
});
const data = await resp.json();
console.log(data);
```

### PHP

```php
<?php
$ch = curl_init("https://api.nyne.ai/person/discover");
curl_setopt_array($ch, [
  CURLOPT_POST => true,
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_HTTPHEADER => [
    "X-API-Key: YOUR_API_KEY",
    "X-API-Secret: YOUR_API_SECRET",
    "Content-Type: application/json",
  ],
  CURLOPT_POSTFIELDS => json_encode([
    "keywords" => "growth marketing fintech",
    "location" => "New York, NY",
    "max_results" => 50,
  ]),
]);
$data = json_decode(curl_exec($ch), true);
print_r($data);
```

## Example response

```json
{
  "request_id": "a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4_1717000000_4271",
  "status": "completed",
  "completed": true,
  "result": [
    {
      "displayname": "Jane Doe",
      "bio": "Growth marketing lead in fintech, focused on B2B SaaS.",
      "location": "New York, NY",
      "altemails": [
        "jane.doe@acme.com"
      ],
      "fullphone": [
        "+1-555-123-4567"
      ],
      "social_profiles": {
        "linkedin": {
          "url": "https://linkedin.com/in/janedoe",
          "photo_url": "https://cdn.example.com/photo.jpg"
        }
      },
      "company": "Acme",
      "work_history": [
        {
          "title": "Growth Marketing Lead",
          "company": "Acme",
          "start_date": "2023-04"
        }
      ]
    }
  ],
  "completed_on": "2026-01-15T10:35:00Z"
}
```

---

All documentation pages are available as Markdown by appending `.md` to their URL. Index: https://api.nyne.ai/llms.txt

---

Source: https://api.nyne.ai/documentation/person/discovery.md

# Discovery

> Discover people from the open web with natural-language queries and match conditions.

- **Endpoint:** `POST https://api.nyne.ai/person/discovery`
- **Group:** Person APIs (https://api.nyne.ai/documentation/person.md)
- **Auth:** `X-API-Key` + `X-API-Secret` headers
- **Mode:** Asynchronous - submit returns a `request_id` (normally with `202 Accepted`); poll `GET /person/discovery?request_id=<request_id>` with the same auth headers until the endpoint reports a terminal response. Where supported, a `callback_url` can notify you when queued work finishes; follow this endpoint's retrieval notes.
- **HTML version:** https://api.nyne.ai/documentation/person/discovery

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

## Authentication

All `/person/*` and `/company/*` endpoints authenticate with an API key and secret sent as HTTP headers on every request: `X-API-Key` and `X-API-Secret`. Create keys from your Nyne.ai dashboard and keep the secret server-side. Rate limits: 100 requests/minute, 1,000 requests/hour. Full guide: https://api.nyne.ai/documentation/authentication.md

## Parameters

| Name | Type | Required | Description | Example |
| --- | --- | --- | --- | --- |
| `query` | string | **yes** | Natural-language query describing the people to find. Max 2000 characters. | "AI researchers specializing in NLP at top US universities" |
| `requirements` | array | no | Match conditions, each with `name` and `description` (max 20). Each is evaluated independently per candidate with evidence-based reasoning. | [{ "name": "published_papers", "description": "Has published research papers in NLP" }] |
| `extract` | array | no | Enrichment fields to extract per matched person, each with `name` and `description` (max 10). | [{ "name": "email", "description": "Professional email address" }] |
| `limit` | integer | no | Maximum results to return. Range 5-100, default 10. | 10 |
| `quality` | string | no | Quality tier - `basic` (fastest) · `standard` (default) · `premium` (most thorough). | "standard" |
| `exclude` | array | no | Entities to exclude from results, each with `name` and `url` (max 100). | [{ "name": "Jane Doe", "url": "janedoe.com" }] |
| `metadata` | object | no | Pass-through metadata returned with the results. Values must be string, number, or boolean. | { "campaign": "outreach-q1" } |
| `callback_url` | string | no | If set, the completed result is POSTed here when the job finishes. Must be a valid HTTP(S) URL on an allowed host when a callback allow-list is configured. | "https://hooks.example.com/result" |

## Polling for the result

A newly queued submit normally returns `202 Accepted` with a `request_id`. Poll the same path until `status` is `completed` (results stay available afterwards). Where supported, pass a `callback_url` on the submit to receive a webhook when queued work finishes; keep the documented GET as a recovery and retrieval path:

```bash
curl "https://api.nyne.ai/person/discovery?request_id=<request_id>" \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "X-API-Secret: YOUR_API_SECRET"
```

## Credit usage

| Item | Credits | Condition |
| --- | --- | --- |
| Discovery Request | 10 | Fixed per request, regardless of the number of results returned |

## Responses

| Code | Meaning |
| --- | --- |
| `202` | Discovery request accepted and queued for processing |
| `400` | INVALID_PARAMETERS / MISSING_PARAMETER |
| `401` | AUTHENTICATION_FAILED - invalid or missing API credentials |
| `402` | INSUFFICIENT_CREDITS - requires 10 credits |
| `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 |

## Example request

### cURL

```bash
curl -X POST https://api.nyne.ai/person/discovery \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "X-API-Secret: YOUR_API_SECRET" \
  -H "Content-Type: application/json" \
  -d '{
    "query": "AI researchers specializing in NLP at top US universities",
    "requirements": [
      {
        "name": "published_papers",
        "description": "Has published research papers in NLP"
      }
    ],
    "extract": [
      {
        "name": "email",
        "description": "Professional email address"
      }
    ],
    "limit": 10,
    "quality": "standard"
  }'
```

### Python

```python
import requests

resp = requests.post(
    "https://api.nyne.ai/person/discovery",
    headers={
        "X-API-Key": "YOUR_API_KEY",
        "X-API-Secret": "YOUR_API_SECRET",
    },
    json={
        "query": "AI researchers specializing in NLP at top US universities",
        "requirements": [
            {
                "name": "published_papers",
                "description": "Has published research papers in NLP",
            },
        ],
        "extract": [
            {
                "name": "email",
                "description": "Professional email address",
            },
        ],
        "limit": 10,
        "quality": "standard",
    },
)
data = resp.json()
print(data)
```

### Node

```javascript
const resp = await fetch("https://api.nyne.ai/person/discovery", {
  method: "POST",
  headers: {
    "X-API-Key": "YOUR_API_KEY",
    "X-API-Secret": "YOUR_API_SECRET",
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    query: "AI researchers specializing in NLP at top US universities",
    requirements: [
      {
        name: "published_papers",
        description: "Has published research papers in NLP",
      },
    ],
    extract: [
      {
        name: "email",
        description: "Professional email address",
      },
    ],
    limit: 10,
    quality: "standard",
  }),
});
const data = await resp.json();
console.log(data);
```

### PHP

```php
<?php
$ch = curl_init("https://api.nyne.ai/person/discovery");
curl_setopt_array($ch, [
  CURLOPT_POST => true,
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_HTTPHEADER => [
    "X-API-Key: YOUR_API_KEY",
    "X-API-Secret: YOUR_API_SECRET",
    "Content-Type: application/json",
  ],
  CURLOPT_POSTFIELDS => json_encode([
    "query" => "AI researchers specializing in NLP at top US universities",
    "requirements" => [
      [
        "name" => "published_papers",
        "description" => "Has published research papers in NLP",
      ],
    ],
    "extract" => [
      [
        "name" => "email",
        "description" => "Professional email address",
      ],
    ],
    "limit" => 10,
    "quality" => "standard",
  ]),
]);
$data = json_decode(curl_exec($ch), true);
print_r($data);
```

## Example response

```json
{
  "request_id": "a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4_1717000000_4271",
  "status": "completed",
  "completed": true,
  "result": {
    "entity_type": "people",
    "query": "AI researchers specializing in NLP at top US universities",
    "results_count": 1,
    "results": [
      {
        "name": "Dr. Jane Smith",
        "url": "janesmith.ai",
        "description": "NLP researcher at Stanford University specializing in large language models",
        "match_status": "matched",
        "evaluations": {
          "published_papers": {
            "value": "yes",
            "matched": true
          }
        },
        "extractions": {
          "email": "jane@stanford.edu"
        },
        "sources": [
          {
            "field": "published_papers",
            "reasoning": "Found multiple publications in top NLP venues including ACL and EMNLP",
            "confidence": "high",
            "citations": [
              {
                "title": "Stanford NLP Lab - Publications",
                "url": "https://nlp.stanford.edu/pubs",
                "excerpts": [
                  "Dr. Smith has published over 30 papers in computational linguistics…"
                ]
              }
            ]
          }
        ]
      }
    ],
    "metrics": {
      "candidates_evaluated": 50,
      "candidates_matched": 10
    }
  },
  "completed_on": "2026-01-15T10:35:00Z"
}
```

---

All documentation pages are available as Markdown by appending `.md` to their URL. Index: https://api.nyne.ai/llms.txt

---

Source: https://api.nyne.ai/documentation/person/simulation.md

# Simulation

> Predict how a person would respond to a question.

- **Endpoint:** `POST https://api.nyne.ai/person/simulation`
- **Group:** Person APIs (https://api.nyne.ai/documentation/person.md)
- **Auth:** `X-API-Key` + `X-API-Secret` headers
- **Mode:** Asynchronous - submit returns a `request_id` (normally with `202 Accepted`); poll `GET /person/simulation?request_id=<request_id>` with the same auth headers until the endpoint reports a terminal response. Where supported, a `callback_url` can notify you when queued work finishes; follow this endpoint's retrieval notes.
- **HTML version:** https://api.nyne.ai/documentation/person/simulation

Runs a persona simulation: predicts how a resolved person would respond to a question, with sentiment and confidence signals. Requires an identifier (`email`, `phone`, or `social_media_url`) and a `question` (max 1000 chars); optional `name`/`company`/`city` sharpen the persona. The request is queued and returns a `request_id` - poll the status endpoint about every 5 seconds or supply a `callback_url`.

## Authentication

All `/person/*` and `/company/*` endpoints authenticate with an API key and secret sent as HTTP headers on every request: `X-API-Key` and `X-API-Secret`. Create keys from your Nyne.ai dashboard and keep the secret server-side. Rate limits: 100 requests/minute, 1,000 requests/hour. Full guide: https://api.nyne.ai/documentation/authentication.md

## Parameters

| Name | Type | Required | Description | Example |
| --- | --- | --- | --- | --- |
| `question` | string | **yes** | The question to simulate a response to. Required, max 1000 characters. | "How would you react to a 20% price increase?" |
| `email` | string | no | Email identifier. Validated for format. | "jane.doe@acme.com" |
| `phone` | string | no | Phone identifier. | "+1-555-123-4567" |
| `social_media_url` | string \| array | no | Profile URL, or an array of up to 3 URLs (one per platform) for faster results. At least one of email/phone/url is required. | "https://linkedin.com/in/janedoe" |
| `name` | string | no | Optional name context. | "Jane Doe" |
| `company` | string | no | Optional employer context. | "Acme" |
| `city` | string | no | Optional location context. | "Austin" |
| `callback_url` | string | no | If set, the completed result is POSTed here when the job finishes. Must be a valid HTTP(S) URL on an allowed host when a callback allow-list is configured. | "https://hooks.example.com/result" |

## Polling for the result

A newly queued submit normally returns `202 Accepted` with a `request_id`. Poll the same path until `status` is `completed` (results stay available afterwards). Where supported, pass a `callback_url` on the submit to receive a webhook when queued work finishes; keep the documented GET as a recovery and retrieval path:

```bash
curl "https://api.nyne.ai/person/simulation?request_id=<request_id>" \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "X-API-Secret: YOUR_API_SECRET"
```

## Credit usage

| Item | Credits | Condition |
| --- | --- | --- |
| Simulation | - | Minimum 10 credits required to submit; charged when processed |
| No match | 0 | Empty results never burn credits |

## Responses

| Code | Meaning |
| --- | --- |
| `200` | Status poll result - returns the current request status and result/error fields when available |
| `202` | Request queued - poll the status endpoint (or wait for the callback) with the returned request_id |
| `400` | Malformed JSON, missing required parameters, or an invalid field |
| `401` | Missing or invalid API credentials |
| `402` | insufficient_credits - not enough credits to complete the request |
| `403` | subscription_required or ip_not_allowed |
| `404` | request_not_found - no matching request is available for this API key |
| `429` | rate_limit_exceeded |
| `503` | service_unavailable - the API is temporarily unavailable |
| `200` | Completed simulation returned inline |

## Example request

### cURL

```bash
curl -X POST https://api.nyne.ai/person/simulation \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "X-API-Secret: YOUR_API_SECRET" \
  -H "Content-Type: application/json" \
  -d '{
    "social_media_url": "https://linkedin.com/in/janedoe",
    "question": "How would you react to a 20% price increase?"
  }'
```

### Python

```python
import requests

resp = requests.post(
    "https://api.nyne.ai/person/simulation",
    headers={
        "X-API-Key": "YOUR_API_KEY",
        "X-API-Secret": "YOUR_API_SECRET",
    },
    json={
        "social_media_url": "https://linkedin.com/in/janedoe",
        "question": "How would you react to a 20% price increase?",
    },
)
data = resp.json()
print(data)
```

### Node

```javascript
const resp = await fetch("https://api.nyne.ai/person/simulation", {
  method: "POST",
  headers: {
    "X-API-Key": "YOUR_API_KEY",
    "X-API-Secret": "YOUR_API_SECRET",
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    social_media_url: "https://linkedin.com/in/janedoe",
    question: "How would you react to a 20% price increase?",
  }),
});
const data = await resp.json();
console.log(data);
```

### PHP

```php
<?php
$ch = curl_init("https://api.nyne.ai/person/simulation");
curl_setopt_array($ch, [
  CURLOPT_POST => true,
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_HTTPHEADER => [
    "X-API-Key: YOUR_API_KEY",
    "X-API-Secret: YOUR_API_SECRET",
    "Content-Type: application/json",
  ],
  CURLOPT_POSTFIELDS => json_encode([
    "social_media_url" => "https://linkedin.com/in/janedoe",
    "question" => "How would you react to a 20% price increase?",
  ]),
]);
$data = json_decode(curl_exec($ch), true);
print_r($data);
```

## Example response

```json
{
  "request_id": "a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4_1717000000_4271",
  "status": "completed",
  "completed": true,
  "result": {
    "at_a_glance": {
      "sentiment": "positive",
      "short_answer": "Likely open to evaluating a cloud-native CRM if integrations and migration are strong.",
      "conviction_level": "moderate",
      "confidence": "high",
      "confidence_reason": "Strong recent social signal directly related to the question topic.",
      "key_drivers": [
        "5+ years in SaaS product leadership",
        "Recent posts about CRM limitations"
      ]
    },
    "is_sufficient_signal": true,
    "simulated_response": "We're always evaluating new tools. Our current solution has reporting gaps - show me better integrations and a faster migration path and I'd be open to a conversation."
  },
  "completed_on": "2026-01-15T10:35:00Z"
}
```

---

All documentation pages are available as Markdown by appending `.md` to their URL. Index: https://api.nyne.ai/llms.txt

---

Source: https://api.nyne.ai/documentation/person/lookup-fields.md

# Lookup Fields

> Request specific fields for a person from any identifier.

- **Endpoint:** `POST https://api.nyne.ai/person/lookup-fields`
- **Group:** Person APIs (https://api.nyne.ai/documentation/person.md)
- **Auth:** `X-API-Key` + `X-API-Secret` headers
- **Mode:** Asynchronous - submit returns a `request_id` (normally with `202 Accepted`); poll `GET /person/lookup-fields?request_id=<request_id>` with the same auth headers until the endpoint reports a terminal response. Where supported, a `callback_url` can notify you when queued work finishes; follow this endpoint's retrieval notes.
- **HTML version:** https://api.nyne.ai/documentation/person/lookup-fields

Targeted lookup: resolve a person from one or more identifiers and return only the `fields` (and/or `profile_urls`) you ask for. Requires at least one of `email`, `phone`, `social_media_url`, or `name`, plus at least one requested field or profile-url key. Credits are billed per requested unit. Use `/person/email` when you only need the best work email, and `/person/phone` when you only need the mobile number. The request is queued and returns a `request_id`; poll the status endpoint or supply a `callback_url`.

## Authentication

All `/person/*` and `/company/*` endpoints authenticate with an API key and secret sent as HTTP headers on every request: `X-API-Key` and `X-API-Secret`. Create keys from your Nyne.ai dashboard and keep the secret server-side. Rate limits: 100 requests/minute, 1,000 requests/hour. Full guide: https://api.nyne.ai/documentation/authentication.md

## Parameters

| Name | Type | Required | Description | Example |
| --- | --- | --- | --- | --- |
| `email` | string | no | Email identifier. `example.com` is rejected as fake/test; lowercased. | "jane.doe@acme.com" |
| `phone` | string | no | Phone identifier. At least 7 digits, ≤50 chars. | "+1-555-123-4567" |
| `social_media_url` | string | no | Profile URL (aliased as `social_url`/`profile_url`/`url`). At least one identifier is required. | "https://linkedin.com/in/janedoe" |
| `name` | string | no | Full name. | "Jane Doe" |
| `company` | string | no | Employer context. | "Acme" |
| `company_domain` | string | no | Company domain; scheme/path/www stripped, must be a bare domain. | "acme.com" |
| `location` | string | no | Free-form location; split into `city`/`state` on the first comma. | "Austin, TX" |
| `state` | string | no | State/region context for a name-based lookup. | "TX" |
| `fields` | array \| string | no | Field names to return (array or comma-separated). Required unless `profile_urls` is supplied. Supported: `displayname`, `firstname`, `lastname`, `best_work_email`, `best_personal_email`, `mobile`, `address`, `location`, `headline`, `current_company`, `current_title`, `photo_url`. The `mobile` selector returns phone data under `result.fullphone`; each phone object uses `phone_type` for classification and does not return a `type` alias. | ["best_work_email", "mobile"] |
| `profile_urls` | array | no | Specific profile-url keys to resolve. Max 10. | ["linkedin"] |
| `probability_score` | boolean | no | Include match-probability scoring. | false |
| `lookup_mode` | string | no | Response-depth preference. Choose based on how long you can wait for the response or callback: `fast` returns sooner with a lighter search, `balanced` allows more time to improve the chance of returning requested fields, and `deep` gives the search the most time for harder-to-find data when omitted. | "balanced" |
| `callback_url` | string | no | If set, the completed result is POSTed here when the job finishes. Must be a valid HTTP(S) URL on an allowed host when a callback allow-list is configured. | "https://hooks.example.com/result" |

## Polling for the result

A newly queued submit normally returns `202 Accepted` with a `request_id`. Poll the same path until `status` is `completed` (results stay available afterwards). Where supported, pass a `callback_url` on the submit to receive a webhook when queued work finishes; keep the documented GET as a recovery and retrieval path:

```bash
curl "https://api.nyne.ai/person/lookup-fields?request_id=<request_id>" \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "X-API-Secret: YOUR_API_SECRET"
```

## Credit usage

| Item | Credits | Condition |
| --- | --- | --- |
| Lookup Fields | - | Billed per requested unit (count of fields + profile_urls) |
| Email field | 1 | /person/email - billed when an email field is requested |
| Phone field | - | /person/phone - billed when a phone field is requested |
| No match | 0 | Empty results never burn credits |

## Responses

| Code | Meaning |
| --- | --- |
| `200` | Status poll result - returns the current request status and result/error fields when available |
| `202` | Request queued - poll the status endpoint (or wait for the callback) with the returned request_id |
| `400` | Malformed JSON, missing required parameters, or an invalid field |
| `401` | Missing or invalid API credentials |
| `402` | insufficient_credits - not enough credits to complete the request |
| `403` | subscription_required or ip_not_allowed |
| `404` | request_not_found - no matching request is available for this API key |
| `429` | rate_limit_exceeded |
| `503` | service_unavailable - the API is temporarily unavailable |
| `404` | not_found - the lookup completed but no matching data exists (a completed response, not a processing failure) |

## Example request

### cURL

```bash
curl -X POST https://api.nyne.ai/person/lookup-fields \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "X-API-Secret: YOUR_API_SECRET" \
  -H "Content-Type: application/json" \
  -d '{
    "email": "jane.doe@acme.com",
    "fields": [
      "best_work_email",
      "mobile",
      "current_title"
    ],
    "lookup_mode": "balanced"
  }'
```

### Python

```python
import requests

resp = requests.post(
    "https://api.nyne.ai/person/lookup-fields",
    headers={
        "X-API-Key": "YOUR_API_KEY",
        "X-API-Secret": "YOUR_API_SECRET",
    },
    json={
        "email": "jane.doe@acme.com",
        "fields": [
            "best_work_email",
            "mobile",
            "current_title",
        ],
        "lookup_mode": "balanced",
    },
)
data = resp.json()
print(data)
```

### Node

```javascript
const resp = await fetch("https://api.nyne.ai/person/lookup-fields", {
  method: "POST",
  headers: {
    "X-API-Key": "YOUR_API_KEY",
    "X-API-Secret": "YOUR_API_SECRET",
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    email: "jane.doe@acme.com",
    fields: [
      "best_work_email",
      "mobile",
      "current_title",
    ],
    lookup_mode: "balanced",
  }),
});
const data = await resp.json();
console.log(data);
```

### PHP

```php
<?php
$ch = curl_init("https://api.nyne.ai/person/lookup-fields");
curl_setopt_array($ch, [
  CURLOPT_POST => true,
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_HTTPHEADER => [
    "X-API-Key: YOUR_API_KEY",
    "X-API-Secret: YOUR_API_SECRET",
    "Content-Type: application/json",
  ],
  CURLOPT_POSTFIELDS => json_encode([
    "email" => "jane.doe@acme.com",
    "fields" => [
      "best_work_email",
      "mobile",
      "current_title",
    ],
    "lookup_mode" => "balanced",
  ]),
]);
$data = json_decode(curl_exec($ch), true);
print_r($data);
```

## Example response

```json
{
  "request_id": "a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4_1717000000_4271",
  "status": "completed",
  "lookup_mode": "balanced",
  "completed": true,
  "result": {
    "best_work_email": "jane.doe@acme.com",
    "fullphone": [
      {
        "fullphone": "+1-555-123-4567",
        "phone_type": "mobile"
      }
    ],
    "organizations": [
      {
        "name": "Acme",
        "title": "Senior Product Manager",
        "is_current": true
      }
    ]
  },
  "completed_on": "2026-01-15T10:31:00Z"
}
```

---

All documentation pages are available as Markdown by appending `.md` to their URL. Index: https://api.nyne.ai/llms.txt

---

Source: https://api.nyne.ai/documentation/person/email.md

# Email Finder

> Find a verified business email for a person.

- **Endpoint:** `POST https://api.nyne.ai/person/email`
- **Group:** Person APIs (https://api.nyne.ai/documentation/person.md)
- **Auth:** `X-API-Key` + `X-API-Secret` headers
- **Mode:** Asynchronous - submit returns a `request_id` (normally with `202 Accepted`); poll `GET /person/email?request_id=<request_id>` with the same auth headers until the endpoint reports a terminal response. Where supported, a `callback_url` can notify you when queued work finishes; follow this endpoint's retrieval notes.
- **HTML version:** https://api.nyne.ai/documentation/person/email

Resolve a person from any identifier (`email`, `phone`, `social_media_url`, or `name`) and get back their best work email. The request is queued and returns a `request_id`; poll the status endpoint or supply a `callback_url`.

## Authentication

All `/person/*` and `/company/*` endpoints authenticate with an API key and secret sent as HTTP headers on every request: `X-API-Key` and `X-API-Secret`. Create keys from your Nyne.ai dashboard and keep the secret server-side. Rate limits: 100 requests/minute, 1,000 requests/hour. Full guide: https://api.nyne.ai/documentation/authentication.md

## Parameters

| Name | Type | Required | Description | Example |
| --- | --- | --- | --- | --- |
| `name` | string | no | Full name. | "Jane Doe" |
| `company` | string | no | Employer - improves match accuracy. | "Acme" |
| `company_domain` | string | no | Company domain (bare host). | "acme.com" |
| `phone` | string | no | Phone identifier. | "+1-555-123-4567" |
| `social_media_url` | string | no | Profile URL. At least one identifier is required. | "https://linkedin.com/in/janedoe" |
| `callback_url` | string | no | If set, the completed result is POSTed here when the job finishes. Must be a valid HTTP(S) URL on an allowed host when a callback allow-list is configured. | "https://hooks.example.com/result" |

## Polling for the result

A newly queued submit normally returns `202 Accepted` with a `request_id`. Poll the same path until `status` is `completed` (results stay available afterwards). Where supported, pass a `callback_url` on the submit to receive a webhook when queued work finishes; keep the documented GET as a recovery and retrieval path:

```bash
curl "https://api.nyne.ai/person/email?request_id=<request_id>" \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "X-API-Secret: YOUR_API_SECRET"
```

## Credit usage

| Item | Credits | Condition |
| --- | --- | --- |
| Email Lookup | 1 | Charged on a found email |
| No match | 0 | Empty results never burn credits |

## Responses

| Code | Meaning |
| --- | --- |
| `200` | Status poll result - returns the current request status and result/error fields when available |
| `202` | Request queued - poll the status endpoint (or wait for the callback) with the returned request_id |
| `400` | Malformed JSON, missing required parameters, or an invalid field |
| `401` | Missing or invalid API credentials |
| `402` | insufficient_credits - not enough credits to complete the request |
| `403` | subscription_required or ip_not_allowed |
| `404` | request_not_found - no matching request is available for this API key |
| `429` | rate_limit_exceeded |
| `503` | service_unavailable - the API is temporarily unavailable |

## Example request

### cURL

```bash
curl -X POST https://api.nyne.ai/person/email \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "X-API-Secret: YOUR_API_SECRET" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Jane Doe",
    "company_domain": "acme.com"
  }'
```

### Python

```python
import requests

resp = requests.post(
    "https://api.nyne.ai/person/email",
    headers={
        "X-API-Key": "YOUR_API_KEY",
        "X-API-Secret": "YOUR_API_SECRET",
    },
    json={
        "name": "Jane Doe",
        "company_domain": "acme.com",
    },
)
data = resp.json()
print(data)
```

### Node

```javascript
const resp = await fetch("https://api.nyne.ai/person/email", {
  method: "POST",
  headers: {
    "X-API-Key": "YOUR_API_KEY",
    "X-API-Secret": "YOUR_API_SECRET",
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    name: "Jane Doe",
    company_domain: "acme.com",
  }),
});
const data = await resp.json();
console.log(data);
```

### PHP

```php
<?php
$ch = curl_init("https://api.nyne.ai/person/email");
curl_setopt_array($ch, [
  CURLOPT_POST => true,
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_HTTPHEADER => [
    "X-API-Key: YOUR_API_KEY",
    "X-API-Secret: YOUR_API_SECRET",
    "Content-Type: application/json",
  ],
  CURLOPT_POSTFIELDS => json_encode([
    "name" => "Jane Doe",
    "company_domain" => "acme.com",
  ]),
]);
$data = json_decode(curl_exec($ch), true);
print_r($data);
```

## Example response

```json
{
  "request_id": "a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4_1717000000_4271",
  "status": "completed",
  "completed": true,
  "result": {
    "best_work_email": "jane.doe@acme.com"
  },
  "completed_on": "2026-01-15T10:31:00Z"
}
```

---

All documentation pages are available as Markdown by appending `.md` to their URL. Index: https://api.nyne.ai/llms.txt

---

Source: https://api.nyne.ai/documentation/person/phone.md

# Phone Finder

> Find a phone number for a person.

- **Endpoint:** `POST https://api.nyne.ai/person/phone`
- **Group:** Person APIs (https://api.nyne.ai/documentation/person.md)
- **Auth:** `X-API-Key` + `X-API-Secret` headers
- **Mode:** Asynchronous - submit returns a `request_id` (normally with `202 Accepted`); poll `GET /person/phone?request_id=<request_id>` with the same auth headers until the endpoint reports a terminal response. Where supported, a `callback_url` can notify you when queued work finishes; follow this endpoint's retrieval notes.
- **HTML version:** https://api.nyne.ai/documentation/person/phone

Resolve a person from any identifier (`email`, `phone`, `social_media_url`, or `name`) and get back their mobile number. The request is queued and returns a `request_id`; poll the status endpoint or supply a `callback_url`.

## Authentication

All `/person/*` and `/company/*` endpoints authenticate with an API key and secret sent as HTTP headers on every request: `X-API-Key` and `X-API-Secret`. Create keys from your Nyne.ai dashboard and keep the secret server-side. Rate limits: 100 requests/minute, 1,000 requests/hour. Full guide: https://api.nyne.ai/documentation/authentication.md

## Parameters

| Name | Type | Required | Description | Example |
| --- | --- | --- | --- | --- |
| `name` | string | no | Full name. | "Jane Doe" |
| `company` | string | no | Employer context. | "Acme" |
| `email` | string | no | Email identifier. | "jane.doe@acme.com" |
| `social_media_url` | string | no | Profile URL. At least one identifier is required. | "https://linkedin.com/in/janedoe" |
| `callback_url` | string | no | If set, the completed result is POSTed here when the job finishes. Must be a valid HTTP(S) URL on an allowed host when a callback allow-list is configured. | "https://hooks.example.com/result" |

## Polling for the result

A newly queued submit normally returns `202 Accepted` with a `request_id`. Poll the same path until `status` is `completed` (results stay available afterwards). Where supported, pass a `callback_url` on the submit to receive a webhook when queued work finishes; keep the documented GET as a recovery and retrieval path:

```bash
curl "https://api.nyne.ai/person/phone?request_id=<request_id>" \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "X-API-Secret: YOUR_API_SECRET"
```

## Credit usage

| Item | Credits | Condition |
| --- | --- | --- |
| Phone Lookup | - | Charged on a found number |
| No match | 0 | Empty results never burn credits |

## Responses

| Code | Meaning |
| --- | --- |
| `200` | Status poll result - returns the current request status and result/error fields when available |
| `202` | Request queued - poll the status endpoint (or wait for the callback) with the returned request_id |
| `400` | Malformed JSON, missing required parameters, or an invalid field |
| `401` | Missing or invalid API credentials |
| `402` | insufficient_credits - not enough credits to complete the request |
| `403` | subscription_required or ip_not_allowed |
| `404` | request_not_found - no matching request is available for this API key |
| `429` | rate_limit_exceeded |
| `503` | service_unavailable - the API is temporarily unavailable |

## Example request

### cURL

```bash
curl -X POST https://api.nyne.ai/person/phone \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "X-API-Secret: YOUR_API_SECRET" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Jane Doe",
    "company": "Acme",
    "email": "jane.doe@acme.com"
  }'
```

### Python

```python
import requests

resp = requests.post(
    "https://api.nyne.ai/person/phone",
    headers={
        "X-API-Key": "YOUR_API_KEY",
        "X-API-Secret": "YOUR_API_SECRET",
    },
    json={
        "name": "Jane Doe",
        "company": "Acme",
        "email": "jane.doe@acme.com",
    },
)
data = resp.json()
print(data)
```

### Node

```javascript
const resp = await fetch("https://api.nyne.ai/person/phone", {
  method: "POST",
  headers: {
    "X-API-Key": "YOUR_API_KEY",
    "X-API-Secret": "YOUR_API_SECRET",
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    name: "Jane Doe",
    company: "Acme",
    email: "jane.doe@acme.com",
  }),
});
const data = await resp.json();
console.log(data);
```

### PHP

```php
<?php
$ch = curl_init("https://api.nyne.ai/person/phone");
curl_setopt_array($ch, [
  CURLOPT_POST => true,
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_HTTPHEADER => [
    "X-API-Key: YOUR_API_KEY",
    "X-API-Secret: YOUR_API_SECRET",
    "Content-Type: application/json",
  ],
  CURLOPT_POSTFIELDS => json_encode([
    "name" => "Jane Doe",
    "company" => "Acme",
    "email" => "jane.doe@acme.com",
  ]),
]);
$data = json_decode(curl_exec($ch), true);
print_r($data);
```

## Example response

```json
{
  "request_id": "a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4_1717000000_4271",
  "status": "completed",
  "completed": true,
  "result": {
    "mobile": "+1-555-123-4567"
  },
  "completed_on": "2026-01-15T10:31:00Z"
}
```

---

All documentation pages are available as Markdown by appending `.md` to their URL. Index: https://api.nyne.ai/llms.txt

---

Source: https://api.nyne.ai/documentation/person/social-lookup.md

# Social Lookup

> Resolve a profile on a target platform from another identifier.

- **Endpoint:** `POST https://api.nyne.ai/person/social-lookup`
- **Group:** Person APIs (https://api.nyne.ai/documentation/person.md)
- **Auth:** `X-API-Key` + `X-API-Secret` headers
- **Mode:** Asynchronous - submit returns a `request_id` (normally with `202 Accepted`); poll `GET /person/social-lookup?request_id=<request_id>` with the same auth headers until the endpoint reports a terminal response. Where supported, a `callback_url` can notify you when queued work finishes; follow this endpoint's retrieval notes.
- **HTML version:** https://api.nyne.ai/documentation/person/social-lookup

Resolve a matching profile on a target `site` from a known `social_media_url` or `email`. The request is queued and returns a `request_id`; poll the status endpoint or supply a `callback_url`.

## Authentication

All `/person/*` and `/company/*` endpoints authenticate with an API key and secret sent as HTTP headers on every request: `X-API-Key` and `X-API-Secret`. Create keys from your Nyne.ai dashboard and keep the secret server-side. Rate limits: 100 requests/minute, 1,000 requests/hour. Full guide: https://api.nyne.ai/documentation/authentication.md

## Parameters

| Name | Type | Required | Description | Example |
| --- | --- | --- | --- | --- |
| `site` | string | **yes** | Target platform to resolve to (canonical site name, not a URL). Many common social media sites are supported. | "twitter" |
| `social_media_url` | string | no | Known profile URL to resolve from. Must be a valid HTTP/HTTPS URL. Wins when both this and `email` are supplied. | "https://linkedin.com/in/janedoe" |
| `email` | string | no | Email to resolve from when no URL is supplied. One of `social_media_url` or `email` is required. | "jane.doe@acme.com" |
| `callback_url` | string | no | If set, the completed result is POSTed here when the job finishes. Must be a valid HTTP(S) URL on an allowed host when a callback allow-list is configured. | "https://hooks.example.com/result" |

## Polling for the result

A newly queued submit normally returns `202 Accepted` with a `request_id`. Poll the same path until `status` is `completed` (results stay available afterwards). Where supported, pass a `callback_url` on the submit to receive a webhook when queued work finishes; keep the documented GET as a recovery and retrieval path:

```bash
curl "https://api.nyne.ai/person/social-lookup?request_id=<request_id>" \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "X-API-Secret: YOUR_API_SECRET"
```

## Credit usage

| Item | Credits | Condition |
| --- | --- | --- |
| Single Social Lookup | - | Charged on a resolved profile |
| No match | 0 | Empty results never burn credits |

## Responses

| Code | Meaning |
| --- | --- |
| `200` | Status poll result - returns the current request status and result/error fields when available |
| `202` | Request queued - poll the status endpoint (or wait for the callback) with the returned request_id |
| `400` | Malformed JSON, missing required parameters, or an invalid field |
| `401` | Missing or invalid API credentials |
| `402` | insufficient_credits - not enough credits to complete the request |
| `403` | subscription_required or ip_not_allowed |
| `404` | request_not_found - no matching request is available for this API key |
| `429` | rate_limit_exceeded |
| `503` | service_unavailable - the API is temporarily unavailable |
| `500` | internal_error - unexpected failure while resolving the profile |

## Example request

### cURL

```bash
curl -X POST https://api.nyne.ai/person/social-lookup \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "X-API-Secret: YOUR_API_SECRET" \
  -H "Content-Type: application/json" \
  -d '{
    "social_media_url": "https://linkedin.com/in/janedoe",
    "site": "twitter"
  }'
```

### Python

```python
import requests

resp = requests.post(
    "https://api.nyne.ai/person/social-lookup",
    headers={
        "X-API-Key": "YOUR_API_KEY",
        "X-API-Secret": "YOUR_API_SECRET",
    },
    json={
        "social_media_url": "https://linkedin.com/in/janedoe",
        "site": "twitter",
    },
)
data = resp.json()
print(data)
```

### Node

```javascript
const resp = await fetch("https://api.nyne.ai/person/social-lookup", {
  method: "POST",
  headers: {
    "X-API-Key": "YOUR_API_KEY",
    "X-API-Secret": "YOUR_API_SECRET",
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    social_media_url: "https://linkedin.com/in/janedoe",
    site: "twitter",
  }),
});
const data = await resp.json();
console.log(data);
```

### PHP

```php
<?php
$ch = curl_init("https://api.nyne.ai/person/social-lookup");
curl_setopt_array($ch, [
  CURLOPT_POST => true,
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_HTTPHEADER => [
    "X-API-Key: YOUR_API_KEY",
    "X-API-Secret: YOUR_API_SECRET",
    "Content-Type: application/json",
  ],
  CURLOPT_POSTFIELDS => json_encode([
    "social_media_url" => "https://linkedin.com/in/janedoe",
    "site" => "twitter",
  ]),
]);
$data = json_decode(curl_exec($ch), true);
print_r($data);
```

## Example response

```json
{
  "request_id": "a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4_1717000000_4271",
  "status": "completed",
  "target_site": "twitter",
  "result": {
    "url": "https://x.com/janedoe",
    "found": true
  }
}
```

---

All documentation pages are available as Markdown by appending `.md` to their URL. Index: https://api.nyne.ai/llms.txt

---

Source: https://api.nyne.ai/documentation/person/single-social-lookup.md

# Single Social Lookup

> Resolve a single social profile (alias of social-lookup).

- **Endpoint:** `POST https://api.nyne.ai/person/single-social-lookup`
- **Group:** Person APIs (https://api.nyne.ai/documentation/person.md)
- **Auth:** `X-API-Key` + `X-API-Secret` headers
- **Mode:** Asynchronous - submit returns a `request_id` (normally with `202 Accepted`); poll `GET /person/single-social-lookup?request_id=<request_id>` with the same auth headers until the endpoint reports a terminal response. Where supported, a `callback_url` can notify you when queued work finishes; follow this endpoint's retrieval notes.
- **HTML version:** https://api.nyne.ai/documentation/person/single-social-lookup

Find one specific platform profile using another identifier. Given a `social_media_url` or `email` plus a target `site`, the API queues a lookup and returns a `request_id`; poll the status endpoint or supply a `callback_url`.

## Authentication

All `/person/*` and `/company/*` endpoints authenticate with an API key and secret sent as HTTP headers on every request: `X-API-Key` and `X-API-Secret`. Create keys from your Nyne.ai dashboard and keep the secret server-side. Rate limits: 100 requests/minute, 1,000 requests/hour. Full guide: https://api.nyne.ai/documentation/authentication.md

## Parameters

| Name | Type | Required | Description | Example |
| --- | --- | --- | --- | --- |
| `site` | string | **yes** | Target platform to resolve to (canonical site name, not a URL). Many common social media sites are supported. | "twitter" |
| `social_media_url` | string | no | Known profile URL to resolve from. Must be a valid HTTP/HTTPS URL. | "https://linkedin.com/in/janedoe" |
| `email` | string | no | Email to resolve from. One of `social_media_url` or `email` is required. | "jane.doe@acme.com" |
| `callback_url` | string | no | If set, the completed result is POSTed here when the job finishes. Must be a valid HTTP(S) URL on an allowed host when a callback allow-list is configured. | "https://hooks.example.com/result" |

## Polling for the result

A newly queued submit normally returns `202 Accepted` with a `request_id`. Poll the same path until `status` is `completed` (results stay available afterwards). Where supported, pass a `callback_url` on the submit to receive a webhook when queued work finishes; keep the documented GET as a recovery and retrieval path:

```bash
curl "https://api.nyne.ai/person/single-social-lookup?request_id=<request_id>" \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "X-API-Secret: YOUR_API_SECRET"
```

## Credit usage

| Item | Credits | Condition |
| --- | --- | --- |
| Single Social Lookup | - | Charged on a resolved profile |
| No match | 0 | Empty results never burn credits |

## Responses

| Code | Meaning |
| --- | --- |
| `200` | Status poll result - returns the current request status and result/error fields when available |
| `202` | Request queued - poll the status endpoint (or wait for the callback) with the returned request_id |
| `400` | Malformed JSON, missing required parameters, or an invalid field |
| `401` | Missing or invalid API credentials |
| `402` | insufficient_credits - not enough credits to complete the request |
| `403` | subscription_required or ip_not_allowed |
| `404` | request_not_found - no matching request is available for this API key |
| `429` | rate_limit_exceeded |
| `503` | service_unavailable - the API is temporarily unavailable |
| `500` | internal_error - unexpected failure while resolving the profile |

## Example request

### cURL

```bash
curl -X POST https://api.nyne.ai/person/single-social-lookup \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "X-API-Secret: YOUR_API_SECRET" \
  -H "Content-Type: application/json" \
  -d '{
    "social_media_url": "https://linkedin.com/in/janedoe",
    "site": "twitter"
  }'
```

### Python

```python
import requests

resp = requests.post(
    "https://api.nyne.ai/person/single-social-lookup",
    headers={
        "X-API-Key": "YOUR_API_KEY",
        "X-API-Secret": "YOUR_API_SECRET",
    },
    json={
        "social_media_url": "https://linkedin.com/in/janedoe",
        "site": "twitter",
    },
)
data = resp.json()
print(data)
```

### Node

```javascript
const resp = await fetch("https://api.nyne.ai/person/single-social-lookup", {
  method: "POST",
  headers: {
    "X-API-Key": "YOUR_API_KEY",
    "X-API-Secret": "YOUR_API_SECRET",
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    social_media_url: "https://linkedin.com/in/janedoe",
    site: "twitter",
  }),
});
const data = await resp.json();
console.log(data);
```

### PHP

```php
<?php
$ch = curl_init("https://api.nyne.ai/person/single-social-lookup");
curl_setopt_array($ch, [
  CURLOPT_POST => true,
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_HTTPHEADER => [
    "X-API-Key: YOUR_API_KEY",
    "X-API-Secret: YOUR_API_SECRET",
    "Content-Type: application/json",
  ],
  CURLOPT_POSTFIELDS => json_encode([
    "social_media_url" => "https://linkedin.com/in/janedoe",
    "site" => "twitter",
  ]),
]);
$data = json_decode(curl_exec($ch), true);
print_r($data);
```

## Example response

```json
{
  "request_id": "a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4_1717000000_4271",
  "status": "completed",
  "target_site": "twitter",
  "result": {
    "url": "https://x.com/janedoe",
    "found": true
  }
}
```

---

All documentation pages are available as Markdown by appending `.md` to their URL. Index: https://api.nyne.ai/llms.txt

---

Source: https://api.nyne.ai/documentation/person/social-account-validator.md

# Social Account Validator

> Validate a public social profile or post and capture a screenshot.

- **Endpoint:** `POST https://api.nyne.ai/person/social-account-validator`
- **Group:** Person APIs (https://api.nyne.ai/documentation/person.md)
- **Auth:** `X-API-Key` + `X-API-Secret` headers
- **Mode:** Asynchronous - submit returns a `request_id` (normally with `202 Accepted`); poll `GET /person/social-account-validator?request_id=<request_id>` with the same auth headers until the endpoint reports a terminal response. Where supported, a `callback_url` can notify you when queued work finishes; follow this endpoint's retrieval notes.
- **HTML version:** https://api.nyne.ai/documentation/person/social-account-validator

Validate a public social profile or supported post URL and return status, screenshot URL, HTML URL, and account-visibility fields when available. The platform and target type are inferred from the URL; multiple URLs can be validated with `POST /person/social-account-validator/batch`. The request is queued and returns a `request_id` to poll, or can deliver the final result to a `callback_url`.

## Authentication

All `/person/*` and `/company/*` endpoints authenticate with an API key and secret sent as HTTP headers on every request: `X-API-Key` and `X-API-Secret`. Create keys from your Nyne.ai dashboard and keep the secret server-side. Rate limits: 100 requests/minute, 1,000 requests/hour. Full guide: https://api.nyne.ai/documentation/authentication.md

## Parameters

| Name | Type | Required | Description | Example |
| --- | --- | --- | --- | --- |
| `url` | string | **yes** | The social profile or post URL to validate (aliased as `social_media_url`). Must be HTTP/HTTPS on a supported platform. | "https://instagram.com/janedoe" |
| `callback_url` | string | no | If set, the completed result is POSTed here when the job finishes. Must be a valid HTTP(S) URL on an allowed host when a callback allow-list is configured. | "https://hooks.example.com/result" |

## Polling for the result

A newly queued submit normally returns `202 Accepted` with a `request_id`. Poll the same path until `status` is `completed` (results stay available afterwards). Where supported, pass a `callback_url` on the submit to receive a webhook when queued work finishes; keep the documented GET as a recovery and retrieval path:

```bash
curl "https://api.nyne.ai/person/social-account-validator?request_id=<request_id>" \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "X-API-Secret: YOUR_API_SECRET"
```

## Credit usage

| Item | Credits | Condition |
| --- | --- | --- |
| Social Account Validator | - | Charged per completed validation target |

## Responses

| Code | Meaning |
| --- | --- |
| `202` | Validation queued - poll the status endpoint with the returned request_id |
| `200` | Completed validation returned inline with status: "completed" |
| `400` | Missing/invalid url or unsupported platform |
| `401` | Missing or invalid API credentials |
| `402` | insufficient_credits |
| `403` | subscription_required or ip_not_allowed |
| `429` | rate_limit_exceeded |
| `503` | service_unavailable - the API is temporarily unavailable |

## Example request

### cURL

```bash
curl -X POST https://api.nyne.ai/person/social-account-validator \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "X-API-Secret: YOUR_API_SECRET" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://instagram.com/janedoe"
  }'
```

### Python

```python
import requests

resp = requests.post(
    "https://api.nyne.ai/person/social-account-validator",
    headers={
        "X-API-Key": "YOUR_API_KEY",
        "X-API-Secret": "YOUR_API_SECRET",
    },
    json={
        "url": "https://instagram.com/janedoe",
    },
)
data = resp.json()
print(data)
```

### Node

```javascript
const resp = await fetch("https://api.nyne.ai/person/social-account-validator", {
  method: "POST",
  headers: {
    "X-API-Key": "YOUR_API_KEY",
    "X-API-Secret": "YOUR_API_SECRET",
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    url: "https://instagram.com/janedoe",
  }),
});
const data = await resp.json();
console.log(data);
```

### PHP

```php
<?php
$ch = curl_init("https://api.nyne.ai/person/social-account-validator");
curl_setopt_array($ch, [
  CURLOPT_POST => true,
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_HTTPHEADER => [
    "X-API-Key: YOUR_API_KEY",
    "X-API-Secret: YOUR_API_SECRET",
    "Content-Type: application/json",
  ],
  CURLOPT_POSTFIELDS => json_encode([
    "url" => "https://instagram.com/janedoe",
  ]),
]);
$data = json_decode(curl_exec($ch), true);
print_r($data);
```

## Example response

```json
{
  "request_id": "sav_9f2c4e6a8b0d4f21a7c3e5b1d8a6c4f2",
  "batch_id": null,
  "target_index": 0,
  "status": "completed",
  "platform": "instagram",
  "target_type": "profile",
  "handle": "janedoe",
  "input_url": "https://instagram.com/janedoe",
  "normalized_url": "https://instagram.com/janedoe",
  "created_on": "2026-01-15T10:32:41",
  "completed_on": "2026-01-15T10:33:00",
  "credits_charged": 10,
  "validation_status": "visible_public_profile",
  "account_active": true,
  "account_active_reason": "The target account or post appears to exist in the page response.",
  "confidence": 0.84,
  "status_reason": "The page includes the account identity plus profile markers.",
  "primary_screenshot_url": "https://api.example.com/social-account-validation-artifacts/sav_9f2c4e6a8b0d4f21a7c3e5b1d8a6c4f2/primary.png",
  "screenshot_url": "https://api.example.com/social-account-validation-artifacts/sav_9f2c4e6a8b0d4f21a7c3e5b1d8a6c4f2/primary.png",
  "evidence": [
    "Handle or target path appears in page text/metadata.",
    "Profile markers seen: followers, following, posts"
  ],
  "artifact_urls": {
    "primary_screenshot_url": "https://api.example.com/social-account-validation-artifacts/sav_9f2c4e6a8b0d4f21a7c3e5b1d8a6c4f2/primary.png",
    "html_url": "https://api.example.com/social-account-validation-artifacts/sav_9f2c4e6a8b0d4f21a7c3e5b1d8a6c4f2/primary.html.txt"
  },
  "html_url": "https://api.example.com/social-account-validation-artifacts/sav_9f2c4e6a8b0d4f21a7c3e5b1d8a6c4f2/primary.html.txt",
  "image_invalidated_at": "2026-01-22T10:33:00",
  "artifacts_invalidated_at": "2026-01-22T10:33:00"
}
```

---

All documentation pages are available as Markdown by appending `.md` to their URL. Index: https://api.nyne.ai/llms.txt

---

Source: https://api.nyne.ai/documentation/person/social-profiles.md

# Social Profiles

> Find all social media accounts for a person.

- **Endpoint:** `POST https://api.nyne.ai/person/social-profiles`
- **Group:** Person APIs (https://api.nyne.ai/documentation/person.md)
- **Auth:** `X-API-Key` + `X-API-Secret` headers
- **Mode:** Asynchronous - submit returns a `request_id` (normally with `202 Accepted`); poll `GET /person/social-profiles?request_id=<request_id>` with the same auth headers until the endpoint reports a terminal response. Where supported, a `callback_url` can notify you when queued work finishes; follow this endpoint's retrieval notes.
- **HTML version:** https://api.nyne.ai/documentation/person/social-profiles

Social-graph discovery: find all matching social media accounts for a person from an `email`, `phone`, or `social_media_url` (at least one required). When no profiles are found the completed result carries an empty `social_profiles` object. The request is queued and returns a `request_id` to poll, or delivered to a `callback_url`.

## Authentication

All `/person/*` and `/company/*` endpoints authenticate with an API key and secret sent as HTTP headers on every request: `X-API-Key` and `X-API-Secret`. Create keys from your Nyne.ai dashboard and keep the secret server-side. Rate limits: 100 requests/minute, 1,000 requests/hour. Full guide: https://api.nyne.ai/documentation/authentication.md

## Parameters

| Name | Type | Required | Description | Example |
| --- | --- | --- | --- | --- |
| `email` | string | no | Email identifier. Validated for format. | "jane.doe@acme.com" |
| `phone` | string | no | Phone identifier. Must normalize to a US 10-digit or international number. | "+1-555-123-4567" |
| `social_media_url` | string | no | Known profile URL; At least one identifier is required. | "https://linkedin.com/in/janedoe" |
| `callback_url` | string | no | If set, the completed result is POSTed here when the job finishes. Must be a valid HTTP(S) URL on an allowed host when a callback allow-list is configured. | "https://hooks.example.com/result" |

## Polling for the result

A newly queued submit normally returns `202 Accepted` with a `request_id`. Poll the same path until `status` is `completed` (results stay available afterwards). Where supported, pass a `callback_url` on the submit to receive a webhook when queued work finishes; keep the documented GET as a recovery and retrieval path:

```bash
curl "https://api.nyne.ai/person/social-profiles?request_id=<request_id>" \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "X-API-Secret: YOUR_API_SECRET"
```

## Credit usage

| Item | Credits | Condition |
| --- | --- | --- |
| Social Profiles Lookup | - | Charged on a result |
| No match | 0 | Empty results never burn credits |

## Responses

| Code | Meaning |
| --- | --- |
| `200` | Status poll result - returns the current request status and result/error fields when available |
| `202` | Request queued - poll the status endpoint (or wait for the callback) with the returned request_id |
| `400` | Malformed JSON, missing required parameters, or an invalid field |
| `401` | Missing or invalid API credentials |
| `402` | insufficient_credits - not enough credits to complete the request |
| `403` | subscription_required or ip_not_allowed |
| `404` | request_not_found - no matching request is available for this API key |
| `429` | rate_limit_exceeded |
| `503` | service_unavailable - the API is temporarily unavailable |
| `500` | internal_error - unexpected failure during the lookup |

## Example request

### cURL

```bash
curl -X POST https://api.nyne.ai/person/social-profiles \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "X-API-Secret: YOUR_API_SECRET" \
  -H "Content-Type: application/json" \
  -d '{
    "email": "jane.doe@acme.com"
  }'
```

### Python

```python
import requests

resp = requests.post(
    "https://api.nyne.ai/person/social-profiles",
    headers={
        "X-API-Key": "YOUR_API_KEY",
        "X-API-Secret": "YOUR_API_SECRET",
    },
    json={
        "email": "jane.doe@acme.com",
    },
)
data = resp.json()
print(data)
```

### Node

```javascript
const resp = await fetch("https://api.nyne.ai/person/social-profiles", {
  method: "POST",
  headers: {
    "X-API-Key": "YOUR_API_KEY",
    "X-API-Secret": "YOUR_API_SECRET",
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    email: "jane.doe@acme.com",
  }),
});
const data = await resp.json();
console.log(data);
```

### PHP

```php
<?php
$ch = curl_init("https://api.nyne.ai/person/social-profiles");
curl_setopt_array($ch, [
  CURLOPT_POST => true,
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_HTTPHEADER => [
    "X-API-Key: YOUR_API_KEY",
    "X-API-Secret: YOUR_API_SECRET",
    "Content-Type: application/json",
  ],
  CURLOPT_POSTFIELDS => json_encode([
    "email" => "jane.doe@acme.com",
  ]),
]);
$data = json_decode(curl_exec($ch), true);
print_r($data);
```

## Example response

```json
{
  "request_id": "a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4_1717000000_4271",
  "status": "completed",
  "completed": true,
  "result": {
    "social_profiles": {
      "linkedin": {
        "url": "https://linkedin.com/in/janedoe"
      },
      "twitter": {
        "url": "https://x.com/janedoe"
      },
      "github": {
        "url": "https://github.com/janedoe"
      }
    }
  },
  "completed_on": "2026-01-15T10:34:00Z"
}
```

---

All documentation pages are available as Markdown by appending `.md` to their URL. Index: https://api.nyne.ai/llms.txt

---

Source: https://api.nyne.ai/documentation/company.md

# Company APIs

> Company intelligence resolved from a domain - firmographics, employees, funding history, buying intent, and product signals.

- **Auth:** `X-API-Key` + `X-API-Secret` headers
- **Mode:** Most operations are asynchronous - submit returns a `request_id`, normally with `202 Accepted`; poll using that endpoint's documented status path or use a `callback_url` webhook.
- **HTML version:** https://api.nyne.ai/documentation/company

The Company APIs resolve a company from a website domain (or an email, phone, or company social URL) and return structured intelligence about it: the firmographic record, the people who work there, what it sells and runs, what it needs, and who funds it.

Every endpoint is an asynchronous `POST`: the submit returns `202 Accepted` with a `request_id`, and you poll the same path - `GET <path>?request_id=…` - until `status` is `completed`, or supply a `callback_url` to receive the result by webhook instead.

Credits are charged only on meaningful results - when no company matches your identifiers, nothing is charged.

## Endpoints

### Find companies

Build target lists from firmographic filters, or rank ICP candidates by demonstrated buying intent.

- **[Company Search](https://api.nyne.ai/documentation/company/search.md)** - `POST /company/search` - Find companies from a natural-language query.
- **[Company Discovery](https://api.nyne.ai/documentation/company/discovery.md)** - `POST /company/discovery` - Discover companies from the open web with natural-language queries and match conditions.
- **[Company Intent](https://api.nyne.ai/documentation/company/intent.md)** - `POST /company/intent` - Find and rank ICP candidates from demonstrated buying-intent signals.

### Profiles & people

The full company record - and the public profiles of the people behind it.

- **[Company Enrichment](https://api.nyne.ai/documentation/company/enrichment.md)** - `POST /company/enrichment` - Resolve a full company profile from a domain, email, phone, or company social URL.
- **[Company Employees](https://api.nyne.ai/documentation/company/employees.md)** - `POST /company/employees` - Retrieve public employee profiles for a company.

### Signals & research

Answer specific questions about a company: what it sells, what its site runs, what it needs, who funds it, and who engages with it.

- **[CheckSeller](https://api.nyne.ai/documentation/company/checkseller.md)** - `POST /company/checkseller` - Verify whether a company sells a given product or service.
- **[CheckFeature](https://api.nyne.ai/documentation/company/checkfeature.md)** - `POST /company/checkfeature` - Detect whether a company’s site has a given feature, technology, or capability.
- **[Company Needs](https://api.nyne.ai/documentation/company/needs.md)** - `POST /company/needs` - Summarize pain points / challenges from a company’s official filings.
- **[Company Funding](https://api.nyne.ai/documentation/company/funding.md)** - `POST /company/funding` - Retrieve verified funding-round and acquisition history for a company.
- **[Company Funders](https://api.nyne.ai/documentation/company/funders.md)** - `POST /company/funders` - Look up an investor / fund profile (partners, thesis, check size, recent deals).
- **[Competitor Engagements](https://api.nyne.ai/documentation/company/competitor-engagements.md)** - `POST /company/competitor-engagements` - Find people who engaged with a company page, with profile URLs and post context.

## Worked example

The flagship endpoint, [Company Enrichment](https://api.nyne.ai/documentation/company/enrichment), shows the request/poll shape every Company API shares. Submit a domain or company social URL, get a `request_id` back immediately, then poll the same path for the full company record.

### 1. Submit - `POST /company/enrichment`

```bash
curl -X POST https://api.nyne.ai/company/enrichment \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "X-API-Secret: YOUR_API_SECRET" \
  -H "Content-Type: application/json" \
  -d '{
    "social_media_url": "https://www.linkedin.com/company/tesla-motors/"
  }'
```

The call returns `202 Accepted` immediately:

```json
{
  "request_id": "dfd84d2d1f065a9b4e7fbc3df6aabbb6_1700000123_8123",
  "status": "queued"
}
```

### 2. Poll until completed

```bash
curl "https://api.nyne.ai/company/enrichment?request_id=<request_id>" \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "X-API-Secret: YOUR_API_SECRET"
```

When `status` is `completed`, the same response carries the result:

```json
{
  "request_id": "dfd84d2d1f065a9b4e7fbc3df6aabbb6_1700000123_8123",
  "status": "completed",
  "completed": true,
  "result": {
    "company_name": "Tesla, Inc.",
    "website": "https://www.tesla.com",
    "description": "Designs and manufactures electric vehicles and energy storage systems.",
    "linkedin_url": "https://www.linkedin.com/company/tesla-motors/",
    "industry": "Automotive",
    "specialties": [
      "Electric Vehicles",
      "Energy Storage"
    ],
    "headcount_range": "10,001+",
    "locations": [
      {
        "city": "Austin",
        "state": "Texas",
        "country": "United States"
      },
      {
        "city": "Fremont",
        "state": "California",
        "country": "United States"
      }
    ],
    "funding": {
      "last_round": "Post-IPO",
      "funding_total": "20.2B"
    },
    "sic_codes": [
      "3711"
    ],
    "naics_codes": [
      "336111"
    ],
    "emails": [
      "press@tesla.com"
    ],
    "phone_numbers": [
      "+1-512-516-8177"
    ]
  },
  "completed_on": "2026-01-15T10:35:00Z"
}
```

## Authentication & credits

All `/person/*` and `/company/*` endpoints authenticate with an API key and secret sent as HTTP headers on every request: `X-API-Key` and `X-API-Secret`. Create keys from your Nyne.ai dashboard and keep the secret server-side. Rate limits: 100 requests/minute, 1,000 requests/hour. Full guide: https://api.nyne.ai/documentation/authentication.md

Credits are charged only on meaningful results - empty results never burn credits. Each endpoint page lists its exact credit costs.

## FAQ

### Which Company API should I start with?

Use Company Enrichment when you already have a domain or company URL, Company Search when you need a filtered account list, and Company Discovery when the criteria are more research-oriented or natural-language.

### What company data can the APIs return?

The Company APIs can return firmographics, employees, funding history, investor context, website and product signals, technographics, buyer-intent signals, and competitor engagement context.

### How are Company API results delivered?

Company endpoints are asynchronous: POST the request, keep the request_id, then poll the same path or provide a callback_url for webhook delivery when the job completes.

---

All documentation pages are available as Markdown by appending `.md` to their URL. Index: https://api.nyne.ai/llms.txt

---

Source: https://api.nyne.ai/documentation/company/search.md

# Company Search

> Find companies from a natural-language query.

- **Endpoint:** `POST https://api.nyne.ai/company/search`
- **Group:** Company APIs (https://api.nyne.ai/documentation/company.md)
- **Auth:** `X-API-Key` + `X-API-Secret` headers
- **Mode:** Asynchronous - submit returns a `request_id` (normally with `202 Accepted`); poll `GET /company/search?request_id=<request_id>` with the same auth headers until the endpoint reports a terminal response. Where supported, a `callback_url` can notify you when queued work finishes; follow this endpoint's retrieval notes.
- **HTML version:** https://api.nyne.ai/documentation/company/search

Discover companies using the same freeform search style as `person/search`. Send a natural-language `query` such as “pre-seed AI infrastructure startups backed by Sequoia in California with fewer than 50 employees”. When a query ties a funding stage, amount, date, or investor to one round, those constraints must match the same funding event. The request is queued asynchronously and returns a `request_id`; poll the status endpoint or supply a `callback_url` to receive the completed result. Completed results use the same page envelope: `results`, `returned_count`, `total_results`, `total_relation`, `limit`, `offset`, `has_more`, and `next_offset`. Use `profile_scoring` to add a 1-5 relevance `score`, and `insights` to add query-fit explanations. Credits are charged per company returned, so an empty result burns nothing.

## Authentication

All `/person/*` and `/company/*` endpoints authenticate with an API key and secret sent as HTTP headers on every request: `X-API-Key` and `X-API-Secret`. Create keys from your Nyne.ai dashboard and keep the secret server-side. Rate limits: 100 requests/minute, 1,000 requests/hour. Full guide: https://api.nyne.ai/documentation/authentication.md

## Parameters

| Name | Type | Required | Description | Example |
| --- | --- | --- | --- | --- |
| `query` | string | **yes** | Natural-language company search request. The backend interprets industries, locations, employee counts, follower counts, founded years, web/LinkedIn presence, funding, investors, organization type, technologies used (technographics), acquisition status, physical location count, and investor-firm criteria (VC/fund, stages they invest in, check size) when present. Funding facts tied to one round are evaluated against the same funding event. Max 700 chars. | "insurance companies without a website in California with less than 10 employees" |
| `limit` | integer | no | Maximum companies to return. Range 1-50, default 10. | 10 |
| `offset` | integer | no | Starting position for offset pagination (0-indexed). Default 0; `offset` + `limit` may not exceed 10000. To retrieve another page, submit the same `query` with the `next_offset` from the previous completed response. | 0 |
| `profile_scoring` | boolean | no | When true, completed company rows include `score`, an AI-generated 1-5 relevance score for the query. Defaults to false. | true |
| `insights` | boolean | no | When true, completed company rows include `insights` with query-fit evidence chips and concise rationales. Defaults to false. | true |
| `callback_url` | string | no | http(s) URL on an allowed host that receives the completed payload automatically. | "https://example.com/webhooks/company-search" |

## Polling for the result

A newly queued submit normally returns `202 Accepted` with a `request_id`. Poll the same path until `status` is `completed` (results stay available afterwards). Where supported, pass a `callback_url` on the submit to receive a webhook when queued work finishes; keep the documented GET as a recovery and retrieval path:

```bash
curl "https://api.nyne.ai/company/search?request_id=<request_id>" \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "X-API-Secret: YOUR_API_SECRET"
```

## Pagination

A completed company search returns one offset-based page. Use `next_offset` from a completed response as the `offset` on a new `POST /company/search` with the same query to request the next page. Polling an existing `request_id` is for checking completion or re-reading the stored page; it does not launch a new billable search page.

### Knowing when to paginate

| Response field | Meaning |
| --- | --- |
| has_more | `true` means more results may be available beyond this page. |
| next_offset | The offset to request for the next page. Present only when `has_more` is `true`. |
| total_results | Exact match count when `total_relation` is `eq`; a lower bound when `total_relation` is `gte`. |

### Fetching the next page

| Method | How |
| --- | --- |
| Repeat the query + offset | Submit the same `query` with a higher `offset` to retrieve another page. |
| request_id polling | Use `GET /company/search?request_id=...` to poll status or re-read the stored page for that request. Optional `limit`/`offset` only slice the stored page when the requested slice overlaps it. |

## Credit usage

| Item | Credits | Condition |
| --- | --- | --- |
| Company Search | 1 | Charged per company returned (per-result) |
| No match | 0 | Empty results never burn credits |

## Responses

| Code | Meaning |
| --- | --- |
| `202` | Search queued - poll the status endpoint with the returned request_id |
| `400` | missing_parameters / invalid_parameters / invalid_limit / invalid_callback_url |
| `401` | Missing or invalid API credentials |
| `402` | insufficient_credits - returned when a queued request cannot continue because credits are unavailable |
| `403` | subscription_required or ip_not_allowed |
| `429` | rate_limit_exceeded / monthly_limit_exceeded |
| `503` | service_unavailable - the API is temporarily unavailable |

## Example request

### cURL

```bash
curl -X POST https://api.nyne.ai/company/search \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "X-API-Secret: YOUR_API_SECRET" \
  -H "Content-Type: application/json" \
  -d '{
    "query": "pre-seed AI infrastructure startups backed by Sequoia in California with fewer than 50 employees",
    "limit": 10,
    "offset": 0,
    "profile_scoring": true,
    "insights": true
  }'
```

### Python

```python
import requests

resp = requests.post(
    "https://api.nyne.ai/company/search",
    headers={
        "X-API-Key": "YOUR_API_KEY",
        "X-API-Secret": "YOUR_API_SECRET",
    },
    json={
        "query": "pre-seed AI infrastructure startups backed by Sequoia in California with fewer than 50 employees",
        "limit": 10,
        "offset": 0,
        "profile_scoring": True,
        "insights": True,
    },
)
data = resp.json()
print(data)
```

### Node

```javascript
const resp = await fetch("https://api.nyne.ai/company/search", {
  method: "POST",
  headers: {
    "X-API-Key": "YOUR_API_KEY",
    "X-API-Secret": "YOUR_API_SECRET",
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    query: "pre-seed AI infrastructure startups backed by Sequoia in California with fewer than 50 employees",
    limit: 10,
    offset: 0,
    profile_scoring: true,
    insights: true,
  }),
});
const data = await resp.json();
console.log(data);
```

### PHP

```php
<?php
$ch = curl_init("https://api.nyne.ai/company/search");
curl_setopt_array($ch, [
  CURLOPT_POST => true,
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_HTTPHEADER => [
    "X-API-Key: YOUR_API_KEY",
    "X-API-Secret: YOUR_API_SECRET",
    "Content-Type: application/json",
  ],
  CURLOPT_POSTFIELDS => json_encode([
    "query" => "pre-seed AI infrastructure startups backed by Sequoia in California with fewer than 50 employees",
    "limit" => 10,
    "offset" => 0,
    "profile_scoring" => true,
    "insights" => true,
  ]),
]);
$data = json_decode(curl_exec($ch), true);
print_r($data);
```

## Example response

```json
{
  "request_id": "cosearch_64f2d8e4_1700000123",
  "status": "completed",
  "completed": true,
  "results": [
    {
      "profile_id": "nyne-ai",
      "name": "Nyne.ai",
      "display_name": "Nyne.ai",
      "url": "nyne.ai",
      "website_url": "nyne.ai",
      "domain": "nyne.ai",
      "linkedin_url": "linkedin.com/company/nyne-ai",
      "linkedin_id": "99082053",
      "linkedin_slug": "nyne-ai",
      "industry": "software development",
      "organization_type": "privately held",
      "employee_count": 12,
      "employee_count_range": {
        "start": 11,
        "end": 50
      },
      "follower_count": 1172,
      "founded_year": 2024,
      "company_size_label": "11-50",
      "total_funding_raised": 1000000,
      "latest_funding_stage": "pre seed",
      "funding_stages": [
        "pre seed"
      ],
      "funding_rounds": [
        {
          "stage": "pre seed",
          "date": "2025-10-03",
          "amount": 1000000,
          "investor_names": [
            "south park commons"
          ]
        }
      ],
      "last_funding_date": "2025-10-03",
      "last_funding_round_url": "crunchbase.com/funding_round/nyne-ai-pre-seed--78449dc7",
      "number_funding_rounds": 1,
      "investor_names": [
        "south park commons"
      ],
      "investor_count": 1,
      "is_acquired": false,
      "technologies": [
        "salesforce",
        "amazon web services"
      ],
      "product_types": [
        "crm"
      ],
      "tech_categories": [
        "crm software"
      ],
      "has_technographics": true,
      "specialities": [
        "ai infrastructure",
        "developer tools"
      ],
      "location_count": 2,
      "is_investor": false,
      "invests_in_stages": [],
      "headquarter": {
        "city": "san francisco",
        "region": "ca",
        "country": "us",
        "country_iso": "US"
      },
      "score": 5,
      "insights": {
        "overall_summary": "Strong match: pre-seed software company backed by the requested investor.",
        "why_matched": [
          {
            "criterion": "Funding stage match",
            "evidence_type": "funding",
            "confidence": "strong",
            "display_text": "Latest funding stage is pre seed.",
            "matched_phrase": "pre seed"
          },
          {
            "criterion": "Investor match",
            "evidence_type": "investor",
            "confidence": "strong",
            "display_text": "Investor list includes South Park Commons.",
            "matched_phrase": "south park commons"
          }
        ],
        "query_insights": [
          {
            "subquery_idx": 0,
            "subquery": "pre-seed software company",
            "priority": "Essential",
            "match_level": "Meets Expectations",
            "short_rationale": "Company has a pre seed funding stage.",
            "rationale": "The company is listed with latest funding stage pre seed.",
            "short_quotes": [
              "pre seed"
            ]
          }
        ]
      }
    }
  ],
  "returned_count": 1,
  "total_results": 1,
  "total_relation": "eq",
  "limit": 10,
  "offset": 0,
  "has_more": false,
  "next_offset": null
}
```

---

All documentation pages are available as Markdown by appending `.md` to their URL. Index: https://api.nyne.ai/llms.txt

---

Source: https://api.nyne.ai/documentation/company/discovery.md

# Company Discovery

> Discover companies from the open web with natural-language queries and match conditions.

- **Endpoint:** `POST https://api.nyne.ai/company/discovery`
- **Group:** Company APIs (https://api.nyne.ai/documentation/company.md)
- **Auth:** `X-API-Key` + `X-API-Secret` headers
- **Mode:** Asynchronous - submit returns a `request_id` (normally with `202 Accepted`); poll `GET /company/discovery?request_id=<request_id>` with the same auth headers until the endpoint reports a terminal response. Where supported, a `callback_url` can notify you when queued work finishes; follow this endpoint's retrieval notes.
- **HTML version:** https://api.nyne.ai/documentation/company/discovery

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`.

## Authentication

All `/person/*` and `/company/*` endpoints authenticate with an API key and secret sent as HTTP headers on every request: `X-API-Key` and `X-API-Secret`. Create keys from your Nyne.ai dashboard and keep the secret server-side. Rate limits: 100 requests/minute, 1,000 requests/hour. Full guide: https://api.nyne.ai/documentation/authentication.md

## Parameters

| Name | Type | Required | Description | Example |
| --- | --- | --- | --- | --- |
| `query` | string | **yes** | Natural-language query describing the companies to find. Max 2000 characters. | "AI startups in healthcare that have raised Series A funding" |
| `requirements` | array | no | Match conditions, each with `name` and `description` (max 20). Each is evaluated independently per company with evidence. | [{ "name": "series_a_funded", "description": "Has raised a Series A funding round" }] |
| `extract` | array | no | Enrichment fields to extract per matched company, each with `name` and `description` (max 10). | [{ "name": "ceo_name", "description": "Name of the CEO or founder" }] |
| `limit` | integer | no | Maximum results to return. Range 5-100, default 10. | 10 |
| `quality` | string | no | Quality tier - `basic` (fastest) · `standard` (default) · `premium` (most thorough). | "standard" |
| `exclude` | array | no | Entities to exclude from results, each with `name` and `url` (max 100). | [{ "name": "Acme Corp", "url": "acme.com" }] |
| `metadata` | object | no | Pass-through metadata returned with the results. Values must be string, number, or boolean. | { "campaign": "q1_outreach" } |
| `callback_url` | string | no | HTTPS URL that receives a webhook notification when processing completes. | "https://example.com/webhook/discovery" |

## Polling for the result

A newly queued submit normally returns `202 Accepted` with a `request_id`. Poll the same path until `status` is `completed` (results stay available afterwards). Where supported, pass a `callback_url` on the submit to receive a webhook when queued work finishes; keep the documented GET as a recovery and retrieval path:

```bash
curl "https://api.nyne.ai/company/discovery?request_id=<request_id>" \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "X-API-Secret: YOUR_API_SECRET"
```

## Credit usage

| Item | Credits | Condition |
| --- | --- | --- |
| Discovery Request | 10 | Fixed per request, regardless of the number of results returned |

## Responses

| Code | Meaning |
| --- | --- |
| `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 |

## Example request

### cURL

```bash
curl -X POST https://api.nyne.ai/company/discovery \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "X-API-Secret: YOUR_API_SECRET" \
  -H "Content-Type: application/json" \
  -d '{
    "query": "AI startups in healthcare that have raised Series A funding",
    "requirements": [
      {
        "name": "series_a_funded",
        "description": "Has raised a Series A funding round"
      }
    ],
    "extract": [
      {
        "name": "ceo_name",
        "description": "Name of the CEO or founder"
      }
    ],
    "limit": 10,
    "quality": "standard"
  }'
```

### Python

```python
import requests

resp = requests.post(
    "https://api.nyne.ai/company/discovery",
    headers={
        "X-API-Key": "YOUR_API_KEY",
        "X-API-Secret": "YOUR_API_SECRET",
    },
    json={
        "query": "AI startups in healthcare that have raised Series A funding",
        "requirements": [
            {
                "name": "series_a_funded",
                "description": "Has raised a Series A funding round",
            },
        ],
        "extract": [
            {
                "name": "ceo_name",
                "description": "Name of the CEO or founder",
            },
        ],
        "limit": 10,
        "quality": "standard",
    },
)
data = resp.json()
print(data)
```

### Node

```javascript
const resp = await fetch("https://api.nyne.ai/company/discovery", {
  method: "POST",
  headers: {
    "X-API-Key": "YOUR_API_KEY",
    "X-API-Secret": "YOUR_API_SECRET",
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    query: "AI startups in healthcare that have raised Series A funding",
    requirements: [
      {
        name: "series_a_funded",
        description: "Has raised a Series A funding round",
      },
    ],
    extract: [
      {
        name: "ceo_name",
        description: "Name of the CEO or founder",
      },
    ],
    limit: 10,
    quality: "standard",
  }),
});
const data = await resp.json();
console.log(data);
```

### PHP

```php
<?php
$ch = curl_init("https://api.nyne.ai/company/discovery");
curl_setopt_array($ch, [
  CURLOPT_POST => true,
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_HTTPHEADER => [
    "X-API-Key: YOUR_API_KEY",
    "X-API-Secret: YOUR_API_SECRET",
    "Content-Type: application/json",
  ],
  CURLOPT_POSTFIELDS => json_encode([
    "query" => "AI startups in healthcare that have raised Series A funding",
    "requirements" => [
      [
        "name" => "series_a_funded",
        "description" => "Has raised a Series A funding round",
      ],
    ],
    "extract" => [
      [
        "name" => "ceo_name",
        "description" => "Name of the CEO or founder",
      ],
    ],
    "limit" => 10,
    "quality" => "standard",
  ]),
]);
$data = json_decode(curl_exec($ch), true);
print_r($data);
```

## Example response

```json
{
  "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"
}
```

---

All documentation pages are available as Markdown by appending `.md` to their URL. Index: https://api.nyne.ai/llms.txt

---

Source: https://api.nyne.ai/documentation/company/enrichment.md

# Company Enrichment

> Resolve a full company profile from a domain, email, phone, or company social URL.

- **Endpoint:** `POST https://api.nyne.ai/company/enrichment`
- **Group:** Company APIs (https://api.nyne.ai/documentation/company.md)
- **Auth:** `X-API-Key` + `X-API-Secret` headers
- **Mode:** Asynchronous - submit returns a `request_id` (normally with `202 Accepted`); poll `GET /company/enrichment?request_id=<request_id>` with the same auth headers until the endpoint reports a terminal response. Where supported, a `callback_url` can notify you when queued work finishes; follow this endpoint's retrieval notes.
- **HTML version:** https://api.nyne.ai/documentation/company/enrichment

Submit one or more identifiers for a company - `domain`, `email`, `phone`, or a company `social_media_url` - and receive a firmographic profile with fields such as industry, headcount, locations, funding, web presence, domains, emails, and phone numbers when available. Fields with no data are omitted from the response. The request is queued asynchronously and returns a `request_id`; poll the status endpoint or supply a `callback_url`. At least one identifier is required. Credits are charged only when the enrichment returns data.

## Authentication

All `/person/*` and `/company/*` endpoints authenticate with an API key and secret sent as HTTP headers on every request: `X-API-Key` and `X-API-Secret`. Create keys from your Nyne.ai dashboard and keep the secret server-side. Rate limits: 100 requests/minute, 1,000 requests/hour. Full guide: https://api.nyne.ai/documentation/authentication.md

## Parameters

| Name | Type | Required | Description | Example |
| --- | --- | --- | --- | --- |
| `domain` | string | no | Company website domain. Scheme, `www.`, and path are stripped automatically before matching. | "tesla.com" |
| `email` | string | no | Company email address. Validated for format. | "contact@example.com" |
| `phone` | string | no | Company phone number (digits, spaces, dashes, parentheses, and + only). | "+1-555-123-4567" |
| `social_media_url` | string | no | Company social profile URL. | "https://www.linkedin.com/company/tesla-motors/" |
| `callback_url` | string | no | http(s) URL on an allowed host that receives the completed enrichment payload. | "https://example.com/webhooks/company-enrichment" |

## Polling for the result

A newly queued submit normally returns `202 Accepted` with a `request_id`. Poll the same path until `status` is `completed` (results stay available afterwards). Where supported, pass a `callback_url` on the submit to receive a webhook when queued work finishes; keep the documented GET as a recovery and retrieval path:

```bash
curl "https://api.nyne.ai/company/enrichment?request_id=<request_id>" \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "X-API-Secret: YOUR_API_SECRET"
```

## Credit usage

| Item | Credits | Condition |
| --- | --- | --- |
| Company Enrichment | - | Charged once per request, only on a meaningful result |
| No match | 0 | No data found never burns credits |

## Responses

| Code | Meaning |
| --- | --- |
| `202` | Enrichment queued - poll the status endpoint with the returned request_id |
| `400` | missing_parameters / invalid_email / invalid_phone / invalid_url / invalid_domain / invalid_callback_url |
| `401` | Missing or invalid API credentials |
| `402` | insufficient_credits |
| `403` | subscription_required or ip_not_allowed |
| `404` | not_found - no company matched the supplied identifiers (no credits charged) |
| `429` | rate_limit_exceeded / monthly_limit_exceeded |
| `503` | service_unavailable - the API is temporarily unavailable |

## Example request

### cURL

```bash
curl -X POST https://api.nyne.ai/company/enrichment \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "X-API-Secret: YOUR_API_SECRET" \
  -H "Content-Type: application/json" \
  -d '{
    "social_media_url": "https://www.linkedin.com/company/tesla-motors/"
  }'
```

### Python

```python
import requests

resp = requests.post(
    "https://api.nyne.ai/company/enrichment",
    headers={
        "X-API-Key": "YOUR_API_KEY",
        "X-API-Secret": "YOUR_API_SECRET",
    },
    json={
        "social_media_url": "https://www.linkedin.com/company/tesla-motors/",
    },
)
data = resp.json()
print(data)
```

### Node

```javascript
const resp = await fetch("https://api.nyne.ai/company/enrichment", {
  method: "POST",
  headers: {
    "X-API-Key": "YOUR_API_KEY",
    "X-API-Secret": "YOUR_API_SECRET",
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    social_media_url: "https://www.linkedin.com/company/tesla-motors/",
  }),
});
const data = await resp.json();
console.log(data);
```

### PHP

```php
<?php
$ch = curl_init("https://api.nyne.ai/company/enrichment");
curl_setopt_array($ch, [
  CURLOPT_POST => true,
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_HTTPHEADER => [
    "X-API-Key: YOUR_API_KEY",
    "X-API-Secret: YOUR_API_SECRET",
    "Content-Type: application/json",
  ],
  CURLOPT_POSTFIELDS => json_encode([
    "social_media_url" => "https://www.linkedin.com/company/tesla-motors/",
  ]),
]);
$data = json_decode(curl_exec($ch), true);
print_r($data);
```

## Example response

```json
{
  "request_id": "dfd84d2d1f065a9b4e7fbc3df6aabbb6_1700000123_8123",
  "status": "completed",
  "completed": true,
  "result": {
    "company_name": "Tesla, Inc.",
    "website": "https://www.tesla.com",
    "description": "Designs and manufactures electric vehicles and energy storage systems.",
    "linkedin_url": "https://www.linkedin.com/company/tesla-motors/",
    "industry": "Automotive",
    "specialties": [
      "Electric Vehicles",
      "Energy Storage"
    ],
    "headcount_range": "10,001+",
    "locations": [
      {
        "city": "Austin",
        "state": "Texas",
        "country": "United States"
      },
      {
        "city": "Fremont",
        "state": "California",
        "country": "United States"
      }
    ],
    "funding": {
      "last_round": "Post-IPO",
      "funding_total": "20.2B"
    },
    "sic_codes": [
      "3711"
    ],
    "naics_codes": [
      "336111"
    ],
    "emails": [
      "press@tesla.com"
    ],
    "phone_numbers": [
      "+1-512-516-8177"
    ]
  },
  "completed_on": "2026-01-15T10:35:00Z"
}
```

---

All documentation pages are available as Markdown by appending `.md` to their URL. Index: https://api.nyne.ai/llms.txt

---

Source: https://api.nyne.ai/documentation/company/employees.md

# Company Employees

> Retrieve public employee profiles for a company.

- **Endpoint:** `POST https://api.nyne.ai/company/employees`
- **Group:** Company APIs (https://api.nyne.ai/documentation/company.md)
- **Auth:** `X-API-Key` + `X-API-Secret` headers
- **Mode:** Asynchronous - submit returns a `request_id` (normally with `202 Accepted`); poll `GET /company/employees?request_id=<request_id>` with the same auth headers until the endpoint reports a terminal response. Where supported, a `callback_url` can notify you when queued work finishes; follow this endpoint's retrieval notes.
- **HTML version:** https://api.nyne.ai/documentation/company/employees

Return a broad roster of public employee profiles for one company, identified by a `company_name`, `domain`, or company `social_media_url` (supply at least one). Use `/person/search` instead when you need title, role, location, experience, or other person-level criteria. Results come back as a `results` array of person-shaped objects with profile links, headlines, locations, organizations, and related fields when available. The request is queued asynchronously and returns a `request_id`; poll or supply a `callback_url`. Credits are charged only for profiles returned.

## Authentication

All `/person/*` and `/company/*` endpoints authenticate with an API key and secret sent as HTTP headers on every request: `X-API-Key` and `X-API-Secret`. Create keys from your Nyne.ai dashboard and keep the secret server-side. Rate limits: 100 requests/minute, 1,000 requests/hour. Full guide: https://api.nyne.ai/documentation/authentication.md

## Parameters

| Name | Type | Required | Description | Example |
| --- | --- | --- | --- | --- |
| `company_name` | string | no | Company name. One of company_name / domain / social_media_url is required. Max 255 chars. | "Acme" |
| `domain` | string | no | Company domain or website hostname. Scheme, path, and `www.` are removed automatically. Max 255 chars. | "acme.com" |
| `social_media_url` | string | no | Company social media URL. Query strings and fragments are stripped before processing. Max 2048 chars. | "https://www.linkedin.com/company/acme/" |
| `max_employees` | integer | no | Maximum profiles to return. Range 1-500, default 10. | 25 |
| `callback_url` | string | no | http(s) URL on an allowed host that receives the completed payload automatically. | "https://example.com/webhook/company-employees" |

## Polling for the result

A newly queued submit normally returns `202 Accepted` with a `request_id`. Poll the same path until `status` is `completed` (results stay available afterwards). Where supported, pass a `callback_url` on the submit to receive a webhook when queued work finishes; keep the documented GET as a recovery and retrieval path:

```bash
curl "https://api.nyne.ai/company/employees?request_id=<request_id>" \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "X-API-Secret: YOUR_API_SECRET"
```

## Credit usage

| Item | Credits | Condition |
| --- | --- | --- |
| Company Employees | 1 | Charged per profile returned (per-result) |
| No profiles | 0 | No employee data found never burns per-result credits |

## Responses

| Code | Meaning |
| --- | --- |
| `202` | Request queued - poll the status endpoint with the returned request_id |
| `400` | missing_parameters / invalid_url / invalid_domain / invalid_parameters / invalid_callback_url |
| `401` | Missing or invalid API credentials |
| `402` | insufficient_credits |
| `403` | subscription_required or ip_not_allowed |
| `429` | rate_limit_exceeded / monthly_limit_exceeded |
| `503` | service_unavailable - the API is temporarily unavailable |

## Example request

### cURL

```bash
curl -X POST https://api.nyne.ai/company/employees \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "X-API-Secret: YOUR_API_SECRET" \
  -H "Content-Type: application/json" \
  -d '{
    "company_name": "Acme",
    "domain": "acme.com",
    "max_employees": 25
  }'
```

### Python

```python
import requests

resp = requests.post(
    "https://api.nyne.ai/company/employees",
    headers={
        "X-API-Key": "YOUR_API_KEY",
        "X-API-Secret": "YOUR_API_SECRET",
    },
    json={
        "company_name": "Acme",
        "domain": "acme.com",
        "max_employees": 25,
    },
)
data = resp.json()
print(data)
```

### Node

```javascript
const resp = await fetch("https://api.nyne.ai/company/employees", {
  method: "POST",
  headers: {
    "X-API-Key": "YOUR_API_KEY",
    "X-API-Secret": "YOUR_API_SECRET",
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    company_name: "Acme",
    domain: "acme.com",
    max_employees: 25,
  }),
});
const data = await resp.json();
console.log(data);
```

### PHP

```php
<?php
$ch = curl_init("https://api.nyne.ai/company/employees");
curl_setopt_array($ch, [
  CURLOPT_POST => true,
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_HTTPHEADER => [
    "X-API-Key: YOUR_API_KEY",
    "X-API-Secret: YOUR_API_SECRET",
    "Content-Type: application/json",
  ],
  CURLOPT_POSTFIELDS => json_encode([
    "company_name" => "Acme",
    "domain" => "acme.com",
    "max_employees" => 25,
  ]),
]);
$data = json_decode(curl_exec($ch), true);
print_r($data);
```

## Example response

```json
{
  "request_id": "94f1bf8a0d1a1f065a9b4e7fbc3df6aa_1700000123_2210",
  "status": "completed",
  "completed": true,
  "result": {
    "results": [
      {
        "profile_id": "a1b2c3d4e5f6",
        "displayname": "Jane Doe",
        "headline": "VP of Sales at Acme",
        "bio": "Sales leader focused on B2B SaaS go-to-market.",
        "address": {
          "city": "San Francisco",
          "state": "CA",
          "country": "United States"
        },
        "organizations": [
          {
            "name": "Acme",
            "title": "VP of Sales",
            "is_current": true
          }
        ],
        "websites": [
          "https://janedoe.com"
        ],
        "social_profiles": {
          "linkedin": {
            "url": "https://linkedin.com/in/janedoe"
          }
        }
      }
    ],
    "total_results": 1
  },
  "completed_on": "2026-01-15T10:35:00Z"
}
```

---

All documentation pages are available as Markdown by appending `.md` to their URL. Index: https://api.nyne.ai/llms.txt

---

Source: https://api.nyne.ai/documentation/company/intent.md

# Company Intent

> Find and rank ICP candidates from demonstrated buying-intent signals.

- **Endpoint:** `POST https://api.nyne.ai/company/intent`
- **Group:** Company APIs (https://api.nyne.ai/documentation/company.md)
- **Auth:** `X-API-Key` + `X-API-Secret` headers
- **Mode:** Asynchronous - submit returns a `request_id` (normally with `202 Accepted`); poll `GET /company/intent?request_id=<request_id>` with the same auth headers until the endpoint reports a terminal response. Where supported, a `callback_url` can notify you when queued work finishes; follow this endpoint's retrieval notes.
- **HTML version:** https://api.nyne.ai/documentation/company/intent

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.

## Authentication

All `/person/*` and `/company/*` endpoints authenticate with an API key and secret sent as HTTP headers on every request: `X-API-Key` and `X-API-Secret`. Create keys from your Nyne.ai dashboard and keep the secret server-side. Rate limits: 100 requests/minute, 1,000 requests/hour. Full guide: https://api.nyne.ai/documentation/authentication.md

## Parameters

| Name | Type | Required | Description | Example |
| --- | --- | --- | --- | --- |
| `interest_company_domain` | string | **yes** | Domain for the company / product category used to find people with demonstrated interest in similar products. Max 255 chars. | "gong.io" |
| `icp_company_domain` | string | **yes** | Domain for the company used to rank candidate ICP fit. Max 255 chars. | "salesforce.com" |
| `max_results` | integer | no | Maximum ranked people to return. Range 1-1000, default 25. | 25 |
| `lite_lookup` | boolean | no | Use the lower-cost lite lookup option for broader demonstrated-interest signals. Defaults to `false`. Returns the same response shape. | false |
| `callback_url` | string | no | Public http(s) endpoint that receives the completed or failed payload. Localhost / private-network targets are rejected. | "https://example.com/webhook/company-intent" |

## Polling for the result

A newly queued submit normally returns `202 Accepted` with a `request_id`. Poll the same path until `status` is `completed` (results stay available afterwards). Where supported, pass a `callback_url` on the submit to receive a webhook when queued work finishes; keep the documented GET as a recovery and retrieval path:

```bash
curl "https://api.nyne.ai/company/intent?request_id=<request_id>" \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "X-API-Secret: YOUR_API_SECRET"
```

## Credit usage

| Item | Credits | Condition |
| --- | --- | --- |
| 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 |

## Responses

| Code | Meaning |
| --- | --- |
| `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 |

## Example request

### 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

resp = requests.post(
    "https://api.nyne.ai/company/intent",
    headers={
        "X-API-Key": "YOUR_API_KEY",
        "X-API-Secret": "YOUR_API_SECRET",
    },
    json={
        "interest_company_domain": "gong.io",
        "icp_company_domain": "salesforce.com",
        "max_results": 25,
    },
)
data = resp.json()
print(data)
```

### Node

```javascript
const resp = await fetch("https://api.nyne.ai/company/intent", {
  method: "POST",
  headers: {
    "X-API-Key": "YOUR_API_KEY",
    "X-API-Secret": "YOUR_API_SECRET",
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    interest_company_domain: "gong.io",
    icp_company_domain: "salesforce.com",
    max_results: 25,
  }),
});
const data = await resp.json();
console.log(data);
```

### PHP

```php
<?php
$ch = curl_init("https://api.nyne.ai/company/intent");
curl_setopt_array($ch, [
  CURLOPT_POST => true,
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_HTTPHEADER => [
    "X-API-Key: YOUR_API_KEY",
    "X-API-Secret: YOUR_API_SECRET",
    "Content-Type: application/json",
  ],
  CURLOPT_POSTFIELDS => json_encode([
    "interest_company_domain" => "gong.io",
    "icp_company_domain" => "salesforce.com",
    "max_results" => 25,
  ]),
]);
$data = json_decode(curl_exec($ch), true);
print_r($data);
```

## Example response

```json
{
  "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"
}
```

---

All documentation pages are available as Markdown by appending `.md` to their URL. Index: https://api.nyne.ai/llms.txt

---

Source: https://api.nyne.ai/documentation/company/checkseller.md

# CheckSeller

> Verify whether a company sells a given product or service.

- **Endpoint:** `POST https://api.nyne.ai/company/checkseller`
- **Group:** Company APIs (https://api.nyne.ai/documentation/company.md)
- **Auth:** `X-API-Key` + `X-API-Secret` headers
- **Mode:** Asynchronous - submit returns a `request_id` (normally with `202 Accepted`); poll `GET /company/checkseller?request_id=<request_id>` with the same auth headers until the endpoint reports a terminal response. Where supported, a `callback_url` can notify you when queued work finishes; follow this endpoint's retrieval notes.
- **HTML version:** https://api.nyne.ai/documentation/company/checkseller

Ask whether a company sells or provides a specific product or service. Both `company_name` and `product_service` are required. The request is queued asynchronously and returns a `request_id`; poll the status endpoint or supply a `callback_url`. The completed result carries a verdict (`sells`), a confidence level, and supporting evidence. A credit is charged only when a verdict is produced.

## Authentication

All `/person/*` and `/company/*` endpoints authenticate with an API key and secret sent as HTTP headers on every request: `X-API-Key` and `X-API-Secret`. Create keys from your Nyne.ai dashboard and keep the secret server-side. Rate limits: 100 requests/minute, 1,000 requests/hour. Full guide: https://api.nyne.ai/documentation/authentication.md

## Parameters

| Name | Type | Required | Description | Example |
| --- | --- | --- | --- | --- |
| `company_name` | string | **yes** | Legal or commonly used company name. Max 255 chars. | "Acme Cloud" |
| `product_service` | string | **yes** | Product or service to test for, e.g. “SOC 2 automation platform”. Max 255 chars. | "SOC 2 compliance automation" |
| `callback_url` | string | no | http(s) URL on an allowed host that receives the completed payload automatically. | "https://example.com/webhooks/checkseller" |

## Polling for the result

A newly queued submit normally returns `202 Accepted` with a `request_id`. Poll the same path until `status` is `completed` (results stay available afterwards). Where supported, pass a `callback_url` on the submit to receive a webhook when queued work finishes; keep the documented GET as a recovery and retrieval path:

```bash
curl "https://api.nyne.ai/company/checkseller?request_id=<request_id>" \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "X-API-Secret: YOUR_API_SECRET"
```

## Credit usage

| Item | Credits | Condition |
| --- | --- | --- |
| CheckSeller | - | Charged once when a verdict (yes/no/unknown) is produced |
| No data | 0 | No verdict / failure never burns credits |

## Responses

| Code | Meaning |
| --- | --- |
| `202` | Seller check queued - poll the status endpoint with the returned request_id |
| `400` | missing_parameters / invalid_parameters / invalid_callback_url |
| `401` | Missing or invalid API credentials |
| `403` | subscription_required or ip_not_allowed |
| `404` | no checkseller data found (no credit charged) |
| `429` | rate_limit_exceeded / monthly_limit_exceeded |
| `503` | service_unavailable - the API is temporarily unavailable |

## Example request

### 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",
    "callback_url": "https://example.com/webhooks/checkseller"
  }'
```

### Python

```python
import requests

resp = requests.post(
    "https://api.nyne.ai/company/checkseller",
    headers={
        "X-API-Key": "YOUR_API_KEY",
        "X-API-Secret": "YOUR_API_SECRET",
    },
    json={
        "company_name": "Acme Cloud",
        "product_service": "SOC 2 compliance automation",
        "callback_url": "https://example.com/webhooks/checkseller",
    },
)
data = resp.json()
print(data)
```

### Node

```javascript
const resp = await fetch("https://api.nyne.ai/company/checkseller", {
  method: "POST",
  headers: {
    "X-API-Key": "YOUR_API_KEY",
    "X-API-Secret": "YOUR_API_SECRET",
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    company_name: "Acme Cloud",
    product_service: "SOC 2 compliance automation",
    callback_url: "https://example.com/webhooks/checkseller",
  }),
});
const data = await resp.json();
console.log(data);
```

### PHP

```php
<?php
$ch = curl_init("https://api.nyne.ai/company/checkseller");
curl_setopt_array($ch, [
  CURLOPT_POST => true,
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_HTTPHEADER => [
    "X-API-Key: YOUR_API_KEY",
    "X-API-Secret: YOUR_API_SECRET",
    "Content-Type: application/json",
  ],
  CURLOPT_POSTFIELDS => json_encode([
    "company_name" => "Acme Cloud",
    "product_service" => "SOC 2 compliance automation",
    "callback_url" => "https://example.com/webhooks/checkseller",
  ]),
]);
$data = json_decode(curl_exec($ch), true);
print_r($data);
```

## Example response

```json
{
  "request_id": "64f2d8e4cs1f065a9b4e7fbc3df6aabb_1700000123_3310",
  "status": "completed",
  "completed": true,
  "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."
  },
  "completed_on": "2026-01-15T10:35:00Z"
}
```

---

All documentation pages are available as Markdown by appending `.md` to their URL. Index: https://api.nyne.ai/llms.txt

---

Source: https://api.nyne.ai/documentation/company/checkfeature.md

# CheckFeature

> Detect whether a company’s site has a given feature, technology, or capability.

- **Endpoint:** `POST https://api.nyne.ai/company/checkfeature`
- **Group:** Company APIs (https://api.nyne.ai/documentation/company.md)
- **Auth:** `X-API-Key` + `X-API-Secret` headers
- **Mode:** Asynchronous - submit returns a `request_id` (normally with `202 Accepted`); poll `GET /company/checkfeature?request_id=<request_id>` with the same auth headers until the endpoint reports a terminal response. Where supported, a `callback_url` can notify you when queued work finishes; follow this endpoint's retrieval notes.
- **HTML version:** https://api.nyne.ai/documentation/company/checkfeature

Check whether a company has a specific feature, technology, or capability - JavaScript libraries, security/compliance badges, technology stacks, integrations, and more. Both `company` (note: this field is named `company`, not `company_name`) and `feature` are required. The request is queued asynchronously and returns a `request_id`; poll or supply a `callback_url`. The completed result carries `has_feature`, a confidence level, and supporting evidence. A credit is charged only when a result is produced.

## Authentication

All `/person/*` and `/company/*` endpoints authenticate with an API key and secret sent as HTTP headers on every request: `X-API-Key` and `X-API-Secret`. Create keys from your Nyne.ai dashboard and keep the secret server-side. Rate limits: 100 requests/minute, 1,000 requests/hour. Full guide: https://api.nyne.ai/documentation/authentication.md

## Parameters

| Name | Type | Required | Description | Example |
| --- | --- | --- | --- | --- |
| `company` | string | **yes** | Company name or domain to check. Use the field name `company`, not `company_name`. Max 255 chars. | "stripe.com" |
| `feature` | string | **yes** | Feature to detect, e.g. “jQuery library”, “SOC 2 badge”, “uses Cloudflare”. Max 500 chars. | "React" |
| `callback_url` | string | no | http(s) URL on an allowed host that receives the completed payload automatically. | "https://example.com/webhooks/checkfeature" |

## Polling for the result

A newly queued submit normally returns `202 Accepted` with a `request_id`. Poll the same path until `status` is `completed` (results stay available afterwards). Where supported, pass a `callback_url` on the submit to receive a webhook when queued work finishes; keep the documented GET as a recovery and retrieval path:

```bash
curl "https://api.nyne.ai/company/checkfeature?request_id=<request_id>" \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "X-API-Secret: YOUR_API_SECRET"
```

## Credit usage

| Item | Credits | Condition |
| --- | --- | --- |
| CheckFeature | - | Charged once when a result (found/not_found) is produced |
| No data | 0 | No result / failure never burns credits |

## Responses

| Code | Meaning |
| --- | --- |
| `202` | Feature check queued - poll the status endpoint with the returned request_id |
| `400` | missing_parameters / invalid_parameters / invalid_callback_url |
| `401` | Missing or invalid API credentials |
| `403` | subscription_required or ip_not_allowed |
| `404` | no checkfeature data found (no credit charged) |
| `429` | rate_limit_exceeded / monthly_limit_exceeded |
| `503` | service_unavailable - the API is temporarily unavailable |

## Example request

### cURL

```bash
curl -X POST https://api.nyne.ai/company/checkfeature \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "X-API-Secret: YOUR_API_SECRET" \
  -H "Content-Type: application/json" \
  -d '{
    "company": "stripe.com",
    "feature": "React",
    "callback_url": "https://example.com/webhooks/checkfeature"
  }'
```

### Python

```python
import requests

resp = requests.post(
    "https://api.nyne.ai/company/checkfeature",
    headers={
        "X-API-Key": "YOUR_API_KEY",
        "X-API-Secret": "YOUR_API_SECRET",
    },
    json={
        "company": "stripe.com",
        "feature": "React",
        "callback_url": "https://example.com/webhooks/checkfeature",
    },
)
data = resp.json()
print(data)
```

### Node

```javascript
const resp = await fetch("https://api.nyne.ai/company/checkfeature", {
  method: "POST",
  headers: {
    "X-API-Key": "YOUR_API_KEY",
    "X-API-Secret": "YOUR_API_SECRET",
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    company: "stripe.com",
    feature: "React",
    callback_url: "https://example.com/webhooks/checkfeature",
  }),
});
const data = await resp.json();
console.log(data);
```

### PHP

```php
<?php
$ch = curl_init("https://api.nyne.ai/company/checkfeature");
curl_setopt_array($ch, [
  CURLOPT_POST => true,
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_HTTPHEADER => [
    "X-API-Key: YOUR_API_KEY",
    "X-API-Secret: YOUR_API_SECRET",
    "Content-Type: application/json",
  ],
  CURLOPT_POSTFIELDS => json_encode([
    "company" => "stripe.com",
    "feature" => "React",
    "callback_url" => "https://example.com/webhooks/checkfeature",
  ]),
]);
$data = json_decode(curl_exec($ch), true);
print_r($data);
```

## Example response

```json
{
  "request_id": "64f2d8e4cf1f065a9b4e7fbc3df6aabb_1700000123_4410",
  "status": "completed",
  "completed": true,
  "result": {
    "company": "stripe.com",
    "feature": "React",
    "has_feature": true,
    "confidence": "high",
    "evidence": "React 18 detected in the site's bundled JavaScript."
  },
  "completed_on": "2026-01-15T10:35:00Z"
}
```

---

All documentation pages are available as Markdown by appending `.md` to their URL. Index: https://api.nyne.ai/llms.txt

---

Source: https://api.nyne.ai/documentation/company/funding.md

# Company Funding

> Retrieve verified funding-round and acquisition history for a company.

- **Endpoint:** `POST https://api.nyne.ai/company/funding`
- **Group:** Company APIs (https://api.nyne.ai/documentation/company.md)
- **Auth:** `X-API-Key` + `X-API-Secret` headers
- **Mode:** Asynchronous - submit returns a `request_id` (normally with `202 Accepted`); poll `GET /company/funding?request_id=<request_id>` with the same auth headers until the endpoint reports a terminal response. Where supported, a `callback_url` can notify you when queued work finishes; follow this endpoint's retrieval notes.
- **HTML version:** https://api.nyne.ai/documentation/company/funding

Retrieve a company’s funding history - rounds with dates, investors, amounts, and valuations, plus acquisition detail when applicable - aggregated from verified sources. Supply at least one of `company_name` or `company_domain`. The request is queued asynchronously and returns a `request_id`; poll the status endpoint or supply a `callback_url`. The completed result includes a `funding_rounds` array (most recent first) and an optional `acquired` object. Rounds may carry an `amount_approximate` flag when the figure is an estimate, and each investor in `funded_by` may be marked `lead_investor`. A credit is charged only when funding data is found.

## Authentication

All `/person/*` and `/company/*` endpoints authenticate with an API key and secret sent as HTTP headers on every request: `X-API-Key` and `X-API-Secret`. Create keys from your Nyne.ai dashboard and keep the secret server-side. Rate limits: 100 requests/minute, 1,000 requests/hour. Full guide: https://api.nyne.ai/documentation/authentication.md

## Parameters

| Name | Type | Required | Description | Example |
| --- | --- | --- | --- | --- |
| `company_name` | string | no | Company name to look up, e.g. “Stripe”, “OpenAI”. Required unless `company_domain` is supplied. Max 255 chars. | "Stripe" |
| `company_domain` | string | no | Company domain to look up, e.g. “stripe.com”. Required unless `company_name` is supplied. Max 255 chars. | "stripe.com" |
| `callback_url` | string | no | http(s) URL on an allowed host that receives the completed payload automatically. | "https://example.com/webhooks/funding" |

## Polling for the result

A newly queued submit normally returns `202 Accepted` with a `request_id`. Poll the same path until `status` is `completed` (results stay available afterwards). Where supported, pass a `callback_url` on the submit to receive a webhook when queued work finishes; keep the documented GET as a recovery and retrieval path:

```bash
curl "https://api.nyne.ai/company/funding?request_id=<request_id>" \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "X-API-Secret: YOUR_API_SECRET"
```

## Credit usage

| Item | Credits | Condition |
| --- | --- | --- |
| Funding Lookup | - | Charged once when funding data is retrieved |
| No data | 0 | No funding found never burns credits |

## Responses

| Code | Meaning |
| --- | --- |
| `202` | Funding lookup queued - poll the status endpoint with the returned request_id |
| `400` | missing_parameters / invalid_parameters / invalid_callback_url |
| `401` | Missing or invalid API credentials |
| `402` | insufficient_credits |
| `403` | subscription_required or ip_not_allowed |
| `404` | no funding data found (no credit charged) |
| `429` | rate_limit_exceeded / monthly_limit_exceeded |
| `503` | service_unavailable - the API is temporarily unavailable |

## Example request

### cURL

```bash
curl -X POST https://api.nyne.ai/company/funding \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "X-API-Secret: YOUR_API_SECRET" \
  -H "Content-Type: application/json" \
  -d '{
    "company_name": "Stripe",
    "callback_url": "https://example.com/webhooks/funding"
  }'
```

### Python

```python
import requests

resp = requests.post(
    "https://api.nyne.ai/company/funding",
    headers={
        "X-API-Key": "YOUR_API_KEY",
        "X-API-Secret": "YOUR_API_SECRET",
    },
    json={
        "company_name": "Stripe",
        "callback_url": "https://example.com/webhooks/funding",
    },
)
data = resp.json()
print(data)
```

### Node

```javascript
const resp = await fetch("https://api.nyne.ai/company/funding", {
  method: "POST",
  headers: {
    "X-API-Key": "YOUR_API_KEY",
    "X-API-Secret": "YOUR_API_SECRET",
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    company_name: "Stripe",
    callback_url: "https://example.com/webhooks/funding",
  }),
});
const data = await resp.json();
console.log(data);
```

### PHP

```php
<?php
$ch = curl_init("https://api.nyne.ai/company/funding");
curl_setopt_array($ch, [
  CURLOPT_POST => true,
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_HTTPHEADER => [
    "X-API-Key: YOUR_API_KEY",
    "X-API-Secret: YOUR_API_SECRET",
    "Content-Type: application/json",
  ],
  CURLOPT_POSTFIELDS => json_encode([
    "company_name" => "Stripe",
    "callback_url" => "https://example.com/webhooks/funding",
  ]),
]);
$data = json_decode(curl_exec($ch), true);
print_r($data);
```

## Example response

```json
{
  "request_id": "64f2d8e4fd1f065a9b4e7fbc3df6aabb_1700000123_5510",
  "status": "completed",
  "completed": true,
  "result": {
    "company_domain": "stripe.com",
    "funding_rounds": [
      {
        "series_type": "Series I",
        "funding_date": {
          "year": 2024,
          "month": 3,
          "day": 15
        },
        "amount": 6940000000,
        "amount_approximate": true,
        "currency": "USD",
        "valuation": 65000000000,
        "funded_by": [
          {
            "name": "Thrive Capital",
            "lead_investor": true
          },
          {
            "name": "General Catalyst"
          }
        ]
      }
    ],
    "acquired": null
  },
  "completed_on": "2026-01-15T10:35:00Z"
}
```

---

All documentation pages are available as Markdown by appending `.md` to their URL. Index: https://api.nyne.ai/llms.txt

---

Source: https://api.nyne.ai/documentation/company/funders.md

# Company Funders

> Look up an investor / fund profile (partners, thesis, check size, recent deals).

- **Endpoint:** `POST https://api.nyne.ai/company/funders`
- **Group:** Company APIs (https://api.nyne.ai/documentation/company.md)
- **Auth:** `X-API-Key` + `X-API-Secret` headers
- **Mode:** Asynchronous - submit returns a `request_id` (normally with `202 Accepted`); poll `GET /company/funders?request_id=<request_id>` with the same auth headers until the endpoint reports a terminal response. Where supported, a `callback_url` can notify you when queued work finishes; follow this endpoint's retrieval notes.
- **HTML version:** https://api.nyne.ai/documentation/company/funders

Retrieve a profile for an investment firm, VC fund, or angel investor - partners, investment thesis, typical check size, the rounds they invest in, portfolio locations, and recent investments. Supply at least one of `company_name` or `company_domain` (the investor’s name/domain - prefer the domain when available, it gives the strongest match). The request is queued asynchronously and returns a `request_id`; poll the status endpoint or supply a `callback_url`. Result arrays are bounded - up to 20 `partners`, 5 `investment_locations`, and 5 `recent_investments` - and fields with no data are omitted. A credit is charged only when investor data is found.

## Authentication

All `/person/*` and `/company/*` endpoints authenticate with an API key and secret sent as HTTP headers on every request: `X-API-Key` and `X-API-Secret`. Create keys from your Nyne.ai dashboard and keep the secret server-side. Rate limits: 100 requests/minute, 1,000 requests/hour. Full guide: https://api.nyne.ai/documentation/authentication.md

## Parameters

| Name | Type | Required | Description | Example |
| --- | --- | --- | --- | --- |
| `company_name` | string | no | Investor name to look up, e.g. “Y Combinator”, “Sequoia Capital”. Required unless `company_domain` is supplied. Max 255 chars. | "Sequoia Capital" |
| `company_domain` | string | no | Investor domain to look up, e.g. “sequoiacap.com”, “a16z.com”. Required unless `company_name` is supplied. Max 255 chars. | "sequoiacap.com" |
| `callback_url` | string | no | http(s) URL on an allowed host that receives the completed payload automatically. | "https://example.com/webhooks/funders" |

## Polling for the result

A newly queued submit normally returns `202 Accepted` with a `request_id`. Poll the same path until `status` is `completed` (results stay available afterwards). Where supported, pass a `callback_url` on the submit to receive a webhook when queued work finishes; keep the documented GET as a recovery and retrieval path:

```bash
curl "https://api.nyne.ai/company/funders?request_id=<request_id>" \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "X-API-Secret: YOUR_API_SECRET"
```

## Credit usage

| Item | Credits | Condition |
| --- | --- | --- |
| Investor Lookup | - | Charged once when investor data is retrieved |
| No data | 0 | No investor found never burns credits |

## Responses

| Code | Meaning |
| --- | --- |
| `202` | Investor lookup queued - poll the status endpoint with the returned request_id |
| `400` | missing_parameters / invalid_parameters / invalid_callback_url |
| `401` | Missing or invalid API credentials |
| `402` | insufficient_credits |
| `403` | subscription_required or ip_not_allowed |
| `404` | no funder data found (no credit charged) |
| `429` | rate_limit_exceeded / monthly_limit_exceeded |
| `503` | service_unavailable - the API is temporarily unavailable |

## Example request

### cURL

```bash
curl -X POST https://api.nyne.ai/company/funders \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "X-API-Secret: YOUR_API_SECRET" \
  -H "Content-Type: application/json" \
  -d '{
    "company_name": "Y Combinator",
    "callback_url": "https://example.com/webhooks/funders"
  }'
```

### Python

```python
import requests

resp = requests.post(
    "https://api.nyne.ai/company/funders",
    headers={
        "X-API-Key": "YOUR_API_KEY",
        "X-API-Secret": "YOUR_API_SECRET",
    },
    json={
        "company_name": "Y Combinator",
        "callback_url": "https://example.com/webhooks/funders",
    },
)
data = resp.json()
print(data)
```

### Node

```javascript
const resp = await fetch("https://api.nyne.ai/company/funders", {
  method: "POST",
  headers: {
    "X-API-Key": "YOUR_API_KEY",
    "X-API-Secret": "YOUR_API_SECRET",
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    company_name: "Y Combinator",
    callback_url: "https://example.com/webhooks/funders",
  }),
});
const data = await resp.json();
console.log(data);
```

### PHP

```php
<?php
$ch = curl_init("https://api.nyne.ai/company/funders");
curl_setopt_array($ch, [
  CURLOPT_POST => true,
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_HTTPHEADER => [
    "X-API-Key: YOUR_API_KEY",
    "X-API-Secret: YOUR_API_SECRET",
    "Content-Type: application/json",
  ],
  CURLOPT_POSTFIELDS => json_encode([
    "company_name" => "Y Combinator",
    "callback_url" => "https://example.com/webhooks/funders",
  ]),
]);
$data = json_decode(curl_exec($ch), true);
print_r($data);
```

## Example response

```json
{
  "request_id": "64f2d8e4fr1f065a9b4e7fbc3df6aabb_1700000123_6610",
  "status": "completed",
  "completed": true,
  "result": {
    "investor_name": "Y Combinator",
    "investor_domain": "ycombinator.com",
    "location": "Mountain View, CA, US",
    "investment_thesis": "Backs early-stage startups at the idea / seed stage.",
    "partners": [
      {
        "name": "Garry Tan",
        "linkedin_url": "https://www.linkedin.com/in/garrytan/"
      }
    ],
    "average_check_size": {
      "low": 125000,
      "high": 500000,
      "currency": "USD"
    },
    "rounds_they_invest_in": [
      "pre_seed",
      "seed"
    ],
    "recent_investments": [
      {
        "company_name": "Example Startup",
        "company_domain": "example.com",
        "amount": 500000,
        "currency": "USD"
      }
    ]
  },
  "completed_on": "2026-01-15T10:35:00Z"
}
```

---

All documentation pages are available as Markdown by appending `.md` to their URL. Index: https://api.nyne.ai/llms.txt

---

Source: https://api.nyne.ai/documentation/company/needs.md

# Company Needs

> Summarize pain points / challenges from a company’s official filings.

- **Endpoint:** `POST https://api.nyne.ai/company/needs`
- **Group:** Company APIs (https://api.nyne.ai/documentation/company.md)
- **Auth:** `X-API-Key` + `X-API-Secret` headers
- **Mode:** Asynchronous - submit returns a `request_id` (normally with `202 Accepted`); poll `GET /company/needs?request_id=<request_id>` with the same auth headers until the endpoint reports a terminal response. Where supported, a `callback_url` can notify you when queued work finishes; follow this endpoint's retrieval notes.
- **HTML version:** https://api.nyne.ai/documentation/company/needs

Surface recent pain points, challenges, or other requested topics from a company’s official filings as concise, structured highlights. Both `company_name` and `content` (the topic to surface) are required; an optional `filing` restricts the search to one filing type. The request is queued asynchronously and returns a `request_id`; poll the status endpoint or supply a `callback_url`. The completed result includes a `needs` array with one entry per matching filing excerpt (filing, content, date, and source URL) - an empty array when nothing matches. Analysis typically takes 15-60 seconds. A credit is charged only when the analysis produces results.

## Authentication

All `/person/*` and `/company/*` endpoints authenticate with an API key and secret sent as HTTP headers on every request: `X-API-Key` and `X-API-Secret`. Create keys from your Nyne.ai dashboard and keep the secret server-side. Rate limits: 100 requests/minute, 1,000 requests/hour. Full guide: https://api.nyne.ai/documentation/authentication.md

## Parameters

| Name | Type | Required | Description | Example |
| --- | --- | --- | --- | --- |
| `company_name` | string | **yes** | Company to analyze, e.g. “Uber Technologies, Inc.”. Max 255 chars. | "Uber Technologies, Inc." |
| `content` | string | **yes** | Topic to surface, e.g. “Regulatory challenges”, “Supply chain issues”. Max 255 chars. | "Regulatory challenges" |
| `filing` | string | no | Restrict to a filing type, e.g. “Form 10-K”, “Form 8-K”. Max 255 chars. | "Form 10-K" |
| `callback_url` | string | no | http(s) URL on an allowed host that receives the completed payload automatically. | "https://example.com/webhooks/company-needs" |

## Polling for the result

A newly queued submit normally returns `202 Accepted` with a `request_id`. Poll the same path until `status` is `completed` (results stay available afterwards). Where supported, pass a `callback_url` on the submit to receive a webhook when queued work finishes; keep the documented GET as a recovery and retrieval path:

```bash
curl "https://api.nyne.ai/company/needs?request_id=<request_id>" \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "X-API-Secret: YOUR_API_SECRET"
```

## Credit usage

| Item | Credits | Condition |
| --- | --- | --- |
| Needs Analysis | - | Charged once when the analysis produces results |
| No data | 0 | No relevant filings never burns credits |

## Responses

| Code | Meaning |
| --- | --- |
| `202` | Needs analysis queued - poll the status endpoint with the returned request_id |
| `400` | missing_parameters / invalid_parameters / invalid_callback_url |
| `401` | Missing or invalid API credentials |
| `403` | subscription_required or ip_not_allowed |
| `404` | no needs data found (no credit charged) |
| `429` | rate_limit_exceeded / monthly_limit_exceeded |
| `503` | service_unavailable - the API is temporarily unavailable |

## Example request

### cURL

```bash
curl -X POST https://api.nyne.ai/company/needs \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "X-API-Secret: YOUR_API_SECRET" \
  -H "Content-Type: application/json" \
  -d '{
    "company_name": "Uber Technologies, Inc.",
    "content": "Regulatory challenges",
    "filing": "Form 10-K",
    "callback_url": "https://example.com/webhooks/company-needs"
  }'
```

### Python

```python
import requests

resp = requests.post(
    "https://api.nyne.ai/company/needs",
    headers={
        "X-API-Key": "YOUR_API_KEY",
        "X-API-Secret": "YOUR_API_SECRET",
    },
    json={
        "company_name": "Uber Technologies, Inc.",
        "content": "Regulatory challenges",
        "filing": "Form 10-K",
        "callback_url": "https://example.com/webhooks/company-needs",
    },
)
data = resp.json()
print(data)
```

### Node

```javascript
const resp = await fetch("https://api.nyne.ai/company/needs", {
  method: "POST",
  headers: {
    "X-API-Key": "YOUR_API_KEY",
    "X-API-Secret": "YOUR_API_SECRET",
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    company_name: "Uber Technologies, Inc.",
    content: "Regulatory challenges",
    filing: "Form 10-K",
    callback_url: "https://example.com/webhooks/company-needs",
  }),
});
const data = await resp.json();
console.log(data);
```

### PHP

```php
<?php
$ch = curl_init("https://api.nyne.ai/company/needs");
curl_setopt_array($ch, [
  CURLOPT_POST => true,
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_HTTPHEADER => [
    "X-API-Key: YOUR_API_KEY",
    "X-API-Secret: YOUR_API_SECRET",
    "Content-Type: application/json",
  ],
  CURLOPT_POSTFIELDS => json_encode([
    "company_name" => "Uber Technologies, Inc.",
    "content" => "Regulatory challenges",
    "filing" => "Form 10-K",
    "callback_url" => "https://example.com/webhooks/company-needs",
  ]),
]);
$data = json_decode(curl_exec($ch), true);
print_r($data);
```

## Example response

```json
{
  "request_id": "64f2d8e4nd1f065a9b4e7fbc3df6aabb_1700000456_7710",
  "status": "completed",
  "completed": true,
  "result": {
    "company": "Uber Technologies, Inc.",
    "needs": [
      {
        "filing": "Form 10-K",
        "content": "Notes increased regulatory compliance costs across multiple regions.",
        "filing_date": "2025-02-14",
        "source_url": "https://www.sec.gov/Archives/edgar/data/1543151/uber-20241231x10k.htm"
      }
    ]
  },
  "completed_on": "2026-01-15T10:35:00Z"
}
```

---

All documentation pages are available as Markdown by appending `.md` to their URL. Index: https://api.nyne.ai/llms.txt

---

Source: https://api.nyne.ai/documentation/company/competitor-engagements.md

# Competitor Engagements

> Find people who engaged with a company page, with profile URLs and post context.

- **Endpoint:** `POST https://api.nyne.ai/company/competitor-engagements`
- **Group:** Company APIs (https://api.nyne.ai/documentation/company.md)
- **Auth:** `X-API-Key` + `X-API-Secret` headers
- **Mode:** Asynchronous - submit returns a `request_id` (normally with `202 Accepted`); poll `GET /company/competitor-engagements?request_id=<request_id>` with the same auth headers until the endpoint reports a terminal response. Where supported, a `callback_url` can notify you when queued work finishes; follow this endpoint's retrieval notes.
- **HTML version:** https://api.nyne.ai/documentation/company/competitor-engagements

Find people who have demonstrated engagement around a company page and return their available profile URLs with post context. Supply a `company_url` plus optional result and sorting controls. The request is queued asynchronously and returns a `request_id`; poll the status endpoint or supply a `callback_url`. Results are person-first engagement items with `linkedin_profile_url`, person details, post date/context, and aggregate engagement metrics; people identified as current employees of the requested company are excluded when current-organization data is available. Callback delivery is best effort - keep the returned `request_id` and use the status endpoint for the final result. Credits are charged per person engagement result returned.

## Authentication

All `/person/*` and `/company/*` endpoints authenticate with an API key and secret sent as HTTP headers on every request: `X-API-Key` and `X-API-Secret`. Create keys from your Nyne.ai dashboard and keep the secret server-side. Rate limits: 100 requests/minute, 1,000 requests/hour. Full guide: https://api.nyne.ai/documentation/authentication.md

## Parameters

| Name | Type | Required | Description | Example |
| --- | --- | --- | --- | --- |
| `company_url` | string | **yes** | Company page URL to analyze. Must be a supported company page, not a person profile URL. | "https://www.linkedin.com/company/nyne-ai" |
| `max_items` | integer | no | Maximum engagement results to return. Range 1-100, default 100. | 100 |
| `page_number` | integer | no | Page number for result pagination. Default 1. | 1 |
| `sort` | string | no | Sort order - `recent` (default) or `top`. | "recent" |
| `callback_url` | string | no | Public http(s) endpoint that receives the completed or failed payload. Localhost / private-network targets are rejected. | "https://example.com/webhook/company-engagements" |

## Polling for the result

A newly queued submit normally returns `202 Accepted` with a `request_id`. Poll the same path until `status` is `completed` (results stay available afterwards). Where supported, pass a `callback_url` on the submit to receive a webhook when queued work finishes; keep the documented GET as a recovery and retrieval path:

```bash
curl "https://api.nyne.ai/company/competitor-engagements?request_id=<request_id>" \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "X-API-Secret: YOUR_API_SECRET"
```

## Credit usage

| Item | Credits | Condition |
| --- | --- | --- |
| Competitor Engagements | 5 | Charged per person engagement result returned (per-result) |
| No results | 0 | No person profile results never burns per-result credits |

## Responses

| Code | Meaning |
| --- | --- |
| `202` | Request queued - poll the status endpoint with the returned request_id |
| `400` | missing_parameters / invalid_company_url / invalid_limit / 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 - the request could not be queued |

## Example request

### cURL

```bash
curl -X POST https://api.nyne.ai/company/competitor-engagements \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "X-API-Secret: YOUR_API_SECRET" \
  -H "Content-Type: application/json" \
  -d '{
    "company_url": "https://www.linkedin.com/company/nyne-ai",
    "max_items": 100,
    "page_number": 1,
    "sort": "recent",
    "callback_url": "https://example.com/webhook/company-engagements"
  }'
```

### Python

```python
import requests

resp = requests.post(
    "https://api.nyne.ai/company/competitor-engagements",
    headers={
        "X-API-Key": "YOUR_API_KEY",
        "X-API-Secret": "YOUR_API_SECRET",
    },
    json={
        "company_url": "https://www.linkedin.com/company/nyne-ai",
        "max_items": 100,
        "page_number": 1,
        "sort": "recent",
        "callback_url": "https://example.com/webhook/company-engagements",
    },
)
data = resp.json()
print(data)
```

### Node

```javascript
const resp = await fetch("https://api.nyne.ai/company/competitor-engagements", {
  method: "POST",
  headers: {
    "X-API-Key": "YOUR_API_KEY",
    "X-API-Secret": "YOUR_API_SECRET",
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    company_url: "https://www.linkedin.com/company/nyne-ai",
    max_items: 100,
    page_number: 1,
    sort: "recent",
    callback_url: "https://example.com/webhook/company-engagements",
  }),
});
const data = await resp.json();
console.log(data);
```

### PHP

```php
<?php
$ch = curl_init("https://api.nyne.ai/company/competitor-engagements");
curl_setopt_array($ch, [
  CURLOPT_POST => true,
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_HTTPHEADER => [
    "X-API-Key: YOUR_API_KEY",
    "X-API-Secret: YOUR_API_SECRET",
    "Content-Type: application/json",
  ],
  CURLOPT_POSTFIELDS => json_encode([
    "company_url" => "https://www.linkedin.com/company/nyne-ai",
    "max_items" => 100,
    "page_number" => 1,
    "sort" => "recent",
    "callback_url" => "https://example.com/webhook/company-engagements",
  ]),
]);
$data = json_decode(curl_exec($ch), true);
print_r($data);
```

## Example response

```json
{
  "request_id": "65f6d9f92799d3c2a24123f4f13a7d7a_1700000123_8810",
  "status": "completed",
  "completed": true,
  "result": {
    "results": [
      {
        "linkedin_profile_url": "https://www.linkedin.com/in/janedoe",
        "person": {
          "name": "Jane Doe",
          "organizations": [
            {
              "name": "Example Software",
              "title": "Head of Growth"
            }
          ]
        },
        "interaction_type": "company_post",
        "post_date": "2026-01-10T15:30:00Z",
        "engagement_metrics": {
          "likes": 24,
          "comments": 3,
          "shares": 1
        }
      }
    ],
    "total_results": 1
  },
  "completed_on": "2026-01-15T10:35:00Z"
}
```

---

All documentation pages are available as Markdown by appending `.md` to their URL. Index: https://api.nyne.ai/llms.txt

---

Source: https://api.nyne.ai/documentation/account.md

# Account APIs

> Account-level monitoring - track credit consumption, monthly allocation, and per-API usage breakdowns.

- **Auth:** `X-API-Key` + `X-API-Secret` headers
- **Mode:** Most operations are asynchronous - submit returns a `request_id`, normally with `202 Accepted`; poll using that endpoint's documented status path or use a `callback_url` webhook.
- **HTML version:** https://api.nyne.ai/documentation/account

The Account APIs report on your own API account rather than on people or companies. They are synchronous reads - no queue, no `request_id` - and they never consume credits.

## Endpoints

### Monitoring

See what your account has consumed and what remains.

- **[Usage](https://api.nyne.ai/documentation/account/usage.md)** - `GET /usage` - Monitor credit consumption, allocation, and per-API breakdown (synchronous, 200).

## Worked example

The [Usage](https://api.nyne.ai/documentation/account/usage) endpoint returns the current month's credit and request statistics in a single synchronous call.

### 1. Submit - `GET /usage`

```bash
curl https://api.nyne.ai/usage \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "X-API-Secret: YOUR_API_SECRET"
```

The call returns `202 Accepted` immediately:

```json
{
  "request_id": "a1b2c3d4e5f6_1717000000_4271",
  "status": "queued"
}
```

### 2. Poll until completed

```bash
curl "https://api.nyne.ai/usage?request_id=<request_id>" \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "X-API-Secret: YOUR_API_SECRET"
```

When `status` is `completed`, the same response carries the result:

```json
{
  "month": 12,
  "year": 2024,
  "period": "2024-12",
  "period_type": "calendar_month",
  "scope": {
    "type": "workspace",
    "workspace_id": 1234,
    "authenticated_api_key_id": 5678
  },
  "credits_used": {
    "total": 68,
    "search": 45,
    "enrichment": 23
  },
  "requests_count": {
    "total": 25,
    "search": 15,
    "enrichment": 10
  },
  "limits": {
    "monthly_allocation": 10000,
    "available_credits": 9932,
    "is_unlimited": false
  },
  "breakdown": {
    "search_results_returned": 45,
    "enrichments_performed": 23,
    "total_credits_consumed": 68
  }
}
```

## Authentication & credits

All `/person/*` and `/company/*` endpoints authenticate with an API key and secret sent as HTTP headers on every request: `X-API-Key` and `X-API-Secret`. Create keys from your Nyne.ai dashboard and keep the secret server-side. Rate limits: 100 requests/minute, 1,000 requests/hour. Full guide: https://api.nyne.ai/documentation/authentication.md

Credits are charged only on meaningful results - empty results never burn credits. Each endpoint page lists its exact credit costs.

## FAQ

### Does the Usage endpoint consume API credits?

No. The Usage endpoint reports credit consumption, request volume, and remaining allocation without consuming enrichment credits.

---

All documentation pages are available as Markdown by appending `.md` to their URL. Index: https://api.nyne.ai/llms.txt

---

Source: https://api.nyne.ai/documentation/account/usage.md

# Usage

> Monitor credit consumption, allocation, and per-API breakdown (synchronous, 200).

- **Endpoint:** `GET https://api.nyne.ai/usage`
- **Group:** Account APIs (https://api.nyne.ai/documentation/account.md)
- **Auth:** `X-API-Key` + `X-API-Secret` headers
- **Mode:** Synchronous - the response is returned inline.
- **HTML version:** https://api.nyne.ai/documentation/account/usage

A single synchronous endpoint to view all API usage across enrichment and search requests: credits consumed, allocation, remaining balance, and detailed per-API breakdowns. Without `month`/`year`, it reports the active billing period. Supplying both selects that calendar month (future periods are rejected with `invalid_date`). For prepaid accounts, usage and available credits are workspace-scoped across every API key in that workspace; legacy manual-billing accounts remain scoped to the authenticated key. The response reports credits, not dollars: the monetary price per credit is determined by the account's subscription or credit-purchase tier. Usage checks are free.

## Authentication

All `/person/*` and `/company/*` endpoints authenticate with an API key and secret sent as HTTP headers on every request: `X-API-Key` and `X-API-Secret`. Create keys from your Nyne.ai dashboard and keep the secret server-side. Rate limits: 100 requests/minute, 1,000 requests/hour. Full guide: https://api.nyne.ai/documentation/authentication.md

## Parameters

| Name | Type | Required | Description | Example |
| --- | --- | --- | --- | --- |
| `month` | integer | no | Calendar month to report (1-12). Omit both month and year to use the active billing period. | 12 |
| `year` | integer | no | Calendar year to report (2020-2030). Supply it together with month; omit both to use the active billing period. | 2026 |

## Credit usage

| Item | Credits | Condition |
| --- | --- | --- |
| Usage | 0 | Monitoring endpoint - usage checks are free |

## Responses

| Code | Meaning |
| --- | --- |
| `200` | Usage statistics retrieved |
| `400` | invalid_month / invalid_year / invalid_date (future months are rejected) |
| `401` | missing_api_key / invalid_api_key / missing_api_secret / invalid_api_secret |
| `403` | api_key_disabled |
| `429` | rate_limit_exceeded |
| `500` | internal_error |

## Example request

### cURL

```bash
curl https://api.nyne.ai/usage \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "X-API-Secret: YOUR_API_SECRET"
```

### Python

```python
import requests

resp = requests.get(
    "https://api.nyne.ai/usage",
    headers={
        "X-API-Key": "YOUR_API_KEY",
        "X-API-Secret": "YOUR_API_SECRET",
    },
)
data = resp.json()
print(data)
```

### Node

```javascript
const resp = await fetch("https://api.nyne.ai/usage", {
  method: "GET",
  headers: {
    "X-API-Key": "YOUR_API_KEY",
    "X-API-Secret": "YOUR_API_SECRET",
  },
});
const data = await resp.json();
console.log(data);
```

### PHP

```php
<?php
$ch = curl_init("https://api.nyne.ai/usage");
curl_setopt_array($ch, [
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_HTTPHEADER => [
    "X-API-Key: YOUR_API_KEY",
    "X-API-Secret: YOUR_API_SECRET",
  ],
]);
$data = json_decode(curl_exec($ch), true);
print_r($data);
```

## Example response

```json
{
  "month": 12,
  "year": 2024,
  "period": "2024-12",
  "period_type": "calendar_month",
  "scope": {
    "type": "workspace",
    "workspace_id": 1234,
    "authenticated_api_key_id": 5678
  },
  "credits_used": {
    "total": 68,
    "search": 45,
    "enrichment": 23
  },
  "requests_count": {
    "total": 25,
    "search": 15,
    "enrichment": 10
  },
  "limits": {
    "monthly_allocation": 10000,
    "available_credits": 9932,
    "is_unlimited": false
  },
  "breakdown": {
    "search_results_returned": 45,
    "enrichments_performed": 23,
    "total_credits_consumed": 68
  }
}
```

---

All documentation pages are available as Markdown by appending `.md` to their URL. Index: https://api.nyne.ai/llms.txt

---

Source: https://api.nyne.ai/documentation/mcp.md

# Nyne.ai MCP Server

> Connect AI assistants like ChatGPT and Claude directly to Nyne.ai's people data workflows using the Model Context Protocol (MCP).

HTML version: https://api.nyne.ai/documentation/mcp

**Model Context Protocol (MCP)** is an open standard that enables AI assistants to securely connect to external data sources and tools - a universal plugin system for AI. The **hosted Nyne.ai MCP Server** brings Nyne.ai's common people search and enrichment workflows directly into your assistant conversations:

- **People Search** - semantic search across millions of profiles by company, role, location, or keywords.
- **Profile Enrichment** - comprehensive person profiles with contact info, work history, education, and socials.
- **AI-Powered Insights** - ask natural-language questions about profiles and get intelligent analysis.

## Coverage

The hosted MCP exposes a curated subset of Nyne.ai workflows: people search, person enrichment, targeted lookup fields, person newsfeed, person Q&A, company search, and company enrichment. For the broader endpoint surface, point agents at the machine-readable docs first:

- llms.txt: https://api.nyne.ai/llms.txt
- Agent manifest: https://api.nyne.ai/.well-known/nyne-api.json

## Available tools

### person_search

Search for people from a natural-language query, structured filters, or pagination cursor/request_id.

- Search by query
- Search by structured filters or docid whitelist
- Request contact fields and profile scoring
- Up to 100 results per query
- Requires 'search' product access

Example: *"Find software engineers at Google in San Francisco"*

### person_enrichment

Get detailed profile information for a person using email, phone, name, or social profile URL. This is also how you look up specific contact fields: the enrichment result already includes best work email, personal email, mobile, headline, current company, current title, and photo URL, so use it when you only need one or a few of those values.

- Lookup by email, phone, social URL, or name
- Comprehensive contact information (best work email, mobile, title, headline, photo URL, and more)
- Use for targeted field lookups: the profile already includes the individual fields
- Work history and education
- Social media profiles
- Requires 'enrichment' product access

Example: *"Get the profile for john@example.com"*

### person_newsfeed

Fetch recent social posts and activity for a social profile URL.

- Supports LinkedIn/social URLs
- Optional limit and posts_after date
- Requires newsfeed product access

### person_ask

Ask AI-powered questions about a person's profile using natural language.

- Natural language Q&A
- AI-powered analysis
- Context-aware answers
- Synthesizes multiple data points
- Requires 'enrichment' product access

Example: *"What is this person's current role and experience?"*

### company_search

Search for companies by industry or website keyword, optionally filtered by location.

### company_enrichment

Enrich a company from domain, email, phone, or social profile URL.

## Why use Nyne.ai MCP?

- **Instant access** - no code required. Connect once and query Nyne.ai data from ChatGPT or Claude.
- **Secure** - uses your existing Nyne.ai API credentials. All requests are authenticated and logged.
- **Natural language** - ask in plain English. The assistant handles the technical details.
- **Accurate** - real-time data from Nyne.ai's people intelligence workflows, no integration code.
- **Cost-effective** - uses your existing Nyne.ai subscription and credit balance. No additional fees.
- **Comprehensive** - the hosted MCP is a curated subset; the full HTTP API is covered by llms.txt + the manifest.

## Integration guides

### ChatGPT

1. Open ChatGPT and go to **Settings → Connectors** (custom connectors require Developer mode; Plus, Pro, Business, or Enterprise).
2. Click **Add custom connector**.
3. Enter the Nyne.ai MCP endpoint `https://api.nyne.ai/mcp`.
4. When prompted for authentication, choose **OAuth** (recommended). The flow uses:

   ```
   Authorization URL: https://api.nyne.ai/mcp/oauth/authorize
   Token URL: https://api.nyne.ai/mcp/oauth/token
   ```

5. ChatGPT handles Dynamic Client Registration and sends the public OAuth `client_id` during token and refresh requests.
6. OAuth returns short-lived access tokens plus rotating refresh tokens so ChatGPT can silently renew access without asking you to log in again.
7. Do not choose ChatGPT's **Access token/API key** Bearer option for Nyne API credentials. Nyne API credentials are a key/secret pair; ChatGPT's single Bearer field cannot send both values.
8. If OAuth is unavailable, select **No authentication** only for discovery. Tool execution requires OAuth or a client/proxy that can send `X-API-Key` and `X-API-Secret` headers.
9. Click **Save**. ChatGPT discovers Nyne.ai tools from the manifest.

### Claude Desktop

1. Open or create the MCP configuration file at `~/.claude/mcp.json`.
2. Add Nyne.ai to your configuration:

   ```json
   {
     "mcpServers": {
       "nyne": {
         "url": "https://api.nyne.ai/mcp",
         "headers": {
           "X-API-Key": "your_nyne_api_key",
           "X-API-Secret": "your_nyne_api_secret"
         }
       }
     }
   }
   ```

3. Restart Claude Desktop. Nyne.ai tools are now available.

### Other MCP clients

- **Discovery endpoint:** `https://api.nyne.ai/.well-known/mcp`
- **MCP endpoint:** `https://api.nyne.ai/mcp`
- **OAuth authorization server metadata:** `https://api.nyne.ai/.well-known/oauth-authorization-server`
- **OAuth protected resource metadata:** `https://api.nyne.ai/.well-known/oauth-protected-resource`
- **Authentication:** OAuth2 (recommended) via `/mcp/oauth/authorize` and `/mcp/oauth/token`; or the `X-API-Key` + `X-API-Secret` headers.

## Pricing & usage

Nyne.ai MCP uses your existing subscription and credit balance. MCP tools use the same credit costs as the REST API.

| Tool | Uses credits like | Required product |
| --- | --- | --- |
| `person_search` | Person Search | Search |
| `person_enrichment` | Person Enrichment | Enrichment |
| `person_newsfeed` | URL Newsfeed | Newsfeed |
| `person_ask` | Person Ask | Enrichment |
| `company_search` | Company Search | Search |
| `company_enrichment` | Company Enrichment | Enrichment |

Per-tool credit costs are loaded from your account and shown in the API reference. MCP requests count toward your API key's rate limits and quotas, just like REST calls.

## Async processing & polling

MCP tools use the same async request pattern as the REST API. Your assistant handles the polling automatically - you just ask naturally.

```
# 1. Invoke tool through JSON-RPC
POST /mcp
{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "person_search",
    "arguments": { "query": "engineers at Google", "limit": 10 }
  }
}

# Response
{
  "jsonrpc": "2.0",
  "id": 1,
  "result": {
    "content": [
      {
        "type": "text",
        "text": "{\"status\":\"pending\",\"request_id\":\"abc123...\",\"endpoint\":\"person_search\"}"
      }
    ]
  }
}

# 2. Poll for results
GET /mcp/status?request_id=abc123...

# Response while processing:
{ "status": "pending", "message": "Processing..." }

# Response when complete:
{
  "status": "completed",
  "results": [],
  "completed_at": "2025-10-10T10:30:00Z"
}
```

## Next steps

- [MCP Quick Start](https://api.nyne.ai/documentation/mcp/quickstart.md)
- [API Reference](https://api.nyne.ai/documentation.md)

---

Source: https://api.nyne.ai/documentation/mcp/quickstart.md

# Nyne.ai MCP Quick Start

> Get up and running with Nyne.ai MCP in three minutes.

HTML version: https://api.nyne.ai/documentation/mcp/quickstart

## What you'll need

- A Nyne.ai account with an active subscription
- API credentials (API Key + Secret)
- An MCP-capable client - Claude (Code or Desktop), ChatGPT, Cursor, VS Code, Windsurf, Zed, or a CLI agent

## Agent discovery links

If an agent is integrating without prior context, point it at the machine-readable docs before the HTML pages - that reduces bad endpoint selection and incomplete generated code.

```
llms.txt:               https://api.nyne.ai/llms.txt
Agent manifest:         https://api.nyne.ai/.well-known/nyne-api.json
Example endpoint (md):  https://api.nyne.ai/documentation/person/enrichment.md
```

The hosted MCP is a curated subset focused on person and company search, enrichment, lookup fields, newsfeed, and profile Q&A. For broader coverage, use the manifest and endpoint markdown docs first.

## Connect your client

The Nyne.ai MCP server is remote (hosted) - there is nothing to install. Point any MCP-capable client at `https://api.nyne.ai/mcp` and authenticate with one of:

- **OAuth 2.0** (recommended) - interactive login, no keys to store. Best for hosted assistants like ChatGPT and Claude Desktop.
- **API Key headers** - send `X-API-Key` and `X-API-Secret`. Best for editors and CLIs that read a config file.

Swap `YOUR_API_KEY` / `YOUR_API_SECRET` for the credentials from your Nyne.ai dashboard. Treat them like passwords - prefer your client's secret-input or environment-variable support over committing them to a shared file.

### Hosted assistants

#### ChatGPT

1. Open ChatGPT → **Settings → Connectors** (custom connectors require Developer mode; Plus, Pro, Business, or Enterprise).
2. Click **Add custom connector** and enter `https://api.nyne.ai/mcp`.
3. Choose **OAuth** and complete Nyne.ai login. The OAuth endpoints are:

   ```
   Authorization URL: https://api.nyne.ai/mcp/oauth/authorize
   Token URL: https://api.nyne.ai/mcp/oauth/token
   ```

4. ChatGPT handles Dynamic Client Registration and sends the public OAuth `client_id` during token and refresh requests.
5. OAuth returns short-lived access tokens plus rotating refresh tokens so ChatGPT can silently renew access without asking you to log in again.
6. Do not choose ChatGPT's **Access token/API key** Bearer option for Nyne API credentials. Nyne API credentials are a key/secret pair; ChatGPT's single Bearer field cannot send both values.
7. ChatGPT cannot send custom `X-API-Key` headers, so OAuth is required for hosted MCP tool execution in ChatGPT.
8. Save and test.

#### Claude Desktop

1. Open **Settings → Connectors → Add custom connector**.
2. Name it `nyne`, set the URL to `https://api.nyne.ai/mcp`, and complete the **OAuth** login.
3. Prefer API keys? The Connectors UI is OAuth-only, so bridge with `mcp-remote` in `claude_desktop_config.json` (Settings → Developer → Edit Config):

   ```json
   {
     "mcpServers": {
       "nyne": {
         "command": "npx",
         "args": [
           "mcp-remote",
           "https://api.nyne.ai/mcp",
           "--header",
           "X-API-Key:${API_KEY}",
           "--header",
           "X-API-Secret:${API_SECRET}"
         ],
         "env": { "API_KEY": "YOUR_API_KEY", "API_SECRET": "YOUR_API_SECRET" }
       }
     }
   }
   ```

4. Restart Claude Desktop.

### Command-line tools

#### Claude Code

Run:

```bash
claude mcp add --transport http nyne https://api.nyne.ai/mcp \
  --header "X-API-Key: YOUR_API_KEY" \
  --header "X-API-Secret: YOUR_API_SECRET"
```

Add `-s user` before the name to register it globally instead of per-project.

#### Gemini CLI

Run:

```bash
gemini mcp add --transport http \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "X-API-Secret: YOUR_API_SECRET" \
  nyne https://api.nyne.ai/mcp
```

In `~/.gemini/settings.json` the URL key is `httpUrl` (not `url`) for HTTP servers.

#### Codex CLI

Add to `~/.codex/config.toml`:

```toml
[mcp_servers.nyne]
url = "https://api.nyne.ai/mcp"
http_headers = { "X-API-Key" = "YOUR_API_KEY", "X-API-Secret" = "YOUR_API_SECRET" }
```

Codex uses `http_headers` (not `headers`). On older builds, add `experimental_use_rmcp_client = true` at the top of the file.

#### GitHub Copilot CLI

Add to `~/.copilot/mcp-config.json`:

```json
{
  "mcpServers": {
    "nyne": {
      "type": "http",
      "url": "https://api.nyne.ai/mcp",
      "headers": { "X-API-Key": "YOUR_API_KEY", "X-API-Secret": "YOUR_API_SECRET" },
      "tools": ["*"]
    }
  }
}
```

#### OpenCode

Add to `opencode.json`:

```json
{
  "mcp": {
    "nyne": {
      "type": "remote",
      "url": "https://api.nyne.ai/mcp",
      "enabled": true,
      "headers": { "X-API-Key": "YOUR_API_KEY", "X-API-Secret": "YOUR_API_SECRET" }
    }
  }
}
```

OpenCode nests servers under `mcp` (not `mcpServers`) and needs `type: "remote"`.

### Editors & IDEs

#### Cursor

Add to `~/.cursor/mcp.json`:

```json
{
  "mcpServers": {
    "nyne": {
      "url": "https://api.nyne.ai/mcp",
      "headers": { "X-API-Key": "YOUR_API_KEY", "X-API-Secret": "YOUR_API_SECRET" }
    }
  }
}
```

#### VS Code (GitHub Copilot)

Add to `.vscode/mcp.json`:

```json
{
  "servers": {
    "nyne": {
      "type": "http",
      "url": "https://api.nyne.ai/mcp",
      "headers": { "X-API-Key": "${input:nyne-key}", "X-API-Secret": "${input:nyne-secret}" }
    }
  },
  "inputs": [
    { "type": "promptString", "id": "nyne-key", "description": "Nyne.ai API Key", "password": true },
    { "type": "promptString", "id": "nyne-secret", "description": "Nyne.ai API Secret", "password": true }
  ]
}
```

The top-level key is `servers` (not `mcpServers`). The `inputs` block prompts for each secret on first run; hardcode the values instead if you prefer.

#### Windsurf

Add to `~/.codeium/windsurf/mcp_config.json`:

```json
{
  "mcpServers": {
    "nyne": {
      "serverUrl": "https://api.nyne.ai/mcp",
      "headers": { "X-API-Key": "YOUR_API_KEY", "X-API-Secret": "YOUR_API_SECRET" }
    }
  }
}
```

Windsurf uses `serverUrl` (not `url`) for remote servers.

#### Zed

Add to your Zed `settings.json`:

```json
{
  "context_servers": {
    "nyne": {
      "url": "https://api.nyne.ai/mcp",
      "headers": { "X-API-Key": "YOUR_API_KEY", "X-API-Secret": "YOUR_API_SECRET" }
    }
  }
}
```

Needs a recent Zed with native HTTP MCP support; older builds require the `mcp-remote` stdio bridge.

#### JetBrains (Junie)

Add to `.junie/mcp/mcp.json`:

```json
{
  "mcpServers": {
    "nyne": {
      "url": "https://api.nyne.ai/mcp",
      "headers": { "X-API-Key": "YOUR_API_KEY", "X-API-Secret": "YOUR_API_SECRET" }
    }
  }
}
```

Junie supports header auth. The plain AI Assistant remote-server form is URL-only - use Junie's config or an `mcp-remote` bridge there.

## Test it out

Try these example queries in your AI assistant:

**Search for people**

```
"Find software engineers at Google in Seattle"
"Show me CTOs in the fintech industry"
"Search for product managers with AI experience"
```

**Get profile details**

```
"Get the profile for john@company.com"
"Find contact info from this social profile URL"
"Enrich this phone: (415) 555-1234"
```

**Ask AI questions**

```
"What is this person's current role?"
"Does this person have sales experience?"
"What companies has this person worked for?"
```

That's it - your AI assistant can now search and analyze Nyne.ai's people data directly.

## Quick reference

| What | Value |
| --- | --- |
| Discovery URL | `https://api.nyne.ai/.well-known/mcp` |
| MCP endpoint | `https://api.nyne.ai/mcp` |
| Auth method | OAuth2 (recommended) via `/mcp/oauth` • `X-API-Key` + `X-API-Secret` for clients that support custom headers |
| Protocol version | `2024-11-01` |

## Credits & pricing

MCP uses the same credit costs as the REST API.

| Tool | Uses credits like |
| --- | --- |
| `person_search` | Person Search |
| `person_enrichment` | Person Enrichment |
| `person_newsfeed` | URL Newsfeed |
| `person_ask` | Person Ask |
| `company_search` | Company Search |
| `company_enrichment` | Company Enrichment |

MCP uses your existing Nyne.ai credits and respects your API rate limits. Costs are loaded from your account and update automatically if they change.

## Async processing

1. Tool invocation returns `HTTP 202` with a `request_id`.
2. Poll `GET /mcp/status?request_id=xxx` every 2-3 seconds.
3. When status is `completed`, results are included in the response.

Polling is automatic - your AI assistant handles it for you; just ask questions naturally and it waits for results.

## Next steps

- [MCP Documentation](https://api.nyne.ai/documentation/mcp.md)
- [API Reference](https://api.nyne.ai/documentation.md)