Introduction and quickstart

The basics

• Base URL: https://api.helixhumancapital.in/v1. HTTPS only.
• Requests and responses are JSON, except resume upload (multipart/form-data) and chat (server-sent events).
• Authentication is a bearer key in the Authorization header. See Authentication and scopes.
• Every response carries x-request-id and x-credits-charged. Quote the request id when you contact support.
• Machine-readable spec: OpenAPI 3.1. Import it into Postman, Insomnia or a code generator.

1. Get a key

Keys are issued by us. Email support@helixhumancapital.in with your company, what you are building and the plan you want. Ask for a test key (hlx_test_…) first: it returns synthetic candidates, is never billed and has the same shapes as production. A live key (hlx_live_…) is shown once when it is created and cannot be recovered, only replaced.

2. Check the key

GET /v1/me is free and tells you the plan, scopes and credits left.

curl https://api.helixhumancapital.in/v1/me \
  -H "Authorization: Bearer $HELIX_KEY"

import os, requests

r = requests.get("https://api.helixhumancapital.in/v1/me",
                 headers={"Authorization": f"Bearer {os.environ['HELIX_KEY']}"})
print(r.json())

const r = await fetch("https://api.helixhumancapital.in/v1/me", {
  headers: { Authorization: `Bearer ${process.env.HELIX_KEY}` },
})
console.log(await r.json())

{
  "company": "Acme Recruiting",
  "environment": "test",
  "plan": { "code": "pro", "name": "Pro", "unlimited": false, "ratePerMinute": 60 },
  "scopes": ["search", "match", "parse", "market", "jobs", "pii:contact", "pii:comp", "pii:docs"],
  "credits": { "allowance": 3000, "used": 0, "remaining": 3000, "periodEnds": "2026-12-09T17:15:28.318Z" }
}

3. Search

Describe who you want in plain language. Results are ranked. Without expand you get an anonymised summary for 1 credit; with expand: true each result is the full record, limited to the field scopes your key holds, for 5 more credits per record.

curl https://api.helixhumancapital.in/v1/search \
  -H "Authorization: Bearer $HELIX_KEY" \
  -H "Content-Type: application/json" \
  -d '{"query": "senior backend engineer, python, postgres, bengaluru",
       "limit": 5,
       "filters": {"maxNoticeDays": 30, "minYears": 5}}'

r = requests.post("https://api.helixhumancapital.in/v1/search",
    headers={"Authorization": f"Bearer {KEY}"},
    json={"query": "senior backend engineer, python, postgres, bengaluru",
          "limit": 5,
          "filters": {"maxNoticeDays": 30, "minYears": 5}})
for c in r.json()["results"]:
    print(c["id"], c["role"], c["yearsExperience"], c["skills"][:5])

const r = await fetch("https://api.helixhumancapital.in/v1/search", {
  method: "POST",
  headers: { Authorization: `Bearer ${KEY}`, "Content-Type": "application/json" },
  body: JSON.stringify({
    query: "senior backend engineer, python, postgres, bengaluru",
    limit: 5,
    filters: { maxNoticeDays: 30, minYears: 5 },
  }),
})
const { results } = await r.json()

{
  "query": "senior backend engineer, python, postgres, bengaluru",
  "expanded": false,
  "count": 5,
  "appliedFilters": { "maxNoticeDays": 30, "minYears": 5 },
  "filtersRelaxed": false,
  "results": [
    { "id": 5428, "role": "Backend Engineer", "seniority": "mid", "yearsExperience": 4,
      "skills": ["Python", "SQL", "Django", "FastAPI"], "summary": "…", "addedAt": "2026-…" }
  ]
}

If your filters match too few people we relax them and say so with filtersRelaxed: true, rather than returning nothing. Page through results by passing the ids you have already seen in exclude.

4. Where next

• Guides: enrich an ATS, source for a role, price an offer with market data.
• Credits and billing: know what a call costs before you make it.
• Idempotency and errors: make your integration safe to retry.
• MCP server: give an AI assistant the same tools.