Skip to content
Log in Sign Up

Developer platform

Connect Hyranse search to your ATS

Run the same candidate search as the app from your ATS or AI assistant. REST for production. MCP for Cursor and Claude Desktop. One API key, one credit balance.

Get API key Quickstart 
POST /candidates/search
X-Api-Key: sk_live_...

{
  "countries": { "orValues": ["Germany"] },
  "keywords": { "andValues": ["golang"] },
  "openToWork": true,
  "limit": 10
}
Response

10 candidates · creditsCharged: 1 · creditsRemaining: 99

Quickstart

Three steps

  1. 1

    Sign up

    Free account. No credit card.

  2. 2

    Open the developer portal

    Your API key is created when you are logged in.

    Open developer portal
  3. 3

    Call search or connect MCP

    REST example · MCP setup

Two interfaces

REST or MCP — same key

REST API

HTTPS JSON for ATS sync, dashboards, and backends.

REST details

MCP

Tools in Cursor, Claude Desktop, or any Streamable HTTP MCP client.

MCP details

Shared

One key. One credit balance.

Auth

X-Api-Key on every REST and MCP request. Keys live in the developer portal.

Credits

Same balance as the app. Billable responses include creditsCharged and creditsRemaining.

Data

The same 250+ public sources, availability filters, skills, and locations.

REST API

Search and contacts over HTTPS

JSON. Use it for ATS jobs, internal tools, and scheduled syncs. Batch contact endpoints look up details for profiles you already found through Hyranse search or your shortlist — within plan credits and rate limits, for defined recruitment workflows only.

Endpoints

  • GET /credits/balance
  • POST /candidates/search
  • GET /contacts/{profileSlug}
  • POST /contacts/bulk

Base URL

https://public-api.hyranse.com/public-api/api

Example request

curl -X POST "https://public-api.hyranse.com/public-api/api/candidates/search" \
  -H "X-Api-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "countries": { "orValues": ["Germany"] },
    "locations": { "orValues": ["Berlin"] },
    "keywords": { "andValues": ["react", "typescript"] },
    "openToWork": true,
    "limit": 10
  }'

Example response

{
  "candidates": [
    {
      "id": "37264913",
      "profileSlug": "john-doe",
      "name": "John Doe",
      "title": "Senior Software Engineer",
      "locations": ["Berlin"],
      "skills": ["react", "typescript"],
      "openToWork": true
    }
  ],
  "count": 1,
  "creditsCharged": 1,
  "creditsRemaining": 99
}

Interactive docs in the developer portal

MCP

Search from the assistant

Connect Cursor or Claude Desktop. Ask in chat. Same credits as REST.

Clients:
  • Cursor
  • Claude Desktop
  • Any MCP client with Streamable HTTP

Chat

You

How many senior Python developers in Berlin are actively available? Peek the top matches.

Assistant

Uses count_candidates, then peek_candidates. You approve each tool call.

Tools

  • count_candidates Free pool estimate
  • peek_candidates Shortlist with snippets
  • get_candidate_cards Full cards by id
  • get_contact By public profile slug
  • get_contacts_bulk Batch contact lookup for shortlisted profiles (plan limits)
Add to Cursor

Cursor config

{
    "mcpServers": {
        "hyranse": {
            "url": "https://public-api.hyranse.com/public-api/mcp",
            "headers": {
                "X-Api-Key": "YOUR_API_KEY"
            }
        }
    }
}

MCP endpoint

https://public-api.hyranse.com/public-api/mcp

Usual order

  1. count_candidates — pool size (free)
  2. peek_candidates — shortlist; keep id vs profileSlug straight
  3. get_candidate_cards — cards by internal id
  4. get_contact — look up one shortlisted profile by slug (profileSlug field), not a full URL
  5. get_contacts_bulk — batch lookup for profiles already in your shortlist (plan limits)

Credits

Same balance as the app

Free includes 5 credits per month for in-app features. Paid plans and Business include REST API, MCP, and 500–4,700 credits per month depending on tier. See plans.

Operation Cost
POST /candidates/search 1 credit per 50 profiles (empty results free)
GET /contacts/{profileSlug} 1 credit per profile with contacts found
POST /contacts/bulk 1 credit per profile with contacts found
count_candidates Free
peek_candidates 1 credit per 50 profiles
get_candidate_cards 1 per 50 compact cards, or 1 per full card
get_contact / get_contacts_bulk 1 credit per profile with contacts found

Security

Keep the key off git

  • Environment variables, never the repo
  • Separate keys for staging and production
  • Review MCP batch contact tool calls before you approve them

Related

If you do not want to write code

AI Candidate Search Paste a JD in the app. No API required. Pricing Free includes 5 credits/month. Paid plans include API, MCP, and 500–4,700 credits. Developer portal Key, try-it docs, MCP setup.

FAQ

Common questions

How do I get an API key?

Sign up for Hyranse, open the API & MCP portal in the app, and your personal API key is generated automatically when you are logged in.

Can I use the API on the Free plan?

No. API and MCP are included on paid plans and Business and draw from the same credit balance as the app. Free is for trying search in the app with 5 monthly credits.

What happens when credits run out?

Billable requests return 400 with Credits have been exhausted. Top up by upgrading your plan or wait for the monthly credit refresh.

Is there a sandbox or test mode?

Use count_candidates (MCP) or GET /credits/balance (REST) to test connectivity for free. Search with limit: 1 to minimize credit usage while developing.

Do API and MCP use the same credits?

Yes. Both interfaces draw from the same credit balance as your Hyranse account. Billable responses include creditsCharged and creditsRemaining.

Which MCP clients are supported?

Cursor, Claude Desktop, and any MCP client that supports Streamable HTTP transport with custom headers.

What is the difference between id and profileSlug?

id is the internal search identifier — use it with get_candidate_cards. profileSlug is the public profile identifier for contact lookup (e.g. john-doe) — use it with get_contact. Pass the slug only; never a full profile URL. Legacy API responses may still include linkedinId with the same meaning.

Who is responsible for lawful use of candidate data?

Hyranse compiles publicly available professional data for recruitment search. Customers must ensure their own use and outreach comply with applicable law, including having a lawful basis where required. See our Privacy Policy and Acceptable Use Policy.

What does batch contact lookup mean?

After you search or build a shortlist in Hyranse, you can look up contact details for multiple shortlisted profiles in one request through the app, REST API (POST /contacts/bulk), or MCP (get_contacts_bulk). Usage draws from your credit balance and plan limits for defined recruitment shortlists.

Can I use both REST API and MCP?

Yes. Use REST for production integrations and MCP for AI-assisted sourcing — same key, same data, same credits.

Get an API key

Sign up free, open the portal, copy the key.

Open developer portal