Introduction

Welcome to the KalendMe's API! You can use our API endpoints to build your next platform and skip all scheduling headaches with a simple to use integration.

You can view code examples in the dark area to the right.

Authentication

# With shell, you can just pass the correct header with each request
curl "https://www.kalendme.com/api/v1/users" \
  -H "Authorization: Bearer abcdef123456"

KalendMe uses API keys to allow access to the API. You can get an API key by creating a free account and then heading over to settings to create an Organization.

KalendMe expects for the API key to be included in all API requests to the server in a header that looks like the following:

Authorization: Bearer abcdef123456

You must replace abcdef123456 with your API key.

Users

User Resource

{
  "user": {
    "id": "123213232",
    "createdAt": "2020-09-01T00:00:00.000Z",
    "updatedAt": "2020-09-01T00:00:00.000Z",
    "name": "Jim Halpert",
    "email": "jim@dundermifflin.com",
    "urlString": "jim-123456",
    "timeZone": "America/New_York",
    "status": "ACTIVE",
    "weekAvailability": {
      "0": [{ "start": "00:00", "end": "00:00" }],
      "1": [{ "start": "08:00", "end": "18:00" }],
      "2": [{ "start": "08:00", "end": "18:00" }],
      "3": [{ "start": "08:00", "end": "18:00" }],
      "4": [{ "start": "08:00", "end": "18:00" }],
      "5": [{ "start": "08:00", "end": "18:00" }],
      "6": [{ "start": "08:00", "end": "18:00" }]
    }
  }
}

Users are all users under your organization. Users are formed by the following fields.

Parameter	Type	Description
id	string	The resource's id
createdAt	timestamp	The resource's creation timesstamp
updatedAt	timestamp	The resource's last updated timestamp
email	string	The email of the user. Must be a valid email address.
name	string	The name of the user
language	string	The language of the user. We currently support only `en` (english), `es` (spanish) and `pt` (portuguese).
urlString	string	A globally unique URL for the user. Used for their bookings page such as kalendme.com/`john-123`. If none is specified, a random one will be generated on user creation.
timeZone	string	The time zone of the user. Must be a valid IANA time zone name such as `America/New_York`.
status	string	The status of the user. Can only be: `ACTIVE` or `INVITED`. Note that invited users do not affect your bill until they accept to join your organization.
weekAvailability	WeekAvailability	An object containing the user's week availability from Sunday [0] through Saturday [7] and each day's availability slots with a `start` and `end` times.

Create a User

curl "https://www.kalendme.com/api/v1/users?sendInvitationEmail=true" \
  -X POST
  -H "Authorization: Bearer abcdef123456"
  -H "Content-Type: application/json"
  -d '{
    "name": "Jim Halpert",
    "email": "jim@dundermifflin.com",
    "language": "en",
    "timeZone": "America/New_York"
  }'

{
  "user": {
    "id": "123213232",
    "createdAt": "2020-09-01T00:00:00.000Z",
    "updatedAt": "2020-09-01T00:00:00.000Z",
    "name": "Jim Halpert",
    "email": "jim@dundermifflin.com",
    "urlString": "jim-123456",
    "timeZone": "America/New_York",
    "weekAvailability": {
      "0": [{ "start": "00:00", "end": "00:00" }],
      "1": [{ "start": "08:00", "end": "18:00" }],
      "2": [{ "start": "08:00", "end": "18:00" }],
      "3": [{ "start": "08:00", "end": "18:00" }],
      "4": [{ "start": "08:00", "end": "18:00" }],
      "5": [{ "start": "08:00", "end": "18:00" }],
      "6": [{ "start": "08:00", "end": "18:00" }]
    }
  }
}

This endpoint creates a new user under your organization.

HTTP Request

POST https://www.kalendme.com/api/v1/users

Body Parameters

Parameter	Type	Required	Description
email	string	Required	The email of the user. Must be a valid email address.
name	string	Optional	The name of the user
language	string	Required	The language of the user. We currently support only `en` (english), `es` (spanish) and `pt` (portuguese).
urlString	string	Optional	A globally unique URL for the user. Used for their bookings page such as kalendme.com/`john-123`. If none is specified, a random one will be generated on user creation.
timeZone	string	Required	The time zone of the user. Must be a valid IANA time zone name such as `America/New_York`.
weekAvailability	WeekAvailability	Optional	An object containing the user's week availability from Sunday [0] through Saturday [7] and each day's availability slots with a `start` and `end` times.

URL Parameters

Parameter	Type	Description
sendInvitationEmail	boolean	Send the newly created user an invitation email on behalf of your organization to join your organization and configure their account.
activateOnCreate	boolean	Activate the newly created user on behalf of your organization. If not specified, the user will be created in an `INVITED` state and will not affect your bill until they accept to join your organization.
inviteOnConflict	boolean	If a user with the same email already exists, send them an invitation email on behalf of your organization to join your organization and configure their account. If not specified, the request will fail with a `409 Conflict` error.

Get All Users

curl "https://www.kalendme.com/api/v1/users" \
  -H "Authorization: Bearer abcdef123456"

{
  "users": [
    {
      "id": "123213233",
      "createdAt": "2020-09-01T00:00:00.000Z",
      "updatedAt": "2020-09-01T00:00:00.000Z",
      "name": "Michael Scott",
      "email": "michael@dundermifflin.com",
      "urlString": "michael-scott",
      "timeZone": "America/New_York",
      "weekAvailability": {
        "0": [{ "start": "00:00", "end": "00:00" }],
        "1": [{ "start": "08:00", "end": "18:00" }],
        "2": [{ "start": "08:00", "end": "18:00" }],
        "3": [{ "start": "08:00", "end": "18:00" }],
        "4": [{ "start": "08:00", "end": "18:00" }],
        "5": [{ "start": "08:00", "end": "18:00" }],
        "6": [{ "start": "08:00", "end": "18:00" }]
      }
    },
    {
      "id": "123213232",
      "createdAt": "2020-09-01T00:00:00.000Z",
      "updatedAt": "2020-09-01T00:00:00.000Z",
      "name": "Pam Beesly",
      "email": "pam@dundermifflin.com",
      "urlString": "pam-beesly",
      "timeZone": "America/New_York",
      "weekAvailability": {
        "0": [{ "start": "00:00", "end": "00:00" }],
        "1": [{ "start": "08:00", "end": "18:00" }],
        "2": [{ "start": "08:00", "end": "18:00" }],
        "3": [{ "start": "08:00", "end": "18:00" }],
        "4": [{ "start": "08:00", "end": "18:00" }],
        "5": [{ "start": "08:00", "end": "18:00" }],
        "6": [{ "start": "08:00", "end": "18:00" }]
      }
    }
  ]
}

This endpoint retrieves all users.

HTTP Request

GET https://www.kalendme.com/api/v1/users

Get a Specific User

curl "https://www.kalendme.com/api/v1/users/123213232" \
  -H "Authorization: Bearer abcdef123456"

{
  "user": {
    "id": "123213232",
    "createdAt": "2020-09-01T00:00:00.000Z",
    "updatedAt": "2020-09-01T00:00:00.000Z",
    "name": "Pam Beesly",
    "email": "pam@dundermifflin.com",
    "urlString": "pam-beesly",
    "timeZone": "America/New_York",
    "weekAvailability": {
      "0": [{ "start": "00:00", "end": "00:00" }],
      "1": [{ "start": "08:00", "end": "18:00" }],
      "2": [{ "start": "08:00", "end": "18:00" }],
      "3": [{ "start": "08:00", "end": "18:00" }],
      "4": [{ "start": "08:00", "end": "18:00" }],
      "5": [{ "start": "08:00", "end": "18:00" }],
      "6": [{ "start": "08:00", "end": "18:00" }]
    }
  }
}

This endpoint retrieves a specific user.

HTTP Request

GET https://www.kalendme.com/api/v1/users/<userId>

URL Parameters

Parameter	Type	Required	Description
userId	string	Required	The ID of the user to retrieve

Update a User

curl "https://www.kalendme.com/api/v1/users" \
  -X PATCH
  -H "Authorization: Bearer abcdef123456"
  -H "Content-Type: application/json"
  -d '{
    "timeZone": "America/Los_Angeles"
  }'

{
  "user": {
    "id": "123213232",
    "createdAt": "2020-09-01T00:00:00.000Z",
    "updatedAt": "2020-09-01T00:00:00.000Z",
    "name": "Jim Halpert",
    "email": "jim@dundermifflin.com",
    "urlString": "jim-123456",
    "timeZone": "America/Los_Angeles",
    "weekAvailability": {
      "0": [{ "start": "00:00", "end": "00:00" }],
      "1": [{ "start": "08:00", "end": "18:00" }],
      "2": [{ "start": "08:00", "end": "18:00" }],
      "3": [{ "start": "08:00", "end": "18:00" }],
      "4": [{ "start": "08:00", "end": "18:00" }],
      "5": [{ "start": "08:00", "end": "18:00" }],
      "6": [{ "start": "08:00", "end": "18:00" }]
    }
  }
}

This endpoint updates a user under your organization.

HTTP Request

PATCH https://www.kalendme.com/api/v1/users/<userId>

Body Parameters

Parameter	Type	Required	Description
name	string	Optional	The name of the user
language	string	Optional	The language of the user. We currently support only `en` (english), `es` (spanish) and `pt` (portuguese).
urlString	string	Optional	A globally unique URL for the user. Used for their bookings page such as kalendme.com/`john-123`.
timeZone	string	Optional	The time zone of the user. Must be a valid IANA time zone name such as `America/New_York`.
weekAvailability	WeekAvailability	Optional	An object containing the user's week availability from Sunday [0] through Saturday [7] and each day's availability slots with a `start` and `end` times.

URL Parameters

Parameter	Type	Required	Description
userId	string	Required	The ID of the user to update

Delete a Specific User

curl "https://www.kalendme.com/api/v1/users/123213232" \
  -X DELETE
  -H "Authorization: Bearer abcdef123456"

{
  "user": {
    "id": "123213232",
    "createdAt": "2020-09-01T00:00:00.000Z",
    "updatedAt": "2020-09-01T00:00:00.000Z",
    "name": "Pam Beesly",
    "email": "pam@dundermifflin.com",
    "urlString": "pam-beesly",
    "timeZone": "America/New_York",
    "weekAvailability": {
      "0": [{ "start": "00:00", "end": "00:00" }],
      "1": [{ "start": "08:00", "end": "18:00" }],
      "2": [{ "start": "08:00", "end": "18:00" }],
      "3": [{ "start": "08:00", "end": "18:00" }],
      "4": [{ "start": "08:00", "end": "18:00" }],
      "5": [{ "start": "08:00", "end": "18:00" }],
      "6": [{ "start": "08:00", "end": "18:00" }]
    }
  }
}

This endpoint deletes a specific user from your organization.

HTTP Request

DELETE https://www.kalendme.com/api/v1/users/<userId>

URL Parameters

Parameter	Type	Required	Description
userId	string	Required	The ID of the user to delete

Calendar Accounts

Calendar Account Resource

{
  "account": {
    "id": "123213232",
    "userId": "123123123",
    "createdAt": "2020-09-01T00:00:00.000Z",
    "updatedAt": "2020-09-01T00:00:00.000Z",
    "connectionStatus": "OK",
    "provider": "google"
  }
}

Calendar accounts belong to users, they are unique calendar account providers that can contain several calendars inside them. Each calendar inside an account can be used to calculate a user's availability. Each KalendMe user comes with a KALENDME Calendr Account which are needed if you want that user to use a KalendMe calendar without needing to connect their Google/Microsoft accounts. Calendar Accounts are formed by the following fields.

Parameter	Type	Description
id	string	The resource's id
createdAt	timestamp	The resource's creation timesstamp
updatedAt	timestamp	The resource's last updated timestamp
userId	string	The ID of the user that this calendar belongs to.
provider	string	The provider, today we support "google", "microsoft" and "kalendme".
connectionStatus	string	Specifies whether the calendar account needs reconnection or is OK to be used.

Connect a Calendar Account

curl "https://www.kalendme.com/api/v1/users/123123123/accounts" \
  -X POST
  -H "Authorization: Bearer abcdef123456"
  -H "Content-Type: application/json"

{
  "connectGoogleAccountUrl": "https://www.kalendme.com/verylongtoken",
  "connectMicrosoftAccountUrl": "https://www.kalendme.com/verylongtoken"
}

This endpoint provides you with two magic links to provide to the user. One to connect a new Microsft account and another to connect a new Google account. The user will be redirected to the provider's authentication page and then redirected back to KalendMe showing that everything worked with your configured branding.

HTTP Request

POST https://www.kalendme.com/api/v1/users/<userId>/accounts

Get a user's Calendar Accounts

curl "https://www.kalendme.com/api/v1/users/123123123/accounts" \
  -H "Authorization: Bearer abcdef123456"

{
  "accounts": [
    {
      "id": "123213232",
      "userId": "123123123",
      "createdAt": "2020-09-01T00:00:00.000Z",
      "updatedAt": "2020-09-01T00:00:00.000Z",
      "provider": "kalendme",
      "connectionStatus": "OK"
    },
    {
      "id": "123213232",
      "userId": "123123123",
      "createdAt": "2020-09-01T00:00:00.000Z",
      "updatedAt": "2020-09-01T00:00:00.000Z",
      "provider": "google",
      "connectionStatus": "OK"
    }
  ]
}

This endpoint retrieves all calendar accounts for a user.

HTTP Request

GET https://www.kalendme.com/api/v1/users/<userId>/calendar-accounts

URL Parameters

Parameter	Type	Required	Description
userId	string	Required	The ID of the user's calendar accounts to retrieve

Get a Specific Calendar Account

curl "https://www.kalendme.com/api/v1/users/123123123/accounts/123213232" \
  -H "Authorization: Bearer abcdef123456"

{
  "account": {
    "id": "123213232",
    "userId": "123123123",
    "createdAt": "2020-09-01T00:00:00.000Z",
    "updatedAt": "2020-09-01T00:00:00.000Z",
    "provider": "google",
    "connectionStatus": "OK"
  }
}

This endpoint retrieves a specific calendar account for a user.

HTTP Request

GET https://www.kalendme.com/api/v1/users/<userId>/accounts/<accountId>

URL Parameters

Parameter	Type	Required	Description
userId	string	Required	The ID of the user's calendar accounts to retrieve
accountId	string	Required	The ID of the calendar account to retrieve

Delete a Specific Calendar Account

curl "https://www.kalendme.com/api/v1/users/123123123/accounts/123213232" \
  -X POST \
  -H "Authorization: Bearer abcdef123456"

{
  "account": {
    "id": "123213232",
    "userId": "123123123",
    "createdAt": "2020-09-01T00:00:00.000Z",
    "updatedAt": "2020-09-01T00:00:00.000Z",
    "provider": "google",
    "connectionStatus": "OK"
  }
}

This endpoint retrieves a specific calendar account for a user.

HTTP Request

DELETE https://www.kalendme.com/api/v1/users/<userId>/accounts/<accountId>

URL Parameters

Parameter	Type	Required	Description
userId	string	Required	The ID of the user's calendar accounts to delete
accountId	string	Required	The ID of the calendar account to delete

Calendars

Calendar Resource

{
  "calendar": {
    "id": "123213232",
    "userId": "123123123",
    "createdAt": "2020-09-01T00:00:00.000Z",
    "updatedAt": "2020-09-01T00:00:00.000Z",
    "accountId": "123213232",
    "name": "My Calendar",
    "isInput": true,
    "isOutput": true,
    "isReadOnly": true
  }
}

Calendars belong to user calendar accounts. They are the calendars that the user has access to. They can be input, output or both. They can also be read-only.

Parameter	Type	Description
id	string	The resource's id
createdAt	timestamp	The resource's creation timesstamp
updatedAt	timestamp	The resource's last updated timestamp
userId	string	The ID of the user that this calendar belongs to.
accountId	string	The ID of the calendar account that this calendar belongs to.
name	string	The name of the calendar
isInput	boolean	Whether this calendar is an input calendar
isOutput	boolean	Whether this calendar is an output calendar
isReadOnly	boolean	Whether this calendar is read-only

Connect a Calendar

Calendars are created after connecting a Calendar account automatically since they come from the account's provider. You don't need to create them manually.

Get a user's Calendars

curl "https://www.kalendme.com/api/v1/users/123123123/calendars" \
  -H "Authorization: Bearer abcdef123456"

{
  "calendars": [
    {
      "id": "123213232",
      "userId": "123123123",
      "createdAt": "2020-09-01T00:00:00.000Z",
      "updatedAt": "2020-09-01T00:00:00.000Z",
      "accountId": "123213232",
      "name": "My Calendar",
      "isInput": true,
      "isOutput": true,
      "isReadOnly": false
    },
    {
      "id": "123213232",
      "userId": "123123123",
      "createdAt": "2020-09-01T00:00:00.000Z",
      "updatedAt": "2020-09-01T00:00:00.000Z",
      "accountId": "123213232",
      "name": "Holidays in Brazil",
      "isInput": true,
      "isOutput": false,
      "isReadOnly": true
    }
  ]
}

This endpoint retrieves all configured calendars for a user.

HTTP Request

GET https://www.kalendme.com/api/v1/users/<userId>/calendars

URL Parameters

Parameter	Type	Required	Description
userId	string	Required	The ID of the user's calendars to retrieve

Get a Specific Calendar

curl "https://www.kalendme.com/api/v1/users/123123123/calendars/123213232" \
  -H "Authorization: Bearer abcdef123456"

{
  "calendar": {
    "id": "123213232",
    "userId": "123123123",
    "createdAt": "2020-09-01T00:00:00.000Z",
    "updatedAt": "2020-09-01T00:00:00.000Z",
    "accountId": "123213232",
    "name": "Holidays in Brazil",
    "isInput": true,
    "isOutput": false,
    "isReadOnly": true
  }
}

This endpoint retrieves a specific calendar for a user.

HTTP Request

GET https://www.kalendme.com/api/v1/users/<userId>/calendars/<calendarId>

URL Parameters

Parameter	Type	Required	Description
userId	string	Required	The ID of the user's calendar accounts to retrieve
calendarId	string	Required	The ID of the calendar to retrieve

Update a Calendar

curl "https://www.kalendme.com/api/v1/users/123123123/calendars/123213232" \
  -X PATCH \
  -H "Authorization: Bearer abcdef123456"

{
  "calendar": {
    "id": "123213232",
    "userId": "123123123",
    "createdAt": "2020-09-01T00:00:00.000Z",
    "updatedAt": "2020-09-01T00:00:00.000Z",
    "accountId": "123213232",
    "name": "Holidays in Brazil",
    "isInput": true,
    "isOutput": false,
    "isReadOnly": true
  }
}

This endpoint updates a calendar for a specific user. Use it to configure the calendar's input, and output properties. This way a user can control which calendars they want to use as input calendars when calculating their availability, and which calendar they want to use as output when sharing their availability so that events can be created there.

HTTP Request

PATCH https://www.kalendme.com/api/v1/users/<userId>/calendars/<calendarId>

URL Parameters

Parameter	Type	Required	Description
userId	string	Required	The ID of the user's calendar accounts to retrieve
calendarId	string	Required	The ID of the calendar to retrieve

Body Parameters

Parameter	Type	Required	Description
isInput	boolean	Optional	Whether this calendar is an input calendar
isOutput	boolean	Optional	Whether this calendar is an output calendar

User Links

User Link Resource

{
  "link": {
    "id": "123213232",
    "createdAt": "2020-09-01T00:00:00.000Z",
    "updatedAt": "2020-09-01T00:00:00.000Z",
    "userId": "112323321",
    "title": "Quick Meeting",
    "durationMinutes": 30,
    "urlString": "quick-meeting",
    "description": "A quick session to catch up",
    "minimumNotice": 0,
    "active": true,
    "visible": true,
    "weekAvailability": [],
    "incrementMinutesOverride": 60,
    "location": {
      "type": "ONLINE"
    },
    "padding": {
      "before": 10,
      "after": 10
    },
    "customQuestions": [
      {
        "id": "3656475289d4aecd03804ec4d6045953", // An ID of your choosing to map to your system
        "order": 0,
        "question": "What's your phone number?"
      }
    ]
  }
}

Links are the different types of events or rules that a user can be booked through. They have pre-defined parameters like duration or specific minimum notice times. They can be accessed by a user's urlString followed by the Link's urlString (example: kalendme.com/john/quick-meeting). Links are formed by the following fields.

Parameter	Type	Description
id	string	The resource's id
createdAt	timestamp	The resource's creation timesstamp
updatedAt	timestamp	The resource's last updated timestamp
userId	string	The ID of the user that this link belongs to
title	string	The title of the event this link will create. For example, `Interview`
description	string	The description of the event this link will create
durationMinutes	int	Required
urlString	string	A unique URL for the user's link. Used for their bookings page such as kalendme.com/`john-123`/`link-url`. If none is specified, a random one will be generated on link creation.
minimumNoticeMinutes	int	The minimum number of minutes notice required to book through this link. For example, `120` if this link type requires a minimum of 2 hours of notice to be booked in advance
enabled	boolean	`Default: true` Specifies whether this link is enabled or not. Disabled links cannot be booked or found through their `urlString`
visible	boolean	`Default: true` Specifies whether this link is visible or not. Making a link non-visible hides it from a user's main urlString.
weekAvailability	WeekAvailability	An object containing an override to the user's general avialability. A specific link's week availability from Sunday [0] through Saturday [7] and each day's availability slots with a `start` and `end` times.
customQuestions	CustomQuestion[]	An array containing custom questions to ask user's when booking this link.
padding	EventPadding	Used to specify if an event needs time padding before and/or after to be scheduled. Must be numbers in minutes of the padding needed and values can be anywhere between 0 and 180.
location	EventLocation	See Special Models definitions, this defines the event's location.
incrementMinutesOverride	int	Use this parameter to force an increment between events in minutes. For example if you want to force only events to be able to be booked every hour only, you pass in 60.

Create a Link

curl "https://www.kalendme.com/api/v1/users/112323321/links" \
  -X POST
  -H "Authorization: Bearer abcdef123456"
  -H "Content-Type: application/json"
  -d '{
    "title": "Quick Meeting",
    "durationMinutes": 30,
    "urlString": "quick-meeting",
    "description": "A quick session to catch up",
    "weekAvailability": [],
    "location": {
      "type": "ONLINE"
    },
    "padding": {
      "before": 10,
      "after": 10,
    },
    "incrementMinutesOverride": 60,
    "customQuestions": [
      {
        "id": "3656475289d4aecd03804ec4d6045953", // An ID of your choosing to map to your system
        "order": 0,
        "question": "Whats your phone number?"
      }
    ]
  }'

{
  "link": {
    "id": "123213232",
    "createdAt": "2020-09-01T00:00:00.000Z",
    "updatedAt": "2020-09-01T00:00:00.000Z",
    "userId": "112323321",
    "title": "Quick Meeting",
    "durationMinutes": 30,
    "urlString": "quick-meeting",
    "description": "A quick session to catch up",
    "minimumNotice": 0,
    "incrementMinutesOverride": 60,
    "active": true,
    "visible": true,
    "weekAvailability": [],
    "location": {
      "type": "ONLINE"
    },
    "padding": {
      "before": 10,
      "after": 10
    },
    "customQuestions": [
      {
        "id": "3656475289d4aecd03804ec4d6045953", // An ID of your choosing to map to your system
        "order": 0,
        "question": "What's your phone number?"
      }
    ]
  }
}

This endpoint creates a new link for a user.

HTTP Request

POST https://www.kalendme.com/api/v1/users/<userId>/links

Body Parameters

Parameter	Type	Required	Description
title	string	Required	The title of the event this link will create. For example, `Interview`
description	string	Optional	The description of the event this link will create. Can be blank.
durationMinutes	int	Required	The duration in minutes of the event this link will create.
urlString	string	Optional	A unique URL for the user's link. Used for their bookings page such as kalendme.com/`john-123`/`link-url`. If none is specified, a random one will be generated on link creation.
minimumNoticeMinutes	int	Optional	The minimum number of minutes notice required to book through this link. For example, `120` if this link type requires a minimum of 2 hours of notice to be booked in advance.
enabled	boolean	Optional	`Default: true` Specifies whether this link is enabled or not. Disabled links cannot be booked or found through their `urlString`
visible	boolean	Optional	`Default: true` Specifies whether this link is visible or not. Making a link non-visible hides it from a user's main urlString.
weekAvailability	Optional	WeekAvailability	An object containing an override to the user's general avialability. A specific link's week availability from Sunday [0] through Saturday [7] and each day's availability slots with a `start` and `end` times.
customQuestions	Optional	CustomQuestion[]	An array containing custom questions to ask user's when booking through this link.
incrementMinutesOverride	int	Optional	Use this parameter to force an increment between events in minutes. For example if you want to force only events to be able to be booked every hour only, you pass in 60.

URL Parameters

Parameter	Type	Required	Description
userId	string	Required	The id of the user this link will belong to.

Get a User's Links

curl "https://www.kalendme.com/api/v1/users/123213233/links" \
  -H "Authorization: Bearer abcdef123456"

{
  "links": [
    {
      "id": "123213232",
      "createdAt": "2020-09-01T00:00:00.000Z",
      "updatedAt": "2020-09-01T00:00:00.000Z",
      "userId": "112323321",
      "title": "Quick Meeting",
      "durationMinutes": 30,
      "urlString": "quick-meeting",
      "description": "A quick session to catch up",
      "minimumNotice": 0,
      "incrementMinutesOverride": 60,
      "active": true,
      "visible": true,
      "weekAvailability": [],
      "location": {
        "type": "ONLINE"
      },
      "customQuestions": [
        {
          "id": "3656475289d4aecd03804ec4d6045953", // An ID of your choosing to map to your system
          "order": 0,
          "question": "What's your phone number?"
        }
      ]
    } // ...
  ]
}

This endpoint retrieves all user links for a specific user.

HTTP Request

GET https://www.kalendme.com/api/v1/users/<userId>/links

URL Parameters

Parameter	Type	Required	Description
userId	string	Required	The id of the user these links belong to.

Get a Specific User Link

curl "https://www.kalendme.com/api/v1/users/112323321/links/123213232" \
  -H "Authorization: Bearer abcdef123456"

{
  "userEventType": {
    "id": "123213232",
    "createdAt": "2020-09-01T00:00:00.000Z",
    "updatedAt": "2020-09-01T00:00:00.000Z",
    "userId": "112323321",
    "title": "Quick Meeting",
    "durationMinutes": 30,
    "urlString": "quick-meeting",
    "description": "A quick session to catch up",
    "minimumNotice": 0,
    "incrementMinutesOverride": 60,
    "active": true,
    "visible": true,
    "weekAvailability": [],
    "location": {
      "type": "ONLINE"
    },
    "padding": {
      "before": 10,
      "after": 10
    },
    "customQuestions": [
      {
        "id": "3656475289d4aecd03804ec4d6045953", // An ID of your choosing to map to your system
        "order": 0,
        "question": "What's your phone number?"
      }
    ]
  }
}

This endpoint retrieves a specific user's link.

HTTP Request

GET https://www.kalendme.com/api/v1/users/<userId>/links/<linkId>

URL Parameters

Parameter	Type	Required	Description
userId	string	Required	The id of the user this link belong to.
linkId	string	Required	The id of the user link.

Update a User link

curl "https://www.kalendme.com/api/v1/users/112323321/links/123213232" \
  -X PATCH
  -H "Authorization: Bearer abcdef123456"
  -H "Content-Type: application/json"
  -d '{
    "visible": false,
    "customQuestions: []
  }'
  -

{
  "userEventType": {
    "id": "123213232",
    "createdAt": "2020-09-01T00:00:00.000Z",
    "updatedAt": "2020-09-01T00:00:00.000Z",
    "userId": "112323321",
    "title": "Quick Meeting",
    "durationMinutes": 30,
    "urlString": "quick-meeting",
    "description": "A quick session to catch up",
    "minimumNotice": 0,
    "incrementMinutesOverride": 60,
    "active": true,
    "visible": false,
    "location": {
      "type": "ONLINE"
    },
    "padding": {
      "before": 10,
      "after": 10
    },
    "weekAvailability": [],
    "customQuestions": []
  }
}

This endpoint updates a user's link.

HTTP Request

PATCH https://www.kalendme.com/api/v1/users/<userId>/links/<linkId>

Body Parameters

Parameter	Type	Required	Description
title	string	Optional	The title of the event. For example, `Interview`
description	string	Optional	The description of the event. Can be blank.
durationMinutes	int	Optional	The duration in minutes of the event.
urlString	string	Optional	A unique URL for the user's link. Used for their bookings page such as kalendme.com/`john-123`/`event-type`. If none is specified, a random one will be generated on user link creation.
minimumNoticeMinutes	int	Optional	The minimum number of minutes notice required to book through this link. For example, `120` if this link type requires a minimum of 2 hours of notice to be booked in advance
enabled	boolean	Optional	Specifies whether this user link is enabled or not. Disabled links cannot be booked or found through their `urlString`
visible	boolean	Optional	Specifies whether this user link is visible or not. Making an event non-visible hides it from a user's main urlString.
weekAvailability	Optional	WeekAvailability	An object containing an override to the user's general avialability. A specific user link's week availability from Sunday [0] through Saturday [7] and each day's availability slots with a `start` and `end` times.
customQuestions	Optional	CustomQuestion[]	An array containing custom questions to ask user's when booking through this link.
incrementMinutesOverride	int	Optional	Use this parameter to force an increment between events in minutes. For example if you want to force only events to be able to be booked every hour only, you pass in 60.

URL Parameters

Parameter	Type	Required	Description
userId	string	Required	The id of the user this link belong to.
linkId	string	Required	The id of the user link.

Delete a Specific User Link

curl "https://www.kalendme.com/api/v1/users/112323321/links/123213232" \
  -X DELETE
  -H "Authorization: Bearer abcdef123456"

{
  "userEventType": {
    "id": "123213232",
    "createdAt": "2020-09-01T00:00:00.000Z",
    "updatedAt": "2020-09-01T00:00:00.000Z",
    "userId": "112323321",
    "title": "Quick Meeting",
    "durationMinutes": 30,
    "incrementMinutesOverride": 60,
    "urlString": "quick-meeting",
    "description": "A quick session to catch up",
    "minimumNotice": 0,
    "active": true,
    "visible": false,
    "location": {
      "type": "ONLINE"
    },
    "padding": {
      "before": 10,
      "after": 10
    },
    "weekAvailability": [],
    "customQuestions": []
  }
}

This endpoint deletes a specific user link.

HTTP Request

DELETE https://www.kalendme.com/api/v1/users/<userId>/links/<linkId>

URL Parameters

Parameter	Type	Required	Description
userId	string	Required	The id of the user this link belong to.
linkId	string	Required	The id of the user link.

User Availability

General booking endpoints to consult user's availaibilities.

Get a User's Availability

curl "https://www.kalendme.com/api/v1/users/123123/availability?month=10&year=2021&durationMinutes=30" \
  -X GET
  -H "Authorization: Bearer abcdef123456"

{
  "availableDateTimes": [
    1234567890000, // Timestamps in epoch milliseconds
    1234567890000,
    1234567890000
  ],
  "potentialAvailableDateTimes": [
    // When passing the optional flag `includePotentialAvailableDateTimes`
    1234567890000, // Timestamps in epoch milliseconds
    1234567890000,
    1234567890000
  ]
}

This endpoint returns a user's general availability for the requrested month, year and duration in minutes.

HTTP Request

GET https://www.kalendme.com/api/v1/users/<userId>/availability

URL Parameters

Parameter	Type	Required	Description
userId	string	Required	The id of the user.
startTimestamp	int	Required	The start timestamp in epoch milliseconds to start the query for.
endTimestamp	int	Required	The end timestamp in epoch milliseconds to start the query for. It cannot span for more than a month.
durationMinutes	int	Required	The duration of the session you want to schedule this user.
timeZone	int	Required	The time zone you want to get the availability for.
year	int	Optional	Instead of querying a specific startTimestamp and endTimestamp you can pass in a year and month.
month	int	Optional	Instead of querying a specific startTimestamp and endTimestamp you can pass in a year and month.
includePotentialAvailableDateTimes	boolean	Optional	Output an optional array of what would be all the potential available date times for a user if they did not have any events.
minimumNoticeMinutes	int	Optional	The minimum number of minutes notice required to book through this link. For example, `120` if this link type requires a minimum of 2 hours of notice to be booked in advance
incrementMinutesOverride	int	Optional	Use this parameter to force an increment between events in minutes. For example if you want to force only events to be able to be booked every hour only, you pass in 60.
paddingMinutesBefore	int	Optional	Used to specify if an event needs time padding before being scheduled. Must be numbers in minutes of the padding needed and values can be anywhere between 0 and 180.
paddingMinutesAfter	int	Optional	Used to specify if an event needs time padding after being scheduled. Must be numbers in minutes of the padding needed and values can be anywhere between 0 and 180.

Get a User's Link Availability

curl "https://www.kalendme.com/api/v1/users/123123/links/654654/availability?month=10&year=2021" \
  -X GET
  -H "Authorization: Bearer abcdef123456"

{
  "availableDateTimes": [
    1234567890000, // Timestamps in epoch milliseconds
    1234567890000,
    1234567890000
  ],
  "potentialAvailableDateTimes": [
    // When passing the optional flag `includePotentialAvailableDateTimes`
    1234567890000, // Timestamps in epoch milliseconds
    1234567890000,
    1234567890000
  ]
}

This endpoint returns a user's specific link's availability for the requested month and year.

HTTP Request

GET https://www.kalendme.com/api/v1/users/<userId>/links/<linkId>/availability

URL Parameters

Parameter	Type	Required	Description
userId	string	Required	The id of the user.
startTimestamp	int	Required	The start timestamp in epoch milliseconds to start the query for.
endTimestamp	int	Required	The end timestamp in epoch milliseconds to start the query for. It cannot span for more than a month.
durationMinutes	int	Required	The duration of the session you want to schedule this user.
timeZone	int	Required	The time zone you want to get the availability for.
year	int	Optional	Instead of querying a specific startTimestamp and endTimestamp you can pass in a year and month.
month	int	Optional	Instead of querying a specific startTimestamp and endTimestamp you can pass in a year and month.
includePotentialAvailableDateTimes	boolean	Optional	Output an optional array of what would be all the potential available date times for a user if they did not have any events.
minimumNoticeMinutes	int	Optional	The minimum number of minutes notice required to book through this link. For example, `120` if this link type requires a minimum of 2 hours of notice to be booked in advance
incrementMinutesOverride	int	Optional	Use this parameter to force an increment between events in minutes. For example if you want to force only events to be able to be booked every hour only, you pass in 60.
paddingMinutesBefore	int	Optional	Used to specify if an event needs time padding before being scheduled. Must be numbers in minutes of the padding needed and values can be anywhere between 0 and 180.
paddingMinutesAfter	int	Optional	Used to specify if an event needs time padding after being scheduled. Must be numbers in minutes of the padding needed and values can be anywhere between 0 and 180.

Calendar Events

Calendar Event Resource

{
  "calendarEvent": {
    "id": "123213232",
    "calendarId": "123123123",
    "userId": "123123123",
    "createdAt": "2020-09-01T00:00:00.000Z",
    "updatedAt": "2020-09-01T00:00:00.000Z",
    "title": "Quick Meeting",
    "description": "Let's discuss a quick topic",
    "startTimestamp": 1634099600000,
    "startTimeUtc": "2020-09-01T00:00:00.000Z",
    "durationMinutes": 30,
    "location": {
      "type": "online",
      "value": "https://myvideoconferencing.com/my-link"
    },
    "guests": ["michael@dundermifflin.com"],
    "mainGuestName": "Pam Beesly",
    "mainGuestTimeZone": "America/New_York",
    "mainGuestLanguage": "en",
    "status": "CONFIRMED"
  }
}

Calendar events belong to users' calendars, they are unique instances in time that a user is booked for. Having a calendar event blocks that user's availability for the duration of the event. Calendar Events are formed by the following fields.

Parameter	Type	Description
id	string	The resource's id
createdAt	timestamp	The resource's creation timesstamp
updatedAt	timestamp	The resource's last updated timestamp
userId	string	The ID of the user that this calendar event belongs to.
calendarId	string	The ID of the calendar that this calendar event belongs to.
title	string	The title of the event. For example, `Interview`
description	string	The description of the event
startTimestamp	long	The timestamp in epoch milliseconds of when this event starts
durationMinutes	int	The duration in minutes of the event
guests	string[]	An array of the guest's emails for this event
mainGuestName	string	The name of the person that booked the event
mainGuestTimeZone	string	The time zone of the person that booked the event
mainGuestLanguage	string	The language of the person that booked the event
status	string	The status of the event. Can be `CONFIRMED` or `CANCELLED`.
padding	EventPadding	Used to specify if an event needs time padding before and/or after to be scheduled. Must be numbers in minutes of the padding needed and values can be anywhere between 0 and 180.
location	EventLocation	See Special Models definitions, this defines the event's location.

Create a Calendar Event

curl "https://www.kalendme.com/api/v1/users/123123123/calendar-events?sendGuestNotificationEmails=true" \
  -X POST
  -H "Authorization: Bearer abcdef123456"
  -H "Content-Type: application/json"
  -d '{
    "title": "Quick Meeting",
    "startTimestamp": 1634099600000,
    "durationMinutes": 30,
    "guests": [
      "michael@dundermifflin.com"
    ],
    "mainGuestName": "Pam Beesly",
    "mainGuestTimeZone": "America/New_York",
    "mainGuestLanguage": "en"
  }'

{
  "calendarEvent": {
    "id": "123213232",
    "userId": "123123123",
    "calendarId": "123123123",
    "createdAt": "2020-09-01T00:00:00.000Z",
    "updatedAt": "2020-09-01T00:00:00.000Z",
    "title": "Quick Meeting",
    "description": "Let's discuss a quick topic",
    "startTimestamp": 1634099600000,
    "startTimeUtc": "2020-09-01T00:00:00.000Z",
    "durationMinutes": 30,
    "guests": ["michael@dundermifflin.com"],
    "mainGuestName": "Pam Beesly",
    "mainGuestTimeZone": "America/New_York",
    "mainGuestLanguage": "en",
    "status": "CONFIRMED",
    "location": {
      "type": "other"
    }
  }
}

This endpoint creates a new calendar event for a user. In other words, it books that user during that time. To control which calendar account this event is written to, you have to configure that user's output calendar connection using the calendars endpoints.

HTTP Request

POST https://www.kalendme.com/api/v1/users/<userId>/calendar-events

Body Parameters

Parameter	Type	Required	Description
title	string	Required	The title of the event. For example, `Interview`
startTimestamp	long	Required	The timestamp in epoch milliseconds of when this event starts
durationMinutes	int	Required	The duration in minutes of the event
guests	string[]	Required	An array of the guest's emails for this event
mainGuestName	string	Required	The name of the person that booked the event
mainGuestTimeZone	string	Required	The time zone of the person that booked the event
mainGuestLanguage	string	Required	The language of the person that booked the event
description	string	Optional	The description of the event
location	EventLocation	Optional	The location of this event
padding	EventPadding	Optional	Any padding needed before or after scheduling this event

URL Parameters

Parameter	Type	Required	Description
userId	string	Required	The id of the user this calendar event will belong to.
sendGuestNotificationEmails	boolean	Optional	`Default: false` Whether you want to send an email notification that this event was created to the `guests`.
sendOrganizerNotificationEmail	boolean	Optional	`Default: false` Whether you want to send an email notification that this event was created to the event organizer (the user who's `userId` you're booking).
linkId	string	Optional	`Default: null` If you want to apply an event's padding rules from a link, use this to specify which one

Get a Calendar Event

curl "https://www.kalendme.com/api/v1/users/123123123/calendar-events/123213232" \
  -H "Authorization: Bearer abcdef123456"

{
  "calendarEvent": {
    "id": "123213232",
    "userId": "123123123",
    "calendarId": "123123123",
    "createdAt": "2020-09-01T00:00:00.000Z",
    "updatedAt": "2020-09-01T00:00:00.000Z",
    "title": "Quick Meeting",
    "description": "Let's discuss a quick topic",
    "startTimestamp": 1634099600000,
    "startTimeUtc": "2020-09-01T00:00:00.000Z",
    "durationMinutes": 30,
    "guests": ["michael@dundermifflin.com"],
    "mainGuestName": "Pam Beesly",
    "mainGuestTimeZone": "America/New_York",
    "mainGuestLanguage": "en",
    "status": "CONFIRMED",
    "location": {
      "type": "other"
    }
  }
}

This endpoint gets a specific calendar event for a user.

HTTP Request

GET https://www.kalendme.com/api/v1/users/<userId>/calendar-events/<eventId>

URL Parameters

Parameter	Type	Required	Description
userId	string	Required	The ID of the user's calendar event to retrieve
eventId	string	Required	The ID of the calendar event to retrieve

Get Calendar Events between timestamps

curl "https://www.kalendme.com/api/v1/users/123123123/calendar-events?startTimestamp=0&endTimestamp=100000" \
  -H "Authorization: Bearer abcdef123456"

{
  "calendarEvents": [
    {
      "id": "123213232",
      "userId": "123123123",
      "calendarId": "123123123",
      "createdAt": "2020-09-01T00:00:00.000Z",
      "updatedAt": "2020-09-01T00:00:00.000Z",
      "title": "Quick Meeting",
      "description": "Let's discuss a quick topic",
      "startTimestamp": 1634099600000,
      "startTimeUtc": "2020-09-01T00:00:00.000Z",
      "durationMinutes": 30,
      "guests": ["michael@dundermifflin.com"],
      "mainGuestName": "Pam Beesly",
      "mainGuestTimeZone": "America/New_York",
      "mainGuestLanguage": "en",
      "status": "CONFIRMED",
      "location": {
        "type": "other"
      }
    } // ...
  ]
}

This endpoint gets a list of calendar events for a user between a start and an end timestamp.

HTTP Request

GET https://www.kalendme.com/api/v1/users/<userId>/calendar-events?startTimestamp=&endTimestamp=

URL Parameters

Parameter	Type	Required	Description
userId	string	Required	The ID of the user's calendar event to retrieve
startTimestamp	int	Required	The start timestamp in epoch milliseconds to start the query for.
endTimestamp	int	Required	The end timestamp in epoch milliseconds to start the query for. It cannot span for more than a month.

Update a Calendar Event

curl "https://www.kalendme.com/api/v1/users/123123123/calendar-events/123213232" \
  -X PATCH
  -H "Authorization: Bearer abcdef123456"
  -H "Content-Type: application/json"
  -d '{
    "status": "CANCELLED"
  }'

{
  "calendarEvent": {
    "id": "123213232",
    "userId": "123123123",
    "calendarId": "123123123",
    "createdAt": "2020-09-01T00:00:00.000Z",
    "updatedAt": "2020-09-01T00:00:00.000Z",
    "title": "Quick Meeting",
    "description": "Let's discuss a quick topic",
    "startTimestamp": 1634099600000,
    "startTimeUtc": "2020-09-01T00:00:00.000Z",
    "durationMinutes": 30,
    "guests": ["michael@dundermifflin.com"],
    "mainGuestName": "Pam Beesly",
    "mainGuestTimeZone": "America/New_York",
    "mainGuestLanguage": "en",
    "status": "CANCELLED",
    "location": {
      "type": "other"
    }
  }
}

This endpoint updates a calendar event. Used for rescheduling or cancelling calendar events.

HTTP Request

PATCH https://www.kalendme.com/api/v1/users/<userId>/calendar-events/<eventId>

Body Parameters

Parameter	Type	Required	Description
title	string	Optional	The title of the event. For example, `Interview`
description	string	Optional	The description of the event
startTimestamp	long	Optional	The timestamp in epoch milliseconds of when this event starts
durationMinutes	int	Optional	The duration in minutes of the event
guests	string[]	Optional	An array of the guest's emails for this event
status	string	Optional	The status of the event. Can be `CONFIRMED` or `CANCELLED`.

URL Parameters

Parameter	Type	Required	Description
userId	string	Required	The ID of the user's calendar event to update
eventId	string	Required	The ID of the calendar event to update

Webhooks

Overview

Webhooks are used to keep your system up to date with KalendMe's information in real-time. You can configure which system events from KalendMe you want to subscribe to so that you can take action on your side with the information provided.

These are signed POST requests to a url of your choosing.

Webhook Event Types

Event Type	Description	Resource Data
`user.acceptedInvite`	Event fired when a user joins the organization (accepts an invitation to join)	User
`event.created`	Event fired when an event is created	Event
`event.cancelled`	Event fired when an event is cancelled	Event

General Body Structure

{
  "id": "123213232",
  "createdAt": "2020-09-01T00:00:00.000Z",
  "type": "event.created",
  "data": {
    "id": "123",
    "userId": "321",
    "createdAt": "2020-09-01T00:00:00.000Z",
    "updatedAt": "2020-09-01T00:00:00.000Z",
    "title": "Quick Meeting",
    "description": "Let's discuss a quick topic",
    "startTimestamp": 1634099600000,
    "durationMinutes": 30,
    "guests": [
      "michael@dundermifflin.com"
    ],
    "mainGuestName": "Pam Beesly",
    "mainGuestTimeZone": "America/New_York",
    "mainGuestLanguage": "en",
    "status": "CONFIRMED"
  }
}

Webhooks are POST requests to your systems. All of KalendMe's requests will come in the shown format with a Content-Type: application/json and the following body structure describing the type of the webhook event and the data.

Security

import { createHash, timingSafeEqual } from 'crypto'

// Your server's endpoint receiving the request
export default async function(req, res) {
 const hashedBody = createHash('sha256')
   .update(`${req.body}${process.env.KALENDME_WEBHOOK_SECRET}`)
   .digest('hex')

 if (!timingSafeEqual(hashedBody, req.headers['Kalendme-Signature'])) {
   res.status(401).end()
   return
 }

 // proceed with the processing of the webhook
}

You’ll be provided with a webhook secret on account setup which you’ll use to calculate a hash to compare against the signature of every webhook.

All webhooks will come with a signature header: Kalendme-Signature

That signature has to be compared to the received body of the event.

Webhook Resource

{
  "webhook": {
    "id": "123213232",
    "createdAt": "2020-09-01T00:00:00.000Z",
    "updatedAt": "2020-09-01T00:00:00.000Z",
    "url": "https://yourdomain.com/my-endpoint",
    "enabledEvents": [ 
      "event.created"
    ],
    "description": "My Webhook",
    "enabled": true
  }
}

Webhooks are all under your organization. Webhooks are formed by the following fields.

Parameter	Type	Description
id	string	The resource's id
createdAt	timestamp	The resource's creation timesstamp
updatedAt	timestamp	The resource's last updated timestamp
url	string	The url of your endpoint that will listen to events coming in
enabledEvents	string[]	An array containing the webhook event types you want to subscribe to
decription	string	A description of ths webhook
enabled	boolean	Controls whether this webhook actually emits events or not

Create a Webhook

curl "https://www.kalendme.com/api/v1/webhooks" \
  -X POST
  -H "Authorization: Bearer abcdef123456"
  -H "Content-Type: application/json"
  -d '{
    "url": "https://yourdomain.com/my-endpoint",
    "enabledEvents": [ 
      "event.created"
    ],
    "description": "My Webhook"
  }'

{
  "webhook": {
    "id": "123213232",
    "createdAt": "2020-09-01T00:00:00.000Z",
    "updatedAt": "2020-09-01T00:00:00.000Z",
    "url": "https://yourdomain.com/my-endpoint",
    "enabledEvents": [ 
      "event.created"
    ],
    "description": "My Webhook",
    "enabled": true
  }
}

This endpoint creates a new webhook under your organization.

HTTP Request

POST https://www.kalendme.com/api/v1/webhooks

Body Parameters

Parameter	Type	Required	Description
url	string	Required	The url of your endpoint that will listen to events coming in
enabledEvents	string[]	Required	An array containing the webhook event types you want to subscribe to
decription	string	Optional	A description of ths webhook
enabled	boolean	Optional	`Default: true` Controls whether this webhook actually emits events or not

Get All Webhooks

curl "https://www.kalendme.com/api/v1/webhooks" \
  -H "Authorization: Bearer abcdef123456"

{
  "webhooks": [
    {
      "id": "123213232",
      "createdAt": "2020-09-01T00:00:00.000Z",
      "updatedAt": "2020-09-01T00:00:00.000Z",
      "url": "https://yourdomain.com/my-endpoint",
      "enabledEvents": [ 
        "event.created"
      ],
      "description": "My Webhook",
      "enabled": true
    },
    {
      "id": "123213233",
      "createdAt": "2020-09-01T00:00:00.000Z",
      "updatedAt": "2020-09-01T00:00:00.000Z",
      "url": "https://yourdomain.com/my-endpoint-2",
      "enabledEvents": [ 
        "event.cancelled"
      ],
      "description": "My Cancelled Events Webhook",
      "enabled": true
    }
  ]
}

This endpoint retrieves all webhooks for your organization.

HTTP Request

GET https://www.kalendme.com/api/v1/webhooks

Get a Specific Webhook

curl "https://www.kalendme.com/api/v1/webhooks/123213232" \
  -H "Authorization: Bearer abcdef123456"

{
  "webhook": {
    "id": "123213232",
    "createdAt": "2020-09-01T00:00:00.000Z",
    "updatedAt": "2020-09-01T00:00:00.000Z",
    "url": "https://yourdomain.com/my-endpoint",
    "enabledEvents": [ 
      "event.created"
    ],
    "description": "My Webhook",
    "enabled": true
  }
}

This endpoint retrieves a specific webhook.

HTTP Request

GET https://www.kalendme.com/api/v1/webhooks/<webhookId>

URL Parameters

Parameter	Type	Required	Description
webhookId	string	Required	The ID of the webhook to retrieve

Get a Webhook's Logs

curl "https://www.kalendme.com/api/v1/webhooks/123213232/logs" \
  -H "Authorization: Bearer abcdef123456"

{ 
  "webhookEventsLogs": [
    {
      "createdAt": "2020-09-01T00:00:00.000Z",
      "updatedAt": "2020-09-01T00:00:00.000Z",
      "webhookId": "12312313",
      "statusCode": 200,
      "requestData": {
        "id": "310675722544874052",
        "createdAt": "2021-09-25T00:58:26.866-03:00",
        "type": "event.created",
        "data": {
          "id": "310663991379624516",
          "startTimestamp": 1633834800000,
          "title": "Test Event",
          "durationMinutes": 30,
          "guests": [
            "raimille2@gmail.com"
          ],
          "mainGuestTimeZone": "America/Sao_Paulo",
          "mainGuestName": "Rai",
          "mainGuestLanguage": "es",
          "status": "CONFIRMED"
        }
      },
      "responseText": "",
      "responseJson": {},
      "id": "123123"
    }
  ]
}

This endpoint retrieves a specific webhook's logs. Contains response status code, text and json contents if available.

Webhook Event Log Resource

Parameter	Type	Description
id	string	The resource's id
createdAt	timestamp	The resource's creation timesstamp
updatedAt	timestamp	The resource's last updated timestamp
webhookId	string	The id of the webhook this log entry belongs to
statusCode	int	The http status code your system replied with when this event was emitted
requestData	string	The JSON data sent over to your system with this event
responseJson	object	The JSON response from your system if replied with content type of `application/json`
responseText	string	The TEXT response from your system if replied with content type other than `application/json`

HTTP Request

GET https://www.kalendme.com/api/v1/webhooks/<webhookId>/logs

URL Parameters

Parameter	Type	Required	Description
webhookId	string	Required	The ID of the webhook to retrieve

Update a Webhook

curl "https://www.kalendme.com/api/v1/webhooks/123213232" \
  -X PATCH
  -H "Authorization: Bearer abcdef123456"
  -H "Content-Type: application/json"
  -d '{
    "enabled": false
  }'

{
  "webhook": {
    "id": "123213232",
    "createdAt": "2020-09-01T00:00:00.000Z",
    "updatedAt": "2020-09-01T00:00:00.000Z",
    "url": "https://yourdomain.com/my-endpoint",
    "enabledEvents": [ 
      "event.created"
    ],
    "description": "My Webhook",
    "enabled": false
  }
}

This endpoint updates a webhook under your organization. Used to switch out the url or disable it by setting the enabled flag to false.

HTTP Request

PATCH https://www.kalendme.com/api/v1/webhooks/<webhookId>

Body Parameters

Parameter	Type	Required	Description
url	string	Optional	The url of your endpoint that will listen to events coming in
enabledEvents	string[]	Optional	An array containing the webhook event types you want to subscribe to
decription	string	Optional	A description of ths webhook
enabled	boolean	Optional	Controls whether this webhook actually emits events or not

URL Parameters

Parameter	Type	Required	Description
webhookId	string	Required	The ID of the webhook to update

Delete a Specific Webhook

curl "https://www.kalendme.com/api/v1/webhooks/123213232" \
  -X DELETE
  -H "Authorization: Bearer abcdef123456"

{
  "webhook": {
    "id": "123213232",
    "createdAt": "2020-09-01T00:00:00.000Z",
    "updatedAt": "2020-09-01T00:00:00.000Z",
    "url": "https://yourdomain.com/my-endpoint",
    "enabledEvents": [ 
      "event.created"
    ],
    "description": "My Webhook",
    "enabled": false
  }
}

This endpoint deletes a specific webhook from your organization.

HTTP Request

DELETE https://www.kalendme.com/api/v1/webhooks/<webhookId>

URL Parameters

Parameter	Type	Required	Description
webhookId	string	Required	The ID of the webhook to delete

Time Zones

Overview

Time zones are a critical component for scheduling. KalendMe provides this endpoint to be able to always be up to date with the latest IANA time zone DB.

Get Time Zones

curl "https://www.kalendme.com/api/v1/time-zones" \
  -H "Authorization: Bearer abcdef123456"

{
    "currentVersion": "2023c",
  "timeZones": [
        "Africa/Algiers",
        "Atlantic/Cape_Verde",
        "Africa/Ndjamena",
        "Africa/Abidjan",
        "Africa/Accra",
    ....
  ]
}

Bulk Operations

These endpoints are hosted under another domain. To use them please use the following base URL: https://api.kalendme.com

# With shell, you can just pass the correct header with each request
curl --request GET \
  --url https://api.kalendme.com/health

Bulk endpoints are mainly focused towards larger organizations with hundreds of users but you can also leverage them to build customized round robin scheduling solutions among other things.

Get Mass Availability

curl --request POST \
--url https://api.kalendme.com/v1/availability/calculate-mass-availability \
--header 'Authorization: Bearer token' \
--header 'Content-Type: application/json' \
--data '{
    "userIds":["12312313",
        "12312"],
    "startTimeMillis": 1675090800000,
    "endTimeMillis": 1676862000000,
    "durationMinutes": 30
}'

{
  "12312313": [1675090800000, 1675090800000],
  "12312": [1675090800000, 1675090800000]
}

This endpoint returns an array of user's availabilities based on the specified rules. You can query the availability for any amount of users and any amount of time. Although this endpoint is built for speed, the response may take longer for larger time spans or larger amounts of users.

HTTP Request

POST https://api.kalendme.com/v1/availability/calculate-mass-availability

Body Parameters

Parameter	Type	Required	Description
userIds	array	Required	The ids of the users.
startTimeMillis	int	Required	The start timestamp in epoch milliseconds to start the query for.
endTimeMillis	int	Required	The end timestamp in epoch milliseconds to start the query for. It cannot span for more than a month.
durationMinutes	int	Required	The duration of the session you want to schedule this user.

Get Users Available between Two Timestamps

curl --request POST \
  --url https://api.kalendme.com/v1/availability/users-available-between \
  --header 'Authorization: Bearer token' \
  --header 'Content-Type: application/json' \
  --data '{
    "startTimeMillis": 1678158000000,
    "endTimeMillis": 1678190400000,
    "durationMinutes": 30
}'

{
  "userIds": ["12341332", "123123123"]
}

This endpoint returns an array of user's ids that are available based on the specified time slot. This is designed to be used as slots, so for example when you want to schedule a meeting next tuesday at 4 pm for 60 minutes and you want to know which users are available.

HTTP Request

POST https://api.kalendme.com/v1/availability/users-available-between

Body Parameters

Parameter	Type	Required	Description
startTimeMillis	int	Required	The start timestamp in epoch milliseconds to start the query for.
endTimeMillis	int	Required	The end timestamp in epoch milliseconds to start the query for. It cannot span for more than a month.
durationMinutes	int	Required	The duration of the session you want to schedule this user.

Get Users Availabilities between Two Timestamps

curl --request POST \
  --url https://api.kalendme.com/v1/availability/users-availabilities-between \
  --header 'Authorization: Bearer token' \
  --header 'Content-Type: application/json' \
  --data '{
    "startTimeMillis": 1678244400000,
    "endTimeMillis": 1678330800000,
    "durationMinutes": 30
}'

{
  "123123123": [1678244400000, 1678244400000],
  "123123123": [1678244400000, 1678244400000]
}

This endpoint returns an array of user's availabilities based on the specified durationMinutes. Similar to the other endpoint but this is used when you want to various availabilities for several users at once.

HTTP Request

POST https://api.kalendme.com/v1/availability/users-availabilities-between

Body Parameters

Parameter	Type	Required	Description
startTimeMillis	int	Required	The start timestamp in epoch milliseconds to start the query for.
endTimeMillis	int	Required	The end timestamp in epoch milliseconds to start the query for. It cannot span for more than a month.
durationMinutes	int	Required	The duration of the session you want to schedule this user.

Special Models

These are common special models across our API.

Week Availability

{
  "weekAvailability": {
    "0": [{ "start": "00:00", "end": "00:00" }], // Sunday -- Not availabile
    "1": [{ "start": "08:00", "end": "18:00" }], // Monday
    "2": [{ "start": "08:00", "end": "18:00" }], // Tuesday
    "3": [{ "start": "08:00", "end": "18:00" }], // Wednesday
    "4": [{ "start": "08:00", "end": "18:00" }], // Thursday
    "5": [{ "start": "08:00", "end": "18:00" }], // Friday
    "6": [{ "start": "08:00", "end": "18:00" }] // Saturday -- Not availabile
  }
}

Used to describe a user's or an event's week availability. 0 through 6 represent the days of the week starting on sunday. All times are represented in local time to the user's configured time zone.

Custom Question

{
  "id": "3656475289d4aecd03804ec4d6045953", // An ID of your choosing to map to your system
  "order": 0,
  "question": "Whats your phone number?"
}

Used for specific user event types as questions for guests to fill out. They have an id, order in which to display to the user and the question itself.

Event Location

{
  "type": "phone", // Other types can be `online`, `zoom`, `inPerson`, `other`
  "value": "+1234567656324",
  "callDirection": "receive" // Only applicable to `phone` type locations. Valid values are: `make`/`receive`
}

Used to configure an event's location, can be used to pre-create links with these settings and also at the time of creating an event. Types are:

Type	Description
online	The event will be created with an auto generated link for videoconferencing. Depending on your calendar provider this can be a Google Meet or a Microsoft Teams link. Value is not needed, since links are autogenerated.
inPerson	The event will be in person at a physical location. You need to pass in a `value` specifying the address or place.
zoom	The event will be created with an auto generated Zoom link. The user must first have linked their Zoom account to their KalendMe account in integrations.
phone	The event will be a phone call. It must include a `callDirection` property indicating: `make` if the host will make a call, or `receive` if the host will receive a call. The value property then becomes the phone number.
other	The event will be created with any special instructions you might want to be included under the value field

Event Padding

{
  "before": 0,
  "after": 180
}

Used to specify if an event needs time padding before and/or after to be scheduled. Must be numbers in minutes of the padding needed and values can be anywhere between 0 and 180.

Errors

KalendMe's API can reply with the following error codes:

Error Code	Message	HTTP Status Code
1000	Missing required body parameter	400
1001	Missing required query parameter	400
1002	Conflict	409
1003	The specified `timeZone` is invalid	400
1004	The specified `weekAvailaibility` is invalid. Must contain all 7 days of the week in the required format: start/end keys in 24-hour HH:MM.	400
1005	The specified `language` is invalid. We only support (en, es, pt).	400
1006	The specified `durationMinutes` is invalid. Can only be integers between 1 and 480.	400
1007	The specified `minimumNoticeMinutes` is invalid. Can only be integers between 0 and 90000 (~2 months).	400
1008	The `enabled` attribute must be a valid boolean.	400
1009	The `visible` attribute must be a valid boolean.	400
1010	The specified `title` is invalid. Can only be a string between 1 and 30 characters.	400
1011	The specified `description` is invalid. Can only be a string up to 60 characters.	400
1012	The specified `customQuestions` are invalid. Must be an array with { id, order, question } objects.	400
1013	You can't change a user's email.	403
1014	The specified `name` is invalid. Can only be a string up to 50 characters.	400
1015	The specified `urlString` is invalid, it can only contain letters, numbers, periods or hyphens (-) without spaces, a minimum of 1 character and a maximum of 30 characters.	400
1016	The specified `email` is invalid. Has to be a properly formatted email.	400
1017	The specified `year` is invalid. Must be a positive small integer.	400
1018	The specified `month` is invalid. Must be a positive integer between 1 and 12.	400
1019	The specified `selectedDateTime` is invalid. Must be a future unix timestamp.	400
1020	The specified `selectedDateTime` is not available anymore. There's a conflict.	409
1021	The specified `guest` array is invalid. Must be an non-empty array with valid email strings.	400
1022	The specified `mainGuestName` is invalid. Can only be a string up to 50 characters.	400
1023	The specified `mainGuestTimeZone` is invalid.	400
1024	The specified `providerId` is invalid. Can only be google or microsoft	400
1025	The specified `day` is invalid. Must be a real year-month-day combination.	400
1026	The specified `nickname` is invalid. Can only be a string up to 50 characters.	400
1027	The specified boolean `enabled` is invalid. Can only be a string equaling true or false.	400
1028	The specified `enabledEvents` list is invalid. Must contain at least one valid webhook event type lowercased.	400
1029	The specified `url` is invalid. Must be a valid URL starting with http/https. localhost is not allowed.	400
1030	The specified `status` is invalid. Must be a string that's either CONFIRMED or CANCELLED.	400
1031	The specified `location` is invalid. Can only be a string up to 256 characters.	400
1032	The specified `description` is invalid. Can only be a string up to 300 characters.	400
1033	The specified `urlString` is already taken, please specify another one.	409
1034	The specified event could not be created because the user doesn't have an `output` calendar connection. Please specify an `output` calendar connection and then create the event.	422
1035	The specified event cannot be edited anymore since it's been cancelled.	422
1036	The specified `startTimestamp` is invalid. Must be a valid unix timestamp.	400
1037	The specified `endTimestamp` is invalid. Must be a valid unix timestamp.	400
1038	The specified `endTimestamp` cannot be before or equal to the specified `startTimestamp`.	400
1039	You cannot specify `year`/`month` and `startTimestamp`/`endTimestsamp`, please pick only one method.	400
1040	The `includePotentialAvailableDateTimes` attribute must be a valid boolean.	400
1041	The specified `startTimestamp` and `endTimestamp` have a timespan of more than 1 month. Please select a smaller range.	400
1042	The specified `padding` is invalid. It must be an object with the keys: "before" and/or "after" specifying the minutes in values between 0 and 180.	400
1043	The specified `incrementMinutesOverride` is invalid. Can only be integers between 1 and 480.	400
1044	The specified event could not be created because the user has a calendar connection as an output that is not properly configured. Please ask them to reconnect the calendar account.	422
1045	The specified `isInput` attribute must be a valid boolean.	400
1046	The specified `isOutput` attribute must be a valid boolean.	400
1047	The specified `location` is invalid. Location is an object containing a required key "type" and an optional key "value" depending on the location type. Types: inPerson & phone (callDirection: receive) require a value	400