Skip to main content
GET
List appointments of 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.

Query Parameters

candidateId
string
required

Identifier of the candidate whose appointments should be returned.

Minimum string length: 1
limit
integer
default:25

Number of appointments to return per page (min: 1, max: 50, default: 25).

Required range: 1 <= x <= 50
Example:

25

cursor
string

Opaque cursor string for pagination. Use the cursor value from a previous response to fetch the next page. Omit for the first page.

startTimeSince

Only return appointments starting on or after this moment. Pass the current time to receive upcoming appointments only. If omitted, no lower bound is applied.

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-01T00:00:00.000Z"

startTimeUntil

Only return appointments starting on or before this moment. If omitted, no upper bound is applied.

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-31T23:59:59.999Z"

Response

The appointments of the candidate, with pagination metadata.

items
object[]
required
pagination
object
required