Person Lookup Fields API

Request only the person fields you need using email, phone, profile URL, or name.

API Endpoint

https://api.nyne.ai/person/lookup-fields

The API returns an enrichment-style response. The result object includes only the fields you requested and that were found.

POST creates a queued lookup request. Use GET with the returned request ID to check the final response.

Authentication

Send your API key and secret in the request headers.

X-API-Key: your_api_key_hereX-API-Secret: your_api_secret_here

Credit Usage

Credits are charged for lookup work after a valid request starts.

Email Lookup Fields: 3 credits per requested email field such as best_work_email or best_personal_email
Phone Lookup Field: 3 credits per requested mobile field
Other Lookup Fields: 3 credits per other requested field or requested profile URL item

Billing

Requests are charged based on the requested field catalog items, including requests that return not_found. Validation errors and status checks are not charged.

For example, requesting best_work_email and mobile costs 6 credits. The playground preselects current_company and current_title, which costs 6 credits. API requests must explicitly provide fields or profile_urls.

Lookup Inputs

Provide at least one lookup input. If you do not provide email, phone, or social_media_url, then name is required.

email, phone, and social_media_url are direct lookup inputs.
name can be used by itself, or with company, city, and state for better matching.
If a direct lookup input is provided, optional name fields provide context but do not replace the direct lookup input.
Name-only lookups return the best available match. Add company or location context when the name is common.

The fields and profile_urls values may be arrays or comma-separated strings. At least one item in fields or profile_urls is required.

POST /person/lookup-fields

Create an asynchronous lookup request. The response includes a request_id that can be used with GET /person/lookup-fields.

POST /person/lookup-fields

Request Parameters

Parameter	Type	Required	Description
`email`	string	No	Email address
`phone`	string	No	Phone number
`social_media_url`	string	No	Profile URL
`name`	string	Required if no email, phone, or profile URL	Full name
`company`	string	No	Company context for name lookup
`city`	string	No	City context for name lookup
`state`	string	No	State context for name lookup
`fields`	array or string	No	Field names to return.
`profile_urls`	array or string	No	Profile URL keys to return under `social_profiles`. Keys must start with a letter and may contain lowercase letters, numbers, and underscores. Maximum 10.
`probability_score`	boolean	No	Return match probability when available
`callback_url`	string	No	URL to receive results asynchronously

At least one item in fields or profile_urls is required.

Supported Fields

[ "displayname", "firstname", "lastname", "best_work_email", "best_personal_email", "mobile", "address", "location", "headline", "current_company", "current_title", "photo_url" ]

Request Example

{ "email": "[email protected]", "fields": ["current_company", "current_title"] }

Name Lookup Example

{ "name": "Jane Example", "company": "Example Company", "city": "San Francisco", "state": "CA", "fields": ["current_company", "current_title"], "probability_score": true }

GET /person/lookup-fields

Check a V1 lookup request.

GET /person/lookup-fields?request_id=REQUEST_ID

Field Catalog

Field	Description
`displayname`	Display name when available
`firstname`	First name when available or derived from display name
`lastname`	Last name when available or derived from display name
`best_work_email`	Best available work email address
`best_personal_email`	Best available personal email address
`mobile`	Best available mobile phone number, returned in `fullphone` format
`address`	Best available address
`location`	Location when available
`headline`	Profile headline when available
`current_company`	Current company, returned in `organizations` format
`current_title`	Current job title, returned in `organizations` format
`photo_url`	Profile photo URL when available

Response Format

Queued

{ "success": true, "data": { "request_id": "abc123...", "status": "queued", "completed": false, "result": null, "error": null, "created_on": "2026-05-10T12:00:00", "completed_on": null }, "timestamp": "2026-05-10T12:00:00Z" }

Completed

{ "success": true, "data": { "request_id": "abc123...", "status": "completed", "completed": true, "result": { "best_work_email": "[email protected]", "fullphone": [ { "fullphone": "(555) 123-4567", "phone_type": "mobile", "type": "mobile" } ], "organizations": [ { "name": "Example Company", "title": "VP Technology", "endDate": "Present", "endDate_formatted": { "is_current": true } } ], "social_profiles": { "linkedin": { "url": "https://www.linkedin.com/in/person" } } }, "error": null, "created_on": "2026-05-10T12:00:00", "completed_on": "2026-05-10T12:00:04" }, "timestamp": "2026-05-10T12:00:04Z" }

Not Found

No matching data returns HTTP 404 with status set to not_found. This is a completed lookup response, not a processing failure.

{ "success": true, "data": { "request_id": "abc123...", "status": "not_found", "completed": true, "result": null, "error": null, "created_on": "2026-05-10T12:00:00", "completed_on": "2026-05-10T12:00:04" }, "timestamp": "2026-05-10T12:00:04Z" }

Error Codes

HTTP	Code	Description
400	`missing_parameters`	No lookup input was provided
400	`invalid_fields`	Unsupported field requested
400	`invalid_profile_urls`	Unsupported profile URL key format
400	`invalid_callback_url`	Callback URL could not be used
401	`invalid_credentials`	API key or secret is incorrect
402	`insufficient_credits`	Not enough credits available
403	`access_denied`	The request is not available to the authenticated account
403	`subscription_required`	The account does not include access to this API
404	`request_not_found`	Status request ID was not found
429	`rate_limit_exceeded`	Rate limit exceeded