Docs

Search the docs

Guides, sections and API endpoints

Guides

Show an interview calendar

Put the week's interviews on a dashboard, a meeting-room screen or a team channel, with who's interviewing whom and where.

Every interview, call and assessment in HireHappy is on List interviews: across all your jobs, soonest first. This guide builds a week's calendar from it: for a dashboard, a screen by the meeting rooms, or a Monday post in your team's chat.

You'll need a key with applications:read.

Interviews, calls and assessments

Each has a kind:

KindWhat it isWhen
interviewAn interview booked with the candidatestarts_at to ends_at
callA call the team made to themstarts_at, when it was made
assessmentWork the candidate was set to hand indue_at, then submitted_at

An application has one per stage: rescheduling an interview changes it, and cancelling one deletes it.

The week's interviews

Ask for interviews starting within the week. Times go in with a timezone and come out in UTC:

Shell
curl "https://api.hirehappy.io/v1/interviews?kind=interview&starts_after=2026-11-02T00:00:00Z&starts_before=2026-11-09T00:00:00Z" \
  -H "Authorization: Bearer $HIREHAPPY_API_KEY"

Each one names the candidate and the interviewers, so there's nothing else to look up:

JSON
{
  "id": "d5e6f7a8-b9c0-4d1e-8f2a-3b4c5d6e7f80",
  "application_id": "e3b1c5d7-9f2a-4b6c-8d0e-1f3a5b7c9d2e",
  "job_id": "7c2e4f1a-9b3d-4e6f-8a1c-2d3e4f5a6b7c",
  "candidate": {
    "id": "c9d8e7f6-…",
    "first_name": "Ana",
    "last_name": "Ribeiro",
    "email": "[email protected]"
  },
  "kind": "interview",
  "starts_at": "2026-11-03T10:00:00Z",
  "ends_at": "2026-11-03T10:45:00Z",
  "location": "https://meet.google.com/abc-defg-hij",
  "interviewers": [
    {
      "id": "9a8b7c6d-…",
      "first_name": "Maya",
      "last_name": "Okafor",
      "email": "[email protected]"
    }
  ]
}

location is free text: a meeting link, an address, or "Phone".

Days in your timezone

The API speaks UTC; your team doesn't. Take the organization's timezone from Retrieve your organization and group the week by local day:

Python
import os
from collections import defaultdict
from datetime import datetime, timedelta
from zoneinfo import ZoneInfo
import httpx

client = httpx.Client(
    base_url="https://api.hirehappy.io/v1",
    headers={"Authorization": f"Bearer {os.environ['HIREHAPPY_API_KEY']}"},
)

tz = ZoneInfo(client.get("/organizations/self").raise_for_status().json()["timezone"])
today = datetime.now(tz).replace(hour=0, minute=0, second=0, microsecond=0)
monday = today - timedelta(days=today.weekday())

interviews = client.get("/interviews", params={
    "kind": "interview",
    "starts_after": monday.isoformat(),
    "starts_before": (monday + timedelta(days=7)).isoformat(),
    "limit": 100,
}).raise_for_status().json()["items"]

days = defaultdict(list)
for interview in interviews:
    starts = datetime.fromisoformat(interview["starts_at"]).astimezone(tz)
    days[starts.date()].append((starts, interview))

for day, entries in sorted(days.items()):
    print(day.strftime("%A %-d %B"))
    for starts, interview in entries:
        candidate = interview["candidate"]
        with_ = ", ".join(i["first_name"] for i in interview["interviewers"])
        print(f"  {starts:%H:%M}  {candidate['first_name']} {candidate['last_name']} with {with_}  ({interview['location']})")
Text
Tuesday 3 November
  11:00  Ana Ribeiro with Maya  (https://meet.google.com/abc-defg-hij)

A week with more than 100 interviews needs more than one page; see Pagination.

Assessments that are due

Assessments have no start time, so leave out the time filters and check due_at and submitted_at yourself:

Shell
curl "https://api.hirehappy.io/v1/interviews?kind=assessment&limit=100" \
  -H "Authorization: Bearer $HIREHAPPY_API_KEY"

Those with submitted_at set are in, waiting for review by their interviewers. Those without are outstanding, and overdue once due_at has passed.

One candidate's rounds

For everything one application has been through, ask the application itself (List an application's interviews): every round, latest first.