# 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](https://hirehappy.io/docs/api/interviews#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:

```bash
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": "ana.ribeiro@example.com"
  },
  "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": "maya@acme.com"
    }
  ]
}
```

`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](https://hirehappy.io/docs/api/organizations#get-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](https://hirehappy.io/docs/pagination).

## Assessments that are due

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

```bash
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](https://hirehappy.io/docs/api/interviews#list-application-interviews)): every round, latest first.
