HirePick

Developers

HirePick API

Last updated November 2026

Everything you need to build on HirePick: a REST API for candidates and positions, real-time webhooks, and an MCP server for AI assistants.

REST API
https://api.hirepick.io/api/integrations/zapier/external
MCP server
https://api.hirepick.io/api/mcp
Authentication
Authorization: Bearer <key>

Getting started

Introduction

HirePick runs AI voice interviews and CV screening for hiring teams. The HirePick API lets you connect it to the rest of your hiring stack: your careers site, ATS, CRM, spreadsheets, chat tools, automation platforms and AI assistants.

There are three ways to build on HirePick:

InterfaceUse it toAuthentication
REST APIAdd, find and update candidates, list positions and manage webhook subscriptions from your own code or an automation tool.API key
WebhooksGet notified in real time when candidates are added, invited, interviewed, approved or rejected, and when positions are created.API key, or a signing secret
MCP serverLet AI assistants such as Claude, ChatGPT and Cursor manage positions, candidates, interviews, CV screening and more in plain language.OAuth (sign in and allow access)

Ready-made connections are also available for Zapier, Make, Slack and Mattermost. See integrations.

Quickstart

  1. Create an API key in HirePick.
  2. Check it works by calling GET /me.
  3. List your positions, then add a candidate to one of them.
  4. Subscribe a URL to INTERVIEW_COMPLETED to get each result as soon as it is scored.

cURL

curl https://api.hirepick.io/api/integrations/zapier/external/me \
  -H "Authorization: Bearer hp_live_your_key"

JavaScript

const BASE_URL = "https://api.hirepick.io/api/integrations/zapier/external";
const headers = {
  Authorization: `Bearer ${process.env.HIREPICK_API_KEY}`,
  "Content-Type": "application/json",
};

const [position] = await fetch(`${BASE_URL}/positions`, { headers }).then((r) => r.json());

const candidate = await fetch(`${BASE_URL}/candidates`, {
  method: "POST",
  headers,
  body: JSON.stringify({
    name: "John Carter",
    email: "john.carter@example.com",
    positionId: position.id,
  }),
}).then((r) => r.json());

console.log(candidate.id, candidate.status);

Conventions

REST base URLhttps://api.hirepick.io/api/integrations/zapier/external
MCP server URLhttps://api.hirepick.io/api/mcp
TransportHTTPS only.
FormatJSON request and response bodies, UTF-8. Send Content-Type: application/json with a body.
ResponsesSuccessful responses return the object or list directly, with no wrapper.
IdsUUID strings.
TimestampsISO 8601 in UTC, for example 2026-11-12T14:30:00.000Z.
Empty valuesFields without a value are null, not omitted.

Versioning and stability

We may add new endpoints, response fields and event types at any time. Build your integration to ignore fields it does not recognise. Existing fields are not removed or renamed without notice. Changes are listed in the changelog.

Authentication

REST and webhook requests are authenticated with an API key sent as a Bearer token in the Authorization header:

Authorization: Bearer hp_live_your_key
CredentialWorks withActs as
API keyREST API and webhook subscriptionsA recruiter, limited by its position access
MCP OAuthMCP serverThe owner or admin who approved the assistant

API keys are not accepted in the URL or query string. A missing, invalid or revoked key returns 401. Using a key with the wrong interface returns 403. MCP assistants authenticate with OAuth instead of a pasted key — see connect an assistant.

API keys

Create an API key

  1. Sign in as an organization owner or admin and open Settings → Integrations, then Zapier or Make.
  2. Click Generate new API key and name it after the tool that will use it.
  3. Choose its position access.
  4. Copy the key. It starts with hp_live_ and is shown only once.

MCP access

The MCP server does not use a dashboard “Create token” flow. Connect an assistant with the MCP server URL; HirePick opens a consent screen and issues OAuth tokens after you allow access. Connected apps are listed on the MCP page and can be revoked there.

Lifecycle

  • Each API key shows when it was last used. Keys unused for 90 days are flagged.
  • Revoking a key takes effect immediately.
  • A key also stops working when its creator is no longer an owner or admin.
  • Webhook subscriptions created with a key stop when the key stops working.
  • Revoking a connected MCP app invalidates its OAuth tokens immediately.

Position access

Each API key has one of two access levels, chosen when it is created:

AccessCan work withpositionId in requests
All positionsEvery position in the organization.Required when creating or updating a candidate. Optional filter elsewhere.
One positionOnly that position.Optional. Defaults to the key's position. Any other position returns 403.

A key limited to one position only lists that position, only returns its candidates, only receives its events, and never receives POSITION_CREATED. Use it when a tool should only touch one role, such as a single job board feed.

REST API

Overview

Account and positions

GET/me

Check an API key

Returns the organization and user the key belongs to. Use it to test a connection. positionId and positionTitle are set only when the key is limited to one position.

Example

Request

curl https://api.hirepick.io/api/integrations/zapier/external/me \
  -H "Authorization: Bearer hp_live_your_key"

Response

{
  "email": "john.carter@example.com",
  "organizationId": "0b7e4c1a-2d3f-4a5b-9c6d-7e8f9a0b1c2d",
  "organizationName": "Acme Inc",
  "positionId": null,
  "positionTitle": null
}

Errors

StatusMessage
401Invalid or revoked API key.
GET/positions

List positions

Returns the active positions the key can access, sorted by title. Closed positions are not included.

Example

Request

curl https://api.hirepick.io/api/integrations/zapier/external/positions \
  -H "Authorization: Bearer hp_live_your_key"

Response

[
  {
    "id": "6f1c2a9e-4b7d-4c3a-9e21-8a5d3f0b7c11",
    "title": "Senior Frontend Engineer",
    "department": "Engineering",
    "location": "Remote"
  }
]

Errors

StatusMessage
401Invalid or revoked API key.

Candidates

Candidate endpoints return the candidate object.

POST/candidates

Create a candidate

Adds a candidate to a position and returns the candidate object. The candidate starts as NOT_INVITED. Candidates created through the REST API do not send the CANDIDATE_IMPORTED event, which prevents automation loops.

Body (JSON)

NameTypeRequiredDescription
namestringRequiredThe candidate's full name.
emailstringRequiredA valid email address, unique within the position. Stored in lowercase.
positionIdstring (uuid)See noteRequired for keys with access to all positions. Keys limited to one position may omit it; any other position returns 403.

Example

Request

curl -X POST https://api.hirepick.io/api/integrations/zapier/external/candidates \
  -H "Authorization: Bearer hp_live_your_key" \
  -H "Content-Type: application/json" \
  -d '{"name":"John Carter","email":"john.carter@example.com","positionId":"6f1c2a9e-4b7d-4c3a-9e21-8a5d3f0b7c11"}'

Response

{
  "id": "a3e7c1d2-5f84-4b9a-8c6e-2d1f9b0a4e57",
  "candidateId": "a3e7c1d2-5f84-4b9a-8c6e-2d1f9b0a4e57",
  "name": "John Carter",
  "email": "john.carter@example.com",
  "status": "NOT_INVITED",
  "source": "MANUAL",
  "positionId": "6f1c2a9e-4b7d-4c3a-9e21-8a5d3f0b7c11",
  "positionTitle": "Senior Frontend Engineer",
  "score": null,
  "scoreOverview": null,
  "evaluationDecision": "PENDING",
  "evaluationRating": null,
  "interviewCompletedAt": null,
  "reviewUrl": "https://app.hirepick.io/dashboard/reviews/6f1c2a9e-4b7d-4c3a-9e21-8a5d3f0b7c11/results?candidate=a3e7c1d2-5f84-4b9a-8c6e-2d1f9b0a4e57",
  "createdAt": "2026-11-13T09:15:00.000Z",
  "updatedAt": "2026-11-13T09:15:00.000Z"
}

Errors

StatusMessage
400Validation failed. (See errors for each field.)
400Choose a position for this request. This API key has no default position.
401Invalid or revoked API key.
403This API key is limited to one position. Use a key without a default position to work across positions.
404Position not found.
409A candidate with this email already exists for this position.
PATCH/candidates/{candidateId}/status

Update a candidate's status

Sets a candidate's status and returns the updated candidate object. Only NOT_INVITED and COMPLETED can be set through the API. Other statuses are managed by HirePick as interviews progress.

Path parameters

NameTypeRequiredDescription
candidateIdstring (uuid)RequiredThe candidate's id.

Body (JSON)

NameTypeRequiredDescription
statusstringRequiredNOT_INVITED or COMPLETED.
positionIdstring (uuid)See noteThe position the candidate belongs to. Required for keys with access to all positions. Keys limited to one position may omit it; any other position returns 403.

Example

Request

curl -X PATCH https://api.hirepick.io/api/integrations/zapier/external/candidates/a3e7c1d2-5f84-4b9a-8c6e-2d1f9b0a4e57/status \
  -H "Authorization: Bearer hp_live_your_key" \
  -H "Content-Type: application/json" \
  -d '{"status":"COMPLETED","positionId":"6f1c2a9e-4b7d-4c3a-9e21-8a5d3f0b7c11"}'

Response

{
  "id": "a3e7c1d2-5f84-4b9a-8c6e-2d1f9b0a4e57",
  "candidateId": "a3e7c1d2-5f84-4b9a-8c6e-2d1f9b0a4e57",
  "name": "John Carter",
  "email": "john.carter@example.com",
  "status": "COMPLETED",
  "source": "MANUAL",
  "positionId": "6f1c2a9e-4b7d-4c3a-9e21-8a5d3f0b7c11",
  "positionTitle": "Senior Frontend Engineer",
  "score": 84,
  "scoreOverview": "Strong React fundamentals and clear communication.",
  "evaluationDecision": "PENDING",
  "evaluationRating": null,
  "interviewCompletedAt": "2026-11-12T14:30:00.000Z",
  "reviewUrl": "https://app.hirepick.io/dashboard/reviews/6f1c2a9e-4b7d-4c3a-9e21-8a5d3f0b7c11/results?candidate=a3e7c1d2-5f84-4b9a-8c6e-2d1f9b0a4e57",
  "createdAt": "2026-11-12T09:15:00.000Z",
  "updatedAt": "2026-11-12T14:31:00.000Z"
}

Errors

StatusMessage
400Validation failed. (See errors for each field.)
400Choose a position for this request. This API key has no default position.
401Invalid or revoked API key.
403This API key is limited to one position. Use a key without a default position to work across positions.
404Position not found.
404Candidate not found. (The candidate is not in that position.)
POST/candidates/{candidateId}/decision

Approve or reject a candidate

Records a hiring decision on a candidate whose interview is finished and returns the updated candidate object. This is the same as approving or rejecting on the review page. It sends the CANDIDATE_STATUS_CHANGED event and does not email the candidate.

Path parameters

NameTypeRequiredDescription
candidateIdstring (uuid)RequiredThe candidate's id.

Body (JSON)

NameTypeRequiredDescription
decisionstringRequiredAPPROVED or REJECTED.
ratingstringRequiredVERY_BAD, BAD, NEUTRAL, GOOD or VERY_GOOD.
commentstringRequiredThe reason for the decision, up to 500 characters.

Example

Request

curl -X POST https://api.hirepick.io/api/integrations/zapier/external/candidates/a3e7c1d2-5f84-4b9a-8c6e-2d1f9b0a4e57/decision \
  -H "Authorization: Bearer hp_live_your_key" \
  -H "Content-Type: application/json" \
  -d '{"decision":"APPROVED","rating":"GOOD","comment":"Clear answers and strong experience."}'

Response

{
  "id": "a3e7c1d2-5f84-4b9a-8c6e-2d1f9b0a4e57",
  "candidateId": "a3e7c1d2-5f84-4b9a-8c6e-2d1f9b0a4e57",
  "name": "John Carter",
  "email": "john.carter@example.com",
  "status": "COMPLETED",
  "source": "MANUAL",
  "positionId": "6f1c2a9e-4b7d-4c3a-9e21-8a5d3f0b7c11",
  "positionTitle": "Senior Frontend Engineer",
  "score": 84,
  "scoreOverview": "Strong React fundamentals and clear communication.",
  "evaluationDecision": "APPROVED",
  "evaluationRating": "GOOD",
  "interviewCompletedAt": "2026-11-12T14:30:00.000Z",
  "reviewUrl": "https://app.hirepick.io/dashboard/reviews/6f1c2a9e-4b7d-4c3a-9e21-8a5d3f0b7c11/results?candidate=a3e7c1d2-5f84-4b9a-8c6e-2d1f9b0a4e57",
  "createdAt": "2026-11-12T09:15:00.000Z",
  "updatedAt": "2026-11-12T14:31:00.000Z"
}

Errors

StatusMessage
400Validation failed. (See errors for each field.)
400Only completed interviews can be evaluated.
401Invalid or revoked API key.
404Candidate not found.
DELETE/candidates/{candidateId}

Delete a candidate

Permanently deletes the candidate, including their interview results and recordings, and returns the candidate as it was before deletion with deleted set to true. Credits held for an open invite are settled first. This cannot be undone.

Path parameters

NameTypeRequiredDescription
candidateIdstring (uuid)RequiredThe candidate's id.

Example

Request

curl -X DELETE https://api.hirepick.io/api/integrations/zapier/external/candidates/a3e7c1d2-5f84-4b9a-8c6e-2d1f9b0a4e57 \
  -H "Authorization: Bearer hp_live_your_key"

Response

{
  "id": "a3e7c1d2-5f84-4b9a-8c6e-2d1f9b0a4e57",
  "candidateId": "a3e7c1d2-5f84-4b9a-8c6e-2d1f9b0a4e57",
  "name": "John Carter",
  "email": "john.carter@example.com",
  "status": "NOT_INVITED",
  "source": "MANUAL",
  "positionId": "6f1c2a9e-4b7d-4c3a-9e21-8a5d3f0b7c11",
  "positionTitle": "Senior Frontend Engineer",
  "score": null,
  "scoreOverview": null,
  "evaluationDecision": "PENDING",
  "evaluationRating": null,
  "interviewCompletedAt": null,
  "reviewUrl": "https://app.hirepick.io/dashboard/reviews/6f1c2a9e-4b7d-4c3a-9e21-8a5d3f0b7c11/results?candidate=a3e7c1d2-5f84-4b9a-8c6e-2d1f9b0a4e57",
  "createdAt": "2026-11-13T09:15:00.000Z",
  "updatedAt": "2026-11-13T09:15:00.000Z",
  "deleted": true
}

Errors

StatusMessage
401Invalid or revoked API key.
404Candidate not found.
GET/candidates

List candidates

Returns candidates newest first, 100 per page. Each item also has a label in the form "Name (email)" for pickers. An empty list means there are no more pages.

Query parameters

NameTypeRequiredDescription
positionIdstring (uuid)OptionalOnly include this position. Keys limited to one position always use their own.
pagenumberOptionalPage number, starting at 0. Defaults to 0.

Example

Request

curl "https://api.hirepick.io/api/integrations/zapier/external/candidates?page=0" \
  -H "Authorization: Bearer hp_live_your_key"

Response

[
  {
    "id": "a3e7c1d2-5f84-4b9a-8c6e-2d1f9b0a4e57",
    "candidateId": "a3e7c1d2-5f84-4b9a-8c6e-2d1f9b0a4e57",
    "name": "John Carter",
    "email": "john.carter@example.com",
    "status": "COMPLETED",
    "source": "MANUAL",
    "positionId": "6f1c2a9e-4b7d-4c3a-9e21-8a5d3f0b7c11",
    "positionTitle": "Senior Frontend Engineer",
    "score": 84,
    "scoreOverview": "Strong React fundamentals and clear communication.",
    "evaluationDecision": "PENDING",
    "evaluationRating": null,
    "interviewCompletedAt": "2026-11-12T14:30:00.000Z",
    "reviewUrl": "https://app.hirepick.io/dashboard/reviews/6f1c2a9e-4b7d-4c3a-9e21-8a5d3f0b7c11/results?candidate=a3e7c1d2-5f84-4b9a-8c6e-2d1f9b0a4e57",
    "createdAt": "2026-11-12T09:15:00.000Z",
    "updatedAt": "2026-11-12T14:31:00.000Z",
    "label": "John Carter (john.carter@example.com)"
  }
]

Errors

StatusMessage
400Validation failed. (See errors for each field.)
401Invalid or revoked API key.
403This API key is limited to one position. Use a key without a default position to work across positions.
GET/candidates/search

Find candidates by email

Returns candidates with an exact email match, most recently updated first, up to 25. The same person can exist in several positions. An empty list means no match.

Query parameters

NameTypeRequiredDescription
emailstringRequiredThe email to look up. Not case sensitive.
positionIdstring (uuid)OptionalOnly include this position. Keys limited to one position always use their own.

Example

Request

curl "https://api.hirepick.io/api/integrations/zapier/external/candidates/search?email=john.carter%40example.com" \
  -H "Authorization: Bearer hp_live_your_key"

Response

[
  {
    "id": "a3e7c1d2-5f84-4b9a-8c6e-2d1f9b0a4e57",
    "candidateId": "a3e7c1d2-5f84-4b9a-8c6e-2d1f9b0a4e57",
    "name": "John Carter",
    "email": "john.carter@example.com",
    "status": "COMPLETED",
    "source": "MANUAL",
    "positionId": "6f1c2a9e-4b7d-4c3a-9e21-8a5d3f0b7c11",
    "positionTitle": "Senior Frontend Engineer",
    "score": 84,
    "scoreOverview": "Strong React fundamentals and clear communication.",
    "evaluationDecision": "PENDING",
    "evaluationRating": null,
    "interviewCompletedAt": "2026-11-12T14:30:00.000Z",
    "reviewUrl": "https://app.hirepick.io/dashboard/reviews/6f1c2a9e-4b7d-4c3a-9e21-8a5d3f0b7c11/results?candidate=a3e7c1d2-5f84-4b9a-8c6e-2d1f9b0a4e57",
    "createdAt": "2026-11-12T09:15:00.000Z",
    "updatedAt": "2026-11-12T14:31:00.000Z"
  }
]

Errors

StatusMessage
400Validation failed. (See errors for each field.)
401Invalid or revoked API key.
403This API key is limited to one position. Use a key without a default position to work across positions.

Webhook subscriptions

Manage webhook subscriptions from code. Each subscription sends one event type to one URL.

POST/hooks

Subscribe to an event

Registers a URL to receive an event. Keep the returned id to unsubscribe. Subscriptions belong to the key that created them and stop when it is revoked.

Body (JSON)

NameTypeRequiredDescription
hookUrlstring (url)RequiredA public https URL. Private and local network addresses are rejected.
eventstringRequiredAn event type.
positionIdstring (uuid)OptionalOnly include this position. Keys limited to one position always use their own.

Example

Request

curl -X POST https://api.hirepick.io/api/integrations/zapier/external/hooks \
  -H "Authorization: Bearer hp_live_your_key" \
  -H "Content-Type: application/json" \
  -d '{"hookUrl":"https://example.com/hirepick","event":"INTERVIEW_COMPLETED"}'

Response

{
  "id": "9c4f2e7a-1b3d-4e5f-8a6b-7c8d9e0f1a2b",
  "eventType": "INTERVIEW_COMPLETED",
  "positionId": null,
  "createdAt": "2026-11-12T09:00:00.000Z"
}

Errors

StatusMessage
400Validation failed. (See errors for each field.)
400That address points to a private or local network.
400That host could not be resolved.
400This API key has too many active Zaps. Turn some off and try again.
401Invalid or revoked API key.
403This API key is limited to one position. Use a key without a default position to work across positions.
404Position not found.
DELETE/hooks/{id}

Unsubscribe

Removes a subscription created by the same key. Safe to call more than once: it succeeds even if the subscription is already gone.

Path parameters

NameTypeRequiredDescription
idstring (uuid)RequiredThe subscription id returned by subscribe.

Example

Request

curl -X DELETE https://api.hirepick.io/api/integrations/zapier/external/hooks/9c4f2e7a-1b3d-4e5f-8a6b-7c8d9e0f1a2b \
  -H "Authorization: Bearer hp_live_your_key"

Response

{
  "id": "9c4f2e7a-1b3d-4e5f-8a6b-7c8d9e0f1a2b"
}

Errors

StatusMessage
401Invalid or revoked API key.
GET/hooks/samples

List sample events

Returns up to 10 recent records for an event, newest first, in the same shape as live deliveries. Use it to map fields before a real event happens. Samples show each record's current state.

Query parameters

NameTypeRequiredDescription
eventstringRequiredAn event type.
positionIdstring (uuid)OptionalOnly include this position. Keys limited to one position always use their own.

Example

Request

curl "https://api.hirepick.io/api/integrations/zapier/external/hooks/samples?event=INTERVIEW_COMPLETED" \
  -H "Authorization: Bearer hp_live_your_key"

Response

[
  {
    "id": "a3e7c1d2-5f84-4b9a-8c6e-2d1f9b0a4e57",
    "candidateId": "a3e7c1d2-5f84-4b9a-8c6e-2d1f9b0a4e57",
    "name": "John Carter",
    "email": "john.carter@example.com",
    "status": "COMPLETED",
    "source": "MANUAL",
    "positionId": "6f1c2a9e-4b7d-4c3a-9e21-8a5d3f0b7c11",
    "positionTitle": "Senior Frontend Engineer",
    "score": 84,
    "scoreOverview": "Strong React fundamentals and clear communication.",
    "evaluationDecision": "PENDING",
    "evaluationRating": null,
    "interviewCompletedAt": "2026-11-12T14:30:00.000Z",
    "reviewUrl": "https://app.hirepick.io/dashboard/reviews/6f1c2a9e-4b7d-4c3a-9e21-8a5d3f0b7c11/results?candidate=a3e7c1d2-5f84-4b9a-8c6e-2d1f9b0a4e57",
    "createdAt": "2026-11-12T09:15:00.000Z",
    "updatedAt": "2026-11-12T14:31:00.000Z",
    "event": "INTERVIEW_COMPLETED",
    "occurredAt": "2026-11-12T14:31:00.000Z"
  }
]

Errors

StatusMessage
400Validation failed. (See errors for each field.)
401Invalid or revoked API key.
403This API key is limited to one position. Use a key without a default position to work across positions.

Webhooks

Overview

Webhooks push events to your URL as they happen. There are two ways to set them up:

SubscriptionsSettings webhook
Set upPOST /hooksSettings → Integrations → Zapier or Make
URLsUp to 100 per API key, one event eachOne per tool, any selection of events
PayloadFull candidate or position objectEvent summary in a data field
SecurityUnique, hard-to-guess URLHMAC signature header
Best forApps and automation platformsA single endpoint you run yourself

Both use the same event types, retry rules and delivery headers.

Receiving events

Each event is sent as a POST request with a JSON body.

Headers

HeaderDescription
Content-Typeapplication/json
X-HirePick-EventThe event type.
X-HirePick-DeliveryUnique id of this delivery. Use it to ignore duplicates.
X-HirePick-SignatureSettings webhooks only. See verifying signatures.

Responding

  • Return any 2xx status within 10 seconds. Do slow work after responding.
  • Any other status, a timeout or a network error counts as a failure. Failed deliveries are retried with increasing delays, up to 3 attempts in total.
  • For subscriptions, return 410 Gone to remove the subscription. No further events are sent to it.
  • Redirects are not followed and count as a failure.
  • URLs must use https and resolve to a public address.

Ordering and duplicates

Events usually arrive within seconds, but order is not guaranteed and a retry can deliver the same event twice. Use X-HirePick-Delivery to detect duplicates and updatedAt to keep the latest state.

Subscription payload

The full candidate or position object, plus event and occurredAt. See event types for examples.

Payloads show the latest state

The object is loaded when the delivery is sent, not when the event happened. A delayed or retried delivery can show newer values, for example a CANDIDATE_INVITED event whose status is already COMPLETED. Use event to know what happened and occurredAt to know when. If the candidate or position was deleted before delivery, the payload contains the event's data fields instead of the full object.

Example receiver (Node.js)

import express from "express";

const app = express();
app.use(express.json());

const seen = new Set();

app.post("/hirepick", (req, res) => {
  const deliveryId = req.get("X-HirePick-Delivery");
  if (seen.has(deliveryId)) return res.sendStatus(200);
  seen.add(deliveryId);

  const { event, name, email, score, reviewUrl } = req.body;
  if (event === "INTERVIEW_COMPLETED") {
    console.log(`${name} <${email}> scored ${score}: ${reviewUrl}`);
  }
  res.sendStatus(200);
});

app.listen(3000);

Settings webhooks and signatures

A webhook URL saved in Settings → Integrations for Zapier or Make receives every event you tick. Each delivery has this body:

{
  "event": "INTERVIEW_COMPLETED",
  "occurredAt": "2026-11-12T14:31:00.000Z",
  "data": {
    "candidateId": "a3e7c1d2-5f84-4b9a-8c6e-2d1f9b0a4e57",
    "positionId": "6f1c2a9e-4b7d-4c3a-9e21-8a5d3f0b7c11",
    "score": 84,
    "overview": "Strong React fundamentals and clear communication."
  }
}

The fields inside data depend on the event and are listed in event types. Use the ids to fetch more detail from the REST API.

Verify the signature

Every delivery is signed with your webhook's signing secret, which you can reveal in the same settings screen. The X-HirePick-Signature header contains sha256= followed by the hex HMAC-SHA256 of the raw request body. Compute it over the exact bytes received, before parsing the JSON, and compare in constant time.

Node.js

import crypto from "node:crypto";
import express from "express";

const app = express();
const SECRET = process.env.HIREPICK_SIGNING_SECRET;

app.post("/hirepick", express.raw({ type: "application/json" }), (req, res) => {
  const received = req.get("X-HirePick-Signature") ?? "";
  const expected =
    "sha256=" + crypto.createHmac("sha256", SECRET).update(req.body).digest("hex");

  const valid =
    received.length === expected.length &&
    crypto.timingSafeEqual(Buffer.from(received), Buffer.from(expected));
  if (!valid) return res.sendStatus(401);

  const { event, occurredAt, data } = JSON.parse(req.body.toString("utf8"));
  console.log(event, occurredAt, data);
  res.sendStatus(200);
});

app.listen(3000);

Test events

The Send test event button sends an event of type TEST with { "message": "HirePick webhook test" } as its data. Delivery results appear in the integration's activity log.

Event types

EventSent whenObject
CANDIDATE_IMPORTEDA candidate is added in HirePick by hand, imported from a file or Google Sheet, or added through the MCP server. Not sent for candidates created through the REST API.Candidate
CANDIDATE_INVITEDA candidate is sent an AI interview invite, including re-invites.Candidate
INTERVIEW_COMPLETEDA candidate finishes an interview and HirePick has scored it.Candidate
CANDIDATE_STATUS_CHANGEDA reviewer approves or rejects a candidate, or a status is set manually.Candidate
POSITION_CREATEDA position is created.Position

API keys limited to one position never receive POSITION_CREATED.

CANDIDATE_IMPORTED

Subscription payload

{
  "id": "a3e7c1d2-5f84-4b9a-8c6e-2d1f9b0a4e57",
  "candidateId": "a3e7c1d2-5f84-4b9a-8c6e-2d1f9b0a4e57",
  "name": "John Carter",
  "email": "john.carter@example.com",
  "status": "NOT_INVITED",
  "source": "MANUAL",
  "positionId": "6f1c2a9e-4b7d-4c3a-9e21-8a5d3f0b7c11",
  "positionTitle": "Senior Frontend Engineer",
  "score": null,
  "scoreOverview": null,
  "evaluationDecision": "PENDING",
  "evaluationRating": null,
  "interviewCompletedAt": null,
  "reviewUrl": "https://app.hirepick.io/dashboard/reviews/6f1c2a9e-4b7d-4c3a-9e21-8a5d3f0b7c11/results?candidate=a3e7c1d2-5f84-4b9a-8c6e-2d1f9b0a4e57",
  "createdAt": "2026-11-13T09:15:00.000Z",
  "updatedAt": "2026-11-13T09:15:00.000Z",
  "event": "CANDIDATE_IMPORTED",
  "occurredAt": "2026-11-13T09:15:00.000Z"
}

Settings webhook data

{
  "candidateId": "a3e7c1d2-5f84-4b9a-8c6e-2d1f9b0a4e57",
  "positionId": "6f1c2a9e-4b7d-4c3a-9e21-8a5d3f0b7c11",
  "name": "John Carter",
  "email": "john.carter@example.com",
  "source": "MANUAL",
  "createdAt": "2026-11-13T09:15:00.000Z"
}

CANDIDATE_INVITED

Subscription payload

{
  "id": "a3e7c1d2-5f84-4b9a-8c6e-2d1f9b0a4e57",
  "candidateId": "a3e7c1d2-5f84-4b9a-8c6e-2d1f9b0a4e57",
  "name": "John Carter",
  "email": "john.carter@example.com",
  "status": "INVITED",
  "source": "MANUAL",
  "positionId": "6f1c2a9e-4b7d-4c3a-9e21-8a5d3f0b7c11",
  "positionTitle": "Senior Frontend Engineer",
  "score": null,
  "scoreOverview": null,
  "evaluationDecision": "PENDING",
  "evaluationRating": null,
  "interviewCompletedAt": null,
  "reviewUrl": "https://app.hirepick.io/dashboard/reviews/6f1c2a9e-4b7d-4c3a-9e21-8a5d3f0b7c11/results?candidate=a3e7c1d2-5f84-4b9a-8c6e-2d1f9b0a4e57",
  "createdAt": "2026-11-13T09:15:00.000Z",
  "updatedAt": "2026-11-13T09:20:00.000Z",
  "event": "CANDIDATE_INVITED",
  "occurredAt": "2026-11-13T09:20:00.000Z"
}

Settings webhook data

{
  "candidateId": "a3e7c1d2-5f84-4b9a-8c6e-2d1f9b0a4e57",
  "positionId": "6f1c2a9e-4b7d-4c3a-9e21-8a5d3f0b7c11",
  "name": "John Carter",
  "email": "john.carter@example.com",
  "invitedById": "5d2e8f1a-3b4c-4d5e-9f6a-7b8c9d0e1f2a",
  "reinvite": false,
  "expiresAt": "2026-11-20T09:20:00.000Z"
}

INTERVIEW_COMPLETED

Subscription payload

{
  "id": "a3e7c1d2-5f84-4b9a-8c6e-2d1f9b0a4e57",
  "candidateId": "a3e7c1d2-5f84-4b9a-8c6e-2d1f9b0a4e57",
  "name": "John Carter",
  "email": "john.carter@example.com",
  "status": "COMPLETED",
  "source": "MANUAL",
  "positionId": "6f1c2a9e-4b7d-4c3a-9e21-8a5d3f0b7c11",
  "positionTitle": "Senior Frontend Engineer",
  "score": 84,
  "scoreOverview": "Strong React fundamentals and clear communication.",
  "evaluationDecision": "PENDING",
  "evaluationRating": null,
  "interviewCompletedAt": "2026-11-12T14:30:00.000Z",
  "reviewUrl": "https://app.hirepick.io/dashboard/reviews/6f1c2a9e-4b7d-4c3a-9e21-8a5d3f0b7c11/results?candidate=a3e7c1d2-5f84-4b9a-8c6e-2d1f9b0a4e57",
  "createdAt": "2026-11-12T09:15:00.000Z",
  "updatedAt": "2026-11-12T14:31:00.000Z",
  "event": "INTERVIEW_COMPLETED",
  "occurredAt": "2026-11-12T14:31:00.000Z"
}

Settings webhook data

{
  "candidateId": "a3e7c1d2-5f84-4b9a-8c6e-2d1f9b0a4e57",
  "positionId": "6f1c2a9e-4b7d-4c3a-9e21-8a5d3f0b7c11",
  "score": 84,
  "overview": "Strong React fundamentals and clear communication."
}

CANDIDATE_STATUS_CHANGED

Subscription payload

{
  "id": "a3e7c1d2-5f84-4b9a-8c6e-2d1f9b0a4e57",
  "candidateId": "a3e7c1d2-5f84-4b9a-8c6e-2d1f9b0a4e57",
  "name": "John Carter",
  "email": "john.carter@example.com",
  "status": "COMPLETED",
  "source": "MANUAL",
  "positionId": "6f1c2a9e-4b7d-4c3a-9e21-8a5d3f0b7c11",
  "positionTitle": "Senior Frontend Engineer",
  "score": 84,
  "scoreOverview": "Strong React fundamentals and clear communication.",
  "evaluationDecision": "APPROVED",
  "evaluationRating": "GOOD",
  "interviewCompletedAt": "2026-11-12T14:30:00.000Z",
  "reviewUrl": "https://app.hirepick.io/dashboard/reviews/6f1c2a9e-4b7d-4c3a-9e21-8a5d3f0b7c11/results?candidate=a3e7c1d2-5f84-4b9a-8c6e-2d1f9b0a4e57",
  "createdAt": "2026-11-12T09:15:00.000Z",
  "updatedAt": "2026-11-12T16:05:00.000Z",
  "event": "CANDIDATE_STATUS_CHANGED",
  "occurredAt": "2026-11-12T16:05:00.000Z"
}

Settings webhook data

{
  "candidateId": "a3e7c1d2-5f84-4b9a-8c6e-2d1f9b0a4e57",
  "positionId": "6f1c2a9e-4b7d-4c3a-9e21-8a5d3f0b7c11",
  "status": "COMPLETED",
  "evaluationDecision": "APPROVED",
  "evaluationRating": "GOOD"
}

evaluationDecision and evaluationRating are included only when the event comes from a review decision. A manual status change, including PATCH /candidates/{candidateId}/status, sends only candidateId, positionId and status.

POSITION_CREATED

Subscription payload

{
  "id": "6f1c2a9e-4b7d-4c3a-9e21-8a5d3f0b7c11",
  "positionId": "6f1c2a9e-4b7d-4c3a-9e21-8a5d3f0b7c11",
  "title": "Senior Frontend Engineer",
  "department": "Engineering",
  "location": "Remote",
  "employmentType": "Full-time",
  "workType": "Remote",
  "status": "ACTIVE",
  "url": "https://app.hirepick.io/dashboard/positions/6f1c2a9e-4b7d-4c3a-9e21-8a5d3f0b7c11",
  "createdAt": "2026-11-12T08:00:00.000Z",
  "updatedAt": "2026-11-12T08:00:00.000Z",
  "event": "POSITION_CREATED",
  "occurredAt": "2026-11-12T08:00:00.000Z"
}

Settings webhook data

{
  "positionId": "6f1c2a9e-4b7d-4c3a-9e21-8a5d3f0b7c11",
  "title": "Senior Frontend Engineer",
  "department": "Engineering",
  "status": "ACTIVE",
  "createdAt": "2026-11-12T08:00:00.000Z"
}

MCP server

Overview

The HirePick MCP server lets AI assistants that support the Model Context Protocol work with your organization in plain language: “Which candidates for the frontend role scored above 80?”, “Invite them and remind anyone who hasn't started.”

URLhttps://api.hirepick.io/api/mcp
Official MCP Registryio.hirepick/hirepick · View listing
TransportStreamable HTTP
AuthenticationOAuth 2.1 with PKCE. Paste the server URL in your assistant; sign in to HirePick and allow access. No MCP token to copy.
Capabilities41 tools and 4 prompts

The server never exposes integration credentials, signing secrets or full webhook addresses.

Connect an assistant

  1. Copy the MCP server URL from Dashboard → MCP, or find io.hirepick/hirepick on the Official MCP Registry.
  2. In Claude, ChatGPT, Cursor or another MCP client, add a remote / HTTP MCP server and paste that URL.
  3. When HirePick opens, sign in (if needed) and allow the assistant for your organization. Connected apps then appear on the MCP page.

Claude Code

claude mcp add --transport http HirePick https://api.hirepick.io/api/mcp

Cursor and other JSON configs

{
  "mcpServers": {
    "HirePick": {
      "url": "https://api.hirepick.io/api/mcp"
    }
  }
}

Your client should start the OAuth flow automatically. Ask something like “Show my open positions” to check the connection. Revoke access any time from the MCP page.

Tools

Account and team

ToolWhat it does
get_account_overviewCredits available and held for pending invites, hiring totals, top positions, interviews completed today, and an activity chart.
list_team_membersTeam members and their roles.

Positions

ToolWhat it does
list_positionsList positions with optional filters and pagination.
get_positionPosition details, screening questions, stats, candidate summary, credits per invite and a dashboard link.
get_position_activityRecent activity for a position: invites, interviews, imports and reviews.
create_positionCreate a position with its screening questions and interview length.
update_positionUpdate a position's fields, screening questions or status.
delete_positionPreview, then delete, a position that has no candidates.
suggest_questionsDraft screening questions for a role without saving anything.

Candidates and interviews

ToolWhat it does
list_candidatesList candidates for a position, or search across the organization.
get_candidateCandidate profile, status, AI score and feedback, decision, rating and review link.
get_interview_transcriptThe interview transcript for a candidate, shortened if very long.
list_review_queueCandidates awaiting a decision for a position.
add_candidatesAdd one or more candidates to a position. Continues past individual failures.
update_candidateUpdate a candidate's details and, optionally, their status.
delete_candidatePreview, then permanently delete, a candidate.
record_decisionApprove or reject a candidate after a completed interview.
invite_candidatesPreview cost, then email interview invites and spend credits. Up to 50 candidates per call.
send_remindersPreview, then send a one-time reminder to invited candidates who have not started. Up to 50 per call.
cancel_inviteCancel a pending invite and refund its reserved credits.

CV screening

ToolWhat it does
screen_cvsAdd PDF or DOCX CVs to a position for AI screening, up to 5 files and 15 MB per call, or get an upload link.
list_cv_screeningsScreened CVs for a position, best matches first, with recommendation and one-line verdict.
get_cv_screeningFull evaluation of one CV: summary, highlights, skills, requirement checklist and experience.
rescore_cvsRe-run screening for some or all CVs, for example after the job description changed.
cv_to_candidateTurn a screened CV into a candidate, or link it to an existing one.

Invite email templates

ToolWhat it does
list_email_templatesList templates and which one is active, or get one template in full.
design_email_templateRender a draft invite email without saving it.
save_email_templateCreate or update a template, and optionally make it active.
activate_email_templateUse a template for all new invites.
delete_email_templatePreview, then delete, a custom template.

Integrations

ToolWhat it does
get_integrations_overviewConnected integrations, their events and last delivery result. Never returns secrets.
diagnose_integrationExplain why an integration is failing and how to fix it.
set_integration_eventsChoose which events a webhook integration receives.
test_integrationPreview, then send, a test event or test email.
disconnect_integrationPreview, then disconnect, a webhook integration or email sender.

Support

ToolWhat it does
create_support_ticketPreview, then open, a ticket with HirePick support.
list_support_ticketsList the organization's support tickets.
get_support_ticketA ticket with its conversation and any credit review outcome.
reply_support_ticketReply to a ticket. Replying to a resolved ticket reopens it.
update_support_ticketClose or reopen a ticket.
get_demo_bookingThe demo booking link and any upcoming demos.

Prompts

Ready-made prompts that assistants can offer as shortcuts:

PromptWhat it does
weekly_hiring_summarySummarize hiring activity, credits and what needs attention this week.
triage_review_queueRank candidates awaiting review for a position and suggest decisions.
screen_and_shortlistScreen CVs for a position, then shortlist who to invite.
diagnose_email_deliveryFind out why invite emails are not being sent or delivered.

Confirmations and limits

Tools that spend credits, send email or delete data work in two steps. The first call returns a preview and a confirmToken. Nothing happens until the tool is called again with that token, within 10 minutes. This gives the person using the assistant a chance to approve the action.

LimitValue
Requests per connected MCP app60 per minute
Candidates per invite or reminder call50
Items per page in list tools50
CV files per screen_cvs call5, up to 15 MB in total

Errors are returned to the assistant as plain-language tool errors, so it can explain them or try another approach.

Integrations

Zapier

  1. In Zapier, add a HirePick trigger, action or search to a Zap and click Sign in.
  2. Paste an API key. The connection is named after your organization.
  3. Choose a position where asked, or leave it empty on triggers to cover every position the key can access.
  4. Test the step and turn the Zap on.
TypeNameWhat it does
TriggerNew CandidateA candidate is added to a position.
TriggerCandidate InvitedA candidate is sent an AI interview invite.
TriggerInterview CompletedA candidate finishes an interview and it is scored.
TriggerCandidate Status ChangedA candidate is approved or rejected, or their status is set manually.
TriggerNew PositionA position is created.
ActionCreate CandidateAdds a candidate to a position.
ActionUpdate Candidate StatusSets a candidate's status to Not Invited or Completed.
SearchFind CandidateFinds a candidate by email.
Search or createFind or Create CandidateFinds a candidate by email, or creates them if not found.

Turning a Zap off removes its subscription. Candidates created by the Create Candidate action do not fire New Candidate, so a Zap cannot trigger itself in a loop.

Make, n8n and other platforms

  • To call HirePick, use the platform's HTTP module with the REST API and an Authorization: Bearer header.
  • To receive events, create a webhook in the platform and either paste its URL into Settings → Integrations → Make, or subscribe it with the API.

Step-by-step guides for Zapier and Make are built into the Integrations screen in HirePick.

Slack and Mattermost

Paste an incoming webhook URL into Settings → Integrations → Slack or Mattermost to post formatted hiring updates to a channel, with a link to open each update in HirePick. These are notification channels only; they do not use the API.

Objects

Candidate

Returned by candidate endpoints and sent with candidate events. Webhook deliveries and samples also include event and occurredAt.

FieldTypeDescription
idstringUnique id of the candidate.
candidateIdstringSame as id. Included for clarity in automation tools.
namestringFull name.
emailstringEmail address, lowercase.
statusstringInterview status. See statuses and decisions.
sourcestringMANUAL or IMPORTED.
positionIdstringId of the candidate's position.
positionTitlestringTitle of the candidate's position.
scoreinteger | nullAI score from 0 to 100. Null until the interview is scored.
scoreOverviewstring | nullShort AI summary of the interview.
evaluationDecisionstring | nullPENDING, APPROVED or REJECTED.
evaluationRatingstring | nullVERY_BAD, BAD, NEUTRAL, GOOD or VERY_GOOD, once a reviewer rates the candidate.
interviewCompletedAtdatetime | nullWhen the interview was completed.
reviewUrlstringLink to the interview review in HirePick. Requires sign-in.
createdAtdatetimeWhen the candidate was added.
updatedAtdatetimeWhen the candidate last changed.

Example

{
  "id": "a3e7c1d2-5f84-4b9a-8c6e-2d1f9b0a4e57",
  "candidateId": "a3e7c1d2-5f84-4b9a-8c6e-2d1f9b0a4e57",
  "name": "John Carter",
  "email": "john.carter@example.com",
  "status": "COMPLETED",
  "source": "MANUAL",
  "positionId": "6f1c2a9e-4b7d-4c3a-9e21-8a5d3f0b7c11",
  "positionTitle": "Senior Frontend Engineer",
  "score": 84,
  "scoreOverview": "Strong React fundamentals and clear communication.",
  "evaluationDecision": "PENDING",
  "evaluationRating": null,
  "interviewCompletedAt": "2026-11-12T14:30:00.000Z",
  "reviewUrl": "https://app.hirepick.io/dashboard/reviews/6f1c2a9e-4b7d-4c3a-9e21-8a5d3f0b7c11/results?candidate=a3e7c1d2-5f84-4b9a-8c6e-2d1f9b0a4e57",
  "createdAt": "2026-11-12T09:15:00.000Z",
  "updatedAt": "2026-11-12T14:31:00.000Z"
}

Position

Sent with POSITION_CREATED. GET /positions returns a shorter version with id, title, department and location.

FieldTypeDescription
idstringUnique id of the position.
positionIdstringSame as id.
titlestringPosition title.
departmentstringDepartment.
locationstring | nullLocation, if set.
employmentTypestring | nullEmployment type, if set.
workTypestring | nullWork type, if set.
statusstringACTIVE or CLOSED.
urlstringLink to the position in HirePick. Requires sign-in.
createdAtdatetimeWhen the position was created.
updatedAtdatetimeSame as createdAt in POSITION_CREATED events.

Example

{
  "id": "6f1c2a9e-4b7d-4c3a-9e21-8a5d3f0b7c11",
  "positionId": "6f1c2a9e-4b7d-4c3a-9e21-8a5d3f0b7c11",
  "title": "Senior Frontend Engineer",
  "department": "Engineering",
  "location": "Remote",
  "employmentType": "Full-time",
  "workType": "Remote",
  "status": "ACTIVE",
  "url": "https://app.hirepick.io/dashboard/positions/6f1c2a9e-4b7d-4c3a-9e21-8a5d3f0b7c11",
  "createdAt": "2026-11-12T08:00:00.000Z",
  "updatedAt": "2026-11-12T08:00:00.000Z"
}

Statuses and decisions

Candidate status

ValueMeaning
NOT_INVITEDAdded but not yet invited.
INVITEDInvite sent; the interview has not started.
IN_PROGRESSThe candidate has started the interview.
COMPLETEDThe interview is finished.
INCOMPLETEThe interview was started but not finished.
EXPIREDThe invite link expired before the interview was finished.

Review decision

ValueMeaning
PENDINGNot reviewed yet.
APPROVEDThe reviewer approved the candidate.
REJECTEDThe reviewer rejected the candidate.

Resources

Errors

Errors return a non-2xx status and a message that is safe to show to users:

{
  "success": false,
  "message": "A candidate with this email already exists for this position."
}

Validation errors use status 400 and list each invalid field:

{
  "success": false,
  "message": "Validation failed.",
  "errors": [
    {
      "field": "email",
      "message": "Please enter a valid email address."
    }
  ]
}
StatusMeaningWhat to do
400A field is missing or invalid, or a webhook URL is not allowed.Fix the request. Do not retry unchanged.
401The key is missing, invalid or revoked.Check the Authorization header, or create a new key.
403The key cannot access this position or interface.Use a key with the right access.
404The candidate or position was not found.Check the ids and position.
409The candidate's email already exists in that position.Find the existing candidate instead.
429Too many requests.Wait a minute, then retry.
5xxSomething went wrong on our side.Retry with an increasing delay.

Rate limits

LimitValue
REST requests per API key30 per minute
MCP requests per connected app60 per minute
Webhook subscriptions per API key100
Records per sample request10
Records per candidate search25
Webhook response timeout10 seconds
Webhook delivery attempts3

Limits are counted per key, not per IP address, so tools that share servers do not affect each other. When you hit a limit you receive 429.

Security

  • Treat keys and signing secrets like passwords. Keep them on the server, never in browser code or public repositories.
  • Create one key per tool, so you can revoke one without breaking the others.
  • Use a key limited to one position when a tool only needs one role.
  • Verify the signature on settings webhooks, and use hard-to-guess URLs for subscriptions.
  • Revoke keys you no longer use. Keys unused for 90 days are flagged in Settings.
  • Candidate data is personal information. Handle it in line with our Privacy Policy and your own obligations.

Changelog

DateChange
November 2026MCP connects with OAuth (no pasted MCP token). HirePick is listed on the Official MCP Registry as io.hirepick/hirepick.
November 2026Approve or reject a candidate, and delete a candidate.
November 2026Webhook subscriptions, sample events, candidate search, API keys with access to all positions, the Zapier app, and this documentation.

Support

Questions, problems or feature requests: support@hirepick.io. Include the request path, the time it happened and the response message. Never send your API key.