Docs

Search the docs

Guides, sections and API endpoints

API reference

Applications

A candidate's candidacy for one job: its stage, status and AI score.

List applications

get/applications

Needs 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

  • job_iduuid
    Only applications to this job.
  • candidate_iduuid
    Only this candidate's applications.
  • stage_iduuid
    Only applications in this stage of their job.
  • statusarray of enum
    Only applications with these statuses; repeat for several, e.g. ?status=active&status=hired.
    One ofactiverejectedhiredwithdrawn
  • qstring
    Every word must match the candidate's name, email or resume, e.g. react berlin.
  • sortenum
    newest first, or score: best match first, failed knockouts and the unscored last.
    One ofnewestscoreDefault "newest"
  • 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
  • job_iduuid
  • candidate_iduuid
  • candidateobject
    4 child attributes
    • iduuid
    • first_namestring
    • last_namestring
    • emailstringnullable
  • stage_iduuid
    A stage of the job (GET /jobs/{job_id}/job-stages).
  • statusenum
    active (in the pipeline), rejected, hired or withdrawn.
    One ofactiverejectedhiredwithdrawn
  • rejection_reasonstringnullable
    Kept with a rejection; internal, never shown to the candidate.
  • withdrawal_reasonstringnullable
    The candidate's own words on withdrawing, if any.
  • reapplied_atdatetimenullable
    Set when a rejected or withdrawn candidate applied again, until its status next changes.
  • status_urlstringnullable
    The candidate's private status page; null for candidates who didn't apply through the job board.
  • scorecardobjectnullable
    Null until scoring has been asked for (it is, on its own, when the job has a rubric).
    4 child attributes
    • statusenum
      pending while being (re)scored.
      One ofpendingcompletedfailed
    • scoreintegernullable
      0-100 against the job's rubric; null until scored, or when the rubric only has knockouts.
    • knockout_resultenumnullable
      The worst of its knockout criteria: failed, else unclear, else passed; null without any.
      One 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"
Response 200
{
  "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

post/applications

Needs 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_iduuidRequired
  • candidate_iduuidRequired
  • stage_iduuidnullable
    A stage of the job; the first one when left out.

Returns 201

  • iduuid
  • created_atdatetime
  • updated_atdatetimenullable
  • job_iduuid
  • candidate_iduuid
  • candidateobject
    4 child attributes
    • iduuid
    • first_namestring
    • last_namestring
    • emailstringnullable
  • stage_iduuid
    A stage of the job (GET /jobs/{job_id}/job-stages).
  • statusenum
    active (in the pipeline), rejected, hired or withdrawn.
    One ofactiverejectedhiredwithdrawn
  • rejection_reasonstringnullable
    Kept with a rejection; internal, never shown to the candidate.
  • withdrawal_reasonstringnullable
    The candidate's own words on withdrawing, if any.
  • reapplied_atdatetimenullable
    Set when a rejected or withdrawn candidate applied again, until its status next changes.
  • status_urlstringnullable
    The candidate's private status page; null for candidates who didn't apply through the job board.
  • scorecardobjectnullable
    Null until scoring has been asked for (it is, on its own, when the job has a rubric).
    4 child attributes
    • statusenum
      pending while being (re)scored.
      One ofpendingcompletedfailed
    • scoreintegernullable
      0-100 against the job's rubric; null until scored, or when the rubric only has knockouts.
    • knockout_resultenumnullable
      The worst of its knockout criteria: failed, else unclear, else passed; null without any.
      One 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"
  }'
Response 201
{
  "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

get/applications/{application_id}

Needs the applications:read scope

Path parameters

  • application_iduuidRequired

Returns 200

  • iduuid
  • created_atdatetime
  • updated_atdatetimenullable
  • job_iduuid
  • candidate_iduuid
  • candidateobject
    4 child attributes
    • iduuid
    • first_namestring
    • last_namestring
    • emailstringnullable
  • stage_iduuid
    A stage of the job (GET /jobs/{job_id}/job-stages).
  • statusenum
    active (in the pipeline), rejected, hired or withdrawn.
    One ofactiverejectedhiredwithdrawn
  • rejection_reasonstringnullable
    Kept with a rejection; internal, never shown to the candidate.
  • withdrawal_reasonstringnullable
    The candidate's own words on withdrawing, if any.
  • reapplied_atdatetimenullable
    Set when a rejected or withdrawn candidate applied again, until its status next changes.
  • status_urlstringnullable
    The candidate's private status page; null for candidates who didn't apply through the job board.
  • scorecardobjectnullable
    Null until scoring has been asked for (it is, on its own, when the job has a rubric).
    4 child attributes
    • statusenum
      pending while being (re)scored.
      One ofpendingcompletedfailed
    • scoreintegernullable
      0-100 against the job's rubric; null until scored, or when the rubric only has knockouts.
    • knockout_resultenumnullable
      The worst of its knockout criteria: failed, else unclear, else passed; null without any.
      One 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"
Response 200
{
  "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

patch/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

  • stage_iduuidnullable
    Move it to another stage of its job, at the bottom of it. The last stage marks it hired.
  • statusenumnullable
    rejected, hired (moves it to the last stage and starts onboarding) or back to active.
    One ofactiverejectedhiredwithdrawn
  • rejection_reasonstringnullable
    Kept with a rejection; internal, never shown to the candidate.
    max 5,000 chars
  • notify_candidateboolean
    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.
    Default false

Returns 200

  • iduuid
  • created_atdatetime
  • updated_atdatetimenullable
  • job_iduuid
  • candidate_iduuid
  • candidateobject
    4 child attributes
    • iduuid
    • first_namestring
    • last_namestring
    • emailstringnullable
  • stage_iduuid
    A stage of the job (GET /jobs/{job_id}/job-stages).
  • statusenum
    active (in the pipeline), rejected, hired or withdrawn.
    One ofactiverejectedhiredwithdrawn
  • rejection_reasonstringnullable
    Kept with a rejection; internal, never shown to the candidate.
  • withdrawal_reasonstringnullable
    The candidate's own words on withdrawing, if any.
  • reapplied_atdatetimenullable
    Set when a rejected or withdrawn candidate applied again, until its status next changes.
  • status_urlstringnullable
    The candidate's private status page; null for candidates who didn't apply through the job board.
  • scorecardobjectnullable
    Null until scoring has been asked for (it is, on its own, when the job has a rubric).
    4 child attributes
    • statusenum
      pending while being (re)scored.
      One ofpendingcompletedfailed
    • scoreintegernullable
      0-100 against the job's rubric; null until scored, or when the rubric only has knockouts.
    • knockout_resultenumnullable
      The worst of its knockout criteria: failed, else unclear, else passed; null without any.
      One 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"
  }'
Response 200
{
  "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"
  }
}