API reference
Jobs
Your jobs: posting them on the job board, closing them, and their details.
List jobs
get
/jobsNeeds the jobs:read scope
Newest first. q matches the title.
Query parameters
- Only jobs with these statuses; repeat for several, e.g. ?status=open&status=draft.
statusarray of enumOne ofdraftopenclosed - Matches part of the title.
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_atdatetimenullabletitlestring- HTML: p, h2-h4, strong, em, u, s, a, ul, ol, li, blockquote, code, pre.
descriptionstringnullable locationstringnullableemployment_typestringnullableworkplace_typeenumnullableOne ofonsitehybridremote- draft (not posted), open (on the job board, taking applications) or closed.
statusenumOne ofdraftopenclosed - A member of the hiring team (a user id).
hiring_manager_iduuidnullable - The job's page on the job board, where candidates apply; null unless open.
job_board_urlstringnullable
Errors
- 401The key is wrong, expired or revoked (api_key_required when missing)
invalid_api_key - 403The key isn't allowed jobs:read
insufficient_scope - 422A parameter or field doesn't validate
missing, uuid_parsing, …
curl "https://api.hirehappy.io/v1/jobs?status=open" \
-H "Authorization: Bearer $HIREHAPPY_API_KEY"{
"items": [
{
"id": "7c2e4f1a-9b3d-4e6f-8a1c-2d3e4f5a6b7c",
"created_at": "2026-10-26T09:30:00Z",
"updated_at": "2026-10-27T14:05:00Z",
"title": "Backend Engineer",
"description": "<p>Build and run the APIs behind our product, in Python and Postgres.</p>",
"location": "Berlin, Germany",
"employment_type": "Full-time",
"workplace_type": "hybrid",
"status": "open",
"hiring_manager_id": "9a8b7c6d-5e4f-4a3b-8c2d-1e0f9a8b7c6d",
"job_board_url": "https://jobs.hirehappy.io/acme/7c2e4f1a-9b3d-4e6f-8a1c-2d3e4f5a6b7c"
}
],
"total": 1,
"limit": 50,
"offset": 0
}Create a job
post
/jobsNeeds the jobs:write scope
Create a job with the default pipeline stages and application form, to set up further in the app.
Bodyapplication/json
titlestringRequiredmin 1 charsmax 200 chars- HTML, as JobResponse.description; anything else is stripped.
descriptionstringnullable locationstringnullablemax 200 charsemployment_typestringnullablemax 50 charsworkplace_typeenumnullableOne ofonsitehybridremote- open posts it to the job board at once.
statusenumOne ofdraftopenclosedDefault"draft" - A user id of a member of the organization.
hiring_manager_iduuidnullable
Returns 201
iduuidcreated_atdatetimeupdated_atdatetimenullabletitlestring- HTML: p, h2-h4, strong, em, u, s, a, ul, ol, li, blockquote, code, pre.
descriptionstringnullable locationstringnullableemployment_typestringnullableworkplace_typeenumnullableOne ofonsitehybridremote- draft (not posted), open (on the job board, taking applications) or closed.
statusenumOne ofdraftopenclosed - A member of the hiring team (a user id).
hiring_manager_iduuidnullable - The job's page on the job board, where candidates apply; null unless open.
job_board_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 jobs:write
insufficient_scope - 422A parameter or field doesn't validate
missing, uuid_parsing, …
curl -X POST "https://api.hirehappy.io/v1/jobs" \
-H "Authorization: Bearer $HIREHAPPY_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"title": "Backend Engineer",
"description": "<p>Build and run the APIs behind our product, in Python and Postgres.</p>",
"location": "Berlin, Germany",
"employment_type": "Full-time",
"workplace_type": "hybrid",
"status": "draft"
}'{
"id": "7c2e4f1a-9b3d-4e6f-8a1c-2d3e4f5a6b7c",
"created_at": "2026-10-26T09:30:00Z",
"updated_at": "2026-10-27T14:05:00Z",
"title": "Backend Engineer",
"description": "<p>Build and run the APIs behind our product, in Python and Postgres.</p>",
"location": "Berlin, Germany",
"employment_type": "Full-time",
"workplace_type": "hybrid",
"status": "open",
"hiring_manager_id": "9a8b7c6d-5e4f-4a3b-8c2d-1e0f9a8b7c6d",
"job_board_url": "https://jobs.hirehappy.io/acme/7c2e4f1a-9b3d-4e6f-8a1c-2d3e4f5a6b7c"
}Retrieve a job
get
/jobs/{job_id}Needs the jobs:read scope
Path parameters
job_iduuidRequired
Returns 200
iduuidcreated_atdatetimeupdated_atdatetimenullabletitlestring- HTML: p, h2-h4, strong, em, u, s, a, ul, ol, li, blockquote, code, pre.
descriptionstringnullable locationstringnullableemployment_typestringnullableworkplace_typeenumnullableOne ofonsitehybridremote- draft (not posted), open (on the job board, taking applications) or closed.
statusenumOne ofdraftopenclosed - A member of the hiring team (a user id).
hiring_manager_iduuidnullable - The job's page on the job board, where candidates apply; null unless open.
job_board_urlstringnullable
Errors
- 401The key is wrong, expired or revoked (api_key_required when missing)
invalid_api_key - 403The key isn't allowed jobs: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/jobs/7c2e4f1a-9b3d-4e6f-8a1c-2d3e4f5a6b7c" \
-H "Authorization: Bearer $HIREHAPPY_API_KEY"{
"id": "7c2e4f1a-9b3d-4e6f-8a1c-2d3e4f5a6b7c",
"created_at": "2026-10-26T09:30:00Z",
"updated_at": "2026-10-27T14:05:00Z",
"title": "Backend Engineer",
"description": "<p>Build and run the APIs behind our product, in Python and Postgres.</p>",
"location": "Berlin, Germany",
"employment_type": "Full-time",
"workplace_type": "hybrid",
"status": "open",
"hiring_manager_id": "9a8b7c6d-5e4f-4a3b-8c2d-1e0f9a8b7c6d",
"job_board_url": "https://jobs.hirehappy.io/acme/7c2e4f1a-9b3d-4e6f-8a1c-2d3e4f5a6b7c"
}Update a job
patch
/jobs/{job_id}Needs the jobs:write scope
Change a job's details, or open (post) or close it.
Path parameters
job_iduuidRequired
Bodyapplication/json
titlestringnullablemin 1 charsmax 200 charsdescriptionstringnullablelocationstringnullablemax 200 charsemployment_typestringnullablemax 50 charsworkplace_typeenumnullableOne ofonsitehybridremote- open posts it to the job board, closed takes it down.
statusenumnullableOne ofdraftopenclosed hiring_manager_iduuidnullable
Returns 200
iduuidcreated_atdatetimeupdated_atdatetimenullabletitlestring- HTML: p, h2-h4, strong, em, u, s, a, ul, ol, li, blockquote, code, pre.
descriptionstringnullable locationstringnullableemployment_typestringnullableworkplace_typeenumnullableOne ofonsitehybridremote- draft (not posted), open (on the job board, taking applications) or closed.
statusenumOne ofdraftopenclosed - A member of the hiring team (a user id).
hiring_manager_iduuidnullable - The job's page on the job board, where candidates apply; null unless open.
job_board_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 jobs: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/jobs/7c2e4f1a-9b3d-4e6f-8a1c-2d3e4f5a6b7c" \
-H "Authorization: Bearer $HIREHAPPY_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"status": "open"
}'{
"id": "7c2e4f1a-9b3d-4e6f-8a1c-2d3e4f5a6b7c",
"created_at": "2026-10-26T09:30:00Z",
"updated_at": "2026-10-27T14:05:00Z",
"title": "Backend Engineer",
"description": "<p>Build and run the APIs behind our product, in Python and Postgres.</p>",
"location": "Berlin, Germany",
"employment_type": "Full-time",
"workplace_type": "hybrid",
"status": "open",
"hiring_manager_id": "9a8b7c6d-5e4f-4a3b-8c2d-1e0f9a8b7c6d",
"job_board_url": "https://jobs.hirehappy.io/acme/7c2e4f1a-9b3d-4e6f-8a1c-2d3e4f5a6b7c"
}