Skip to main content
POST
Plan an appointment for a candidate

Authorizations

x-api-key
string
header
required

API key for authentication. Get your API key from Settings → API Keys in your Spott dashboard.

Body

application/json
candidateId
string
required

Identifier of the candidate the appointment is planned for.

Minimum string length: 1
type
enum<string>
required

Kind of appointment being planned.

Available options:
ONLINE_MEETING,
INTERVIEW,
REGISTRATION
startTime
required

Moment the appointment starts.

Pattern: ^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))T(?:(?:[01]\d|2[0-3]):[0-5]\d(?::[0-5]\d(?:\.\d+)?)?(?:Z))$
Example:

"2026-08-12T08:30:00.000Z"

endTime
required

Moment the appointment ends. Must be after startTime.

Pattern: ^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))T(?:(?:[01]\d|2[0-3]):[0-5]\d(?::[0-5]\d(?:\.\d+)?)?(?:Z))$
Example:

"2026-08-12T09:15:00.000Z"

message
object | null

Subject and body describing the appointment.

location
object | null

Physical location of the appointment. Omit for appointments without location.

applicationId
string | null

Identifier of the application this appointment belongs to. Must be an application of the same candidate.

Minimum string length: 1

Response

The appointment was created. Returns its id.

id
string
required
Minimum string length: 1