API reference
Applications
A candidate's candidacy for one job: its stage, status and AI score.
List applications
/applicationsNeeds the applications:read scope
Newest first, or best match first with sort=score (failed knockouts and the unscored last). q searches the candidate's name, email and resume (every word has to match).
Query parameters
- Only applications to this job.
job_iduuid - Only this candidate's applications.
candidate_iduuid - Only applications in this stage of their job.
stage_iduuid - Only applications with these statuses; repeat for several, e.g. ?status=active&status=hired.
statusarray of enumOne ofactiverejectedhiredwithdrawn - Every word must match the candidate's name, email or resume, e.g. react berlin.
qstring - newest first, or score: best match first, failed knockouts and the unscored last.
sortenumOne ofnewestscoreDefault"newest" - How many to return.
limitintegermin 1max 100Default50 - How many to skip. See Pagination.
offsetintegerDefault0
Returns 200
A page of objects like this one, in items, with the total count. Pagination
iduuidcreated_atdatetimeupdated_atdatetimenullablejob_iduuidcandidate_iduuidcandidateobject4 child attributes
iduuidfirst_namestringlast_namestringemailstringnullable
- A stage of the job (GET /jobs/{job_id}/job-stages).
stage_iduuid - active (in the pipeline), rejected, hired or withdrawn.
statusenumOne ofactiverejectedhiredwithdrawn - Kept with a rejection; internal, never shown to the candidate.
rejection_reasonstringnullable - The candidate's own words on withdrawing, if any.
withdrawal_reasonstringnullable - Set when a rejected or withdrawn candidate applied again, until its status next changes.
reapplied_atdatetimenullable - The candidate's private status page; null for candidates who didn't apply through the job board.
status_urlstringnullable - Null until scoring has been asked for (it is, on its own, when the job has a rubric).
scorecardobjectnullable4 child attributes
- pending while being (re)scored.
statusenumOne ofpendingcompletedfailed - 0-100 against the job's rubric; null until scored, or when the rubric only has knockouts.
scoreintegernullable - The worst of its knockout criteria: failed, else unclear, else passed; null without any.
knockout_resultenumnullableOne ofpassedunclearfailed scored_atdatetimenullable
Errors
- 401The key is wrong, expired or revoked (api_key_required when missing)
invalid_api_key - 403The key isn't allowed applications:read
insufficient_scope - 422A parameter or field doesn't validate
missing, uuid_parsing, …
curl "https://api.hirehappy.io/v1/applications?job_id=7c2e4f1a-9b3d-4e6f-8a1c-2d3e4f5a6b7c&status=active&sort=score" \
-H "Authorization: Bearer $HIREHAPPY_API_KEY"{
"items": [
{
"id": "e3b1c5d7-9f2a-4b6c-8d0e-1f3a5b7c9d2e",
"created_at": "2026-10-26T09:30:00Z",
"updated_at": "2026-10-27T14:05:00Z",
"job_id": "7c2e4f1a-9b3d-4e6f-8a1c-2d3e4f5a6b7c",
"candidate_id": "c9d8e7f6-5a4b-4c3d-8e2f-1a0b9c8d7e6f",
"candidate": {
"id": "c9d8e7f6-5a4b-4c3d-8e2f-1a0b9c8d7e6f",
"first_name": "Ana",
"last_name": "Ribeiro",
"email": "[email protected]"
},
"stage_id": "a41f7b2c-3d5e-4f6a-9b8c-1d2e3f4a5b6c",
"status": "active",
"rejection_reason": null,
"withdrawal_reason": null,
"reapplied_at": null,
"status_url": "https://jobs.hirehappy.io/acme/status/Zk3pQ9vX2mL7",
"scorecard": {
"status": "completed",
"score": 82,
"knockout_result": "passed",
"scored_at": "2026-10-26T09:31:12Z"
}
}
],
"total": 1,
"limit": 50,
"offset": 0
}Create an application
/applicationsNeeds the applications:write scope
Put a candidate forward for a job, in its first stage unless stage_id says otherwise. Scored in the background when the job has a rubric. 409 when they already have an application for it.
Bodyapplication/json
job_iduuidRequiredcandidate_iduuidRequired- A stage of the job; the first one when left out.
stage_iduuidnullable
Returns 201
iduuidcreated_atdatetimeupdated_atdatetimenullablejob_iduuidcandidate_iduuidcandidateobject4 child attributes
iduuidfirst_namestringlast_namestringemailstringnullable
- A stage of the job (GET /jobs/{job_id}/job-stages).
stage_iduuid - active (in the pipeline), rejected, hired or withdrawn.
statusenumOne ofactiverejectedhiredwithdrawn - Kept with a rejection; internal, never shown to the candidate.
rejection_reasonstringnullable - The candidate's own words on withdrawing, if any.
withdrawal_reasonstringnullable - Set when a rejected or withdrawn candidate applied again, until its status next changes.
reapplied_atdatetimenullable - The candidate's private status page; null for candidates who didn't apply through the job board.
status_urlstringnullable - Null until scoring has been asked for (it is, on its own, when the job has a rubric).
scorecardobjectnullable4 child attributes
- pending while being (re)scored.
statusenumOne ofpendingcompletedfailed - 0-100 against the job's rubric; null until scored, or when the rubric only has knockouts.
scoreintegernullable - The worst of its knockout criteria: failed, else unclear, else passed; null without any.
knockout_resultenumnullableOne ofpassedunclearfailed scored_atdatetimenullable
Errors
- 400A value is out of place
validation_error - 401The key is wrong, expired or revoked (api_key_required when missing)
invalid_api_key - 403The key isn't allowed applications:write
insufficient_scope - 409When they already have an application for it
conflict - 422A parameter or field doesn't validate
missing, uuid_parsing, …
curl -X POST "https://api.hirehappy.io/v1/applications" \
-H "Authorization: Bearer $HIREHAPPY_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"job_id": "7c2e4f1a-9b3d-4e6f-8a1c-2d3e4f5a6b7c",
"candidate_id": "c9d8e7f6-5a4b-4c3d-8e2f-1a0b9c8d7e6f"
}'{
"id": "e3b1c5d7-9f2a-4b6c-8d0e-1f3a5b7c9d2e",
"created_at": "2026-10-26T09:30:00Z",
"updated_at": "2026-10-27T14:05:00Z",
"job_id": "7c2e4f1a-9b3d-4e6f-8a1c-2d3e4f5a6b7c",
"candidate_id": "c9d8e7f6-5a4b-4c3d-8e2f-1a0b9c8d7e6f",
"candidate": {
"id": "c9d8e7f6-5a4b-4c3d-8e2f-1a0b9c8d7e6f",
"first_name": "Ana",
"last_name": "Ribeiro",
"email": "[email protected]"
},
"stage_id": "a41f7b2c-3d5e-4f6a-9b8c-1d2e3f4a5b6c",
"status": "active",
"rejection_reason": null,
"withdrawal_reason": null,
"reapplied_at": null,
"status_url": "https://jobs.hirehappy.io/acme/status/Zk3pQ9vX2mL7",
"scorecard": {
"status": "completed",
"score": 82,
"knockout_result": "passed",
"scored_at": "2026-10-26T09:31:12Z"
}
}Retrieve an application
/applications/{application_id}Needs the applications:read scope
Path parameters
application_iduuidRequired
Returns 200
iduuidcreated_atdatetimeupdated_atdatetimenullablejob_iduuidcandidate_iduuidcandidateobject4 child attributes
iduuidfirst_namestringlast_namestringemailstringnullable
- A stage of the job (GET /jobs/{job_id}/job-stages).
stage_iduuid - active (in the pipeline), rejected, hired or withdrawn.
statusenumOne ofactiverejectedhiredwithdrawn - Kept with a rejection; internal, never shown to the candidate.
rejection_reasonstringnullable - The candidate's own words on withdrawing, if any.
withdrawal_reasonstringnullable - Set when a rejected or withdrawn candidate applied again, until its status next changes.
reapplied_atdatetimenullable - The candidate's private status page; null for candidates who didn't apply through the job board.
status_urlstringnullable - Null until scoring has been asked for (it is, on its own, when the job has a rubric).
scorecardobjectnullable4 child attributes
- pending while being (re)scored.
statusenumOne ofpendingcompletedfailed - 0-100 against the job's rubric; null until scored, or when the rubric only has knockouts.
scoreintegernullable - The worst of its knockout criteria: failed, else unclear, else passed; null without any.
knockout_resultenumnullableOne ofpassedunclearfailed scored_atdatetimenullable
Errors
- 401The key is wrong, expired or revoked (api_key_required when missing)
invalid_api_key - 403The key isn't allowed applications:read
insufficient_scope - 404It isn't there, or belongs to another organization
resource_not_found - 422A parameter or field doesn't validate
missing, uuid_parsing, …
curl "https://api.hirehappy.io/v1/applications/e3b1c5d7-9f2a-4b6c-8d0e-1f3a5b7c9d2e" \
-H "Authorization: Bearer $HIREHAPPY_API_KEY"{
"id": "e3b1c5d7-9f2a-4b6c-8d0e-1f3a5b7c9d2e",
"created_at": "2026-10-26T09:30:00Z",
"updated_at": "2026-10-27T14:05:00Z",
"job_id": "7c2e4f1a-9b3d-4e6f-8a1c-2d3e4f5a6b7c",
"candidate_id": "c9d8e7f6-5a4b-4c3d-8e2f-1a0b9c8d7e6f",
"candidate": {
"id": "c9d8e7f6-5a4b-4c3d-8e2f-1a0b9c8d7e6f",
"first_name": "Ana",
"last_name": "Ribeiro",
"email": "[email protected]"
},
"stage_id": "a41f7b2c-3d5e-4f6a-9b8c-1d2e3f4a5b6c",
"status": "active",
"rejection_reason": null,
"withdrawal_reason": null,
"reapplied_at": null,
"status_url": "https://jobs.hirehappy.io/acme/status/Zk3pQ9vX2mL7",
"scorecard": {
"status": "completed",
"score": 82,
"knockout_result": "passed",
"scored_at": "2026-10-26T09:31:12Z"
}
}Update an application
/applications/{application_id}Needs the applications:write scope
Move it to another stage, or change its status: reject, hire (moves it to the last stage, and starts onboarding), or back to active. As in the app, a candidate who applied through the job board is emailed on moving on to a later public stage and on being hired; on being rejected only when notify_candidate asks.
Path parameters
application_iduuidRequired
Bodyapplication/json
- Move it to another stage of its job, at the bottom of it. The last stage marks it hired.
stage_iduuidnullable - rejected, hired (moves it to the last stage and starts onboarding) or back to active.
statusenumnullableOne ofactiverejectedhiredwithdrawn - Kept with a rejection; internal, never shown to the candidate.
rejection_reasonstringnullablemax 5,000 chars - With status "rejected": email the candidate their default rejection email, now. Other emails (moved on to a later public stage, hired) go to candidates who applied through the job board on their own.
notify_candidatebooleanDefaultfalse
Returns 200
iduuidcreated_atdatetimeupdated_atdatetimenullablejob_iduuidcandidate_iduuidcandidateobject4 child attributes
iduuidfirst_namestringlast_namestringemailstringnullable
- A stage of the job (GET /jobs/{job_id}/job-stages).
stage_iduuid - active (in the pipeline), rejected, hired or withdrawn.
statusenumOne ofactiverejectedhiredwithdrawn - Kept with a rejection; internal, never shown to the candidate.
rejection_reasonstringnullable - The candidate's own words on withdrawing, if any.
withdrawal_reasonstringnullable - Set when a rejected or withdrawn candidate applied again, until its status next changes.
reapplied_atdatetimenullable - The candidate's private status page; null for candidates who didn't apply through the job board.
status_urlstringnullable - Null until scoring has been asked for (it is, on its own, when the job has a rubric).
scorecardobjectnullable4 child attributes
- pending while being (re)scored.
statusenumOne ofpendingcompletedfailed - 0-100 against the job's rubric; null until scored, or when the rubric only has knockouts.
scoreintegernullable - The worst of its knockout criteria: failed, else unclear, else passed; null without any.
knockout_resultenumnullableOne ofpassedunclearfailed scored_atdatetimenullable
Errors
- 400A value is out of place
validation_error - 401The key is wrong, expired or revoked (api_key_required when missing)
invalid_api_key - 403The key isn't allowed applications:write
insufficient_scope - 404It isn't there, or belongs to another organization
resource_not_found - 422A parameter or field doesn't validate
missing, uuid_parsing, …
curl -X PATCH "https://api.hirehappy.io/v1/applications/e3b1c5d7-9f2a-4b6c-8d0e-1f3a5b7c9d2e" \
-H "Authorization: Bearer $HIREHAPPY_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"stage_id": "a41f7b2c-3d5e-4f6a-9b8c-1d2e3f4a5b6c"
}'{
"id": "e3b1c5d7-9f2a-4b6c-8d0e-1f3a5b7c9d2e",
"created_at": "2026-10-26T09:30:00Z",
"updated_at": "2026-10-27T14:05:00Z",
"job_id": "7c2e4f1a-9b3d-4e6f-8a1c-2d3e4f5a6b7c",
"candidate_id": "c9d8e7f6-5a4b-4c3d-8e2f-1a0b9c8d7e6f",
"candidate": {
"id": "c9d8e7f6-5a4b-4c3d-8e2f-1a0b9c8d7e6f",
"first_name": "Ana",
"last_name": "Ribeiro",
"email": "[email protected]"
},
"stage_id": "a41f7b2c-3d5e-4f6a-9b8c-1d2e3f4a5b6c",
"status": "active",
"rejection_reason": null,
"withdrawal_reason": null,
"reapplied_at": null,
"status_url": "https://jobs.hirehappy.io/acme/status/Zk3pQ9vX2mL7",
"scorecard": {
"status": "completed",
"score": 82,
"knockout_result": "passed",
"scored_at": "2026-10-26T09:31:12Z"
}
}