Scheduling Links

Endpoints for creating, reading, and updating scheduling links.

List Scheduling Links

This endpoint allows you to list your scheduling 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

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

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

Get Scheduling Link

This endpoint allows you to fetch a single scheduling link.

Response

When successful, returns a Scheduling Link resource.

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

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

Create Scheduling Link

This endpoint allows you to create a new scheduling link.

To create the link under personal scope for the authenticated user:

To create the link under a specific team scope:

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	string	The short description visible on the scheduling link.
type	string	Either recurring for “Multi-Use” links, or single for “Single-Use” links. Defaults to recurring.

Example Requests

Here’s an example of how to create a link under the personal scope:

curl https://api.savvycal.com/v1/links \
  -H 'Authorization: Bearer YOUR_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{"name": "My New Link"}'

Here’s an example of how to create a link under a team:

curl https://api.savvycal.com/v1/scopes/acme-inc/links \
  -H 'Authorization: Bearer YOUR_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{"name": "My New Link for Acme, Inc."}'

Response

When successful, returns the Scheduling Link resource.

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

Update Scheduling Link

This endpoint allows you to update a scheduling link.

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	string	The short description visible on the scheduling link.
type	string	Either recurring for “Multi-Use” links, or single for “Single-Use” links. Defaults to recurring.

Response

When successful, returns the newly-updated Scheduling Link resource.

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

Toggle Scheduling Link

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

Response

When successful, returns the Scheduling Link resource.

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

Duplicate Scheduling Link

This endpoint allows you to duplicate a scheduling link.

Response

When successful, returns the newly-duplicated Scheduling Link resource.

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

Delete Scheduling Link

This endpoint allows you to delete a scheduling link.

Response

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.

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

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));