Calendar and Bookings

Calendar connections link external calendar providers (Google Calendar, Microsoft Outlook) to a workspace via OAuth. Once connected, oHallo can check availability, create bookings, and manage scheduling on behalf of your team.

Required scope: calendar:read for GET endpoints, calendar:write for write endpoints.

List calendar connections

Retrieve all calendar connections for a workspace.

curl "https://api.ohallo.eu/api/workspaces/a1b2c3d4-e5f6-7890-abcd-ef1234567890/calendar-connections" \
  -H "Authorization: Bearer sf_live_v1_a3Bx9kLmP2qR7wYz4nDfGhJkQpStUvWx"

Response:

{
  "items": [
    {
      "id": "11223344-5566-4788-89aa-bbccddeeff00",
      "workspaceId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
      "provider": "google",
      "displayName": "Sales Team Calendar",
      "calendarId": "sales@nordic-parts.dk",
      "enabled": true,
      "bookingConfig": {
        "workingHours": {
          "monday": { "start": "09:00", "end": "17:00" },
          "tuesday": { "start": "09:00", "end": "17:00" },
          "wednesday": { "start": "09:00", "end": "17:00" },
          "thursday": { "start": "09:00", "end": "17:00" },
          "friday": { "start": "09:00", "end": "16:00" }
        },
        "bufferMinutes": 15,
        "timezone": "Europe/Copenhagen",
        "blockedDates": ["2026-12-24", "2026-12-25", "2026-12-31"]
      },
      "createdAt": "2026-03-10T08:00:00.000Z",
      "updatedAt": "2026-03-12T14:20:00.000Z"
    }
  ],
  "total": 1
}

Get calendar connection

Retrieve a single calendar connection by its identifier.

curl "https://api.ohallo.eu/api/calendar-connections/11223344-5566-4788-89aa-bbccddeeff00" \
  -H "Authorization: Bearer sf_live_v1_a3Bx9kLmP2qR7wYz4nDfGhJkQpStUvWx"

Response:

{
  "id": "11223344-5566-4788-89aa-bbccddeeff00",
  "workspaceId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "provider": "google",
  "displayName": "Sales Team Calendar",
  "calendarId": "sales@nordic-parts.dk",
  "enabled": true,
  "bookingConfig": {
    "workingHours": {
      "monday": { "start": "09:00", "end": "17:00" },
      "tuesday": { "start": "09:00", "end": "17:00" },
      "wednesday": { "start": "09:00", "end": "17:00" },
      "thursday": { "start": "09:00", "end": "17:00" },
      "friday": { "start": "09:00", "end": "16:00" }
    },
    "bufferMinutes": 15,
    "timezone": "Europe/Copenhagen",
    "blockedDates": ["2026-12-24", "2026-12-25", "2026-12-31"]
  },
  "createdAt": "2026-03-10T08:00:00.000Z",
  "updatedAt": "2026-03-12T14:20:00.000Z"
}

Update calendar connection

Update an existing calendar connection. Only the fields you include in the request body are changed.

Required scope: calendar:write

curl -X PATCH "https://api.ohallo.eu/api/calendar-connections/11223344-5566-4788-89aa-bbccddeeff00" \
  -H "Authorization: Bearer sf_live_v1_a3Bx9kLmP2qR7wYz4nDfGhJkQpStUvWx" \
  -H "Content-Type: application/json" \
  -d '{
    "displayName": "Sales and Support Calendar",
    "bookingConfig": {
      "workingHours": {
        "monday": { "start": "08:00", "end": "17:00" },
        "tuesday": { "start": "08:00", "end": "17:00" },
        "wednesday": { "start": "08:00", "end": "17:00" },
        "thursday": { "start": "08:00", "end": "17:00" },
        "friday": { "start": "08:00", "end": "15:00" }
      },
      "bufferMinutes": 10,
      "timezone": "Europe/Copenhagen",
      "blockedDates": ["2026-12-24", "2026-12-25", "2026-12-31", "2027-01-01"]
    }
  }'

Request body:

Field	Type	Required	Description
displayName	string	No	Human-readable name for the connection
calendarId	string or null	No	Calendar identifier from the provider. Set to null to unlink the selected calendar.
bookingConfig	object	No	Scheduling configuration (see fields below)
bookingConfig.workingHours	object	No	Per-day start and end times in HH:mm format
bookingConfig.bufferMinutes	integer	No	Minimum buffer between consecutive bookings (minimum 0)
bookingConfig.timezone	string	No	IANA timezone identifier for interpreting working hours
bookingConfig.blockedDates	string[]	No	Dates in YYYY-MM-DD format when no bookings are accepted
enabled	boolean	No	Whether the connection is active

Response: Returns the full updated calendar connection.

Delete calendar connection

Permanently delete a calendar connection and remove the stored OAuth credentials.

Required scope: calendar:write

curl -X DELETE "https://api.ohallo.eu/api/calendar-connections/11223344-5566-4788-89aa-bbccddeeff00" \
  -H "Authorization: Bearer sf_live_v1_a3Bx9kLmP2qR7wYz4nDfGhJkQpStUvWx"

Response: 204 No Content on success.

List available calendars

After a calendar connection has been authorised via OAuth, this endpoint returns the calendars available on the connected account. Use the returned identifiers to set the calendarId field on the connection.

curl "https://api.ohallo.eu/api/calendar-connections/11223344-5566-4788-89aa-bbccddeeff00/calendars" \
  -H "Authorization: Bearer sf_live_v1_a3Bx9kLmP2qR7wYz4nDfGhJkQpStUvWx"

Response:

{
  "items": [
    {
      "calendarId": "sales@nordic-parts.dk",
      "name": "Sales Team",
      "primary": false
    },
    {
      "calendarId": "support@nordic-parts.dk",
      "name": "Support Team",
      "primary": false
    },
    {
      "calendarId": "erik@nordic-parts.dk",
      "name": "Erik Andersen",
      "primary": true
    }
  ]
}

Start OAuth flow

Initiate the OAuth authorisation flow for a calendar provider.

Caution

Dashboard-only. This endpoint returns a provider redirect URL that must be followed by a browser to complete the consent screen at Google or Microsoft. It is currently accessible only via a dashboard session (Kinde JWT); programmatic API-key access is intentionally disabled because a headless integration cannot follow the redirect. Use the dashboard at https://app.ohallo.eu/settings/calendar to connect a new calendar.

List bookings

Retrieve bookings for a specific calendar connection.

curl "https://api.ohallo.eu/api/workspaces/a1b2c3d4-e5f6-7890-abcd-ef1234567890/bookings?calendarConnectionId=cal_11223344-5566-7788-99aa-bbccddeeff00" \
  -H "Authorization: Bearer sf_live_v1_a3Bx9kLmP2qR7wYz4nDfGhJkQpStUvWx"

Query parameters:

Parameter	Type	Required	Description
calendarConnectionId	UUID	Yes	Filter bookings by calendar connection

Response:

{
  "items": [
    {
      "id": "aabbccdd-eeff-4011-2233-445566778899",
      "calendarConnectionId": "11223344-5566-4788-89aa-bbccddeeff00",
      "conversationId": "c9f8e7d6-b5a4-3210-fedc-ba9876543210",
      "contactId": "f7e8d9c0-b1a2-3456-7890-abcdef123456",
      "contactName": "Henrik Larsen",
      "contactEmail": "henrik@nordic-parts.dk",
      "title": "Product demo -- Nordic Parts",
      "startTime": "2026-03-20T10:00:00.000Z",
      "endTime": "2026-03-20T10:30:00.000Z",
      "timezone": "Europe/Copenhagen",
      "status": "confirmed",
      "createdAt": "2026-03-15T14:00:00.000Z"
    }
  ],
  "total": 1
}