Booking links
Links people use to book a meeting type.
Headers
The endpoints on this page take these headers. Each endpoint's curl shows the ones it sends.
| Name | In | Type | Required | Description |
|---|---|---|---|---|
Ken-Version | header | string, one of: 2026-11-02, 1.1 | optional | The API version, a date in YYYY-MM-DD form. 1.1 is another name for the first dated version. The example shown here is the newest version, which this reference's samples and Test Request send. Leave it out to use your API key's pinned version. Keys created in the Kenso app are pinned to the newest version; keys minted by the CLI login are not. A key with no pinned version and no header gets the legacy shape where the path has one, and 404 where the path exists only in this version. A date that is not a version answers 400 unsupported_version; any other value that is not a version is treated as legacy. |
X-Ken-Workspace-Id | header | integer (int64) | optional | The id of the workspace to act in. Leave it out when your API key reaches only one workspace. When the key reaches more than one, a request without this header answers 400 workspace_required. A workspace you are not a member of answers 404 not_found. |
List your open single-use links
/v1/booking-linksbooking-links.list- Permission
- Calendar view
- Rate limit
- 12,000 requests a minute per API key
scheduler feature on your workspace. Until it is on, calls answer 404.Lists the single-use links you made in this workspace that can still book: not used, not expired, and on a meeting type that still exists. Newest first. A single-use link belongs to the member who made it, so you see only your own, also with the members permission.
The items have no url: Kenso keeps only a hash of each link's token, so the URL is shown once, when you create the link. Page with limit, from 1 to 200 (default 50), and the cursor from pagination.nextCursor.
Errors:
400 validation_failed:limitis out of range, orcursoris not valid.403 forbidden: the API key is not tied to a member of the workspace.
Requires Meetings view.
Parameters
| Name | In | Type | Required | Description |
|---|---|---|---|---|
limit | query | integer (int32) | optional | Number of links per page, from 1 to 200. Default 50. |
cursor | query | string | optional | The nextCursor from the previous page. Omit it for the first page. |
curl -X GET "https://api.ken.so/v1/booking-links?limit=50" \
-H "Authorization: Bearer $KENSO_API_KEY" \
-H "Ken-Version: 2026-11-02" \
-H "X-Ken-Workspace-Id: $KENSO_WORKSPACE_ID"Response 200
data is a list of BookingLinkSummary. Each item has these fields. The response also carries pagination.
Show the 7 response fields and an example
The fields and an example are also on this endpoint's Markdown page.
Create a booking link
/v1/booking-linksbooking-links.create- Permission
- Calendar view
- Rate limit
- 4,800 requests a minute per API key
scheduler feature on your workspace. Until it is on, calls answer 404.Creates a link to a member's booking page. kind is person or single_use. hostMemberId is the member whose page the link opens and defaults to you. Another member's page or meeting type needs the members permission.
A person link needs personId. Kenso keeps one link per person for each source, campaign, Studio page, meeting type and host, so asking again returns the same link with 200 instead of 201. source is personal, campaign, reply or studio. When you leave it out, Kenso uses campaign with a campaignId, studio with an assetId, and personal otherwise. source: campaign and stepOrder need campaignId, and source: studio needs assetId. Links for email and LinkedIn never use a Kenso domain. With channel: email, senderAddress is the From address of the email the link goes in: Kenso serves a campaign email's link from cal. on the sending domain when that host is ready.
A single-use link books one meeting and expires after 30 days. It takes personId, accountId, meetingTypeId, hostMemberId, channel and availability. meetingTypeId defaults to the host's default type. availability gives the link its own weekly hours and date overrides, used instead of the meeting type's and the host's hours. Calendar busy time, the minimum notice, the booking window, the buffers and the daily cap still apply. Save the returned url: Kenso keeps only a hash of a single-use link's token and cannot show the URL again.
The response's id is the link id that PATCH /v1/booking-links/{bookingLinkId} takes.
Errors:
400 validation_failed:kindis missing or unknown, a field does not apply to the kind, a field another field needs is missing,senderAddressis not an email address,accountIdortouchIdis not the person's,hostMemberIddoes not host the meeting type, or the host has no default meeting type.403 forbidden: you need thememberspermission for another member's page or meeting type, or the API key is not tied to a member of the workspace.403 permission_denied: Client seats cannot create booking links.404 not_found: the person, member, meeting type, account, campaign, touch or Studio page is not in this workspace, or you cannot see it.409 invalid_state: no booking domain can serve the link yet, or the meeting type is turned off.503 service_unavailable: Kenso cannot make booking links right now. Try again in a few minutes.
Requires Meetings view.
Request body
application/json, optional.
| Field | Type | Required | Description |
|---|---|---|---|
kind | string | optional | The kind of link: person or single_use. |
personId | integer (int64) | optional | The person the link is for. Required for a person link. |
meetingTypeId | integer (int64) | optional | The meeting type the link books. On a single-use link it defaults to the host's default type. |
hostMemberId | integer (int64) | optional | The member whose booking page the link opens. Defaults to you; another member needs the members permission. |
accountId | integer (int64) | optional | The person's account the booking belongs to. |
campaignId | integer (int64) | optional | The campaign the link goes out in, on a person link. |
stepOrder | integer (int32) | optional | The campaign step the link goes out in. Needs campaignId. |
touchId | integer (int64) | optional | The person's touch the link goes out in, on a person link. |
assetId | integer (int64) | optional | The Studio page the link sits on, on a person link. |
source | string | optional | Where a person link is used: personal, campaign, reply or studio. Left out, it is campaign with a campaignId, studio with an assetId, and personal otherwise. |
channel | string | optional | The channel the link goes out on: email, linkedin or web. |
senderAddress | string | optional | The From address of the email the link goes in, on a person link with channel: email. |
availability | AvailabilitySchedule | optional | For single-use links only: the link's own available times, used instead of the meeting type's and the host's. Leave it out, or send null, to use the type's. |
curl -X POST "https://api.ken.so/v1/booking-links" \
-H "Authorization: Bearer $KENSO_API_KEY" \
-H "Ken-Version: 2026-11-02" \
-H "X-Ken-Workspace-Id: $KENSO_WORKSPACE_ID" \
-H "Content-Type: application/json" \
-d '{
"kind": "person",
"personId": 812,
"meetingTypeId": 812,
"hostMemberId": 812,
"accountId": 812,
"campaignId": 812,
"stepOrder": 1,
"touchId": 812,
"assetId": 812,
"source": "personal",
"channel": "email",
"senderAddress": "string",
"availability": {
"timeZone": "America/New_York",
"weekly": {
"monday": [
{
"start": "string",
"end": "string"
}
],
"tuesday": [
{
"start": "string",
"end": "string"
}
],
"wednesday": [
{
"start": "string",
"end": "string"
}
],
"thursday": [
{
"start": "string",
"end": "string"
}
],
"friday": [
{
"start": "string",
"end": "string"
}
],
"saturday": [
{
"start": "string",
"end": "string"
}
],
"sunday": [
{
"start": "string",
"end": "string"
}
]
},
"overrides": [
{
"date": "string",
"ranges": [
{
"start": "string",
"end": "string"
}
]
}
]
}
}'Response 201
Also answers 200. data is a BookingLink.
Show the 5 response fields and an example
The fields and an example are also on this endpoint's Markdown page.
Update a single-use link's times
/v1/booking-links/{bookingLinkId}booking-links.update- Permission
- Calendar view
- Rate limit
- 4,800 requests a minute per API key
scheduler feature on your workspace. Until it is on, calls answer 404.Changes the hours of a single-use link you made, for example after you copied it into an email. Send availability with the link's own schedule, in the same shape and rules as on create, or null to use the meeting type's hours again. A schedule here may hold only date overrides. Leaving availability out changes nothing. Returns the link as the list shows it.
Errors:
400 validation_failed: the body is missing, has an unknown field, or the schedule breaks a rule.403 forbidden: the API key is not tied to a member of the workspace.403 permission_denied: Client seats cannot change booking links.404 not_found: the link is not a single-use link you made in this workspace.409 invalid_state: the link was already used to book (link_used) or has expired (link_expired).
Requires Meetings view.
Parameters
| Name | In | Type | Required | Description |
|---|---|---|---|---|
bookingLinkId | path | integer (int64) | required | The single-use link's id, from the create response or the list. |
Request body
application/json, optional.
| Field | Type | Required | Description |
|---|---|---|---|
availability | AvailabilitySchedule | optional | The link's own available times, replacing the whole schedule, with the same shape and rules as on create. Null clears it, so the link uses its meeting type's times again. Leave it out to change nothing. |
curl -X PATCH "https://api.ken.so/v1/booking-links/812" \
-H "Authorization: Bearer $KENSO_API_KEY" \
-H "Ken-Version: 2026-11-02" \
-H "X-Ken-Workspace-Id: $KENSO_WORKSPACE_ID" \
-H "Content-Type: application/json" \
-d '{
"availability": {
"timeZone": "America/New_York",
"weekly": {
"monday": [
{
"start": "string",
"end": "string"
}
],
"tuesday": [
{
"start": "string",
"end": "string"
}
],
"wednesday": [
{
"start": "string",
"end": "string"
}
],
"thursday": [
{
"start": "string",
"end": "string"
}
],
"friday": [
{
"start": "string",
"end": "string"
}
],
"saturday": [
{
"start": "string",
"end": "string"
}
],
"sunday": [
{
"start": "string",
"end": "string"
}
]
},
"overrides": [
{
"date": "string",
"ranges": [
{
"start": "string",
"end": "string"
}
]
}
]
}
}'Response 200
data is a BookingLinkSummary.
Show the 7 response fields and an example
The fields and an example are also on this endpoint's Markdown page.
Get suggested times for a person
/v1/booking-links/suggested-timesbooking-links.suggested-times- Permission
- Calendar view
- Rate limit
- 12,000 requests a minute per API key
scheduler feature on your workspace. Until it is on, calls answer 404.Returns up to three open times on a person's own booking link, to offer in a reply. Each time has a url that opens the booking page with that time picked. Opening it does not book.
Query parameters: personId is required. hostMemberId is the member whose page the link opens and defaults to you; another member's page needs the members permission. meetingTypeId must be one of that member's own personal types and defaults to their default type. campaignId is the campaign of the thread you are answering, so a booking through the link counts for that campaign. senderAddress is the mailbox the reply goes out from: with a campaign, Kenso serves the link from cal. on the sending domain when that host is ready.
The times are for the member the page routes this person to, given in the response's hostMemberId and routingReason. Kenso takes the first open time of each day that has one, for up to three days in the next 14 days, counting days in the host's time zone. Kenso creates the person's link when it does not exist yet. A Client seat creates nothing: it gets times only on a link that already exists for this person.
status is available, no_availability, or unavailable with a reason. When the member books through Calendly, Cal.com, HubSpot or Chili Piper, status is external_tool and url is that tool's link, with no times.
Errors:
400 validation_failed:personIdis missing,senderAddressis not an email address, ormeetingTypeIdis not one of the member's personal types.403 forbidden: you need thememberspermission for another member's page, or the API key is not tied to a member of the workspace.404 not_found: the person, member, campaign or meeting type is not in this workspace, or you cannot see it.409 invalid_state: the meeting type is turned off, the member has no meeting type, no booking domain can serve the link yet, or a Client seat asked for a person who has no link yet.503 service_unavailable: Kenso cannot make booking links right now. Try again in a few minutes.
Requires Meetings view.
Parameters
| Name | In | Type | Required | Description |
|---|---|---|---|---|
personId | query | integer (int64) | optional | The person to suggest times to, by person id. Required. |
meetingTypeId | query | integer (int64) | optional | The meeting type to book, one of the host's own personal types. Omitted uses the host's default type. |
hostMemberId | query | integer (int64) | optional | The member whose booking page the link opens, by member id. Omitted means you, and another member's id needs the members permission. |
campaignId | query | integer (int64) | optional | The campaign of the thread you are answering. A booking through the link then counts for that campaign. |
senderAddress | query | string | optional | The mailbox the reply goes out from, as an email address. With campaignId, the link uses cal. on the sender's domain once that host is ready. |
curl -X GET "https://api.ken.so/v1/booking-links/suggested-times" \
-H "Authorization: Bearer $KENSO_API_KEY" \
-H "Ken-Version: 2026-11-02" \
-H "X-Ken-Workspace-Id: $KENSO_WORKSPACE_ID"Response 200
data is a SuggestedTimes.
Show the 9 response fields and an example
The fields and an example are also on this endpoint's Markdown page.
More in Meetings and calls:Meeting typesBookingsExternal bookingsMeeting briefsCallingAll resources