Skip to Content
Contacts and companies

Contacts

List, search, read, update and remove contacts, add them to campaigns and change many in one call.

Contacts and companies13 endpointsKen-Version: 2026-11-02AuthenticationWorkspacesErrors
MarkdownOpenAPI

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.

NameInTypeRequiredDescription
contactIdpathinteger (int64)requiredThe contact id.

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 contacts

GET/v1/contactscontacts.list
Permission
Campaigns view
Rate limit
12,000 requests a minute per API key

Try it on developer.ken.so

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: limit is not between 1 and 200, sort is not createdAt or -createdAt, cursor is not valid or comes from another sort, or createdBefore is not later than createdAfter.
  • 429 quota_exceeded: the workspace used up its API read rows for the day.

Requires Campaigns view.

Parameters

NameInTypeRequiredDescription
campaignIdqueryinteger (int64)optionalOnly contacts in this campaign.
companyIdqueryinteger (int64)optionalOnly contacts at this company, matched on the contact's companyId.
segmentIdqueryinteger (int64)optionalOnly contacts in this campaign segment.
emailquerystringoptionalOnly contacts that have this email address. The match is exact and ignores case.
personIdqueryinteger (int64)optionalOnly the contacts of this person, one per campaign they are in.
qquerystringoptionalFree-text search on the first name, last name, full name and email addresses. It matches any part of a value and ignores case.
isQualifiedquerybooleanoptionalTrue keeps only qualified contacts, false only unqualified ones. Omitted keeps both.
doNotContactquerybooleanoptionalTrue keeps only do-not-contact contacts, false only the others. Omitted keeps both.
createdAfterquerystring (date-time)optionalOnly contacts created at or after this time, in UTC.
createdBeforequerystring (date-time)optionalOnly contacts created before this time, in UTC. Must be later than createdAfter.
sortquerystringoptionalThe 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.
limitqueryinteger (int32)optionalContacts per page, from 1 to 200. Default 50.
cursorquerystringoptionalThe nextCursor of the previous page. Omitted starts at the first page.
Request
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

POST/v1/campaigns/{campaignId}/contactscontacts.create
Permission
Campaigns edit
Rate limit
480 requests a minute per API key

Try it on developer.ken.so

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: contacts is 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

NameInTypeRequiredDescription
campaignIdpathinteger (int64)requiredThe campaign to add the contacts to.

Request body

application/json, optional.

FieldTypeRequiredDescription
contactsarray of CreateCampaignContactRequestrequiredRequired. From 1 to 1,000 contacts, processed in request order.
Request
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

GET/v1/contacts/{contactId}contacts.get
Permission
Campaigns view
Rate limit
12,000 requests a minute per API key

Try it on developer.ken.so

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.

Request
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

PATCH/v1/contacts/{contactId}contacts.update
Permission
Campaigns edit
Rate limit
4,800 requests a minute per API key

Try it on developer.ken.so

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, isQualified or doNotContact is 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.

FieldTypeRequiredDescription
firstNamestringoptionalFirst name. Null clears it.
lastNamestringoptionalLast name. Null clears it.
titlestringoptionalJob title. Null clears it.
linkedInUrlstringoptionalLinkedIn profile URL. Null clears it.
locationstringoptionalLocation. Null clears it.
emailstringoptionalThe 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.
isQualifiedbooleanoptionalTrue or false to mark the contact qualified or not. Null is refused.
doNotContactbooleanoptionalTrue to mark the contact do-not-contact, so Kenso sends it nothing, or false to clear that. Null is refused.
outreachLanguagestringoptionalThe 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.
customVariablesmap of stringoptionalValues 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.
customImageUrlstringoptionalThe 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.
customVideostringoptionalThe 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.
Request
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

DELETE/v1/contacts/{contactId}contacts.delete
Permission
Campaigns edit
Rate limit
4,800 requests a minute per API key

Try it on developer.ken.so

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.

Request
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

Response 204
HTTP/1.1 204 No Content

Delete contacts in bulk

POST/v1/contacts/bulk-deletecontacts.bulk-delete
Permission
Campaigns edit
Rate limit
480 requests a minute per API key

Try it on developer.ken.so

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: ids is 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.

FieldTypeRequiredDescription
idsarray of integer (int64)requiredRequired. From 1 to 1,000 contact ids in the workspace.
Request
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

POST/v1/contacts/bulk-pausecontacts.bulk-pause
Permission
Campaigns edit and the launch permission
Rate limit
480 requests a minute per API key
Needs the pause_leads feature on your workspace. Until it is on, calls answer 404.

Try it on developer.ken.so

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: ids is 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.

FieldTypeRequiredDescription
idsarray of integer (int64)requiredRequired. From 1 to 1,000 contact ids in the workspace.
Request
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

POST/v1/contacts/bulk-resumecontacts.bulk-resume
Permission
Campaigns edit and the launch permission
Rate limit
480 requests a minute per API key

Try it on developer.ken.so

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: ids is 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.

FieldTypeRequiredDescription
idsarray of integer (int64)requiredRequired. From 1 to 1,000 contact ids in the workspace.
Request
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

POST/v1/contacts/bulk-updatecontacts.bulk-update
Permission
Campaigns edit
Rate limit
480 requests a minute per API key

Try it on developer.ken.so

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, because items is empty, holds more than 1,000 entries, holds an entry that is not an object or has no positive contactId, or repeats a contactId.

Requires Campaigns edit.

Request body

application/json, required.

FieldTypeRequiredDescription
itemsarray of BulkUpdateContactItemBodyrequiredRequired. From 1 to 1,000 items, run in request order.
Request
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

POST/v1/contacts/bulk-restorecontacts.bulk-restore
Permission
Campaigns edit
Rate limit
480 requests a minute per API key

Try it on developer.ken.so

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. skipped counts 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: ids is 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.

FieldTypeRequiredDescription
idsarray of integer (int64)requiredRequired. From 1 to 1,000 contact ids in the workspace.
Request
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

POST/v1/contacts/searchcontacts.search
Permission
Campaigns view
Rate limit
12,000 requests a minute per API key

Try it on developer.ken.so

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 50 campaignIds or 1,000 contactIds, readyOnly or awaitingFirstEmail without exactly one campaign, an unknown sort field, direction without sort, a bad limit or cursor, createdBefore not later than createdAfter, a behaviorTag condition without the behavior_signals feature, 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.

FieldTypeRequiredDescription
campaignIdsarray of integer (int64)optionalOnly contacts in these campaigns, at most 50 ids.
companyIdinteger (int64)optionalOnly contacts at this company, matched on the contact's companyId.
segmentIdinteger (int64)optionalOnly contacts in this campaign segment.
emailstringoptionalOnly contacts that have this email address. The match is exact and ignores case.
qstringoptionalFree-text search on the first name, last name, full name and email addresses. It matches any part of a value and ignores case.
isQualifiedbooleanoptionalTrue keeps only qualified contacts, false only unqualified ones. Omitted keeps both.
doNotContactbooleanoptionalTrue keeps only do-not-contact contacts, false only the others. Omitted keeps both.
createdAfterstring (date-time)optionalOnly contacts created at or after this time, in UTC.
createdBeforestring (date-time)optionalOnly contacts created before this time, in UTC. Must be later than createdAfter.
filtersarray of ContactSearchFilterGroupoptionalField conditions joined with AND or OR, at most 20 groups. A behaviorTag condition needs the behavior_signals feature on the workspace.
readyOnlybooleanoptionalTrue keeps only the contacts the campaign can send to now. Needs exactly one id in campaignIds. Default false.
awaitingFirstEmailbooleanoptionalTrue 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.
contactIdsarray of integer (int64)optionalOnly these contacts, at most 1,000 ids.
securityGatewayarray of stringoptionalOnly 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.
mailboxProviderarray of stringoptionalOnly 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.
sortstringoptionalSort field: name, email, company, title, location, leadQualityScore, emailsSent, totalClicks, replies, unsubscribes, bounces or yearsOfExperience. Omitted sorts by contact id.
directionstringoptionalSort direction, asc or desc, sent only with sort. Omitted sorts ascending.
limitinteger (int32)optionalContacts per page, from 1 to 200. Default 50.
cursorstringoptionalThe nextCursor of the previous page, sent with the same filters and sort. Omitted starts at the first page.
Request
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

GET/v1/contacts/{contactId}/eventscontacts.events
Permission
Campaigns view
Rate limit
12,000 requests a minute per API key

Try it on developer.ken.so

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: limit is not between 1 and 200, cursor is not valid, was issued for another limit or 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

NameInTypeRequiredDescription
typequerystringoptionalOnly 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.
occurredAfterquerystring (date-time)optionalOnly events at or after this time, in UTC.
occurredBeforequerystring (date-time)optionalThe 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.
limitqueryinteger (int32)optionalEvents per page, from 1 to 200. Default 50.
cursorquerystringoptionalThe nextCursor of the previous page. It works only with the same limit.
Request
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

GET/v1/contacts/{contactId}/website-pagescontacts.list-website-pages
Permission
Campaigns view
Rate limit
12,000 requests a minute per API key

Try it on developer.ken.so

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.

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


On this page