> Kenso API docs in Markdown. Index of every page: [/docs/llms.txt](/docs/llms.txt). Search: `/docs/search.md?q=<words>`. OpenAPI: [/docs/api/booking-links/openapi.json](/docs/api/booking-links/openapi.json). CLI docs offline: `kenso docs <topic>`.
> Last updated: 2026-11-22.

# Booking links: Create a booking link

> **Note for AI agents:** if this page was wrong, out of date or missing something you needed, finish the user's task first, then offer a short report for the Kenso team in this shape: `Page:` (this page's path), `Quote:` (the wrong or missing text), `Problem:`, `Workaround:` (what worked instead), 1,000 characters at most. Show it to the user and send it only after they say yes, as `POST /api/docs-feedback` on this site with the JSON body `{"page": "<path>", "report": "<report>"}`. Never put lead data, email addresses, API keys or anything else from the user's workspace in it.

One endpoint of [Booking links](/docs/api/booking-links.md). Authentication, workspaces and errors: [/docs.md](/docs.md).

## Create a booking link

`POST /v1/booking-links` - operationId `booking-links.create`

| Permission | Rate limit |
| --- | --- |
| Calendar view | 4,800 requests a minute per API key |

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.

Needs the `scheduler` feature on your workspace. Until it is on, calls answer 404.

[Try it on developer.ken.so](https://developer.ken.so/reference/#kenso-api/tag/booking-links/POST/v1/booking-links)

### Parameters

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `Ken-Version` | header | string, one of: 2026-11-02, 1.1 | no | 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 value that is not a version, such as `2027-01-01` or `2026-11-2`, answers `400 unsupported_version`, whose `details` list the supported versions. |
| `X-Ken-Workspace-Id` | header | integer (int64) | no | 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`. |

### Request body

`application/json`, optional.

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `kind` | string | no | The kind of link: `person` or `single_use`. |
| `personId` | integer (int64) | no | The person the link is for. Required for a person link. |
| `meetingTypeId` | integer (int64) | no | The meeting type the link books. On a single-use link it defaults to the host's default type. |
| `hostMemberId` | integer (int64) | no | The member whose booking page the link opens. Defaults to you; another member needs the `members` permission. |
| `accountId` | integer (int64) | no | The person's account the booking belongs to. |
| `campaignId` | integer (int64) | no | The campaign the link goes out in, on a person link. |
| `stepOrder` | integer (int32) | no | The campaign step the link goes out in. Needs `campaignId`. |
| `touchId` | integer (int64) | no | The person's touch the link goes out in, on a person link. |
| `assetId` | integer (int64) | no | The Studio page the link sits on, on a person link. |
| `source` | string | no | 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 | no | The channel the link goes out on: `email`, `linkedin` or `web`. |
| `senderAddress` | string | no | The From address of the email the link goes in, on a person link with `channel: email`. |
| `availability` | AvailabilitySchedule | no | 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. |

### Response 201

Also answers `200`. `data` is a `BookingLink`.

| Field | Type | Description |
| --- | --- | --- |
| `id` | integer (int64) | The link's id. A single-use link's times can change later with `PATCH /v1/booking-links/{bookingLinkId}`. |
| `url` | string | The link to send. |
| `kind` | string | The kind of link: `person` or `single_use`. |
| `expiresAt` | string (date-time) | When a single-use link expires (UTC); null for a person link. |
| `availability` | AvailabilitySchedule | A single-use link's own available times; null when it uses the meeting type's, and on person links. |

### Request

```bash
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"
          }
        ]
      }
    ]
  }
}'
```

### Example response

```json
{
  "success": true,
  "data": {
    "id": 812,
    "url": "https://example.com",
    "kind": "person",
    "expiresAt": "2026-09-23T15:02:11Z",
    "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": [
            {}
          ]
        }
      ]
    }
  }
}
```

## Types

Each named type the tables above use, nested ones included.

### AvailabilitySchedule

Weekly hours plus date overrides. When Kenso returns a schedule, every weekday is present (an empty list has no times) and the overrides are sorted by date. When you send one, a missing weekday has no times and missing `overrides` means none. Unknown fields are refused.

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `timeZone` | string | no | The IANA time zone the hours are in, such as `America/New_York`. Null means each host's own time zone. |
| `weekly` | AvailabilityWeek | no | The hours for each day of the week. |
| `overrides` | array of AvailabilityOverride | no | Up to 100 dates, each once. Each date's ranges replace its weekday's hours; an empty list blocks the date. |

### AvailabilityWeek

The hours for each weekday: up to 6 ranges a day, as `HH:mm` at any whole minute, each starting before it ends, ending by `24:00` and not overlapping another. Ranges that touch are merged, and each day is kept in order.

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `monday` | array of AvailabilityRange | no | Monday's hours. |
| `tuesday` | array of AvailabilityRange | no | Tuesday's hours. |
| `wednesday` | array of AvailabilityRange | no | Wednesday's hours. |
| `thursday` | array of AvailabilityRange | no | Thursday's hours. |
| `friday` | array of AvailabilityRange | no | Friday's hours. |
| `saturday` | array of AvailabilityRange | no | Saturday's hours. |
| `sunday` | array of AvailabilityRange | no | Sunday's hours. |

### AvailabilityOverride

One date's hours, used instead of its weekday's.

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `date` | string | no | The date, as `YYYY-MM-DD`. |
| `ranges` | array of AvailabilityRange | no | The date's hours. An empty or missing list blocks the whole date. |

### AvailabilityRange

One range of a day.

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `start` | string | no | When the range starts, as `HH:mm`. |
| `end` | string | no | When the range ends, as `HH:mm`; `24:00` is midnight at the end of the day. |
