Skip to main content
POST
Create a calendar connect link

Authorizations

Authorization
string
header
required

Your API key, sent bare. See Authentication.

Body

application/json
workspace_id
string
required

Workspace ID, beginning with wks_. Treat it as an opaque string. Integer workspace ids are still accepted.

Example:

"wks_01k6a2r9s8x7c2dvq3m5n6p4ab"

provider
enum<string>
required

The calendar to connect.

  • google: Google Calendar.
  • microsoft: Microsoft Outlook calendar.
Available options:
google,
microsoft
return_url
string
required

An absolute https URL. The browser returns here after consent, with the outcome in the query string.

Maximum string length: 2048
member_data
object

The member to create when the user consents. Nothing is created until then.

member_id
string

An existing member to reconnect, or one you created with POST /members. Whichever account they approve is connected. Not with member_data; send neither to create the member from the connected account with no name or metadata.

client_reference_id
string

Your own id for the user, echoed on return_url and the link.

Maximum string length: 255

Response

The link, new or the open one it matched.

id
string

Stable typed ID beginning with ccl_.

object
string

Always calendar_connect_link.

workspace_id
string

Workspace ID, beginning with wks_. Treat it as an opaque string.

Example:

"wks_01k6a2r9s8x7c2dvq3m5n6p4ab"

member_id
string | null

The member connecting, or null to create the member from the connected account.

provider
enum<string>

The calendar to connect.

  • google: Google Calendar.
  • microsoft: Microsoft Outlook calendar.
Available options:
google,
microsoft
return_url
string

Where the browser returns after consent, with the outcome in the query string.

client_reference_id
string | null

Your own reference, returned on the redirect.

member_data
object | null

The member the consent creates, as you sent it (metadata is {} when you sent none), or null.

url
string | null

The link to send the user to. null once it can no longer be opened.

expires_at
string<date-time>

When the link stops working, 24 hours after it was created.

status
enum<string>
  • open: waiting for the user, including after they declined consent.
  • completed: the user connected their calendar; see calendar_connection_id.
  • failed: it could not connect; error says why.
  • expired: 24 hours went by.
Available options:
open,
completed,
failed,
expired
calendar_connection_id
string | null

The connection it made, once status is completed.

error
object | null

Why the link failed, or null.

created_at
string<date-time>

When the link was created, in ISO 8601.