API Reference

The engine base URL is https://recruit.hyreflow.ai. Every endpoint except the public bootstrap set requires a bearer token:

Authorization: Bearer hf_live_xxx

Mint and manage keys under API Keys. All responses are JSON. Metered endpoints return a _meta block with credits_charged, balance, and a run_id. _meta.settled says whether those figures are final: it is false while credits are still held for in-flight work (_meta.reserved reports the held amount — it covers the whole workspace, so another call running at the same time can hold credits and make this one provisional too) or while an async provider job the call left running is still open (_meta.pending_jobs lists each as {provider, job_id}, plus fetch — the job-status endpoint below — when the job can be polled directly). Its charge lands on a later poll or when the job finishes. While settled is false, treat credits_charged/balance as provisional and re-read GET /billing/balance to reconcile. A poll of a native job scraper also returns billed_jobs (jobs this call charged for) and already_billed (delivered jobs charged on an earlier poll), so credits_charged: 0 with already_billed > 0 means "already paid for", not "free".

Prefer to connect an agent without writing HTTP? The same tools are exposed over the Model Context Protocol at /api/v2/mcp (OAuth sign-in, one workspace per connection), see MCP Setup.

Tools

Discover and run a single tool/method.

curl -X POST https://recruit.hyreflow.ai/tools/apollo/search_people \
  -H "Authorization: Bearer hf_live_xxx" \
  -d '{"payload": {"titles": ["CTO"], "locations": ["New York"]}, "dry_run": true}'

curl -X POST https://recruit.hyreflow.ai/tools/personal_email \
  -H "Authorization: Bearer hf_live_xxx" \
  -d '{"rows": [{"linkedin_url": "https://linkedin.com/in/jane"}, {"linkedin_url": "https://linkedin.com/in/joe"}]}'

Search (waterfall)

Body

{
  "query": {
    "titles": ["Backend Engineer"],
    "locations": ["Berlin"],
    "skills": ["Go"],
    "company_domains": ["acme.com"],
    "seniority": "senior",
    "limit": 25
  },
  "coverage": "single",
  "limit": 25
}

• coverage: "single" (default): walk the provider order, accumulate + dedup, and stop as soon as limit people are collected. Providers that fill the quota win; the rest are skipped and never billed.
• coverage: "max": run every source and return the deduped union. Each source is paged only as far as limit needs (a source that does not page returns one page), so the union can exceed limit.

Filters may be written nested under query or flat at the body top level. A recognized top-level filter key is folded into the query, and an explicit query wins for any field it names: a top-level alias never outranks the nested canonical. Both shapes work here and via the CLI's hyreflow tools execute people_search --payload …, which takes the same envelope. The non-filter envelope keys are query, coverage, limit, providers, dry_run, preview, session_id, workflow_run_id.

Web results (Exa, Serper) whose location falls outside locations carry outside_locations: true and an outside_locations warning.

A key that matches no known filter is listed in _meta.ignored_query_keys; a non-empty list means that key narrowed nothing, so check it whenever a search comes back wider than you expected.

Response carries results[] (each tagged _source), per-provider steps[], hit, and _meta.balance + _meta.charged (what this search cost) — with the settled/reserved markers from the _meta contract above.

Each entry in steps[] carries counts (returned, new, charged, pages), an outcome explaining why that provider contributed nothing, or both, a step can return 0 rows and still carry an outcome naming why. Outcomes worth knowing:

Public-web coverage for company-scoped queries

The people databases at the front of the chain hold no rows at all for some companies, typically very small or very new ones. When the query names a company (via company_names, company_domains or company_linkedin_urls) and the databases haven't filled limit, the chain continues onto the public web: first a people search that returns structured work history, then a LinkedIn profile search. Under coverage: "max" they run as part of the union like every other source.

• Rows are kept only when the person's current company matches the company you asked for, so a plausible stranger at another company is dropped instead of counted or billed as a match. The match is on the whole company name, truncation included: a request that matches a whole word and runs into the next one (Acme Corp matching Acme Corporation) is the same company. A single word that merely contains or begins with what you asked for (a query for acme against GoAcme or Acmeteer) is a different company, and its people are dropped. Spelling differences of the same name (Acme Inc, ACME-Inc) and a domain brand like acmelabs for Acme Labs can still match.
• These two steps read a company anchor and portable filters (titles, locations, seniority, keywords, min_experience_years). A query carrying a filter nothing in a web result can prove, skills, max_experience_years, tenure windows, departments, firmographics: ends at the databases with unsupported_fields rather than being answered by a search that quietly ignored it.
• A row from the LinkedIn profile search carries verification_required: true and a verification_reason: it comes from a search result rather than a profile record, so confirm the company and title on the profile before contacting the person. When any such row is returned, _meta.warnings carries an unverified_web_results entry with the count.
• Two more advisory _meta.warnings codes, both free: many_companies (more than 10 companies in one search: results can't be attributed back to a company, search one company per call) and over_filtered (nothing came back with two or more filter groups applied: drop one at a time, keywords first).
• A keyword that is exactly "open to work" (or #OpenToWork) is searched as profile_badges: ["OPEN_TO_WORK"] instead, and _meta.warnings carries keyword_to_profile_badge. The badge is AI Ark only, so the other providers are skipped and any remaining keywords must also match. The keyword is searched as written when AI Ark can't run for you (left out of providers, or no key) or when nothing else, such as titles or locations, scopes the search.
• limit is the total you want. When it is larger than one vendor page, the paginated sources (AI Ark, Prospeo) size their pages evenly to cover it, so limit: 130 at 25 per page bills 6 pages of 22 rows rather than 6 of 25. Every returned row on a per-result source is billed.

Enrich (waterfall)

Body

{ "rows": [ { "linkedin_url": "https://linkedin.com/in/jane" } ] }

For each row the engine walks the provider chain in order and stops at the first real hit. Only the hitting step is billed, soft misses charge 0, and so does a result the capability rejects: on personal_email, an address on the person's own company domain is not a personal email, so it is dropped and charged 0 no matter which provider returned it. _meta.charged is what the whole call cost; a row's check_credits is what its email checks cost, on top of its steps' charged. A row whose reason is insufficient_credits was stopped by your workspace balance, not the provider. Add "preview": true to see each provider's mapped payload without calling or spending. Rows in a single run are processed in parallel, so a batch takes about as long as its slowest row rather than the sum of every row.

A batch is walked stage by stage and batched at the provider. With more than one row the engine sends every row through the first provider, the rows still without an answer through the second, and so on: first hit still wins per row. Where a provider accepts a batch (FullEnrich, up to 100 contacts) all the pending rows become one provider job with one poll loop rather than one job per row, so 12 or 100 rows finish in roughly the time a single row takes. Results are matched back to rows by a per-contact correlation key the engine stamps, never by position. Billing stays per row: one charge per hit, misses free, and a shared provider call never bills twice.

A multi-row call returns as soon as the batch is registered. The response comes back in seconds carrying _meta.dataset_id, _meta.run_id and _meta.status: "running" while the batch is walked in the background — rows land in the dataset as they are enriched, so a slow provider chain can never outlast your HTTP client's timeout. Read them with hyreflow_dataset_read/hyreflow_dataset_export (or the dataset endpoints).

A re-sent batch replays for free. Re-POSTing an identical rows batch within 15 minutes returns the first call's dataset (_meta.dataset_id again, _meta.replayed: true, charged: 0) with no provider calls at all — so a retry after a gateway timeout never bills twice for the same rows. After the window, an identical call is treated as a fresh re-run and bills normally.

Still enriching. If a provider job is still running when the poll budget ends, that step reports "outcome": "still_enriching" with "charged": 0, plus the job's identity, and that row's chain ends there — no further provider is started or paid for that row:

{ "step": "fullenrich.start_personal_email_enrichment", "outcome": "still_enriching", "charged": 0,
  "job_id": "abc123", "resume": { "tool": "fullenrich", "method": "get_bulk_enrichment", "id_arg": "enrichment_id" } }

The job is persisted and Hyreflow keeps polling it to completion on its own; the settled result is billed once, the same dedup a manual poll uses, and written into that row's entry in the run's dataset (_meta.dataset_id) — a batch is never left half-priced by a dropped connection. The response's _meta.pending_jobs lists every job still open like this, and _meta.settled stays false until they resolve, since their charges land after the response. To check it sooner, resume with POST /tools/{resume.tool}/{resume.method} and body {"payload": {"<id_arg>": "<job_id>"}}, or fetch the job directly:

Both are free polls; do not resend the original row, that starts and pays for a second job. Every row of one batch shares one job_id, so one resume call covers them all. A row whose whole chain ended without a verdict carries the same job_id/resume at row level with reason: "still_enriching" and a hint holding the exact command.

A cap is not a miss. When the workspace spending cap stops a provider mid-run, the affected rows record {"outcome": "skip", "detail": "spending_cap_reached"} for that step, and the response carries one top-level entry in _meta.warnings:

{ "code": "spending_cap_reached", "rows_affected": 9, "providers_skipped": ["fullenrich"], "message": "…" }

Those rows were never asked, so a lower hit count says nothing about coverage: retry them once the cap is raised or rolls over. Do not substitute another provider, and never a work-email finder on the personal_email channel (see BetterContact).

linkedin_profile returns a normalized profile: {headline, current_title, current_company, experience[{company, title, start, end, is_current, duration_months?, description?}], about?, skills?, certifications? education?}, newest role first. The dated experience[] is the result, an answer without employment history counts as a miss, costs nothing, and the chain moves to the next provider. The other fields are filled only by providers that carry them, so read an empty skills/about as unknown. Enrich profiles before POST /qualify, which scores on that history. When the row carries a name, the profile must match it, and an employer the row names must appear somewhere in the profile's experience (an earlier role counts, so a job change still matches). A location or portfolio/website can only confirm a match, never reject one. A URL that belongs to someone else ends the row with outcome identity_mismatch, charged 0, and the step names the matched_name it found instead.

Each entry in steps[] carries its outcome and what it charged. An address the chain drops is not a usable result, so the step that produced it charges 0 and the chain continues: corporate_domain (a work address on the personal channel), company_mismatch (an address at some other employer) and invalid_email (an address that isn't safe to send to) all settle at zero. Deliverability is checked by hyreflow's email verifier, which is charged for its verdict: once per address, however many providers offered it. Only an address it marks safe to send to is returned; one it answers as not safe (a role account, a mailbox that doesn't exist) is invalid_email and the chain keeps walking. When the address is on a catch-all domain, or the verifier couldn't judge it at all, Enrichley checks it too (charged at Enrichley's own rate), and only an address Enrichley clears is returned. A catch-all address Enrichley doesn't clear is invalid_email and the chain keeps walking. If the verdict doesn't come back in time, Enrichley checks the address too: one it calls invalid is invalid_email, and one it can't answer for is dropped with outcome verify_timeout. Either way the chain keeps walking. If neither verifier can give any verdict at all (both unavailable), the address is dropped with outcome unverified_email and the row's chain stops there. A rejected address is never echoed back, not even on its step.

On email_enrichment an address is only accepted if it belongs to the person's current employer, so send the employer along with the identifiers. A company_domain on the row is authoritative: an address on the same domain or a sub-domain of it is accepted. An address on a different domain is scored by a model for how likely it belongs to the same company (acme.com for an acme.de employer) and kept at or above a threshold. Anything below it is dropped with outcome company_mismatch and the chain keeps walking, which is what keeps a former employer's address (the person moved, the provider's record didn't) out of the result, at no cost. Sending a company_domain from people_search is the strongest signal and the only thing that can reject a mismatch. With only a company_name the engine compares the name against the address domain and reports the verdict without dropping anything, since a company can legitimately send mail from an unrelated domain. An employer field that carries no usable domain (a placeholder value, or a social/site-builder link) is treated as no domain at all, so nothing on the row is dropped because of it. Either way the row carries company_match plus the company_match_basis (company_domain or company_name) it was judged on, or model when the model scored a different domain, kept or dropped, with its probability in company_match_score.

Dataset enrichment runs

Send "detach": true for any live run that might take more than a few seconds. The response then comes back within about 20 seconds: either the finished run, or a handle while the run keeps going in the background:

{ "_meta": { "run_id": "enr_…", "status": "running", "dataset_id": "ds_…", "progress": { "done": 40, "total": 200 }, "poll_after_s": 10 } }

Without detach the call blocks until every row is done, and a large batch can outlive your HTTP client or a gateway (Cloudflare closes a request at about 100 seconds) while the run carries on and bills server-side. The CLI sends detach on every live run from 0.2.348.

Poll every poll_after_s seconds until status is completed or failed. Rows land in dataset_id as they are enriched, so the dataset endpoints can read them while the run is still going.

A re-sent run reattaches for free. Re-POSTing the identical rows, steps and range within 15 minutes of the first call returns that run (_meta.replayed: true, credits_charged: 0), still running or finished. A different range, or the same request after the window, is a new run and bills again. If you lose track of a run after the window, poll it by run_id; don't re-send it.

Qualify

Body

{
  "job_spec": "<JD text>",
  "candidates": [ { "full_name": "Jane Doe", "profile": { "experience": [ /* … */ ] } } ],
  "min_score": 7,
  "allow_thin_profiles": false,
  "async": false
}

Scoring reads each candidate's work history with dates, profile.experience[] from POST /enrich/linkedin_profile, or an experience[]/work_experience[]/job_history[] the row already carries (e.g. a CRM record), together with the headline, skills, certifications and education when present. If structured history is absent, a pasted resume in profile.about is read in full. A current title alone cannot separate a long-tenured specialist from a recent career changer, so enrich the pool first.

With "async": true, the call detaches into a background run instead of scoring inline (falling back to the inline walk when no background worker is running) and returns {run_id, dataset_id, status: "running", candidates, _meta} — here candidates is the row count, not the list — poll GET /api/v2/datasets/{dataset_id} for enrich_status, then read each row's qualify cell. min_score is not applied on this path; filter the scored cells yourself.

Returns candidates ranked by score (desc), each with qualify: {score, basis, summary, strengths, gaps}, where basis is work_history, resume_text, or title_only. With min_score set, only those at/above it are kept. _meta.scored_on counts both bases and _meta.thin_profiles names the rows that had no history, both describe everything that was scored, so a row min_score filtered out of candidates[] still appears there.

A batch in which every candidate is title-only is rejected with 422 and detail.error = "no_work_history": enrich the rows, or set allow_thin_profiles: true to rank on the sourcing fields (current title, employer, location) knowingly.

candidates is a list of candidate objects — the rows people_search or /enrich/linkedin_profile returned, passed through as they came back. A row that is anything else is rejected with 422 and detail.error = "bad_candidates", with detail.rows listing the offending positions. min_score is a number (7, not "7"); anything else is rejected with detail.error = "bad_min_score". Both are checked before the batch is scored, so a malformed body costs nothing.

Monitors

A monitor checks a source on a schedule and records the items it finds. Its type says what it watches and shapes its config and its items (see types). Its first check records what's already there as the baseline; every later check reports the new items. Each completed check costs a run fee plus credits for each new item, billed to the workspace; items seen before are free, and a failed check costs nothing. estimate.price says how much. Monitors belong to the workspace, not to one member, so a member's own spending cap doesn't limit a monitor's checks; the workspace cap still does. Anyone in the workspace can pause or delete a monitor. A bad field answers 422 with the reason in detail, and another workspace's monitor answers 404.

Monitors are turned on per workspace: for a workspace without them, every /api/v2/monitors route is a 404.

Monitor types

Billing

Any member can read billing: GET /billing/balance, /api/v2/billing/overview, /api/v2/billing/ledger.csv (one row per call, with the user_email of the member who made it: every call for the workspace owner, only your own calls for anyone else) and /api/v2/billing/auto-top-up. Every route that changes billing (checkout, subscription change and cancel, the billing portal, saved cards, auto top-up, spend caps, promo codes, the LinkedIn reward) is owner-only and answers any other member with 403 {"detail": "only the workspace owner can manage billing"}.

For any other member signed in as themselves, the balance block on GET /billing/balance, /api/v2/billing/overview, /api/v2/me and /api/v2/workspace is their own and carries "scope": "member": spent is what that member was charged in the last 30 days, reserved is their calls still in flight, granted is their spend cap in credits (null without one), and balance is what they can still spend. That is what the workspace has left, bounded by its own 30-day spending cap and by the room left under their cap, so it can be lower than granted - spent - reserved. limited_by names which of the three sets it: member_cap, workspace_cap or workspace_balance. The workspace's grant and total spend are the owner's view, and the overview's buckets is null for everyone else.

A member with a spend cap also gets that allowance as _meta.balance on /tools/* and /enrich/run (and as current_balance on an /enrich/run estimate or refusal, where can_run is judged on it), and as balance on a 402. _meta.reserved and _meta.settled there still cover the whole workspace, so don't reconcile a capped member's balance against reserved: re-read GET /billing/balance instead. Other metered routes (/search/*, /enrich/{capability}, /qualify, the shortlist and screening routes) still report the workspace balance, and so does current_balance on the spend confirmation quote, /enrich/run's included.

GET /api/v2/me, GET /billing/balance and GET /api/v2/billing/overview all carry the workspace's plan state: plan (the effective plan: always present, Free included), subscription (null on Free, else the sold terms plus status, period bounds, cancel_at_period_end, pending_plan_id/pending_cadence, cap_grace_until, next_grant_at), can_buy_credits (true when the workspace has a live subscription or has beta access), beta (true when the workspace has beta access, the plan limits on top-ups and data-provider keys don't apply to it), and seats ({"used", "limit"}, limit: null means unlimited). The overview additionally carries buckets: {"balance", "plan_credits", "purchased_credits", "plan_remaining", "purchased_remaining", "rollover_cap"}: the two balances a charge draws from and the live rollover ceiling (null on Free/Enterprise custom).

All four self-serve subscription routes (checkout, change, cancel, portal) are owner only, and all four return 503 {"error": "stripe_disabled"} when payments aren't configured. When the payment provider refuses a request, credit checkout and the four subscription routes answer 402 (the card was refused; message is the reason to show the cardholder) or 424 (anything else), both shaped {"detail": {"error": "plan_change_failed", "message": "..."}} (the error code names the route).

While the workspace is scheduled for deletion, credit checkout, subscription checkout, /change and /cancel with resume: true answer 409 (cancel the deletion first). Cancelling a plan stays open.

Per-member spend caps

The workspace owner can cap what ONE member spends, in USD, over a rolling 30 days — independent of the workspace-wide spending cap above. A member cannot set or clear caps, not even their own. A member's own cap gates any call attributed to that member (their 30-day charged spend plus any pending holds plus the new charge): once it would cross their cap, the call is refused with the same spending_cap_reached reason as the workspace cap, plus cap_scope: "member" so a caller can tell which cap stopped it (the workspace cap refusal carries cap_scope: "workspace"). A workflow or scheduled run isn't attributed to any one member, so it is governed by the workspace cap only.

An invite can carry a cap too: POST /api/v2/workspace/invites accepts an optional spend_cap_usd (owner only), applied to the member when they accept. An email that isn't a valid address is refused with 400 and nothing is stored. GET /api/v2/workspace/invites returns {"invites": [...], "seat_available": true}. seat_available is always true because every plan allows unlimited members.

Custom skills

Skills your workspace writes itself: see Custom skills for the rules. Every route needs a key that belongs to a signed-in user, and answers 403 otherwise. A skill you can't see answers 404. A package that isn't a valid text skill answers 400 with the reason in detail.

Plan-gated actions

Topping up on Free or connecting your own key for a data provider below Essential returns 402 in this shape:

{
  "error": "plan_required",
  "feature": "byok_managed_data",
  "provider": "apollo",
  "required_plan": "essential",
  "current_plan": "free",
  "message": "Connecting your own Apollo key needs the Essential plan or above."
}

feature is "byok_managed_data" or "topup"; provider is only set for the BYOK case. A workspace with beta access is not subject to these limits.

Desk defaults

The search defaults your workspace saves once and the dashboard prompt builder pre-fills. The fields are discipline, role_titles, geography, industries, icp and exclusions. Each is text, up to 500 characters, except icp which allows 4000.

Play matching

API keys

Sessions

Every session endpoint except POST /session/start names its session: in the body as session_id, or in the path as {sid}. It must be the ses_… id /session/start returned; anything else is a 400. A well-formed ses_… id that belongs to another workspace reads the same as one that doesn't exist: 404.

Bootstrap (no auth)

These are public so the CLI can install itself:

Any agent with its own skill installer can install from the catalog instead of using the hyreflow CLI, each archive is byte-stable, so its digest is safe to pin and to re-check for updates. skills.sha256 in /api/v2/versions is the same version number the catalog reports, so one request answers "is what I have current?" whichever route installed it.

The index declares its $schema as https://schemas.agentskills.io/discovery/0.2.0/schema.json, so a generic installer that speaks agent-skills discovery can take the catalog as-is:

npx skills@latest add https://recruit.hyreflow.ai/.well-known/skills/index.json \
  --agent claude-code --global --skill '*' -y

The CLI ships on public npm: npm install -g hyreflow is the primary install. The install script above uses it, and falls back to this host's npm registry (/api/v2/npm/) for locked-down sandboxes that can't reach npmjs.com.

Inspecting the CLI before you run it

The CLI is MIT-licensed and ships as a single self-contained JavaScript bundle. Fetch and read it without installing anything globally:

npm pack hyreflow
tar -xzf hyreflow-*.tgz
less package/dist/cli.mjs

Every published version carries npm's own integrity hash, covering the exact bytes the registry serves:

npm view [email protected] dist.integrity      # sha512-… for that exact version
npm view hyreflow dist.integrity              # …for whatever `latest` currently resolves to

That hash is fixed at publish time and a published version is immutable, so the check works for any version: including the one you are about to install. GET /api/v2/cli/releases lists every published version alongside its SHA-256 if you'd rather pin from this host.

Installing through this host's registry fallback verifies the same way: the packument it serves carries npm's own shasum and integrity untouched, and the tarball is proxied byte-for-byte, so a client that resolves and downloads entirely through /api/v2/npm/ still ends up verifying against what npm published.