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:
| Kind | What it is | When |
|---|---|---|
interview | An interview booked with the candidate | starts_at to ends_at |
call | A call the team made to them | starts_at, when it was made |
assessment | Work the candidate was set to hand in | due_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:
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:
{
"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:
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']})")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:
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.