Calling
Phone numbers, calls, recordings and call notes.
Path parameters
The endpoints whose path names one of these take it as described here. An endpoint's own table lists a path parameter only when it describes it differently.
| Name | In | Type | Required | Description |
|---|---|---|---|---|
numberId | path | integer (int64) | required | The phone number's id. |
callId | path | integer (int64) | required | The call's id, from the response that started it. |
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 phone numbers
/v1/calling/numberscalling.numbers-list- Permission
- Any workspace member except a Network member
- Rate limit
- 12,000 requests a minute per API key
calling feature on your workspace. Until it is on, calls answer 404.Lists the workspace's numbers that are not released, newest first, in one page (at most five). unpaid is true when Kenso could not charge a number's month; calls from it are refused until it is paid.
Open to any workspace member.
curl -X GET "https://api.ken.so/v1/calling/numbers" \
-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 CallingNumber. Each item has these fields. The response also carries pagination.
Show the 12 response fields and an example
The fields and an example are also on this endpoint's Markdown page.
Buy a phone number
/v1/calling/numberscalling.numbers-buy- Permission
- The
billingandworkspace_settingspermissions - Credits
- Spends credits, price not on the rate card yet (
phone_number_monthly) - Rate limit
- 4,800 requests a minute per API key
calling feature on your workspace. Until it is on, calls answer 404.Buys a local number for 100 credits a month. Send country and, optionally, the e164 picked from the search, an areaCode or a locality: Kenso searches again and buys e164 if still offered, else the first result. assignedMemberId gives it to an active member without a number. cnam is the caller name: up to 15 letters, digits, spaces and .,&-, US numbers only. The number is ordering until the carrier assigns it; Kenso charges the first month when it turns active. Toll-free numbers are not sold. A number inside the plan's included numbers costs no credits.
Errors:
400 validation_failed: a field is missing or breaks its rule.400 invalid_member:assignedMemberIdis not an active member.402 insufficient_credits: the credits do not cover the first month;error.refusalsays how short.402 trial_cap_reached: the workspace is on the Growth trial and already has its included number (error.refusal.metriccalling_numbers).409 member_already_has_number: the member has a number.409 number_limit_reached: the workspace has five numbers.409 no_numbers_available: the search found none.503 provider_unavailable: calling is not set up, or the carrier refused the order. Nothing is charged.
Requires the workspace_settings permission and the billing permission.
Request body
application/json, optional.
| Field | Type | Required | Description |
|---|---|---|---|
e164 | string | optional | The number to buy, in E.164 format, from the search. Kenso searches again before it buys: when that search no longer offers this number, Kenso buys the first number it offers instead. |
country | string | required | Required. The number's country, US or CA; it must be one of the workspace's calling countries. |
areaCode | string | optional | Search this three-digit area code. With a US or Canadian e164 and no area code, Kenso uses the number's own. |
locality | string | optional | Search this city, at most 100 characters. |
assignedMemberId | integer (int64) | optional | The member who calls from the number. They must be active in the workspace and hold no other number. |
cnam | string | optional | The caller name shown with the number's calls: at most 15 letters, digits, spaces and .,&-, on US numbers only. |
curl -X POST "https://api.ken.so/v1/calling/numbers" \
-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 '{
"e164": "string",
"country": "string",
"areaCode": "string",
"locality": "string",
"assignedMemberId": 812,
"cnam": "string"
}'Response 201
data is a CallingNumber.
Show the 12 response fields and an example
The fields and an example are also on this endpoint's Markdown page.
Update a phone number
/v1/calling/numbers/{numberId}calling.numbers-update- Permission
- The
workspace_settingspermission - Rate limit
- 4,800 requests a minute per API key
calling feature on your workspace. Until it is on, calls answer 404.Changes the fields you send. assignedMemberId gives the number to an active member without one; null takes it back. cnam sets the caller name, with the rules of the buy; null clears it.
Errors:
400 validation_failed: a field is unknown, of the wrong type or breaks its rule.400 invalid_member:assignedMemberIdis not an active member.404 not_found: no live number has this id in the workspace.409 invalid_state: the number is releasing, still ordering (for a caller name), or changed meanwhile.409 member_already_has_number: the member has another number.503 provider_unavailable: calling is not set up, or the carrier refused the caller name.
Requires the workspace_settings permission.
Request body
application/json, optional: object.
curl -X PATCH "https://api.ken.so/v1/calling/numbers/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 '{}'Response 200
data is a CallingNumber.
Show the 12 response fields and an example
The fields and an example are also on this endpoint's Markdown page.
Release a phone number
/v1/calling/numbers/{numberId}calling.numbers-release- Permission
- The
billingandworkspace_settingspermissions - Rate limit
- 4,800 requests a minute per API key
calling feature on your workspace. Until it is on, calls answer 404.Gives the number back to the carrier and stops its monthly charge; the paid month is not refunded. Returns it released, or 202 with status: releasing while the carrier has not taken it back: Kenso then finishes by itself, and a repeat delete retries.
Errors:
404 not_found: no number has this id in the workspace.409 invalid_state: the number changed meanwhile.503 provider_unavailable: calling is not set up.
Requires the workspace_settings permission and the billing permission.
curl -X DELETE "https://api.ken.so/v1/calling/numbers/812" \
-H "Authorization: Bearer $KENSO_API_KEY" \
-H "Ken-Version: 2026-11-02" \
-H "X-Ken-Workspace-Id: $KENSO_WORKSPACE_ID"Response 200
Also answers 202. data is a CallingNumber.
Show the 12 response fields and an example
The fields and an example are also on this endpoint's Markdown page.
Start a call
/v1/calling/callscalling.calls-create- Permission
- Accounts edit
- Credits
- Varies with the request (
call_minutes); Spends credits, price not on the rate card yet (call_recording_minutes) - Rate limit
- 4,800 requests a minute per API key
calling feature on your workspace. Until it is on, calls answer 404.Calls a person from your browser. Kenso rings your browser first and dials the person when you answer, so log the browser in with a token from POST /v1/calling/tokens before you start. The call comes back with status: ringing_rep.
Send personId. toNumber must be one of the person's phones; leave it out to call their primary phone. fromNumberId picks the number the call shows; leave it out to use your own number, else the workspace's first active one. Link the call to an open call task with callTaskId, or to a call touch with touchId, which the call's outcome then closes. Send one of them, not both. recording (default true) asks to record the call, and recordingAllowed in the response says whether Kenso will.
Before it dials, Kenso checks the person's calling hours in their time zone, opt-outs, the workspace's calling countries and its limits on calls per person, calls at once and calls per day. It then holds 10 minutes of credits at millicreditsPerMinute and charges the started minutes when the call ends. On a plan with included calling minutes, the US and Canadian minutes still included come off the hold and the charge.
Errors:
400 validation_failed:personIdis missing,callTaskIdis not an open call task of the person,touchIdis not a call touch of the person, or both were sent.400 invalid_phone:toNumberis not one of the person's phones.402 insufficient_credits: the workspace's credits do not cover the hold.402 calling_limit_reached: the hold would pass the monthly calling spend limit.402 member_credit_limit_reached: the hold would pass your own monthly credit limit.402 trial_cap_reached: the workspace is on the Growth trial and has used its included calling minutes (error.refusal.metriccalling_minutes).403 forbidden: the API key is not tied to a member of the workspace.404 not_found: no person, or no touch fortouchId, has this id in the workspace.422 call_refused: Kenso refused the call.details[0].codenames the reason, such asoutside_calling_hours,opted_out,dnc_listed,no_phone,no_numberordaily_limit. For a reason that passes with time,details[0].nextAllowedAtsays when to try again.503 provider_unavailable: calling is not set up yet, or the carrier did not take the call. Nothing is charged.503 try_again: another call in the workspace is starting. Retry after theRetry-Afterheader.
Requires Accounts edit.
Request body
application/json, optional.
| Field | Type | Required | Description |
|---|---|---|---|
personId | integer (int64) | required | Required. The person to call. |
toNumber | string | optional | The number to call, one of the person's phones. Leave it out to call their primary phone. |
fromNumberId | integer (int64) | optional | The workspace number the call shows. Leave it out to use your own number, else the workspace's first active one. |
callTaskId | integer (int64) | optional | An open call task of the person that this call works. Send this or touchId, not both. |
touchId | integer (int64) | optional | A call touch of the person that this call works; the call's outcome closes it. Send this or callTaskId, not both. |
recording | boolean | optional | Record the call where the workspace's settings and the law allow it. Defaults to true. |
curl -X POST "https://api.ken.so/v1/calling/calls" \
-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 '{
"personId": 812,
"toNumber": "string",
"fromNumberId": 812,
"callTaskId": 812,
"touchId": 812,
"recording": true
}'Response 200
data is a CallingCall.
Show the 10 response fields and an example
The fields and an example are also on this endpoint's Markdown page.
Hang up a call
/v1/calling/calls/{callId}/hangupcalling.calls-hangup- Permission
- Accounts edit
- Rate limit
- 4,800 requests a minute per API key
calling feature on your workspace. Until it is on, calls answer 404.Hangs up both sides of a call you placed. You get 202 with the call's current status, and the call ends when the carrier confirms. A call that already ended returns 200 with its final status.
Errors:
403 forbidden: you did not place this call, or the API key is not tied to a member.404 not_found: no call started in Kenso has this id in the workspace.503 provider_unavailable: calling is not set up yet.
Requires Accounts edit.
curl -X POST "https://api.ken.so/v1/calling/calls/812/hangup" \
-H "Authorization: Bearer $KENSO_API_KEY" \
-H "Ken-Version: 2026-11-02" \
-H "X-Ken-Workspace-Id: $KENSO_WORKSPACE_ID"Response 200
Also answers 202. data is a CallingHangup.
Show the 2 response fields and an example
The fields and an example are also on this endpoint's Markdown page.
Drop a voicemail greeting on a call
/v1/calling/calls/{callId}/voicemail-dropcalling.calls-voicemail-drop- Permission
- Accounts edit
- Rate limit
- 4,800 requests a minute per API key
calling feature on your workspace. Until it is on, calls answer 404.Leaves one of your recorded greetings on the person's voicemail. Send voicemailId, or leave it out to use your oldest greeting. The call must be one you placed, the other side must have answered, and the call's voicemailDropMode must not be off.
Kenso waits for the voicemail beep, hangs up your side, plays the greeting and then hangs up. The call is logged with the voicemail outcome. When Kenso heard a person rather than a machine, no beep comes and the greeting plays at once, so ask for the drop after you hear the beep. Do not hang up the call after a drop: that cuts the greeting off.
You get 202 with voicemailDropStatus requested, starting, playing or failed, and 200 once it is dropped. Asking again while a drop is under way returns its state.
Errors:
403 forbidden: you did not place this call, or the API key is not tied to a member.404 not_found: no call started in Kenso has this id in the workspace, orvoicemailIdis not one of your greetings.409 invalid_state: the call ended, nobody has answered yet, or voicemail drops are off for it.409 no_voicemail: you sent novoicemailIdand have no greeting.503 provider_unavailable: calling or Kenso's audio storage is not set up yet.503 try_again: the call is busy. Retry after theRetry-Afterheader.
Requires Accounts edit.
Request body
application/json, optional.
| Field | Type | Required | Description |
|---|---|---|---|
voicemailId | integer (int64) | optional | One of your greetings. Leave it out to drop your oldest. |
curl -X POST "https://api.ken.so/v1/calling/calls/812/voicemail-drop" \
-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 '{
"voicemailId": 812
}'Response 200
Also answers 202. data is a CallingVoicemailDrop.
Show the 3 response fields and an example
The fields and an example are also on this endpoint's Markdown page.
Create a browser calling token
/v1/calling/tokenscalling.tokens-create- Permission
- Accounts edit
- Rate limit
- 4,800 requests a minute per API key
calling feature on your workspace. Until it is on, calls answer 404.Returns a WebRTC login token for your browser, with your sipUsername and the token's expiresAt. The browser logs in with it so it can answer the calls you start. The token is a secret: keep it in memory and do not store it. Create a new one when it expires.
Errors:
403 forbidden: the API key is not tied to a member of the workspace.422 call_refused: calling is not available right now (calling_disabled).503 provider_unavailable: calling is not set up yet, or the carrier cannot be reached.
Requires Accounts edit.
curl -X POST "https://api.ken.so/v1/calling/tokens" \
-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 CallingToken.
Show the 3 response fields and an example
The fields and an example are also on this endpoint's Markdown page.
Get calling settings
/v1/calling/settingscalling.settings-get- Permission
- Any workspace member except a Network member
- Rate limit
- 12,000 requests a minute per API key
calling feature on your workspace. Until it is on, calls answer 404.Returns the workspace's calling settings. Until they are saved, the defaults apply and updatedAt is null.
Open to any workspace member.
curl -X GET "https://api.ken.so/v1/calling/settings" \
-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 CallingSettings.
Show the 9 response fields and an example
The fields and an example are also on this endpoint's Markdown page.
Update calling settings
/v1/calling/settingscalling.settings-update- Permission
- The
workspace_settingspermission - Rate limit
- 4,800 requests a minute per API key
calling feature on your workspace. Until it is on, calls answer 404.Changes the fields you send; none takes null. recordingEnabled records calls. consentNotice says when the person hears the call may be recorded: auto (where the law asks), always or never, which skips recording where all parties must consent. voicemailDropMode is off, manual or auto. voicemailToMobile: true needs acceptTcpaNotice: true in the same body, which records who accepted and when. allowedCountries holds US, CA or both. dncScrub is saved for an outside do-not-call list Kenso does not check yet; numbers of opted-out people are always refused.
Errors:
400 validation_failed: a field is unknown, null, of the wrong type or not one of its values, oracceptTcpaNotice: trueis missing.
Requires the workspace_settings permission.
Request body
application/json, optional: object.
curl -X PATCH "https://api.ken.so/v1/calling/settings" \
-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 '{}'Response 200
data is a CallingSettings.
Show the 9 response fields and an example
The fields and an example are also on this endpoint's Markdown page.
Search phone numbers for sale
/v1/calling/numbers/availablecalling.numbers-available- Permission
- The
workspace_settingspermission - Rate limit
- 12,000 requests a minute per API key
calling feature on your workspace. Until it is on, calls answer 404.Returns up to 10 local numbers to buy in country (required: US or CA, one of the workspace's calling countries), optionally in a three-digit areaCode or a city in locality.
Errors:
400 validation_failed:country,areaCodeorlocalityis missing or invalid.503 provider_unavailable: calling is not set up, or the carrier cannot be reached.
Requires the workspace_settings permission.
Parameters
| Name | In | Type | Required | Description |
|---|---|---|---|---|
country | query | string | optional | Required. The country to search, US or CA; it must be one of the workspace's calling countries. |
areaCode | query | string | optional | Only numbers in this three-digit area code, like 415. |
locality | query | string | optional | Only numbers in this city, at most 100 characters. |
curl -X GET "https://api.ken.so/v1/calling/numbers/available" \
-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 AvailableCallingNumber. Each item has these fields. The response also carries pagination.
Show the 5 response fields and an example
The fields and an example are also on this endpoint's Markdown page.
Get the call rate for a number
/v1/calling/ratescalling.rates-get- Permission
- Any workspace member except a Network member
- Rate limit
- 12,000 requests a minute per API key
calling feature on your workspace. Until it is on, calls answer 404.Returns what a call to to costs per started minute, in millicredits (1,000 are 1 credit), covering both sides of the call; recordingMillicreditsPerMinute is added when it is recorded. An unpriced destination is priced: false with null rates, and calls to it are refused.
Errors:
400 invalid_phone:tois missing or not a phone number.
Open to any workspace member.
Parameters
| Name | In | Type | Required | Description |
|---|---|---|---|---|
to | query | string | optional | The number to price, in E.164 format, like +14155550100. |
curl -X GET "https://api.ken.so/v1/calling/rates" \
-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 CallingRate.
Show the 6 response fields and an example
The fields and an example are also on this endpoint's Markdown page.
Get the calling spend limit
/v1/calling/spend-limitcalling.spend-limit-get- Permission
- Any workspace member except a Network member
- Rate limit
- 12,000 requests a minute per API key
calling feature on your workspace. Until it is on, calls answer 404.Returns the monthly calling spend limit and this UTC month's calling spend, in millicredits. Null is no limit; until one is set it is 2,000 credits with isDefault: true. The spend counts call minutes, recordings and the holds of calls in progress, not number fees.
Open to any workspace member.
curl -X GET "https://api.ken.so/v1/calling/spend-limit" \
-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 CallingSpendLimit.
Show the 3 response fields and an example
The fields and an example are also on this endpoint's Markdown page.
Update the calling spend limit
/v1/calling/spend-limitcalling.spend-limit-update- Permission
- The
billingandworkspace_settingspermissions - Rate limit
- 4,800 requests a minute per API key
calling feature on your workspace. Until it is on, calls answer 404.Sets monthlyLimitMillicredits: 1 to 100,000,000, or null for no limit. The next call checks it; a call that would pass it gets 402 calling_limit_reached.
Errors:
400 validation_failed: the field is missing, not a whole number or out of range, or another was sent.
Requires the workspace_settings permission and the billing permission.
Request body
application/json, optional: object.
curl -X PATCH "https://api.ken.so/v1/calling/spend-limit" \
-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 '{}'Response 200
data is a CallingSpendLimit.
Show the 3 response fields and an example
The fields and an example are also on this endpoint's Markdown page.
List your voicemail greetings
/v1/calling/voicemailscalling.voicemails-list- Permission
- Any workspace member except a Network member
- Rate limit
- 12,000 requests a minute per API key
calling feature on your workspace. Until it is on, calls answer 404.Lists your greetings, oldest first. Each member keeps their own, up to five. The first one is the greeting an auto drop plays and the one a drop uses when you name none. audioUrl lets you listen to it for 5 minutes, and is missing while Kenso's audio storage is not set up.
Errors:
403 forbidden: the API key is not tied to a member of the workspace.
Open to any workspace member.
curl -X GET "https://api.ken.so/v1/calling/voicemails" \
-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 CallingVoicemail. Each item has these fields. The response also carries pagination.
Show the 6 response fields and an example
The fields and an example are also on this endpoint's Markdown page.
Upload a voicemail greeting
/v1/calling/voicemailscalling.voicemails-create- Permission
- Accounts edit
- Rate limit
- 480 requests a minute per API key
calling feature on your workspace. Until it is on, calls answer 404.Uploads a greeting as multipart/form-data. file is a WAV or MP3 recording of at most 12 MiB and 60 seconds; Kenso reads the format from the audio itself. name is optional, at most 80 characters, and defaults to Voicemail. You can keep up to five greetings.
Errors:
400 validation_failed:nameis too long, orfileis missing or too big (invalid), in another format such as WebM or Ogg (unsupported_audio), unreadable (unreadable_audio) or longer than 60 seconds (too_long).403 forbidden: the API key is not tied to a member of the workspace.409 voicemail_limit_reached: you already have five greetings. Delete one first.503 provider_unavailable: Kenso's audio storage is not set up or cannot be reached.503 try_again: another of your greetings is uploading. Retry after theRetry-Afterheader.
Requires Accounts edit.
Request body
multipart/form-data, optional.
| Field | Type | Required | Description |
|---|---|---|---|
file | string (binary) | optional | |
name | string | optional |
curl -X POST "https://api.ken.so/v1/calling/voicemails" \
-H "Authorization: Bearer $KENSO_API_KEY" \
-H "Ken-Version: 2026-11-02" \
-H "X-Ken-Workspace-Id: $KENSO_WORKSPACE_ID" \
-F "file=@./file" \
-F 'name=string'Response 201
data is a CallingVoicemail.
Show the 6 response fields and an example
The fields and an example are also on this endpoint's Markdown page.
Delete a voicemail greeting
/v1/calling/voicemails/{voicemailId}calling.voicemails-delete- Permission
- Accounts edit
- Rate limit
- 4,800 requests a minute per API key
calling feature on your workspace. Until it is on, calls answer 404.Deletes one of your greetings and its audio. A drop that has not played it yet fails.
Errors:
403 forbidden: the API key is not tied to a member of the workspace.404 not_found: the greeting is not yours or is already deleted.
Requires Accounts edit.
Parameters
| Name | In | Type | Required | Description |
|---|---|---|---|---|
voicemailId | path | integer (int64) | required | The greeting's id. |
curl -X DELETE "https://api.ken.so/v1/calling/voicemails/812" \
-H "Authorization: Bearer $KENSO_API_KEY" \
-H "Ken-Version: 2026-11-02" \
-H "X-Ken-Workspace-Id: $KENSO_WORKSPACE_ID"Response 204
HTTP/1.1 204 No ContentMore in Meetings and calls:Meeting typesBooking linksBookingsExternal bookingsMeeting briefsAll resources