Contacts
List, search, read, update and remove contacts, add them to campaigns and change many in one call.
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 |
|---|---|---|---|---|
contactId | path | integer (int64) | required | The contact id. |
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 contacts
/v1/contactscontacts.list- Permission
- Campaigns view
- Rate limit
- 12,000 requests a minute per API key
Returns the workspace's contacts, ordered by id. Deleted contacts are left out. The query parameters narrow the list to one campaign, segment or company, an email address, a person (personId: their contact in each campaign they are in), a name search, a qualified or do-not-contact state, or a creation time range.
sort=createdAt lists by each contact's createdAt, oldest first, and sort=-createdAt newest first. Keep the same sort while you page: a cursor from another order is refused.
Each contact on a page counts against the workspace's daily allowance of API read rows. Past it, the call returns 429 quota_exceeded with a Retry-After header. To filter on more than one campaign, on contact fields or on another sort order, use POST /v1/contacts/search.
Errors:
400 validation_failed:limitis not between 1 and 200,sortis notcreatedAtor-createdAt,cursoris not valid or comes from anothersort, orcreatedBeforeis not later thancreatedAfter.429 quota_exceeded: the workspace used up its API read rows for the day.
Requires Campaigns view.
Parameters
| Name | In | Type | Required | Description |
|---|---|---|---|---|
campaignId | query | integer (int64) | optional | Only contacts in this campaign. |
companyId | query | integer (int64) | optional | Only contacts at this company, matched on the contact's companyId. |
segmentId | query | integer (int64) | optional | Only contacts in this campaign segment. |
email | query | string | optional | Only contacts that have this email address. The match is exact and ignores case. |
personId | query | integer (int64) | optional | Only the contacts of this person, one per campaign they are in. |
q | query | string | optional | Free-text search on the first name, last name, full name and email addresses. It matches any part of a value and ignores case. |
isQualified | query | boolean | optional | True keeps only qualified contacts, false only unqualified ones. Omitted keeps both. |
doNotContact | query | boolean | optional | True keeps only do-not-contact contacts, false only the others. Omitted keeps both. |
createdAfter | query | string (date-time) | optional | Only contacts created at or after this time, in UTC. |
createdBefore | query | string (date-time) | optional | Only contacts created before this time, in UTC. Must be later than createdAfter. |
sort | query | string | optional | The order, by each contact's createdAt: createdAt lists oldest first and -createdAt newest first. Omitted keeps the id order. Keep the same sort while you page. |
limit | query | integer (int32) | optional | Contacts per page, from 1 to 200. Default 50. |
cursor | query | string | optional | The nextCursor of the previous page. Omitted starts at the first page. |
curl -X GET "https://api.ken.so/v1/contacts?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 Contact. Each item has these fields. The response also carries pagination.
Show the 96 response fields and an example
The fields and an example are also on this endpoint's Markdown page.
Add contacts to a campaign
/v1/campaigns/{campaignId}/contactscontacts.create- Permission
- Campaigns edit
- Rate limit
- 480 requests a minute per API key
Adds up to 1,000 people to a campaign, or updates them when the campaign already has them. A row matches an existing contact of the campaign by email, or by LinkedIn URL for a row without an email in a campaign with only LinkedIn steps. results reports each row in request order: created, updated, skipped or failed, with a reason and message when the row was not saved.
Kenso saves the rows in batches of 100. A later batch can fail after earlier ones saved, and a retry of the same body is safe. A row on the workspace blocklist is not saved: it is failed with reason blocklisted. A row that matches a contact already marked do-not-contact is updated with sendable false. A contact the plan has no allowance left for is added unqualified, with sendable false.
A row with useKenEmail and no email takes a recently verified address from Kenso's email database when it has one, free, for the first 25 such rows of the request. A row with emailValidity safe qualifies a new contact in a campaign without AI qualification and uses one contact from the plan's allowance.
A row with a malformed customImageUrl or customVideo or a bad custom variable key fails before anything is written. When the workspace does not have campaign images or campaign videos, the contact is saved and the row fails. A batch that would take the campaign past 50 custom variables fails every row in it.
Errors:
400 validation_failed:contactsis missing or empty, or holds more than 1,000 rows.404 not_found: no campaign with this id in the workspace.
Requires Campaigns edit.
Parameters
| Name | In | Type | Required | Description |
|---|---|---|---|---|
campaignId | path | integer (int64) | required | The campaign to add the contacts to. |
Request body
application/json, optional.
| Field | Type | Required | Description |
|---|---|---|---|
contacts | array of CreateCampaignContactRequest | required | Required. From 1 to 1,000 contacts, processed in request order. |
curl -X POST "https://api.ken.so/v1/campaigns/812/contacts" \
-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 '{
"contacts": [
{
"email": "[email protected]",
"firstName": "Amanda",
"lastName": "Chen",
"title": "VP of Engineering",
"linkedInUrl": "https://www.linkedin.com/in/amanda-chen-northwind",
"companyName": "Northwind Labs",
"companyDomain": "northwind.example.com",
"customVariables": {
"open_roles": "12 engineering roles"
},
"emailValidity": "safe"
},
{
"email": "[email protected]",
"firstName": "Priya",
"lastName": "Shah",
"title": "Engineering Manager",
"companyName": "Northwind Labs",
"companyDomain": "northwind.example.com"
}
]
}'Response 200
data is a ContactBulkResult.
Show the 3 response fields and an example
The fields and an example are also on this endpoint's Markdown page.
Get a contact
/v1/contacts/{contactId}contacts.get- Permission
- Campaigns view
- Rate limit
- 12,000 requests a minute per API key
Returns one contact with two fields the list, search and update responses leave out: dataFlags, signals about the contact's data such as a job change, and personalEmails, personal addresses found for the person. Kenso never sends to, verifies or exports a personal address. It also returns linkedInWait when the contact's LinkedIn connection request cannot go out yet, with the reason and a message ready to show.
A read of one contact does not count against the workspace's API read rows.
Errors:
404 not_found: no contact with this id in the workspace, or the contact is deleted.
Requires Campaigns view.
curl -X GET "https://api.ken.so/v1/contacts/812" \
-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 ContactDetail.
Show the 99 response fields and an example
The fields and an example are also on this endpoint's Markdown page.
Update a contact
/v1/contacts/{contactId}contacts.update- Permission
- Campaigns edit
- Rate limit
- 4,800 requests a minute per API key
Changes the fields you send and returns the updated contact. A field you leave out stays as it is, and null clears a text field. A field the body does not define is refused.
outreachLanguage sets the language Ken writes to the contact in, as a locale such as fr-FR or es-MX or a language code such as de. Kenso locks a language you set, so no import, enrichment or reply changes it. Null clears the language and unlocks it.
customVariables is an object of string or null values. A string sets that key, null or an empty string removes it, and keys you leave out stay. A key new to the campaign is added to the campaign's custom variables. The object itself cannot be null.
customImageUrl is the contact's own image, shown in emails as {{custom_image}}: a public https URL of at most 2,048 characters. Kenso downloads and hosts the image. customVideo is the contact's own video, shown as {{custom_video}}: a Loom, YouTube, Vimeo, Wistia, Vidyard, Sendspark or HeyGen share link or embed code, at most 20,480 characters, on a contact in a campaign. An empty string or null clears either one.
Errors:
400 validation_failed: the body is not a JSON object, a field is unknown or invalid,isQualifiedordoNotContactis null, the email is already another contact's or is one of the contact's personal addresses, or the workspace does not have campaign images or campaign videos. The error names the field.404 not_found: no contact with this id in the workspace, or the contact is deleted.409 video_in_use: a sent or queued email step uses the contact's current video, so it cannot change. The old video stays.
Requires Campaigns edit.
Request body
application/json, required.
| Field | Type | Required | Description |
|---|---|---|---|
firstName | string | optional | First name. Null clears it. |
lastName | string | optional | Last name. Null clears it. |
title | string | optional | Job title. Null clears it. |
linkedInUrl | string | optional | LinkedIn profile URL. Null clears it. |
location | string | optional | Location. Null clears it. |
email | string | optional | The contact's email address. It must be valid, not another contact's address and not one of the contact's personal addresses. Null removes it. |
isQualified | boolean | optional | True or false to mark the contact qualified or not. Null is refused. |
doNotContact | boolean | optional | True to mark the contact do-not-contact, so Kenso sends it nothing, or false to clear that. Null is refused. |
outreachLanguage | string | optional | The language Ken writes to the contact in: a locale such as fr-FR or es-MX, or a language code such as de. Kenso locks it, so no import, enrichment or reply changes it. Null clears and unlocks it. |
customVariables | map of string | optional | Values to merge into the contact's custom variables, by key. A string sets the key, and null or an empty string removes it. Keys you leave out stay. The object itself cannot be null. |
customImageUrl | string | optional | The contact's own image, shown in emails as {{custom_image}}: a public https URL of at most 2,048 characters, which Kenso downloads and hosts. An empty string or null clears it. Needs campaign images on the workspace. |
customVideo | string | optional | The contact's own video, shown in emails as {{custom_video}}: a Loom, YouTube, Vimeo, Wistia, Vidyard, Sendspark or HeyGen share link or embed code, at most 20,480 characters. An empty string or null clears it. Needs campaign videos on the workspace and a contact in a campaign. While a sent or queued step uses the current video, it cannot change. |
curl -X PATCH "https://api.ken.so/v1/contacts/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 '{
"title": "SVP of Engineering",
"location": "Austin, Texas, United States",
"isQualified": true,
"doNotContact": false,
"outreachLanguage": "en-US",
"customVariables": {
"open_roles": "15 engineering roles"
}
}'Response 200
data is a Contact.
Show the 96 response fields and an example
The fields and an example are also on this endpoint's Markdown page.
Delete a contact
/v1/contacts/{contactId}contacts.delete- Permission
- Campaigns edit
- Rate limit
- 4,800 requests a minute per API key
Deletes the contact. Kenso keeps the record, so POST /v1/contacts/bulk-restore can bring it back. A deleted contact leaves every list and read, and its campaign sends it nothing more.
Errors:
404 not_found: no contact with this id in the workspace, or the contact is deleted.
Requires Campaigns edit.
curl -X DELETE "https://api.ken.so/v1/contacts/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 ContentDelete contacts in bulk
/v1/contacts/bulk-deletecontacts.bulk-delete- Permission
- Campaigns edit
- Rate limit
- 480 requests a minute per API key
Deletes up to 1,000 contacts in one call, as the single delete does. succeeded lists the ids this call deleted. An id that is not a contact in the workspace is in failed with code not_found and nothing changes for it.
Errors:
400 validation_failed:idsis missing or empty, holds more than 1,000 ids, or holds an id that is not positive.
Requires Campaigns edit.
Request body
application/json, optional.
| Field | Type | Required | Description |
|---|---|---|---|
ids | array of integer (int64) | required | Required. From 1 to 1,000 contact ids in the workspace. |
curl -X POST "https://api.ken.so/v1/contacts/bulk-delete" \
-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 '{
"ids": [
90125,
90126,
90131
]
}'Response 200
data is a ContactBulkResult.
Show the 3 response fields and an example
The fields and an example are also on this endpoint's Markdown page.
Pause sequences for contacts
/v1/contacts/bulk-pausecontacts.bulk-pause- Permission
- Campaigns edit and the
launchpermission - Rate limit
- 480 requests a minute per API key
pause_leads feature on your workspace. Until it is on, calls answer 404.Stops the campaign sequence of up to 1,000 contacts. Each paused contact gets sequenceStopReason paused and a sequenceStoppedAt time, and its pending unsent steps are cancelled. A paused contact is not do-not-contact and stays in its campaign. Resume it with POST /v1/contacts/bulk-resume.
succeeded lists every id that is paused after the call, including contacts that were already paused, so a retry is safe. Every other id is in failed with one of these codes:
already_stopped: the sequence already stopped for another reason, which stays.do_not_contact: the contact is do-not-contact.not_found: the id is not a contact in the workspace, the contact is deleted, or it is in no campaign.internal_error: the pause failed. Retry that id.
Errors:
400 validation_failed:idsis missing or empty, holds more than 1,000 ids, or holds an id that is not positive.
Requires Campaigns edit and the launch permission.
Request body
application/json, optional.
| Field | Type | Required | Description |
|---|---|---|---|
ids | array of integer (int64) | required | Required. From 1 to 1,000 contact ids in the workspace. |
curl -X POST "https://api.ken.so/v1/contacts/bulk-pause" \
-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 '{
"ids": [
90125,
90126,
90131
]
}'Response 200
data is a ContactBulkResult.
Show the 3 response fields and an example
The fields and an example are also on this endpoint's Markdown page.
Resume sequences for paused contacts
/v1/contacts/bulk-resumecontacts.bulk-resume- Permission
- Campaigns edit and the
launchpermission - Rate limit
- 480 requests a minute per API key
Restarts the campaign sequence of up to 1,000 paused contacts. Only a stop with sequenceStopReason paused is cleared. Kenso plans the next steps of resumed contacts on its next planning pass, about every 10 minutes, and a held LinkedIn step picks up within the hour.
succeeded lists the ids this call resumed. Every other id is in failed with one of these codes:
not_paused: the sequence is running, or it stopped for another reason, which stays.not_found: the id is not a contact in the workspace.
Errors:
400 validation_failed:idsis missing or empty, holds more than 1,000 ids, or holds an id that is not positive.
Requires Campaigns edit and the launch permission.
Request body
application/json, optional.
| Field | Type | Required | Description |
|---|---|---|---|
ids | array of integer (int64) | required | Required. From 1 to 1,000 contact ids in the workspace. |
curl -X POST "https://api.ken.so/v1/contacts/bulk-resume" \
-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 '{
"ids": [
90125,
90126,
90131
]
}'Response 200
data is a ContactBulkResult.
Show the 3 response fields and an example
The fields and an example are also on this endpoint's Markdown page.
Update contacts in bulk
/v1/contacts/bulk-updatecontacts.bulk-update- Permission
- Campaigns edit
- Rate limit
- 480 requests a minute per API key
Updates up to 1,000 contacts in one call. Each item is a contactId plus any fields PATCH /v1/contacts/{contactId} accepts, with the same rules. Items run one at a time in request order, and a problem with one item fails only that item.
results has one entry per item in request order. Its status is updated, not_found (no such contact in the workspace), validation_failed (a field is invalid), video_in_use (a sent or queued step uses the contact's video) or failed. After 5 failed items in a row, Kenso stops and marks every remaining item failed with a message asking you to retry it.
Errors:
400 validation_failed: nothing was written, becauseitemsis empty, holds more than 1,000 entries, holds an entry that is not an object or has no positivecontactId, or repeats acontactId.
Requires Campaigns edit.
Request body
application/json, required.
| Field | Type | Required | Description |
|---|---|---|---|
items | array of BulkUpdateContactItemBody | required | Required. From 1 to 1,000 items, run in request order. |
curl -X POST "https://api.ken.so/v1/contacts/bulk-update" \
-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 '{
"items": [
{
"contactId": 90125,
"title": "SVP of Engineering",
"customVariables": {
"open_roles": "15 engineering roles"
}
},
{
"contactId": 90131,
"doNotContact": true
}
]
}'Response 200
data is a ContactBulkUpdateResult.
Show the 3 response fields and an example
The fields and an example are also on this endpoint's Markdown page.
Restore deleted contacts
/v1/contacts/bulk-restorecontacts.bulk-restore- Permission
- Campaigns edit
- Rate limit
- 480 requests a minute per API key
Brings back up to 1,000 deleted contacts, the undo of a delete. Each contact returns to the campaign and segment it was deleted from, with its emails and fields unchanged. Nothing is charged and no enrichment runs again.
A restored contact in an active campaign can get its next email steps again. LinkedIn steps that stopped while the contact was deleted stay stopped. A contact your client removed during a lead list approval comes back too, and the approval does not change.
succeeded lists the ids this call restored, and restored counts them. Every other id is in failed with one of these codes:
not_deleted: the contact is not deleted, so nothing changed.skippedcounts these, and a retry of an id already restored returns this code.not_found: the id is not a contact in the workspace.internal_error: the restore failed. Retry that id.
Errors:
400 validation_failed:idsis missing or empty, holds more than 1,000 ids, or holds an id that is not positive.
Requires Campaigns edit.
Request body
application/json, optional.
| Field | Type | Required | Description |
|---|---|---|---|
ids | array of integer (int64) | required | Required. From 1 to 1,000 contact ids in the workspace. |
curl -X POST "https://api.ken.so/v1/contacts/bulk-restore" \
-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 '{
"ids": [
90125,
90126,
90131
]
}'Response 200
data is a ContactBulkRestoreResult.
Show the 4 response fields and an example
The fields and an example are also on this endpoint's Markdown page.
Search contacts
/v1/contacts/searchcontacts.search- Permission
- Campaigns view
- Rate limit
- 12,000 requests a minute per API key
Finds contacts with the list filters plus more: several campaigns at once, field conditions in filters, a set of contact ids, readyOnly for the contacts a campaign can send to now, awaitingFirstEmail for the ready leads its readyLeadCount counts, and the email security gateway or mailbox host of each contact's first Safe or Verified email. Deleted contacts are left out.
Results are ordered by contact id unless you set sort. Keep the same body and sort while you page with cursor. The response has no total count. Each contact on a page counts against the workspace's API read rows, as on the list.
Errors:
400 validation_failed: a body field breaks its rule. Examples: more than 50campaignIdsor 1,000contactIds,readyOnlyorawaitingFirstEmailwithout exactly one campaign, an unknownsortfield,directionwithoutsort, a badlimitorcursor,createdBeforenot later thancreatedAfter, abehaviorTagcondition without thebehavior_signalsfeature, or a gateway or mailbox filter on a workspace without security gateways. The error names the field.429 quota_exceeded: the workspace used up its API read rows for the day.
Requires Campaigns view.
Request body
application/json, optional.
| Field | Type | Required | Description |
|---|---|---|---|
campaignIds | array of integer (int64) | optional | Only contacts in these campaigns, at most 50 ids. |
companyId | integer (int64) | optional | Only contacts at this company, matched on the contact's companyId. |
segmentId | integer (int64) | optional | Only contacts in this campaign segment. |
email | string | optional | Only contacts that have this email address. The match is exact and ignores case. |
q | string | optional | Free-text search on the first name, last name, full name and email addresses. It matches any part of a value and ignores case. |
isQualified | boolean | optional | True keeps only qualified contacts, false only unqualified ones. Omitted keeps both. |
doNotContact | boolean | optional | True keeps only do-not-contact contacts, false only the others. Omitted keeps both. |
createdAfter | string (date-time) | optional | Only contacts created at or after this time, in UTC. |
createdBefore | string (date-time) | optional | Only contacts created before this time, in UTC. Must be later than createdAfter. |
filters | array of ContactSearchFilterGroup | optional | Field conditions joined with AND or OR, at most 20 groups. A behaviorTag condition needs the behavior_signals feature on the workspace. |
readyOnly | boolean | optional | True keeps only the contacts the campaign can send to now. Needs exactly one id in campaignIds. Default false. |
awaitingFirstEmail | boolean | optional | True keeps only the campaign's ready leads still waiting for their first email: the leads its readyLeadCount counts. Narrower than readyOnly, which also keeps leads already emailed. Needs exactly one id in campaignIds. Default false. |
contactIds | array of integer (int64) | optional | Only these contacts, at most 1,000 ids. |
securityGateway | array of string | optional | Only contacts whose first Safe or Verified email sits behind one of these email security gateways: a gateway slug such as proofpoint, or none or pending. At most 100 values, and any one matches. Needs security gateways on the workspace. |
mailboxProvider | array of string | optional | Only contacts whose mailbox host is one of these: a host slug such as google_workspace, or unknown or pending. At most 100 values, and any one matches. Needs security gateways on the workspace. |
sort | string | optional | Sort field: name, email, company, title, location, leadQualityScore, emailsSent, totalClicks, replies, unsubscribes, bounces or yearsOfExperience. Omitted sorts by contact id. |
direction | string | optional | Sort direction, asc or desc, sent only with sort. Omitted sorts ascending. |
limit | integer (int32) | optional | Contacts per page, from 1 to 200. Default 50. |
cursor | string | optional | The nextCursor of the previous page, sent with the same filters and sort. Omitted starts at the first page. |
curl -X POST "https://api.ken.so/v1/contacts/search" \
-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 '{
"campaignIds": [
4821
],
"isQualified": true,
"filters": [
{
"operator": "and",
"conditions": {
"field": "Title",
"operator": "contains",
"value": "Engineering",
"dataType": "string"
}
}
],
"readyOnly": false,
"awaitingFirstEmail": false,
"sort": "leadQualityScore",
"direction": "desc",
"limit": 50
}'Response 200
data is a list of Contact. Each item has these fields. The response also carries pagination.
Show the 96 response fields and an example
The fields and an example are also on this endpoint's Markdown page.
List a contact's events
/v1/contacts/{contactId}/eventscontacts.events- Permission
- Campaigns view
- Rate limit
- 12,000 requests a minute per API key
Returns the contact's timeline, newest first: emails sent, opened and clicked, replies, bounces, unsubscribes, and video activity. Filter it by event type and by time with occurredAfter and occurredBefore.
A cursor works only with the limit of the page that returned it.
Errors:
400 validation_failed:limitis not between 1 and 200,cursoris not valid, was issued for anotherlimitor is past page 10,000, or the time range is reversed or longer than 366 days.404 not_found: no contact with this id in the workspace.
Requires Campaigns view.
Parameters
| Name | In | Type | Required | Description |
|---|---|---|---|---|
type | query | string | optional | Only events of this type, such as email_sent, email_opened, contact_replied or video_event. A video activity such as video_watched keeps only that activity. Omitted returns every type. |
occurredAfter | query | string (date-time) | optional | Only events at or after this time, in UTC. |
occurredBefore | query | string (date-time) | optional | The end of the range, in UTC. Kenso returns events up to one day after this time. Must be later than occurredAfter, and the range can span at most 366 days. |
limit | query | integer (int32) | optional | Events per page, from 1 to 200. Default 50. |
cursor | query | string | optional | The nextCursor of the previous page. It works only with the same limit. |
curl -X GET "https://api.ken.so/v1/contacts/812/events?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 ContactEvent. 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.
List the contact's company website pages
/v1/contacts/{contactId}/website-pagescontacts.list-website-pages- Permission
- Campaigns view
- Rate limit
- 12,000 requests a minute per API key
Returns the pages Kenso holds for the website of the contact's company, each with its text as markdown. The list puts the home page first, then the about, pricing, product, customer and careers pages, then the rest, newest first within each type. Pages without content are left out.
The list holds at most 50 pages and has no further pages.
Errors:
404 not_found: no contact with this id in the workspace.
Requires Campaigns view.
curl -X GET "https://api.ken.so/v1/contacts/812/website-pages" \
-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 ContactWebsitePage. 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.
More in Contacts and companies:Contact importsContact exportsTagsBlocklistBlocklist rulesContact fieldsCompaniesCompany dataContact behaviorAll resources