SavvyCal API
Endpoints
Resources
Webhooks
SavvyCal API
Home

Scheduling Links

Endpoints for creating, reading, and updating scheduling links.

This endpoint allows you to list your scheduling links.

GET
/v1/links

Parameters

Name Type Description
before string A pagination cursor for entries before a specific point in the collection.
after string A pagination cursor for entries after a specific point in the collection.
limit integer The maximum number of entries to retrieve (defaults to 20, up to 100 allowed).

Response

200
OK

When successful, returns a Paginated List of Scheduling Link resources.

{
"entries": [
// items
],
"metadata": {
"before": nil,
"after": "g3QAAAABZAACaWRiAAAbFA==",
"limit": 20
}
}

This endpoint allows you to fetch a single scheduling link.

GET
/v1/links/:link_id

Response

200
OK

When successful, returns a Scheduling Link resource.

{
"id": "link_01ED74HMFGVZ92YVCWTD8Y8H6X",
// ...
}
404
Not Found

It the link does not exist or is not accessible, returns a not found response.

This endpoint allows you to create a new scheduling link.

POST
/v1/links

Parameters

Name Type Description
name string The name of the scheduling link.
private_name string The private name of the link (not visible to schedulers).
description integer The short description visible on the scheduling link.

Response

201
Created

When successful, returns the Scheduling Link resource.

{
"id": "link_01ED74HMFGVZ92YVCWTD8Y8H6X",
// ...
}

This endpoint allows you to toggle the active/disabled state of a scheduling link.

POST
/v1/links/:link_id/toggle

Response

200
OK

When successful, returns the Scheduling Link resource.

{
"id": "link_01ED74HMFGVZ92YVCWTD8Y8H6X",
// ...
}

This endpoint allows you to delete a scheduling link.

DELETE
/v1/links/:link_id

Response

200
OK

When successful, returns the Scheduling Link resource.

{
"id": "link_01ED74HMFGVZ92YVCWTD8Y8H6X",
// ...
}

List Available Slots

This endpoint allows you to list your available slots on a scheduling link.

GET
/v1/links/:link_id/slots

Parameters

Name Type Description
from string The lower-bound date/time (in ISO-8601 format). Defaults to now.
until string The upper-bound date/time (in ISO-8601 format). Defaults to 7 days from now.

Response

200
OK

When successful, returns a list of Slot resources.

[
{
start_at: "2021-06-01T00:00:00Z",
end_at: "2021-06-01T00:30:00Z",
duration: 30,
rank: 1
}
]

If the link organizer has configured multiple durations, we’ll return all possible time slots for each duration. For example, if the organizer allows schedulers to book either 30 or 60 minutes, then you may see slots that start at the same time (or overlap) with different durations:

[
{
start_at: "2021-06-01T00:00:00Z",
end_at: "2021-06-01T00:30:00Z",
duration: 30,
rank: 1
},
{
start_at: "2021-06-01T00:00:00Z",
end_at: "2021-06-01T01:00:00Z",
duration: 60,
rank: 1
}
]

If the organizer is using ranked availability, then the response may include slots with different rank values:

[
// A slot with "first" preference
{
start_at: "2021-06-01T00:00:00Z",
end_at: "2021-06-01T00:30:00Z",
duration: 30,
rank: 1
},
// A slot with "second" preference
{
start_at: "2021-06-01T03:00:00Z",
end_at: "2021-06-01T03:30:00Z",
duration: 60,
rank: 2
}
]

Slots with rank 1 are those the organizer prefers the most. Slots with rank 2 (and higher) will include all the slot times from lower ranks, plus additional times available in that rank. This means if you want to get the “expanded” availability (e.g. up to rank 2), you simply need to filter the list for slots where rank === 2 (not where rank === 1 || rank === 2).

Here’s some JavaScript pseudo-code to demonstrate:

const slots = await fetchSlots();

// Includes just the rank 1 times
const preferredAvailability = slots.filter(({ rank } => rank === 1));

// Includes all rank 1 AND rank 2 times
const expandedAvailability = slots.filter(({ rank } => rank === 2));

// Includes all rank 1, rank 2 and rank 3 times
const moreExpandedAvailability = slots.filter(({ rank } => rank === 3));