Core Concepts

Interpreting API responses

Every reply from the Nyne.ai API arrives in the same envelope, so reading one correctly means reading them all. This page covers the rules: 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.

every response, one shape

"success": true or false,

"data" or "error" one, never both,

"timestamp": "server UTC, ISO-8601"

success: true

Your payload is in data.

success: false

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:

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

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

Check success, 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:

{
  "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. Terminal failures may instead arrive as an error envelope or non-2xx response without a completed flag:

{
  "success": true,
  "data": {
    "request_id": "a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4_1717000000_4271",
    "status": "completed",
    "completed": true,
    "result": {
      "displayname": "Jane Doe",
      "best_business_email": "jane.doe@acme.com"
    }
  },
  "timestamp": "2026-05-28T18:04:39"
}

Use completed as the primary success signal

When a successful payload includes data.completed, keep polling while it is false and stop when it is true, regardless of whether the HTTP status is 200 or 202. A documented terminal error envelope or non-retriable non-2xx job response also stops that request. Transient transport/status-infrastructure responses remain retryable when the endpoint documents a retry policy. Then read data.status for the endpoint-specific successful outcome. See Async requests and polling for the full lifecycle, poll cadence, and webhook callbacks.

Confidence and scoring

Search can rank and score its matches. Opt in with profile_scoring, and add probability_score to surface a probability match score (0 to 1) on each result:

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, "probability_score": true }'

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

Build against documented fields

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:

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

Retry the transient, accept the clean no-match

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

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 - the full submit, poll, and callback lifecycle behind every 202.
Rate limits - which errors are retryable, and how to back off cleanly.
Effective requests - send stronger identifiers to get fuller, higher-confidence matches.
Your first request - the end-to-end walkthrough this page's rules apply to.