Enrichment and facets

Search and lookup return a skeleton: the developer's identity and basic profile, enough to decide whether you care. Everything beyond that is a facet, requested explicitly and priced explicitly.

The reason for the split is cost. Most results in a search are not the person you want, and computing contact details or a grade for all of them would charge you for work you throw away. So you get identity for everyone, and you pay for depth only on the ones you keep.

A facet is one fact about one developer

Facets cover things like contact details, activity signals, grades, and generated summaries. GET /v1/pricing/catalog lists every facet, what it gives you, what it costs, and which other facets it depends on.

Two properties in the catalog matter when you plan a request:

• requires names facets this one depends on. Those bill on top.
• requiresReport marks a facet that must be computed rather than read from cache, which means it comes back through the report flow below rather than inline.

The three ways to ask

1. Inline with a search. POST /v1/searches/execute accepts a facets array and returns the cells on results[].facets, billed in the same call. Best when you know up front what you need for the whole page.

2. Inline with a lookup. POST /v1/developers accepts facets and returns whatever is already cached. This call never starts a computation. A facet that would have to be computed comes back marked report_required rather than making you wait.

3. As a durable report. POST /v1/developers/reports requests facets that must be computed. It returns a reportId immediately and bills up front, which means polling GET /v1/developers/reports/{reportId} is free. Poll until it settles.

The rule of thumb: if POST /v1/developers hands you report_required, that is the API telling you to move that request to POST /v1/developers/reports.

You are not charged twice for the same fact

This is the part worth understanding before you build a sync loop.

When your account is billed for a facet on a developer, the account is granted ownership of that facet for that developer. Ownership means two things:

• Re-reading is free. Ask for the same facet on the same developer again and you are not billed again while the grant is live.
• Access does not expire. An ownership grant keeps giving you the newest value we hold for that fact. Expiry governs price, not visibility. You never lose access to something you paid for.

Cached values are shared across all customers, but ownership is per account. Another customer having already computed a fact makes it fast for you, not free for you. You pay the first time you ask for it.

Practical consequences:

• Re-running the same enrichment nightly on a stable list of developers does not multiply your bill.
• Widening a list does. You pay for the developers you added, not the ones you already owned.
• Because facets bill per SKU, request every facet you want from one SKU in a single call. Two calls for two facets in the same SKU can cost twice what one call for both would.

If you want certainty before a large batch, send it with ?vamo_estimate=1 first. The estimate accounts for what you already own.

Worked example

Find people, keep a few, enrich only those.

# 1. Plan a search. Free, and the plan is yours to edit before you spend.
curl -X POST https://api.vamotalent.ai/v1/searches/plan \
  -H "Authorization: Bearer vamo_sk_..." \
  -H "Content-Type: application/json" \
  -d '{"query": "rust systems engineers in berlin"}'

# 2. Run it. Billed per developer returned; these are skeletons.
curl -X POST https://api.vamotalent.ai/v1/searches/run \
  -H "Authorization: Bearer vamo_sk_..." \
  -H "Content-Type: application/json" \
  -d '{"plan": { }, "limit": 50}'

# 3. Enrich only the ones you kept.
curl -X POST https://api.vamotalent.ai/v1/developers \
  -H "Authorization: Bearer vamo_sk_..." \
  -H "Content-Type: application/json" \
  -d '{"developerIds": ["..."], "facets": ["contact.emails"]}'

# 4. Anything that came back report_required, request as a report.
curl -X POST https://api.vamotalent.ai/v1/developers/reports \
  -H "Authorization: Bearer vamo_sk_..." \
  -H "Content-Type: application/json" \
  -d '{"developerIds": ["..."], "facets": ["dossier.core"]}'

Every field name above is in the reference, which is generated from the API and is the thing to trust. The facet keys are real, and the full table with prices and dependencies is the free GET /v1/pricing/catalog.