RecruitMCP

docs reference

Changelog

What this version of the API includes.

2026-11-01

The first public version. A short balance returns part of a search page: resume is the same page again, and leads already billed are free. credits.low uses each workspace's low_balance_credits (default 250). Pin it with RecruitMCP-Version: 2026-11-01; keys pin it when they are created. See Errors, pagination, and versions for what counts as a breaking change.

API shape

  • Three layers: Raw (filters one to one with the person index, full profiles), Building blocks (lookups, seen register, lists, suppressions), and Guided (intents, search plans, runs). See API layers.
  • Every operation has an operationId. openapi.yaml is the source of the API reference and of the generated TypeScript and Python SDKs and the n8n node.
  • Every list uses cursor pagination: { object: "list", data, next_cursor, has_more }.
  • Every paid or sending call takes ?dry_run=true and needs an Idempotency-Key to execute.
  • Distinct error codes for every failure the client should handle differently, including unsupported_filter, not_cached, daily_credit_cap_reached, outreach_cap_reached, account_paused, and account_not_ready.

Sourcing

  • POST /v1/runs accepts job text, an intent, or a plan. A dry run returns the plan and estimate for free.
  • Intents use must, nice, and exclude blocks. Every intent, plan, and raw search reports applied_filters and ignored_fields.
  • Raw filters include past companies, schools, job functions, profile languages, company headcount, and names. Filters the index cannot apply, such as time in the current title, are refused with unsupported_filter. Raw-layer requests also refuse unknown fields and raw: true; profiles are always normalized.
  • GET /v1/people/{profile_id} never charges. POST /v1/people:fetch takes up to 100 ids or URLs. POST /v1/people:match finds one person by name and company.
  • Full CRUD for intents, the seen register (with tags and external ids), and lists (with CSV export).
  • There is no fit score. Candidates carry distance, experience, tenure, and tier.

Platform

  • Account-wide events and signed webhook endpoints for runs, jobs, contacts, enrollments, actions, replies, accounts, and credits.
  • Customers: sub-workspaces with their own memory, outreach accounts, and daily caps, selected by header or by a bound key.
  • OAuth 2.1 for MCP clients such as claude.ai, next to API keys. Sending outreach is its own scope, outreach:send.
  • MCP toolsets selected on the URL, a one-call start_search, get_search_results that waits, output schemas, prompts, resource templates, and get_guide.

Outreach

  • Enroll a run, a list, profile ids, or named people in one call, with a full preview first.
  • Sequences, enrollments, actions, and conversations have full read and manage endpoints.
  • The safety layer is unchanged: caps, warmup, daily jitter, spacing, working hours, reply-stop, and auto-pause. Raising a cap needs risk_acknowledged and is audited.

Credits and privacy

  • Credits live in buckets with a source and an expiry. Unused plan credits roll over for 2 more cycles, top-ups expire after 12 months, and free signup credits after 30 days.
  • A person can opt out at /opt-out. Suppression applies in every layer, raw search included.
  • POST /v1/erasures erases one person from the workspace and keeps a hashed suppression.

Prices on this page are the defaults: 1 credit per lead returned, 2 per live profile, 1 per new company lookup, 1,250 credits on signup, €49 per connected account per month.

API reference