HAhappyscribe
Calendar connections

Create a calendar connect link

A hosted link that takes one of your users through Google or Microsoft consent and connects their calendar. Put url behind your "Connect calendar" button: create it when your page renders, or from a route of your own behind your login that creates it and redirects. Creating one again for the same member, provider, return_url, client_reference_id and member_data while one is open returns that link, so a page that creates a link on every render adds nothing.

After consent the browser returns to return_url with calendar_connect_link_id, status (connected or error), and member_id, calendar_connection_id, error and client_reference_id when they apply. calendar_connection.connected is sent as well.

Send member_data and the member is created when the user consents, with that name and metadata. Its email is the account the user connects, as the provider verifies it (a Microsoft account's user principal name), and it is never one of the workspace's owners or admins. member_data.email only pre-fills the provider's account chooser. Send member_id instead to reconnect a member you already have: whichever account they approve is connected. A member whose calendar is already connected, through the API or in HappyScribe, must be disconnected first.

post/calendar_connect_links

Request

  • Base URL
    https://www.happyscribe.com/api/v1
  • Auth
    API key in header Authorization

Request body

workspace_idstring required

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

provider'google' | 'microsoft' required

The calendar to connect.

  • google: Google Calendar.
  • microsoft: Microsoft Outlook calendar.
return_urlstring required

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

member_idstring

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_idstring

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

Example request

{
  "workspace_id": "wks_01k6a2r9s8x7c2dvq3m5n6p4ab",
  "member_data": {
    "metadata": {
      "gurusup_user_id": "usr_8812"
    }
  }
}

Response

The link, new or the open one it matched.

idstring

Stable typed ID beginning with ccl_.

objectstring

Always calendar_connect_link.

workspace_idstring

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

member_idstring nullable

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

provider'google' | 'microsoft'

The calendar to connect.

  • google: Google Calendar.
  • microsoft: Microsoft Outlook calendar.
return_urlstring

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

client_reference_idstring nullable

Your own reference, returned on the redirect.

urlstring nullable

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

expires_atstring date-time

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

status'open' | 'completed' | 'failed' | 'expired'
  • 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.
calendar_connection_idstring nullable

The connection it made, once status is completed.

created_atstring date-time

When the link was created, in ISO 8601.

Example response

{
  "workspace_id": "wks_01k6a2r9s8x7c2dvq3m5n6p4ab",
  "member_data": {
    "metadata": {
      "gurusup_user_id": "usr_8812"
    }
  }
}

Changes

No recorded changes to this operation across all 1 revision of this API.