RecruitHorizon Docs

From zero to a sourced candidate pipeline in 60 seconds. No email confirmation, no credit card required for the free tier.

1. Sign up

curl -X POST https://recruithorizon.ai/api/v1/auth/signup \
  -H "Content-Type: application/json" \
  -d '{
    "email": "you@startup.com",
    "companyName": "Acme AI",
    "agreedToTerms": true
  }'

# Response:
# {
#   "companyId": "cm...",
#   "apiKey": "rh_live_xxx...",
#   "environment": "live",
#   "freeQuota": { "callsRemaining": 100 },
#   "docsUrl": "https://recruithorizon.ai/docs",
#   "mcpUrl": "https://recruithorizon.ai/api/mcp"
# }

Save the apiKey — it's shown once. The free tier gives you 100 API calls per month.

2. Create a job

curl -X POST https://recruithorizon.ai/api/v1/jobs \
  -H "Authorization: Bearer rh_live_xxx" \
  -H "Content-Type: application/json" \
  -d '{
    "title": "Senior Software Engineer",
    "description": "Full job description with responsibilities and requirements...",
    "location": "Remote",
    "type": "FULL_TIME",
    "salaryMin": 120000,
    "salaryMax": 180000,
    "salaryPeriod": "ANNUAL"
  }'

The job is created in DRAFT status. Required: title and description (≥20 chars). All other fields default sensibly.

3. Publish + auto-source

curl -X POST https://recruithorizon.ai/api/v1/jobs/cmXXX/publish \
  -H "Authorization: Bearer rh_live_xxx"

# Response:
# {
#   "id": "cmXXX",
#   "status": "PUBLISHED",
#   "magicPipelineStatus": "running",
#   "message": "Magic Pipeline is sourcing candidates..."
# }

Publishing automatically triggers Magic Pipeline. It searches Coresignal's 839M+ profile database, runs Claude Haiku screening on top matches, and imports up to 5 candidates with score ≥70 — typically completing in 30-90 seconds.

4. List sourced candidates

curl "https://recruithorizon.ai/api/v1/candidates?jobId=cmXXX&limit=25" \
  -H "Authorization: Bearer rh_live_xxx"

5. Read the audit trail

curl "https://recruithorizon.ai/api/v1/audit-log?actionPrefix=job_&limit=50" \
  -H "Authorization: Bearer rh_live_xxx"

Every action — yours, your team's, your agents' — has a receipt. This is the compliance moat: you can replay every decision an autonomous agent made on your behalf.

All requests to /api/v1/* and /api/mcp require a Bearer token in the Authorization header:

Authorization: Bearer rh_live_YOUR_KEY_HERE

Keys are scoped to a single company. Generate them via the programmatic signup endpoint above, or from the dashboard at Settings → API Keys.

Two environments: rh_live_* (production) and rh_test_* (sandbox, no metered billing).

Lost a key? Revoke it from the dashboard and create a new one. There is no recovery — only revoke + reissue.

The MCP server at https://recruithorizon.ai/api/mcp exposes the same actions as the REST API, but discoverable and callable from any MCP client (Claude Desktop, Cursor, custom agents).

Full MCP setup walkthrough at /agents/mcp. Tools available:

• create_job—create a draft job
• publish_job—publish + auto-source candidates
• get_job—get a single job's status
• list_candidates—list pipeline candidates
• get_audit_log—read the receipts trail

Pay-per-call. No per-seat fees. Free tier covers prototyping; paid tiers add monthly call quota + per-call overage.

Cost-per-action: standard endpoints = 1 unit, sourcing/screening = 5 units, AI interview = 5 units. Check your real-time usage at /api/v1/usage.