## Schedule an interview of an open application (managers of the posting)

`POST /api/hr/v1/recruiting/applications/{id}/interviews`

Module: HR · operationId: `scheduleInterview` · Tag: Recruiting · Auth: access token (`Authorization: Bearer <accessToken>`)

With `notify` the applicant gets an invitation from the recruiting mailbox with a link to confirm or decline (valid until a week after the appointment).

### Parameters

| Name | In | Type | Required | Description |
|---|---|---|---|---|
| `id` | path | string (uuid) | yes |  |

### Request body

`application/json` (required)

- `startsAt` (string (date-time), required): Start of the interview
- `attendees` (array of string (uuid)): Employees taking part
- `durationMin` (integer): Length in minutes (default `60`; max 600)
- `location` (string): Address for on-site interviews (max length 500)
- `message` (string): Added to the invitation (max length 5000)
- `mode` (string): How the interview takes place (one of `onsite`, `video`, `phone`; default `"onsite"`)
- `notify` (boolean): Mail the applicant
- `version` (integer): Version of the interview a change is based on (ignored when scheduling)
- `videoUrl` (string): https link (required for video)

Example:

```json
{
  "attendees": [
    "9b1d3f5a-7c9e-4b1d-8f3a-5c7e9b1d3f2e",
    "f2a4c6e8-0b2d-4f4a-8c6e-8a0c2e4b6d1c"
  ],
  "durationMin": 90,
  "location": "Muster IT-Systemhaus GmbH, Industriestraße 12, 93055 Regensburg, Besprechungsraum 2",
  "message": "Fachgespräch mit der Technik, anschließend ein kurzer Rundgang durch das Büro.",
  "mode": "onsite",
  "notify": true,
  "startsAt": "2026-11-24T09:00:00Z"
}
```

### Responses

- **201** Scheduled (`application/json`)
- **400** Error (`application/json`)
- **403** Error (`application/json`)
- **404** Error (`application/json`)
- **409** Error (`application/json`)

Fields of the 201 answer:

- `applicantName` (string): Only in listMyInterviews
- `applicationId` (string (uuid)): Id of the application
- `attendees` (array of string (uuid)): Employee ids of the interviewers
- `createdAt` (string (date-time)): When the interview was created
- `durationMin` (integer): Length in minutes
- `id` (string (uuid)): Id of the interview
- `location` (string): Address for on-site interviews
- `message` (string): Message to the applicant in the invitation
- `mode` (string): How the interview takes place (one of `onsite`, `video`, `phone`)
- `postingTitle` (string): Only in listMyInterviews
- `respondedAt` (string (date-time)): When the applicant answered
- `responseNote` (string): The applicant's note with their answer
- `startsAt` (string (date-time)): Start of the interview
- `state` (string): The applicant's answer or the cancellation (one of `invited`, `confirmed`, `declined`, `cancelled`)
- `updatedAt` (string (date-time)): When the interview was last changed
- `version` (integer): Version for optimistic locking: send the version you read with a change (stale: 409 version_conflict)
- `videoUrl` (string): Link of a video interview

Example 201 answer:

```json
{
  "applicationId": "1c3e5a7c-9e1a-4c3e-9a5c-9e1a3c5e7a89",
  "attendees": [
    "9b1d3f5a-7c9e-4b1d-8f3a-5c7e9b1d3f2e",
    "f2a4c6e8-0b2d-4f4a-8c6e-8a0c2e4b6d1c"
  ],
  "createdAt": "2026-11-12T10:34:00Z",
  "durationMin": 90,
  "id": "5a7c9e1a-3c5e-4a7c-9e1a-3c5e7a9c1e98",
  "location": "Muster IT-Systemhaus GmbH, Industriestraße 12, 93055 Regensburg, Besprechungsraum 2",
  "message": "Fachgespräch mit der Technik, anschließend ein kurzer Rundgang durch das Büro.",
  "mode": "onsite",
  "respondedAt": "2026-11-12T20:15:00Z",
  "startsAt": "2026-11-24T09:00:00Z",
  "state": "confirmed",
  "updatedAt": "2026-11-12T20:15:00Z",
  "version": 2
}
```

### Example request

```bash
curl -X POST 'https://api.mbcom.cloud/api/hr/v1/recruiting/applications/3f2b8c1e-7d4a-4e9b-9c2a-5b1d6e8f0a12/interviews' \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H 'Content-Type: application/json' \
  --data '{"attendees":["9b1d3f5a-7c9e-4b1d-8f3a-5c7e9b1d3f2e","f2a4c6e8-0b2d-4f4a-8c6e-8a0c2e4b6d1c"],"durationMin":90,"location":"Muster IT-Systemhaus GmbH, Industriestraße 12, 93055 Regensburg, Besprechungsraum 2","message":"Fachgespräch mit der Technik, anschließend ein kurzer Rundgang durch das Büro.","mode":"onsite","notify":true,"startsAt":"2026-11-24T09:00:00Z"}'
```
