Docs

Search the docs

Guides, sections and API endpoints

API reference

Jobs

Your jobs: posting them on the job board, closing them, and their details.

List jobs

get/jobs

Needs the jobs:read scope

Newest first. q matches the title.

Query parameters

  • statusarray of enum
    Only jobs with these statuses; repeat for several, e.g. ?status=open&status=draft.
    One ofdraftopenclosed
  • qstring
    Matches part of the title.
  • limitinteger
    How many to return.
    min 1max 100Default 50
  • offsetinteger
    How many to skip. See Pagination.
    Default 0

Returns 200

A page of objects like this one, in items, with the total count. Pagination

  • iduuid
  • created_atdatetime
  • updated_atdatetimenullable
  • titlestring
  • descriptionstringnullable
    HTML: p, h2-h4, strong, em, u, s, a, ul, ol, li, blockquote, code, pre.
  • locationstringnullable
  • employment_typestringnullable
  • workplace_typeenumnullable
    One ofonsitehybridremote
  • statusenum
    draft (not posted), open (on the job board, taking applications) or closed.
    One ofdraftopenclosed
  • hiring_manager_iduuidnullable
    A member of the hiring team (a user id).
  • job_board_urlstringnullable
    The job's page on the job board, where candidates apply; null unless open.

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"
Response 200
{
  "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/jobs

Needs the jobs:write scope

Create a job with the default pipeline stages and application form, to set up further in the app.

Bodyapplication/json

  • titlestringRequired
    min 1 charsmax 200 chars
  • descriptionstringnullable
    HTML, as JobResponse.description; anything else is stripped.
  • locationstringnullable
    max 200 chars
  • employment_typestringnullable
    max 50 chars
  • workplace_typeenumnullable
    One ofonsitehybridremote
  • statusenum
    open posts it to the job board at once.
    One ofdraftopenclosedDefault "draft"
  • hiring_manager_iduuidnullable
    A user id of a member of the organization.

Returns 201

  • iduuid
  • created_atdatetime
  • updated_atdatetimenullable
  • titlestring
  • descriptionstringnullable
    HTML: p, h2-h4, strong, em, u, s, a, ul, ol, li, blockquote, code, pre.
  • locationstringnullable
  • employment_typestringnullable
  • workplace_typeenumnullable
    One ofonsitehybridremote
  • statusenum
    draft (not posted), open (on the job board, taking applications) or closed.
    One ofdraftopenclosed
  • hiring_manager_iduuidnullable
    A member of the hiring team (a user id).
  • job_board_urlstringnullable
    The job's page on the job board, where candidates apply; null unless open.

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"
  }'
Response 201
{
  "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

  • iduuid
  • created_atdatetime
  • updated_atdatetimenullable
  • titlestring
  • descriptionstringnullable
    HTML: p, h2-h4, strong, em, u, s, a, ul, ol, li, blockquote, code, pre.
  • locationstringnullable
  • employment_typestringnullable
  • workplace_typeenumnullable
    One ofonsitehybridremote
  • statusenum
    draft (not posted), open (on the job board, taking applications) or closed.
    One ofdraftopenclosed
  • hiring_manager_iduuidnullable
    A member of the hiring team (a user id).
  • job_board_urlstringnullable
    The job's page on the job board, where candidates apply; null unless open.

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"
Response 200
{
  "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

  • titlestringnullable
    min 1 charsmax 200 chars
  • descriptionstringnullable
  • locationstringnullable
    max 200 chars
  • employment_typestringnullable
    max 50 chars
  • workplace_typeenumnullable
    One ofonsitehybridremote
  • statusenumnullable
    open posts it to the job board, closed takes it down.
    One ofdraftopenclosed
  • hiring_manager_iduuidnullable

Returns 200

  • iduuid
  • created_atdatetime
  • updated_atdatetimenullable
  • titlestring
  • descriptionstringnullable
    HTML: p, h2-h4, strong, em, u, s, a, ul, ol, li, blockquote, code, pre.
  • locationstringnullable
  • employment_typestringnullable
  • workplace_typeenumnullable
    One ofonsitehybridremote
  • statusenum
    draft (not posted), open (on the job board, taking applications) or closed.
    One ofdraftopenclosed
  • hiring_manager_iduuidnullable
    A member of the hiring team (a user id).
  • job_board_urlstringnullable
    The job's page on the job board, where candidates apply; null unless open.

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"
  }'
Response 200
{
  "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"
}