Skip to Content
Meetings and calls

Booking links

Links people use to book a meeting type.

Meetings and calls4 endpointsKen-Version: 2026-11-02AuthenticationWorkspacesErrors
MarkdownOpenAPI

Headers

The endpoints on this page take these headers. Each endpoint's curl shows the ones it sends.

NameInTypeRequiredDescription
Ken-Versionheaderstring, one of: 2026-11-02, 1.1optionalThe 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-Idheaderinteger (int64)optionalThe 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

GET/v1/booking-linksbooking-links.list
Permission
Calendar view
Rate limit
12,000 requests a minute per API key
Needs the scheduler feature on your workspace. Until it is on, calls answer 404.

Try it on developer.ken.so

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: limit is out of range, or cursor is not valid.
  • 403 forbidden: the API key is not tied to a member of the workspace.

Requires Meetings view.

Parameters

NameInTypeRequiredDescription
limitqueryinteger (int32)optionalNumber of links per page, from 1 to 200. Default 50.
cursorquerystringoptionalThe nextCursor from the previous page. Omit it for the first page.
Request
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

POST/v1/booking-linksbooking-links.create
Permission
Calendar view
Rate limit
4,800 requests a minute per API key
Needs the scheduler feature on your workspace. Until it is on, calls answer 404.

Try it on developer.ken.so

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: kind is missing or unknown, a field does not apply to the kind, a field another field needs is missing, senderAddress is not an email address, accountId or touchId is not the person's, hostMemberId does not host the meeting type, or the host has no default meeting type.
  • 403 forbidden: you need the members permission 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.

FieldTypeRequiredDescription
kindstringoptionalThe kind of link: person or single_use.
personIdinteger (int64)optionalThe person the link is for. Required for a person link.
meetingTypeIdinteger (int64)optionalThe meeting type the link books. On a single-use link it defaults to the host's default type.
hostMemberIdinteger (int64)optionalThe member whose booking page the link opens. Defaults to you; another member needs the members permission.
accountIdinteger (int64)optionalThe person's account the booking belongs to.
campaignIdinteger (int64)optionalThe campaign the link goes out in, on a person link.
stepOrderinteger (int32)optionalThe campaign step the link goes out in. Needs campaignId.
touchIdinteger (int64)optionalThe person's touch the link goes out in, on a person link.
assetIdinteger (int64)optionalThe Studio page the link sits on, on a person link.
sourcestringoptionalWhere 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.
channelstringoptionalThe channel the link goes out on: email, linkedin or web.
senderAddressstringoptionalThe From address of the email the link goes in, on a person link with channel: email.
availabilityAvailabilityScheduleoptionalFor 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.
Request
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

PATCH/v1/booking-links/{bookingLinkId}booking-links.update
Permission
Calendar view
Rate limit
4,800 requests a minute per API key
Needs the scheduler feature on your workspace. Until it is on, calls answer 404.

Try it on developer.ken.so

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

NameInTypeRequiredDescription
bookingLinkIdpathinteger (int64)requiredThe single-use link's id, from the create response or the list.

Request body

application/json, optional.

FieldTypeRequiredDescription
availabilityAvailabilityScheduleoptionalThe 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.
Request
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

GET/v1/booking-links/suggested-timesbooking-links.suggested-times
Permission
Calendar view
Rate limit
12,000 requests a minute per API key
Needs the scheduler feature on your workspace. Until it is on, calls answer 404.

Try it on developer.ken.so

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: personId is missing, senderAddress is not an email address, or meetingTypeId is not one of the member's personal types.
  • 403 forbidden: you need the members permission 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

NameInTypeRequiredDescription
personIdqueryinteger (int64)optionalThe person to suggest times to, by person id. Required.
meetingTypeIdqueryinteger (int64)optionalThe meeting type to book, one of the host's own personal types. Omitted uses the host's default type.
hostMemberIdqueryinteger (int64)optionalThe member whose booking page the link opens, by member id. Omitted means you, and another member's id needs the members permission.
campaignIdqueryinteger (int64)optionalThe campaign of the thread you are answering. A booking through the link then counts for that campaign.
senderAddressquerystringoptionalThe 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.
Request
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.


On this page