API reference
Candidates
The people you're considering, one per person across all your jobs, with their resumes.
List candidates
/candidatesNeeds the candidates:read scope
Newest first. q matches part of the name or email.
Query parameters
- Matches part of the name or email.
qstring - 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_atdatetimenullablefirst_namestringlast_namestring- Unique within the organization.
emailstringnullable phonestringnullablelocationstringnullablelinkedin_urlstringnullable- Where they came from: "careers_page" for the job board, or whatever was set ("referral", "linkedin", ...).
sourcestringnullable - Their resume (PDF); null when there's none.
resume_urlstringnullable
Errors
- 401The key is wrong, expired or revoked (api_key_required when missing)
invalid_api_key - 403The key isn't allowed candidates:read
insufficient_scope - 422A parameter or field doesn't validate
missing, uuid_parsing, …
curl "https://api.hirehappy.io/v1/candidates?q=ribeiro" \
-H "Authorization: Bearer $HIREHAPPY_API_KEY"{
"items": [
{
"id": "c9d8e7f6-5a4b-4c3d-8e2f-1a0b9c8d7e6f",
"created_at": "2026-10-26T09:30:00Z",
"updated_at": "2026-10-27T14:05:00Z",
"first_name": "Ana",
"last_name": "Ribeiro",
"email": "[email protected]",
"phone": "+49 30 901820",
"location": "Lisbon, Portugal",
"linkedin_url": "https://www.linkedin.com/in/ana-ribeiro",
"source": "referral",
"resume_url": "https://files.hirehappy.io/0b6f3c2e/resume-ana-ribeiro.pdf"
}
],
"total": 1,
"limit": 50,
"offset": 0
}Create a candidate
/candidatesNeeds the candidates:write scope
Add a candidate, to put forward for a job with POST /applications. 409 when another candidate has the email.
Bodyapplication/json
first_namestringRequiredmin 1 charsmax 100 charslast_namestringRequiredmin 1 charsmax 100 chars- 409 when another candidate has it.
emailemailnullable phonestringnullablemax 50 charslocationstringnullablemax 200 charslinkedin_urlstringnullablemax 500 chars- Where they came from, in your own words: referral, linkedin, agency, ...
sourcestringnullablemax 100 chars
Returns 201
iduuidcreated_atdatetimeupdated_atdatetimenullablefirst_namestringlast_namestring- Unique within the organization.
emailstringnullable phonestringnullablelocationstringnullablelinkedin_urlstringnullable- Where they came from: "careers_page" for the job board, or whatever was set ("referral", "linkedin", ...).
sourcestringnullable - Their resume (PDF); null when there's none.
resume_urlstringnullable
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 candidates:write
insufficient_scope - 409When another candidate has the email
conflict - 422A parameter or field doesn't validate
missing, uuid_parsing, …
curl -X POST "https://api.hirehappy.io/v1/candidates" \
-H "Authorization: Bearer $HIREHAPPY_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"first_name": "Ana",
"last_name": "Ribeiro",
"email": "[email protected]",
"linkedin_url": "https://www.linkedin.com/in/ana-ribeiro",
"source": "referral"
}'{
"id": "c9d8e7f6-5a4b-4c3d-8e2f-1a0b9c8d7e6f",
"created_at": "2026-10-26T09:30:00Z",
"updated_at": "2026-10-27T14:05:00Z",
"first_name": "Ana",
"last_name": "Ribeiro",
"email": "[email protected]",
"phone": "+49 30 901820",
"location": "Lisbon, Portugal",
"linkedin_url": "https://www.linkedin.com/in/ana-ribeiro",
"source": "referral",
"resume_url": "https://files.hirehappy.io/0b6f3c2e/resume-ana-ribeiro.pdf"
}Retrieve a candidate
/candidates/{candidate_id}Needs the candidates:read scope
Path parameters
candidate_iduuidRequired
Returns 200
iduuidcreated_atdatetimeupdated_atdatetimenullablefirst_namestringlast_namestring- Unique within the organization.
emailstringnullable phonestringnullablelocationstringnullablelinkedin_urlstringnullable- Where they came from: "careers_page" for the job board, or whatever was set ("referral", "linkedin", ...).
sourcestringnullable - Their resume (PDF); null when there's none.
resume_urlstringnullable
Errors
- 401The key is wrong, expired or revoked (api_key_required when missing)
invalid_api_key - 403The key isn't allowed candidates: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/candidates/c9d8e7f6-5a4b-4c3d-8e2f-1a0b9c8d7e6f" \
-H "Authorization: Bearer $HIREHAPPY_API_KEY"{
"id": "c9d8e7f6-5a4b-4c3d-8e2f-1a0b9c8d7e6f",
"created_at": "2026-10-26T09:30:00Z",
"updated_at": "2026-10-27T14:05:00Z",
"first_name": "Ana",
"last_name": "Ribeiro",
"email": "[email protected]",
"phone": "+49 30 901820",
"location": "Lisbon, Portugal",
"linkedin_url": "https://www.linkedin.com/in/ana-ribeiro",
"source": "referral",
"resume_url": "https://files.hirehappy.io/0b6f3c2e/resume-ana-ribeiro.pdf"
}Update a candidate
/candidates/{candidate_id}Needs the candidates:write scope
Path parameters
candidate_iduuidRequired
Bodyapplication/json
first_namestringnullablemin 1 charsmax 100 charslast_namestringnullablemin 1 charsmax 100 charsemailemailnullablephonestringnullablemax 50 charslocationstringnullablemax 200 charslinkedin_urlstringnullablemax 500 charssourcestringnullablemax 100 chars
Returns 200
iduuidcreated_atdatetimeupdated_atdatetimenullablefirst_namestringlast_namestring- Unique within the organization.
emailstringnullable phonestringnullablelocationstringnullablelinkedin_urlstringnullable- Where they came from: "careers_page" for the job board, or whatever was set ("referral", "linkedin", ...).
sourcestringnullable - Their resume (PDF); null when there's none.
resume_urlstringnullable
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 candidates: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/candidates/c9d8e7f6-5a4b-4c3d-8e2f-1a0b9c8d7e6f" \
-H "Authorization: Bearer $HIREHAPPY_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"phone": "+49 30 901820",
"location": "Lisbon, Portugal"
}'{
"id": "c9d8e7f6-5a4b-4c3d-8e2f-1a0b9c8d7e6f",
"created_at": "2026-10-26T09:30:00Z",
"updated_at": "2026-10-27T14:05:00Z",
"first_name": "Ana",
"last_name": "Ribeiro",
"email": "[email protected]",
"phone": "+49 30 901820",
"location": "Lisbon, Portugal",
"linkedin_url": "https://www.linkedin.com/in/ana-ribeiro",
"source": "referral",
"resume_url": "https://files.hirehappy.io/0b6f3c2e/resume-ana-ribeiro.pdf"
}Delete a candidate
/candidates/{candidate_id}Needs the candidates:write scope
Delete a candidate for good, with their applications and notes (a request to erase their data, say).
Path parameters
candidate_iduuidRequired
Returns 204
No content.
Errors
- 401The key is wrong, expired or revoked (api_key_required when missing)
invalid_api_key - 403The key isn't allowed candidates: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 DELETE "https://api.hirehappy.io/v1/candidates/c9d8e7f6-5a4b-4c3d-8e2f-1a0b9c8d7e6f" \
-H "Authorization: Bearer $HIREHAPPY_API_KEY"Upload a candidate's resume
/candidates/{candidate_id}/resumeNeeds the candidates:write scope
Set the candidate's resume, a PDF sent as multipart/form-data (resume), replacing any they had. It's searchable at once; scorecards use it from the next scoring on.
Path parameters
candidate_iduuidRequired
Bodymultipart/form-data
resumestringRequired
Returns 200
iduuidcreated_atdatetimeupdated_atdatetimenullablefirst_namestringlast_namestring- Unique within the organization.
emailstringnullable phonestringnullablelocationstringnullablelinkedin_urlstringnullable- Where they came from: "careers_page" for the job board, or whatever was set ("referral", "linkedin", ...).
sourcestringnullable - Their resume (PDF); null when there's none.
resume_urlstringnullable
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 candidates: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 PUT "https://api.hirehappy.io/v1/candidates/c9d8e7f6-5a4b-4c3d-8e2f-1a0b9c8d7e6f/resume" \
-H "Authorization: Bearer $HIREHAPPY_API_KEY" \
-F "[email protected];type=application/pdf"{
"id": "c9d8e7f6-5a4b-4c3d-8e2f-1a0b9c8d7e6f",
"created_at": "2026-10-26T09:30:00Z",
"updated_at": "2026-10-27T14:05:00Z",
"first_name": "Ana",
"last_name": "Ribeiro",
"email": "[email protected]",
"phone": "+49 30 901820",
"location": "Lisbon, Portugal",
"linkedin_url": "https://www.linkedin.com/in/ana-ribeiro",
"source": "referral",
"resume_url": "https://files.hirehappy.io/0b6f3c2e/resume-ana-ribeiro.pdf"
}