Person APIs

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. The convenience routes /person/email and /person/phone are thin wrappers that force fields to ["best_work_email"] and ["mobile"] respectively. The request is queued and returns a request_id; poll the status endpoint or supply a callback_url.

POST https://api.nyne.ai/person/lookup-fields API key

Overview

Request specific fields for a person from any identifier.

Parameters

email string optional

Email identifier. example.com is rejected as fake/test; lowercased.

phone string optional

Phone identifier. At least 7 digits, ≤50 chars.

social_media_url string optional

Profile URL (aliased as social_url/profile_url/url). At least one identifier is required.

name string optional

Full name.

company string optional

Employer context.

company_domain string optional

Company domain; scheme/path/www stripped, must be a bare domain.

location string optional

Free-form location; split into city/state on the first comma.

state string optional

State/region context for a name-based lookup.

fields array | string optional

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.

profile_urls array optional

Specific profile-url keys to resolve. Max 10.

0 / 10

probability_score boolean optional

Include match-probability scoring.

e.g. false

callback_url string optional

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.

Retrieving the result

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

curl "https://api.nyne.ai/person/lookup-fields?request_id=<request_id>" \
  -H "X-API-Key: nyne_live_a17f…3c9b" \
  -H "X-API-Secret: nyne_sec_••••••••"

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

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

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

Prefer push delivery?

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

Credit usage

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

Feature	Credits	Notes
Lookup Fields	-	credit_costs.person_lookup_fields - billed per requested unit (count of fields + profile_urls)
Email field	1	/person/email - credit_costs.person_email (default 1)
Phone field	-	/person/phone - credit_costs.person_phone
No match	0	Empty results never burn credits

Heads up

A positive credit balance is required before each request. Empty results do not burn credits.

Responses

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 - no balance in the selected bucket

403 subscription_required or ip_not_allowed

429 rate_limit_exceeded

503 service_unavailable - backing store/queue unconfigured

404 not_found - the lookup completed but no matching data exists (a completed response, not a processing failure)

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

{
  "success": true,
  "data": {
    "request_id": "a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4_1717000000_4271",
    "status": "completed",
    "completed": true,
    "result": {
      "best_work_email": "[email protected]",
      "mobile": "+1-555-123-4567",
      "title": "Senior Product Manager",
      "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"
  },
  "timestamp": "2026-06-13T21:36:05"
}