Get Started

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. Most endpoints answer asynchronously, so you submit, get a request_id, and poll the same path until the result is ready. Learn the pattern once here with person enrichment, and the rest of the API works exactly the same way.

POST Submit

/person/enrichment

Send your identifiers.
202 Accepted

request_id

Queued, not done yet.
GET Poll

?request_id=

Same path, until ready.
200 Done

result

The enriched profile.

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

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:

{
  "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:

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"

Usually one poll is enough

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

The completed poll returns the merged, sanitized profile - name and headline, location, business email, social profiles with follower counts, and work history:

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

Notice the shape of both responses above. Every reply from the API - from any endpoint, success or failure - is wrapped in the same three keys. The envelope never changes; only what sits inside data does.

envelope, always the same

"success": true,

"data": the endpoint's payload lives here,

"timestamp": "2026-05-28T18:04:45"

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:

{
  "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.

Build against documented fields

Parse only the fields documented for the endpoint. Undocumented metadata must not be used for application logic.

What's next

Authentication - keys, secrets, IP locking, and rate limits in full.
Person Enrichment - every parameter, response code, and field in the profile you just saw.
Person Search - find people by natural-language query instead of a known identifier.
MCP Quick Start - wire Nyne.ai into Claude, ChatGPT, Cursor, and other AI clients.