Docs

Search the docs

Guides, sections and API endpoints

API reference

Interviews

Interviews, calls and assessments of applications.

List interviews

get/interviews

Needs the applications:read scope

The organization's interviews, calls and assessments, soonest first (an assessment by when it's due). For a calendar, e.g. the week's interviews: kind=interview&starts_after=2026-11-02T00:00:00Z&starts_before=2026-11-09T00:00:00Z. Times are ISO 8601 with a timezone; bounding the start leaves assessments out, as they have none.

Query parameters

  • kindarray of enum
    Only these kinds; repeat for several, e.g. ?kind=interview&kind=call.
    One ofinterviewcallassessment
  • job_iduuid
    Only interviews for this job.
  • candidate_iduuid
    Only this candidate's interviews.
  • application_iduuid
    Only this application's interviews.
  • starts_afterdatetime
    Only those starting at or after this time, with a timezone, e.g. 2026-11-02T00:00:00Z. Leaves out assessments.
  • starts_beforedatetime
    Only those starting before this time, with a timezone. Leaves out assessments.
  • 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
  • application_iduuid
  • job_iduuid
  • candidateobject
    4 child attributes
    • iduuid
    • first_namestring
    • last_namestring
    • emailstringnullable
  • stage_iduuidnullable
    The stage it's for; null once that stage is deleted.
  • kindenum
    One ofinterviewcallassessment
  • starts_atdatetimenullable
    Interviews: when it's scheduled. Calls: when it was made. Null for assessments.
  • ends_atdatetimenullable
    Interviews: when it ends (an hour after it starts when no length was set). Calls: when given a length. Null for assessments.
  • duration_minutesintegernullable
  • locationstringnullable
    Interviews: where, as free text: an address, a meeting link, "Phone".
  • interviewersarray of object
    Who's interviewing, or reviewing the work.
    4 child attributes
    • iduuid
    • first_namestring
    • last_namestring
    • emailstring
  • detailsstringnullable
    Interviews: what the invite tells the candidate. Calls: how it went.
  • due_atdatetimenullable
    Assessments: when the work is due; null for no due date.
  • submitted_atdatetimenullable
    Assessments: when the work was handed in.

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/interviews?kind=interview&starts_after=2026-11-02T00%3A00%3A00Z&starts_before=2026-11-09T00%3A00%3A00Z" \
  -H "Authorization: Bearer $HIREHAPPY_API_KEY"
Response 200
{
  "items": [
    {
      "id": "d5e6f7a8-b9c0-4d1e-8f2a-3b4c5d6e7f80",
      "created_at": "2026-10-26T09:30:00Z",
      "updated_at": "2026-10-27T14:05:00Z",
      "application_id": "e3b1c5d7-9f2a-4b6c-8d0e-1f3a5b7c9d2e",
      "job_id": "7c2e4f1a-9b3d-4e6f-8a1c-2d3e4f5a6b7c",
      "candidate": {
        "id": "c9d8e7f6-5a4b-4c3d-8e2f-1a0b9c8d7e6f",
        "first_name": "Ana",
        "last_name": "Ribeiro",
        "email": "[email protected]"
      },
      "stage_id": "a41f7b2c-3d5e-4f6a-9b8c-1d2e3f4a5b6c",
      "kind": "interview",
      "starts_at": "2026-11-03T10:00:00Z",
      "ends_at": "2026-11-03T10:45:00Z",
      "duration_minutes": 45,
      "location": "https://meet.google.com/abc-defg-hij",
      "interviewers": [
        {
          "id": "9a8b7c6d-5e4f-4a3b-8c2d-1e0f9a8b7c6d",
          "first_name": "Maya",
          "last_name": "Okafor",
          "email": "[email protected]"
        }
      ],
      "details": "We'll talk through a system you've built. Bring questions!",
      "due_at": null,
      "submitted_at": null
    }
  ],
  "total": 1,
  "limit": 50,
  "offset": 0
}

List an application's interviews

get/applications/{application_id}/interviews

Needs the applications:read scope

Every round of the application, the stage it's in now and earlier ones, latest first.

Path parameters

  • application_iduuidRequired

Returns 200

An array of objects like this one, all of them.

  • iduuid
  • created_atdatetime
  • updated_atdatetimenullable
  • application_iduuid
  • job_iduuid
  • candidateobject
    4 child attributes
    • iduuid
    • first_namestring
    • last_namestring
    • emailstringnullable
  • stage_iduuidnullable
    The stage it's for; null once that stage is deleted.
  • kindenum
    One ofinterviewcallassessment
  • starts_atdatetimenullable
    Interviews: when it's scheduled. Calls: when it was made. Null for assessments.
  • ends_atdatetimenullable
    Interviews: when it ends (an hour after it starts when no length was set). Calls: when given a length. Null for assessments.
  • duration_minutesintegernullable
  • locationstringnullable
    Interviews: where, as free text: an address, a meeting link, "Phone".
  • interviewersarray of object
    Who's interviewing, or reviewing the work.
    4 child attributes
    • iduuid
    • first_namestring
    • last_namestring
    • emailstring
  • detailsstringnullable
    Interviews: what the invite tells the candidate. Calls: how it went.
  • due_atdatetimenullable
    Assessments: when the work is due; null for no due date.
  • submitted_atdatetimenullable
    Assessments: when the work was handed in.

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/interviews" \
  -H "Authorization: Bearer $HIREHAPPY_API_KEY"
Response 200
[
  {
    "id": "d5e6f7a8-b9c0-4d1e-8f2a-3b4c5d6e7f80",
    "created_at": "2026-10-26T09:30:00Z",
    "updated_at": "2026-10-27T14:05:00Z",
    "application_id": "e3b1c5d7-9f2a-4b6c-8d0e-1f3a5b7c9d2e",
    "job_id": "7c2e4f1a-9b3d-4e6f-8a1c-2d3e4f5a6b7c",
    "candidate": {
      "id": "c9d8e7f6-5a4b-4c3d-8e2f-1a0b9c8d7e6f",
      "first_name": "Ana",
      "last_name": "Ribeiro",
      "email": "[email protected]"
    },
    "stage_id": "a41f7b2c-3d5e-4f6a-9b8c-1d2e3f4a5b6c",
    "kind": "interview",
    "starts_at": "2026-11-03T10:00:00Z",
    "ends_at": "2026-11-03T10:45:00Z",
    "duration_minutes": 45,
    "location": "https://meet.google.com/abc-defg-hij",
    "interviewers": [
      {
        "id": "9a8b7c6d-5e4f-4a3b-8c2d-1e0f9a8b7c6d",
        "first_name": "Maya",
        "last_name": "Okafor",
        "email": "[email protected]"
      }
    ],
    "details": "We'll talk through a system you've built. Bring questions!",
    "due_at": null,
    "submitted_at": null
  }
]