Build a sourcing pipeline

This is the whole product in one pass: describe a role, find people, keep the good ones, enrich only those, and hand them off. Every step names what it costs so you can see where the money goes.

The exact request and response shapes are in the reference. What follows is the order and the reasoning.

Step 0. Know your budget

curl https://api.vamotalent.ai/v1/account/credits \
  -H "Authorization: Bearer vamo_sk_..."

Free. Pair it with GET /v1/quotas if you also want your allowances, which are a separate ceiling from your balance.

Step 1. Turn the role into a plan

curl -X POST https://api.vamotalent.ai/v1/searches/plan \
  -H "Authorization: Bearer vamo_sk_..." \
  -H "Content-Type: application/json" \
  -d '{"query": "senior rust engineers who have shipped async runtimes, europe"}'

Free. You get back a structured plan. Read it. If it inferred something you did not mean, edit that field and keep going. Iterating here costs nothing, which is deliberate: fixing a plan is cheaper than running a bad one.

Step 2. Run it

curl -X POST https://api.vamotalent.ai/v1/searches/run \
  -H "Authorization: Bearer vamo_sk_..." \
  -H "Content-Type: application/json" \
  -d '{"plan": { ...the plan from step 1... }, "limit": 50}'

1 credit per developer actually returned. A limit of 50 that yields 12 people costs 12. A page that yields nothing costs nothing.

You get skeletons: identity and basic profile. That is enough to decide who is worth paying more attention to, and it is why enrichment is a separate step.

Want more without repeat results? Send the ids you have already seen in excludeDeveloperIds and run again.

Step 3. Save the ones you are keeping

POST /v1/contacts/save-developers turns developers into contacts. Free.

A contact is the account-side record of a person you are working: it is what carries do-not-contact, and what outreach rules apply to. Do this before the next step, because a shortlist holds contacts, not raw developers.

Step 4. Group them

POST /v1/shortlists creates the list, and POST /v1/shortlists/{id}/members adds the contacts from step 3 to it. Free.

Shortlists and projects are the grouping primitives. A contact carries no tags of its own, so these are what grouping is for.

Step 5. Enrich only that group

This is the step that decides your bill. Enrich the three you kept, not the fifty you found.

curl -X POST 'https://api.vamotalent.ai/v1/developers?vamo_estimate=1' \
  -H "Authorization: Bearer vamo_sk_..." \
  -H "Content-Type: application/json" \
  -d '{"developerIds": ["..."], "facets": ["contact.emails"]}'

Run it with vamo_estimate=1 first and you get the price with nothing charged. Drop the parameter to actually run it.

Facets you already own on those developers come back free. Anything that has to be computed comes back report_required, which is your cue to request it as a report instead. Both behaviours are explained in Enrichment and facets.

What the run cost

For a 50-result search where you kept 3 and pulled one contact facet on each:

plan: 0
run: 12 credits, because 12 developers came back
save as contacts: 0
shortlist and members: 0
enrichment: the contact SKU once per developer, on 3 developers

Every step is free except the two that produce facts about people: the search that found them, and the enrichment on the ones you kept. That is the whole shape of the pricing, and step 5 is the lever. Skeletons are cheap and depth is not, so decide who matters before you buy depth on them.

Doing it again tomorrow

Re-running the same enrichment over the same shortlist does not bill again: you own those facets. Adding people to the shortlist bills for the people you added. That property is what makes a nightly sync affordable, and it is worth designing around.