Complete recruiter platform API reference.

Verify session

Returns the current actor's identity, organization, alias, role, portfolio context, and site config.

curl -H "Authorization: Bearer $HTC_API_KEY" \
  "$BASE_URL/v2/auth/session/verify"

{
  "user_id": "user_abc123",
  "org_id": "user_abc123",
  "email": "[email protected]",
  "alias_email": "[email protected]",
  "auth_method": "api_key",
  "actor_type": "bot",
  "role": "owner",
  "portfolio": null,
  "connected": false,
  "site": { "site_name": "Hidden Talent Club", "site_tagline": "..." },
  "request_id": "req_..."
}

Semantic search

Search resumes with a natural-language query plus optional filters. By default returns semantic results without LLM reranking. Set rerank: true for reranked output.

curl -X POST "$BASE_URL/v2/catalog/search" \
  -H "Authorization: Bearer $HTC_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "query_text": "Senior backend engineer with Go experience",
    "limit": 10,
    "years_experience_min": 4,
    "years_experience_max": 10,
    "preferred_locations": ["Bengaluru", "Remote"]
  }'

const res = await fetch(`${BASE_URL}/v2/catalog/search`, {
  method: "POST",
  headers: {
    "Authorization": `Bearer ${apiKey}`,
    "Content-Type": "application/json"
  },
  body: JSON.stringify({
    query_text: "Senior backend engineer with Go experience",
    limit: 10,
    years_experience_min: 4,
    years_experience_max: 10,
    preferred_locations: ["Bengaluru", "Remote"]
  })
});
const data = await res.json();

import requests

resp = requests.post(
    f"{BASE_URL}/v2/catalog/search",
    headers={
        "Authorization": f"Bearer {api_key}",
        "Content-Type": "application/json",
    },
    json={
        "query_text": "Senior backend engineer with Go experience",
        "limit": 10,
        "years_experience_min": 4,
        "years_experience_max": 10,
        "preferred_locations": ["Bengaluru", "Remote"],
    },
    timeout=30,
)
data = resp.json()

// Response
{
  "items": [
    {
      "resume_id": 42,
      "external_resume_id": "ext_abc123",
      "title": "Senior Backend Engineer",
      "summary": "8 years in distributed systems, Go, Kubernetes...",
      "years_of_experience": 8,
      "current_ctc_inr_lpa": 28.5,
      "preferred_job_location": "Bengaluru",
      "price_credits": 100,
      "purchased": false,
      "score": 0.92,
      "match_explanation": "Strong Go background...",
      "match_score_100": 92,
      "tags": ["shortlisted"]
    }
  ],
  "query": "Senior backend engineer with Go experience",
  "source": "pinecone+mysql",
  "reranked": false,
  "request_id": "req_..."
}

Resume detail

Returns the masked profile view. Purchased orgs receive full details through owned-resume endpoints.

curl -H "Authorization: Bearer $HTC_API_KEY" \
  "$BASE_URL/v2/catalog/resumes/42/detail"

{
  "item": {
    "resume_id": 42,
    "title": "Senior Backend Engineer",
    "summary": "8 years in distributed systems...",
    "years_of_experience": 8,
    "current_ctc_inr_lpa": 28.5,
    "price_credits": 100,
    "purchased": false,
    "shortlist_count": 3,
    "fetch_count": 12,
    "claim_count": 1,
    "pdf_url": "https://s3.../presigned..."
  },
  "full_resume_text": "[anonymized text]",
  "request_id": "req_..."
}

Similar resumes

Fetches nearest-neighbor style recommendations for a given resume.

curl -H "Authorization: Bearer $HTC_API_KEY" \
  "$BASE_URL/v2/catalog/resumes/42/similar?limit=10"

Resume metrics

Returns shortlist, fetch, and claim counters.

curl -H "Authorization: Bearer $HTC_API_KEY" \
  "$BASE_URL/v2/resumes/42/metrics"

{
  "resume_id": 42,
  "shortlist_count": 3,
  "fetch_count": 12,
  "claim_count": 1,
  "updated_at": "2026-03-19T00:00:00Z",
  "request_id": "req_..."
}

Prompt profiles

Store reusable search prompts that guide result ordering. Profiles work with both semantic and reranked modes.

// Create a prompt profile
curl -X POST "$BASE_URL/v2/search/prompt-profiles" \
  -H "Authorization: Bearer $HTC_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Backend hiring",
    "prompt_text": "Prioritize candidates with Go, distributed systems, and 5+ years experience",
    "is_default": true
  }'

// List all profiles
curl -H "Authorization: Bearer $HTC_API_KEY" \
  "$BASE_URL/v2/search/prompt-profiles"

// Update a profile
curl -X PATCH "$BASE_URL/v2/search/prompt-profiles/7" \
  -H "Authorization: Bearer $HTC_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "prompt_text": "Updated: also prefer Kubernetes experience" }'

Upload a resume

Uploads a PDF resume through the processing pipeline using the shared structured intake contract. The authenticated recruiter route preserves alias ownership and upload-credit behavior; the public route accepts open website submissions without trusting org ownership from the browser. Max size: 15 MB.

curl -X POST "$BASE_URL/v2/resumes/upload" \
  -H "Authorization: Bearer $HTC_API_KEY" \
  -F "resume=@./candidate.pdf;type=application/pdf" \
  -F "[email protected]" \
  -F "[email protected]" \
  -F "current_ctc=12 LPA" \
  -F "expected_ctc=18 LPA" \
  -F "preferred_location=Bengaluru" \
  -F "years_of_experience=5.5" \
  -F "custom_notes=Candidate prefers a backend platform role"

import requests

with open("candidate.pdf", "rb") as f:
    resp = requests.post(
        f"{BASE_URL}/v2/resumes/upload",
        headers={"Authorization": f"Bearer {api_key}"},
        files={"resume": ("candidate.pdf", f, "application/pdf")},
        data={
            "uploader_email": "[email protected]",
            "referrer_email": "[email protected]",
            "current_ctc": "12 LPA",
            "expected_ctc": "18 LPA",
            "preferred_location": "Bengaluru",
            "years_of_experience": "5.5",
            "custom_notes": "Candidate prefers a backend platform role",
        },
    )
print(resp.json())

{
  "accepted": true,
  "message": "",
  "is_resume": true,
  "refer_id": "AbC123xYz987PqR",
  "alias_email": "[email protected]",
  "uploader_email": "[email protected]",
  "filename": "candidate.pdf",
  "credit_price": 18,
  "credits_added": 18,
  "request_id": "req_..."
}

Shortlists

// Add to shortlist
curl -X POST "$BASE_URL/v2/shortlists" \
  -H "Authorization: Bearer $HTC_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"resume_id": 42, "notes": "Strong Go + search background"}'

// List shortlist
curl -H "Authorization: Bearer $HTC_API_KEY" "$BASE_URL/v2/shortlists"

// Remove from shortlist
curl -X DELETE -H "Authorization: Bearer $HTC_API_KEY" \
  "$BASE_URL/v2/shortlists/42"

Wallet balance

curl -H "Authorization: Bearer $HTC_API_KEY" \
  "$BASE_URL/v2/wallet/balance"

{ "balance_credits": 500, "request_id": "req_..." }

Claim (purchase) a resume

Deducts credits and delivers the full CV.

curl -X POST "$BASE_URL/v2/resumes/42/claim" \
  -H "Authorization: Bearer $HTC_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "recipient_emails": ["[email protected]"]
  }'

Owned resumes

// List purchased resumes
curl -H "Authorization: Bearer $HTC_API_KEY" \
  "$BASE_URL/v2/owned/resumes?limit=20&offset=0"

// Get full detail of owned resume
curl -H "Authorization: Bearer $HTC_API_KEY" \
  "$BASE_URL/v2/owned/resumes/42/detail"

Resume visibility

Control whether a resume is private, portfolio-masked, or fully shared.

curl -X PATCH "$BASE_URL/v2/resumes/42/visibility" \
  -H "Authorization: Bearer $HTC_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "visibility_mode": "portfolio_masked" }'

Mail aliases

// Create a forwarding alias
curl -X POST "$BASE_URL/v2/mail-aliases" \
  -H "Authorization: Bearer $HTC_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "localpart": "hiring-ops",
    "forward_to_email": "[email protected]",
    "forwarding_enabled": true
  }'

// List all aliases
curl -H "Authorization: Bearer $HTC_API_KEY" "$BASE_URL/v2/mail-aliases"

{
  "items": [
    { "id": 12, "alias_email": "[email protected]", "is_default": true, "forwarding_enabled": false },
    { "id": 18, "alias_email": "[email protected]", "is_default": false, "forward_to_email": "[email protected]", "forwarding_enabled": true }
  ],
  "alias_domain": "hiddentalent.club",
  "max_aliases": 20
}

Inbox messages

// List inbox messages
curl -H "Authorization: Bearer $HTC_API_KEY" \
  "$BASE_URL/v2/inbox/messages?limit=20&offset=0"

// Get single message
curl -H "Authorization: Bearer $HTC_API_KEY" \
  "$BASE_URL/v2/inbox/messages/501"

// Reply to a message
curl -X POST "$BASE_URL/v2/inbox/messages/501/reply" \
  -H "Authorization: Bearer $HTC_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "subject": "Re: Resume follow-up",
    "body_text": "Thanks for the note. We will review and get back shortly."
  }'

// Forward a message
curl -X POST "$BASE_URL/v2/inbox/messages/501/forward" \
  -H "Authorization: Bearer $HTC_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "to_email": "[email protected]",
    "note": "Please review this inbound candidate thread."
  }'

Merchant API keys

// Create a new API key
curl -X POST "$BASE_URL/v2/api-keys" \
  -H "Authorization: Bearer $HTC_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"name": "ci-worker"}'

// Response (raw key shown ONCE)
{ "id": 5, "name": "ci-worker", "key_prefix": "htc_a3b...", "raw_key": "htc_a3b8d1...", "request_id": "req_..." }

// List all keys
curl -H "Authorization: Bearer $HTC_API_KEY" "$BASE_URL/v2/api-keys"

// Revoke a key
curl -X DELETE -H "Authorization: Bearer $HTC_API_KEY" "$BASE_URL/v2/api-keys/5"

BYOK provider keys

Supported providers: groq, cerebras, openrouter. Used when platform LLM quota is exhausted during reranking.

curl -X POST "$BASE_URL/v2/byok/keys" \
  -H "Authorization: Bearer $HTC_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "provider": "groq", "api_key": "gsk_live_your_key" }'

Organization members & invites

// List members
curl -H "Authorization: Bearer $HTC_API_KEY" "$BASE_URL/v2/org/members"

// Invite a new member
curl -X POST "$BASE_URL/v2/org/member-invites" \
  -H "Authorization: Bearer $HTC_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "email": "[email protected]", "role": "member" }'

Portfolio endpoints

// Bootstrap a new portfolio
curl -X POST "$BASE_URL/v2/portfolio/bootstrap" \
  -H "Authorization: Bearer $HTC_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Acme Ventures Portfolio",
    "site_name": "Acme Talent Hub",
    "site_tagline": "Internal talent sharing for Acme portfolio companies"
  }'

// Get portfolio context
curl -H "Authorization: Bearer $HTC_API_KEY" "$BASE_URL/v2/portfolio/context"

// Update portfolio settings
curl -X PATCH "$BASE_URL/v2/portfolio/admin/settings" \
  -H "Authorization: Bearer $HTC_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "default_visibility_mode": "portfolio_masked",
    "allow_company_self_share": true,
    "site_name": "Acme Talent Hub"
  }'

// Add organization to portfolio
curl -X POST "$BASE_URL/v2/portfolio/admin/organizations" \
  -H "Authorization: Bearer $HTC_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "org_id": "user_company123" }'

Error response format

{ "error": "error_code", "message": "Human-readable description", "request_id": "req_..." }

Every response includes a request_id field for debugging and support.