Core Concepts

Choosing request depth

Every request trades latency, coverage, and cost against each other. Four dials set that balance: lookup_mode on enrichment, the search type, the higher-tier person_enrich mode, and the search feature toggles that change the price. Deeper is not always better - the right depth is the shallowest one that still answers your question.

Shallow

fast • light

Least latency, least coverage, least cost.

Balanced

balanced • medium

A middle ground on all three.

Deep

deep • premium

Most coverage, most latency, most cost.

Enrichment depth: `lookup_mode`

On /person/enrichment, the lookup_mode field sets how hard the provider waterfalls work. It takes one of three values, and the default is deep:

lookup_mode	Behavior	Latency	Coverage
fast prefill timeout 0	Fast-path: skips the deeper enrichment-prefill augmentation. Lowest latency, lower coverage.	Lowest	Lower
balanced 5s prefill timeout	A 5-second prefill timeout at the initial and post-waterfall stages. The middle ground.	Medium	Medium
deepdefault no timeout cap	Runs the full provider waterfalls with no timeout cap. Highest coverage, highest latency.	Highest	Highest

Pass it in the JSON body. Here is the middle-ground balanced mode:

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 '{ "email": "[email protected]", "lookup_mode": "balanced" }'

Deep is the default

If you send no lookup_mode, you get deep - the full waterfalls, best coverage, highest latency. Drop to balanced or fast when a caller is waiting on the response.

Search tier: `type`

On /person/search, the type field picks the search tier. Result quality and coverage rise with the tier, and so does cost. Internally it maps to provider speed tiers (light is the fastest, premium the deepest). The default is premium:

type	Provider tier	Quality	Notes
light	Fastest provider tier	Lower	Lowest cost and latency. For light, insights and high_freshness are force-disabled.
medium	Middle provider tier	Medium	A balance of result quality and cost.
premiumdefault	Deepest provider tier	Highest	Highest result quality and coverage, and the highest cost.

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 in San Francisco", "type": "premium", "show_emails": true }'

type also sets queue priority

Beyond result depth, type maps to the Gearman queue priority that runs your search, so a higher tier can also mean a faster start. Note that for light, insights and high_freshness are force-disabled - they do not apply at the fastest tier.

The `person_enrich` tier

Standard person_enrichment is the right call most of the time. When it is not enough, the higher-tier person_enrich mode forces all newsfeed sources (force-newsfeed) to pull a fuller, fresher record - the complete social activity, not just the merged profile.

It is worth the upgrade for hard-to-find people the standard enrichment misses, or when you specifically need full social activity rather than a static profile. It also costs more: person_enrich cross-links additional credit-bearing sources, so reach for it deliberately, not by default.

Start standard, escalate when it falls short

Run person_enrichment first. If the record comes back thin for someone you know exists, or you need their live social feed, re-run through person_enrich for the deeper pull.

Search feature toggles that change the price

Several search flags each change the credit price when you turn them on. Broadly, turning more on means better and richer results, a higher cost, and often higher latency. See Credits & pricing for the exact per-feature costs.

Toggle	Tradeoff
show_emails	Return matched email addresses. Adds to the credit price.
show_phone_numbers	Return matched phone numbers. Adds to the credit price.
insights	Attach AI-derived insights to each result. Richer, higher cost and latency.
profile_scoring	Score and rank results against your query. Higher cost.
high_freshness	Prefer fresher records over cached ones. Higher cost and latency.
require_emails	Drop results without an email. Fewer but better-qualified results.
require_phone_numbers	Drop results without a phone. Fewer but better-qualified results.
require_phones_or_emails	Drop results without a phone or an email. Fewer but contactable results.

Only pay for what you use

The require_* toggles narrow results rather than enrich them - use them to trim what you never wanted, not to widen coverage. Every added signal has a price; leave off the ones you will not read.

Picking a depth

Stated plainly: a deeper lookup_mode, a higher search type, and more toggles all buy you better coverage at a higher cost and higher latency. There is no universally right setting - only the right one for a given call. Start from the use case:

Use case	lookup_mode	search type	Notes
Interactive / autocomplete / low latency	fast	light	Answer while the user waits.
General enrichment / balanced	balanced	medium	The default-ish middle ground.
Hard-to-find / maximum recall / batch	deep	premium	Add person_enrich when the standard record is not enough.

Measure on your own data

These are starting points, not verdicts. Coverage and latency depend on the identifiers and audience you send, so run each candidate depth against a sample of your real inputs before you commit. The Evaluating the API guide walks through how to compare depths fairly.

What's next

Credits & pricing - how each mode, tier, and toggle maps to credits.
Writing effective requests - the identifiers and query shapes that raise coverage before you pay for more depth.
Evaluating the API - measure coverage, latency, and cost on your own data before committing.
Async & polling - why deeper modes take longer and how to poll for the result.