# Interviews

> Interviews, calls and assessments of applications. Part of the HireHappy API reference (https://hirehappy.io/docs/api).

Base URL: `https://api.hirehappy.io/v1`. Authenticate with `Authorization: Bearer <API key>`.

### List interviews

`GET https://api.hirehappy.io/v1/interviews`

Scope: `applications:read`

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**

| Name | Type | Description |
| --- | --- | --- |
| `kind` | array of enum | Only these kinds; repeat for several, e.g. ?kind=interview&kind=call. one of `interview`, `call`, `assessment` |
| `job_id` | uuid | Only interviews for this job. |
| `candidate_id` | uuid | Only this candidate's interviews. |
| `application_id` | uuid | Only this application's interviews. |
| `starts_after` | datetime | Only those starting at or after this time, with a timezone, e.g. 2026-11-02T00:00:00Z. Leaves out assessments. |
| `starts_before` | datetime | Only those starting before this time, with a timezone. Leaves out assessments. |
| `limit` | integer | How many to return. min 1, max 100, default `50` |
| `offset` | integer | How many to skip. See [Pagination](https://hirehappy.io/docs/pagination). default `0` |

**Example request**

```bash
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` (a page: `items`, `total`, `limit`, `offset`)

| Name | Type | Description |
| --- | --- | --- |
| `id` | uuid |  |
| `created_at` | datetime |  |
| `updated_at` | datetime | nullable |
| `application_id` | uuid |  |
| `job_id` | uuid |  |
| `candidate` | object |  |
| `candidate.id` | uuid |  |
| `candidate.first_name` | string |  |
| `candidate.last_name` | string |  |
| `candidate.email` | string | nullable |
| `stage_id` | uuid | The stage it's for; null once that stage is deleted. nullable |
| `kind` | enum | one of `interview`, `call`, `assessment` |
| `starts_at` | datetime | Interviews: when it's scheduled. Calls: when it was made. Null for assessments. nullable |
| `ends_at` | datetime | Interviews: when it ends (an hour after it starts when no length was set). Calls: when given a length. Null for assessments. nullable |
| `duration_minutes` | integer | nullable |
| `location` | string | Interviews: where, as free text: an address, a meeting link, "Phone". nullable |
| `interviewers` | array of object | Who's interviewing, or reviewing the work. |
| `interviewers.id` | uuid |  |
| `interviewers.first_name` | string |  |
| `interviewers.last_name` | string |  |
| `interviewers.email` | string |  |
| `details` | string | Interviews: what the invite tells the candidate. Calls: how it went. nullable |
| `due_at` | datetime | Assessments: when the work is due; null for no due date. nullable |
| `submitted_at` | datetime | Assessments: when the work was handed in. nullable |

```json
{
  "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": "ana.ribeiro@example.com"
      },
      "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": "maya@acme.com"
        }
      ],
      "details": "We'll talk through a system you've built. Bring questions!",
      "due_at": null,
      "submitted_at": null
    }
  ],
  "total": 1,
  "limit": 50,
  "offset": 0
}
```

**Errors**: `401` the key is wrong, expired or revoked (api_key_required when missing); `403` the key isn't allowed applications:read; `422` a parameter or field doesn't validate.

### List an application's interviews

`GET https://api.hirehappy.io/v1/applications/{application_id}/interviews`

Scope: `applications:read`

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

**Path parameters**

| Name | Type | Description |
| --- | --- | --- |
| `application_id` | uuid | required |

**Example request**

```bash
curl "https://api.hirehappy.io/v1/applications/e3b1c5d7-9f2a-4b6c-8d0e-1f3a5b7c9d2e/interviews" \
  -H "Authorization: Bearer $HIREHAPPY_API_KEY"
```

**Response** `200` (an array)

| Name | Type | Description |
| --- | --- | --- |
| `id` | uuid |  |
| `created_at` | datetime |  |
| `updated_at` | datetime | nullable |
| `application_id` | uuid |  |
| `job_id` | uuid |  |
| `candidate` | object |  |
| `candidate.id` | uuid |  |
| `candidate.first_name` | string |  |
| `candidate.last_name` | string |  |
| `candidate.email` | string | nullable |
| `stage_id` | uuid | The stage it's for; null once that stage is deleted. nullable |
| `kind` | enum | one of `interview`, `call`, `assessment` |
| `starts_at` | datetime | Interviews: when it's scheduled. Calls: when it was made. Null for assessments. nullable |
| `ends_at` | datetime | Interviews: when it ends (an hour after it starts when no length was set). Calls: when given a length. Null for assessments. nullable |
| `duration_minutes` | integer | nullable |
| `location` | string | Interviews: where, as free text: an address, a meeting link, "Phone". nullable |
| `interviewers` | array of object | Who's interviewing, or reviewing the work. |
| `interviewers.id` | uuid |  |
| `interviewers.first_name` | string |  |
| `interviewers.last_name` | string |  |
| `interviewers.email` | string |  |
| `details` | string | Interviews: what the invite tells the candidate. Calls: how it went. nullable |
| `due_at` | datetime | Assessments: when the work is due; null for no due date. nullable |
| `submitted_at` | datetime | Assessments: when the work was handed in. nullable |

```json
[
  {
    "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": "ana.ribeiro@example.com"
    },
    "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": "maya@acme.com"
      }
    ],
    "details": "We'll talk through a system you've built. Bring questions!",
    "due_at": null,
    "submitted_at": null
  }
]
```

**Errors**: `401` the key is wrong, expired or revoked (api_key_required when missing); `403` the key isn't allowed applications:read; `404` it isn't there, or belongs to another organization; `422` a parameter or field doesn't validate.
