ConnectCloud Developers

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:

{
  "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:

{
  "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

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"}'

View as Markdown · Interactive reference · OpenAPI