API Reference

The HIRESSCOPE REST API lets you upload CVs, retrieve AI scores, manage jobs, and automate your hiring pipeline. All responses are JSON.

View live API docs (Swagger UI)Download OpenAPI spec

The Swagger UI is available on the dev server. The OpenAPI JSON spec is bundled with this site.

Base URL

https://api.hiresscope.com/api/v1

Authentication

Bearer Token (JWT)

Obtain a JWT access token via POST /auth/login. Include it in every protected request:

Authorization: Bearer <accessToken>

Access tokens expire after 15 minutes. Use POST /auth/refresh with the refresh token (7-day expiry) to obtain a new access token.

API Key

For server-to-server integrations, use an API key header instead of a Bearer token. Generate keys from Settings → API Keys.

X-API-Key: hsk_live_xxxxxxxxxxxxxxxxxxxx

Rate limits

WindowLimitScope
1 minute100 requestsPer tenant (most endpoints)
10 minutes500 requestsPer tenant (all endpoints)
1 minute5 requestsPOST /auth/login (brute-force protection)
When rate-limited, the API returns HTTP 429 with a Retry-After header.

Endpoints

Authentication

—Employer sign-up, login, token refresh and profile.
POST/auth/signupCreate employer account (starts 3-day free trial)public
POST/auth/loginLog in and receive access + refresh tokenspublic
POST/auth/refreshRotate refresh token and get new access tokenpublic
POST/auth/logoutRevoke refresh token
GET/auth/meReturn authenticated user and tenant details

Jobs

—Create and manage job postings. Each job gets a unique public apply link.
GET/jobsList all jobs for tenant (optional ?status filter)
POST/jobsCreate a new job posting
GET/jobs/:idGet a single job by ID
PATCH/jobs/:idUpdate job fields (partial)
DELETE/jobs/:idSoft-delete job; returns talent-pool eligible candidates
POST/jobs/:id/confirm-deleteConfirm deletion; save selected candidates to talent pool
POST/jobs/:id/optimizeRe-run AI job description optimizer
GET/jobs/publicList public active jobs (optional ?company filter)public

Applications

—Upload CVs (PDF/DOCX), retrieve AI scores, update candidate statuses.
POST/jobs/:jobId/applicationsUpload a single CV (multipart/form-data)
POST/jobs/:jobId/applications/bulkUpload up to 50 CVs at once
GET/jobs/:jobId/applicationsList applications for a job (paginated, sortable)
GET/applications/:idGet full application detail including AI explanation
PATCH/applications/:id/statusUpdate status: SHORTLISTED | REJECTED
GET/jobs/:jobId/applications/export-csvExport scored applications as CSV
POST/apply/:slugPublic apply endpoint — candidate submits CV via linkpublic

Candidates

—Candidate-facing portal: register, log in, view scores.
POST/candidates/registerRegister candidate accountpublic
POST/candidates/loginCandidate login → candidate JWTpublic
GET/candidates/me/applicationsCandidate: list own applications (candidateJWT)
GET/candidates/me/score/:appIdCandidate: get AI score + explanation for one application
PATCH/candidates/me/profileCandidate: update name / phone / LinkedIn URL
GET/candidates/:idEmployer: get candidate detail (tenant-scoped)

Analytics

—Aggregated hiring metrics and per-job breakdowns.
GET/analytics/overviewActive jobs, total CVs, avg score, shortlisted count (5-min cache)
GET/analytics/jobs/:jobIdDaily trend, score distribution, status breakdown (1-min cache)

Talent Pool

—Save top candidates across closed jobs.
GET/talent-poolList saved candidates (optional ?department filter)
POST/talent-poolSave a candidate to the talent pool
DELETE/talent-pool/:idRemove a candidate from the talent pool
GET/talent-pool/suggest/:jobIdSuggest talent pool candidates for a job by score + dept

Webhooks

—Register endpoints to receive real-time event notifications.
GET/webhooksList webhook endpoints
POST/webhooksCreate a webhook endpoint
PATCH/webhooks/:idUpdate endpoint URL or events
DELETE/webhooks/:idDelete endpoint
POST/webhooks/:id/testSend a test event to the endpoint

Billing

—Plan details and current usage.
GET/billing/plansList all plans with pricing and feature limitspublic
GET/billing/usageCurrent period CV uploads, jobs created, subscription status

Referrals

—Referral link generation and reward tracking.
POST/referrals/generateGenerate or retrieve referral code + link
GET/referrals/statsInvited / converted / months earned counters

Health

—Service health check — used by load balancers and uptime monitors.
GET/healthReturns { status, db, timestamp, version }public

Error responses

All errors follow the same envelope format:

{
  "statusCode": 400,
  "message": "Validation failed: email must be an email",
  "error": "Bad Request"
}
400Validation error — check request body fields
401Missing or expired JWT / API key
403Plan limit reached or feature not available on your plan
404Resource not found or outside your tenant scope
409Conflict — e.g. duplicate email application
413File too large (max 5 MB per CV)
415Unsupported file type (only PDF, DOCX, DOC, TXT)
429Rate limit exceeded — see Retry-After header
500Internal server error — reported to Sentry automatically
Zapier IntegrationLive Swagger UIPricing & plans