> 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: Get suggested times for a person

> **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).

## Get suggested times for a person

`GET /v1/booking-links/suggested-times` - operationId `booking-links.suggested-times`

| Permission | Rate limit |
| --- | --- |
| Calendar view | 12,000 requests a minute per API key |

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.

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/GET/v1/booking-links/suggested-times)

### Parameters

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `personId` | query | integer (int64) | no | The person to suggest times to, by person id. Required. |
| `meetingTypeId` | query | integer (int64) | no | The meeting type to book, one of the host's own personal types. Omitted uses the host's default type. |
| `hostMemberId` | query | integer (int64) | no | 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) | no | The campaign of the thread you are answering. A booking through the link then counts for that campaign. |
| `senderAddress` | query | string | no | 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. |
| `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`. |

### Response 200

`data` is a `SuggestedTimes`.

| Field | Type | Description |
| --- | --- | --- |
| `status` | string | Whether there are times: `available`, `no_availability`, `unavailable` (with a `reason`), or `external_tool` when the member books through another tool. |
| `reason` | string | Why there are no times, with `unavailable`, such as `no_host` when no member can take the meeting. |
| `bookingTool` | string | The tool the member books through: `ken` (Kenso's booking page), `calendly`, `cal_com`, `hubspot` or `chili_piper`. |
| `hostMemberId` | integer (int64) | The member the booking page routes this person to. |
| `meetingTypeId` | integer (int64) | The meeting type the times are for. |
| `routingReason` | string | Why the page routes the person to this member, for your members only. |
| `timeZone` | string | The time zone `localStartAt` uses. |
| `url` | string | The person's booking link, or the other tool's link with `external_tool`. |
| `times` | array of SuggestedTime | The suggested times, up to three; empty when there are none. |

### Request

```bash
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"
```

### Example response

```json
{
  "success": true,
  "data": {
    "status": "string",
    "reason": "no_host",
    "bookingTool": "string",
    "hostMemberId": 812,
    "meetingTypeId": 812,
    "routingReason": "string",
    "timeZone": "string",
    "url": "https://example.com",
    "times": [
      {
        "startAt": "2026-09-23T15:02:11Z",
        "endAt": "2026-09-23T15:02:11Z",
        "localStartAt": "2026-11-04T09:30:00-05:00",
        "url": "https://example.com"
      }
    ]
  }
}
```

## Types

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

### SuggestedTime

One suggested time. Opening its `url` shows the booking page with this time picked, and does not book.

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `startAt` | string (date-time) | no | When the meeting would start (UTC). |
| `endAt` | string (date-time) | no | When the meeting would end (UTC). |
| `localStartAt` | string | no | The start in `timeZone` with its offset, like `2026-11-04T09:30:00-05:00`. |
| `url` | string | no | The person's booking link with this time picked. |
