# 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=` 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=" \ -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 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