Guides and recipes

Four integrations teams build first, each with working code and an honest credit estimate.

1. Source candidates for a role

Go from a job description to a short, ranked list without reading a single CV. Parse once, match once, then spend credits only on the people worth a full record.

Python

import os, uuid, requests
H = {"Authorization": f"Bearer {os.environ['HELIX_KEY']}"}
API = "https://api.helixhumancapital.in/v1"

jd = open("backend-engineer.txt").read()

# 1) Match: 10 credits. Returns the extracted requirements and ranked summaries (no personal data yet).
m = requests.post(f"{API}/match", json={"jobDescription": jd, "limit": 20},
                  headers={**H, "Idempotency-Key": str(uuid.uuid4())}, timeout=90).json()
print("must-haves:", [r["label"] for r in m["requirements"] if r["kind"] == "must"])

# 2) Keep only strong fits, then release full records for those: 5 credits each.
strong = [x["candidate"]["id"] for x in m["matches"] if x["fit"] == "strong"][:5]
for cid in strong:
    c = requests.get(f"{API}/candidates/{cid}", headers=H).json()["candidate"]
    print(c["contact"]["name"], c["contact"]["email"], c["compensation"]["expectedLpa"])

Cost: 10 + 5 × 5 = 35 credits for a vetted shortlist of five with contact details. Each match also returns a fit band (strong, possible, stretch) so you decide whom to pay to open.

2. Enrich an ATS or CRM

When a recruiter opens a requisition, pre-populate it with candidates from the pool and a CV link, using the requisition text as the query.

Node.js

async function suggestCandidates(requisition) {
  const r = await fetch("https://api.helixhumancapital.in/v1/search", {
    method: "POST",
    headers: {
      Authorization: `Bearer ${process.env.HELIX_KEY}`,
      "Content-Type": "application/json",
      "Idempotency-Key": `req-${requisition.id}-v${requisition.version}`, // same requisition+version = free replay
    },
    body: JSON.stringify({
      query: `${requisition.title}, ${requisition.skills.join(", ")}, ${requisition.city}`,
      limit: 10,
      expand: true,
      filters: { maxNoticeDays: 60, minYears: requisition.minYears },
    }),
  })
  const { results } = await r.json()
  return results.map((c) => ({
    externalId: `helix:${c.id}`,
    name: c.contact?.name,
    email: c.contact?.email,
    expectedLpa: c.compensation?.expectedLpa,
    resume: c.cv?.url, // short-lived: copy the file into your store if you need it later
  }))
}

3. Price an offer with market data

Free. Combine observed pay with your own band, and use the confidence level to decide how much to trust it.

curl

curl "https://api.helixhumancapital.in/v1/market/pay-bands?role=sales%20manager&city=pune" \
  -H "Authorization: Bearer $HELIX_KEY"

Response (shape)

{
  "role": "sales manager",
  "currency": "INR",
  "unit": "observed: lakh per annum; benchmarks: rupees per year",
  "benchmarks": [ { "title": "…", "category": "…", "experience": "7–10 yrs", "annualInr": 3500000, "lakhPerAnnum": 35 } ],
  "observed": {
    "matchedCandidates": 400,
    "withPayData": 30,
    "overall": { "people": 30, "currentFixedLpa": { "p25": 10.3, "median": 15, "p75": 20.8 }, "expectedMedianLpa": 21 },
    "byLevel": [ { "group": "senior", "people": 12, "currentFixedLpa": { "p25": 8, "median": 11.6, "p75": 13.6 }, "expectedMedianLpa": 17.5 } ],
    "confidence": "medium"
  },
  "note": "Observed figures are self-reported by candidates and unverified. Groups smaller than 5 people are not shown."
}

current is what people earn now; expected is what they ask for. An offer near the expected median closes faster; near the current median it competes with the status quo.
Groups under 5 people are never returned, and confidence (none, low, medium, high) reflects how many people stand behind the figure. Do not automate decisions on low.
Add city to narrow to people currently in that city; the sample, and the confidence, will shrink.
/v1/market/skills shows which skills co-occur around a role, handy for writing a realistic job description.

4. Parse inbound resumes

Turn uploaded CVs into structured JSON for your own database. Nothing you upload is stored by us.

curl

curl https://api.helixhumancapital.in/v1/parse/resume \
  -H "Authorization: Bearer $HELIX_KEY" \
  -F "file=@candidate.pdf"

PDF, DOC or DOCX up to 5 MB, 2 credits. Scanned or image-only files return 422 no_text and are not charged. Pair it with POST /v1/fit (3 credits) to score the parsed person against a role, or POST /v1/parse/jd to turn a job description into a must-have / nice-to-have checklist.

5. Keep a bulk job safe

Put an Idempotency-Key on every call and persist it with the work item, so a crashed worker can resume without paying twice.
Check GET /v1/me before a batch and stop early if credits.remaining is below your estimate.
Register a credits.low webhook and pause the queue when it fires.
Stay under your plan's requests-per-minute and honour Retry-After; see Rate limits and errors.

← PreviousMCP server Next →API reference