Core Concepts

Constructing effective requests

Every Nyne.ai request falls into one of two shapes. Enrichment and lookup identify one person from the identifiers you already hold, while search takes a filter and returns the people who match. Getting the inputs right - the right identifiers, a clean company name, only the fields you need - is what drives your hit rate, your latency, and your credit cost.

POST Enrichment / Lookup

/person/enrichment · /person/lookup-fields

Identify one person from identifiers you already have.

POST Search

/person/search

Describe a filter and get back the people who match.

Identifiers for enrichment and lookup

Enrichment and lookup identify a single person. You must send at least one of email, phone, social_media_url, or name. The more specific the identifier, the better the match - email and social_media_url resolve to exactly one person, while name works best when you also pass company and a location to disambiguate.

key	What it is
email	A work or personal email address. The strongest single identifier.
phone	A phone number in any common format.
social_media_url	A profile URL, e.g. a LinkedIn page.
name	Full name. Works best paired with company + location to disambiguate.
company	Employer name. Strip legal suffixes first (see below).
city	City the person is in, to narrow a name match.
state	State or region, alongside city.
company_domain	Employer domain (lookup-fields), e.g. acme.com.
location	A free-form location string (lookup-fields).
postal_code	Postal or ZIP code (lookup-fields).
profile_url / url	A profile URL alias accepted by lookup-fields.

More context, sharper match

Extra identifiers never hurt. If you have a name plus company, city, and state, send them all - each one narrows the candidate set and raises your chance of a clean, single-person match.

Ask for only what you need: the fields array

Lookup requests take a fields array. Request only the fields you actually use: a narrower request is cheaper and faster, because each field can pull from a different source. Common contact fields are best_work_email, best_personal_email, and mobile. If you already hold specific profile URLs you want resolved, pass them in profile_urls.

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": "[email protected]",
    "fields": ["best_work_email", "mobile"]
  }'

The email and phone shortcuts

When you need exactly one contact field, skip the fields array. POST /person/email and POST /person/phone are thin wrappers over lookup-fields that force the field set for you: /person/email forces fields=["best_work_email"] and /person/phone forces fields=["mobile"], and both clear profile_urls. They take the same person identifiers - this is the simplest possible request when you only want that one value:

POST /person/email

curl -X POST https://api.nyne.ai/person/email \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "X-API-Secret: YOUR_API_SECRET" \
  -H "Content-Type: application/json" \
  -d '{ "name": "Jane Doe", "company": "acme" }'

POST /person/phone

curl -X POST https://api.nyne.ai/person/phone \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "X-API-Secret: YOUR_API_SECRET" \
  -H "Content-Type: application/json" \
  -d '{ "social_media_url": "https://linkedin.com/in/janedoe" }'

Under the hood, /person/email is exactly a lookup-fields call with this body forced on top of your identifiers:

{
  "fields": [
    "best_work_email"
  ],
  "profile_urls": []
}

Start from what you know, expand outward

A hard identifier is one that resolves to a single person on its own: an email, a phone, or a LinkedIn or other social_media_url. Once you have one, submit it back to enrichment to expand the record - filling out title, company, socials, and work history from that single anchor. You do not need to send anything else:

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 '{ "social_media_url": "https://linkedin.com/in/janedoe" }'

This "known key in, full record out" flow is the backbone of most integrations: capture whatever strong identifier a user gives you, then let enrichment fill in the rest.

Company-name hygiene

Legal and entity suffixes throw off company matching. Before you send a company value, lowercase it and strip trailing suffix tokens repeatedly until none remain. So "Acme Corp Inc" becomes "acme". Copy-paste this suffix list:

inc, llc, ltd, co, corp, corporation, company, gmbh, sa, ag,
plc, llp, lp, pllc, pty, group, holdings, holding, the

Strip repeatedly, from the end

Match tokens case-insensitively and remove them one at a time from the end, so a doubled suffix like Corp Inc is fully cleaned. Do this to any name you send as company - in enrichment, lookup, the shortcuts, and the search companies filter alike.

Search filters and requirements

Search does not identify one person - it takes a custom_filters object and returns everyone who matches. Each field in custom_filters is an array you can combine, plus numeric range pairs like min_linkedin_followers / max_linkedin_followers:

custom_filters field	Matches on
locations	Regions, metros, or countries.
languages	Languages the person uses.
titles	Job titles or role names.
industries	Industry categories.
companies	Current or past employers.
universities	Schools attended.
keywords	Free-text terms matched across the profile.
degrees	Degree types held.
specialization_categories	Areas of specialization.
company_funding_stages	Funding stage of the employer.
company_latest_funding_stages	Most recent funding stage.
company_investor_names	Investors backing the employer.

Alongside the filters, contact-requirement toggles narrow the result set to people who have the contact data you care about, and probability_score attaches a match probability to each result:

parameter	Effect
require_emails	Keep only results that have an email.
require_phone_numbers	Keep only results that have a phone.
require_phones_or_emails	Keep only results with a phone or an email.
probability_score	Attach a match-probability score to 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 '{
    "custom_filters": {
      "titles": ["VP of Engineering", "CTO"],
      "locations": ["San Francisco Bay Area"],
      "industries": ["Software"],
      "min_linkedin_followers": 1000
    },
    "require_phones_or_emails": true,
    "probability_score": true,
    "limit": 10
  }'

Every requirement narrows results and can raise cost

Each toggle you add filters more people out and can increase the cost per result, because guaranteeing a phone or email means resolving more data. See Credits and Request depth for how the trade-off is priced.

Async delivery with callback_url

Any submit can carry a callback_url. When the result is ready, Nyne POSTs it there instead of making you poll. The URL is validated against an allowed-hosts list, so register your host first. See Async and webhooks for the full setup.

What's next

Request depth - how far Nyne digs for a result, and what that costs.
Credits - what each request type charges, and when.
Async and webhooks - polling versus callback_url delivery.
Responses - the envelope and the fields you get back.