Developer platform

Build on Hyranse's candidate data

Integrate candidate search and contact enrichment into your ATS, internal tools, or AI assistant. One API key, one credit balance — REST API or MCP.

Same account as the Hyranse app. Generate your API key in the developer portal after sign-up.

Get API key View 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

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

Tools

count_candidates · peek_candidates · get_candidate_cards · get_contact

Quickstart

Up and running in 3 steps

1

Sign up for Hyranse

Create a free account — no credit card required.
2

Open the developer portal

Your personal API key is generated automatically when you are logged in.
Open developer portal →
3

Make your first request

Use REST API from your backend, or connect MCP to Cursor and ask in natural language.
REST API example → · MCP setup →

Two ways to integrate

Choose the interface that fits your stack

REST API

HTTP endpoints for ATS sync, internal dashboards, and backend services.

REST API details →

MCP Server

Model Context Protocol for Cursor, Claude Desktop, and other AI assistants.

MCP details →

Shared platform

One key. One credit balance.

Authentication

Include X-Api-Key on every REST and MCP request. Keys are generated in the app developer portal.

Credits

API and MCP share the same credits as your Hyranse account. Every billable response includes creditsCharged and creditsRemaining.

Data

Access the same candidate database as the Hyranse app — 250+ public sources, Open To Work signals, skills, and locations.

REST API

Programmatic candidate search and contacts

JSON over HTTPS. Ideal for ATS integrations, internal recruiting tools, and automated workflows.

Endpoints

GET /credits/balance
POST /candidates/search
GET /contacts/{linkedinId}
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",
      "linkedinId": "john-doe",
      "name": "John Doe",
      "title": "Senior Software Engineer",
      "locations": ["Berlin"],
      "skills": ["react", "typescript"],
      "openToWork": true
    }
  ],
  "count": 1,
  "creditsCharged": 1,
  "creditsRemaining": 99
}

Full interactive docs with try-it requests in the developer portal →

Example

ATS sync workflow

Scenario Nightly job syncs new Open To Work candidates for active roles

Flow search → shortlist → enrich contacts → push to ATS

1. POST /candidates/search with role filters · 2. Store new profiles in your ATS · 3. GET /contacts/{linkedinId} for shortlisted candidates · 4. Trigger outreach workflow

MCP Server

Use Hyranse in your AI assistant

Connect Cursor, Claude Desktop, or any MCP-compatible client. Search candidates and enrich contacts directly from chat.

Supported clients:

Cursor
Claude Desktop
Any MCP client with Streamable HTTP

Chat workflow

You

How many senior Python developers in Berlin are open to work? Peek the top matches.

Assistant

Found 340 candidates matching your filters. Here are the top 5 with snippets — Anna K. (Senior Python Engineer, Berlin), Mark L. (Backend Developer, Remote EU)…

Available tools

count_candidates Free pool estimate
peek_candidates Shortlist with snippets
get_candidate_cards Full profile cards
get_contact Single contact lookup
get_contacts_bulk Up to 500 contacts

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

Recommended workflow

count_candidates — estimate pool size (free)
peek_candidates — shortlist; note id vs linkedinId
get_candidate_cards — open cards by internal id
get_contact — enrich by linkedinId slug

Example prompts

How many senior Python developers in Berlin are open to work? Peek the top matches and open cards for the best three.

Peek iOS developers in Germany, open cards for the top 3 by id, then get contacts using their linkedinId values.

Compare

REST API vs MCP — when to use which

	REST API	MCP
Interface	HTTP + JSON	AI assistant tools
Best for	Production integrations	Interactive AI workflows
Auth	`X-Api-Key` header	`X-Api-Key` header
Credits	Shared account balance	Shared account balance
Typical user	Backend developer	AI / ops engineer

Credits

Pay per use from your account balance

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

See account plans →

Security

Keep your API key safe

Store keys in environment variables — never commit to git
Use separate keys per environment (staging / production)
Review MCP assistant actions before approving bulk contact requests

AI Candidate Search Need ranked shortlists without code? Paste a job description and get fit scores. Pricing & plans Compare Free and PRO credit allowances for API usage. Developer portal Interactive API reference, MCP setup, and your API key.

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?

Yes. API and MCP access is available on all plans. Usage draws from your account credit balance — Free includes 100 credits/month.

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 linkedinId?

id is the internal OpenSearch identifier — use it with get_candidate_cards. linkedinId is the LinkedIn vanity slug (e.g. john-doe) — use it with get_contact. Never pass full LinkedIn URLs.

Is candidate data GDPR-compliant?

Hyranse processes publicly available professional data. You are responsible for lawful use in your jurisdiction and having a valid legal basis for outreach to candidates.

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.

Start building on Hyranse

Open developer portal

Build on Hyranse's candidate data

Up and running in 3 steps

Sign up for Hyranse

Open the developer portal

Make your first request

Choose the interface that fits your stack

REST API

MCP Server

One key. One credit balance.

Authentication

Credits

Data

Programmatic candidate search and contacts

Endpoints

Example request

Example response

ATS sync workflow

Use Hyranse in your AI assistant

Chat workflow

Available tools

Cursor config

Recommended workflow

Example prompts

REST API vs MCP — when to use which

Pay per use from your account balance

Keep your API key safe

Common questions

Start building on Hyranse