Tags
Tag definitions, and assigning them to records one at a time or in bulk.
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 |
|---|---|---|---|---|
tagId | path | integer (int64) | required | The tag's 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 tags
/v1/tagstags.list- Permission
- Any workspace member except a Network member
- Rate limit
- 12,000 requests a minute per API key
Lists the workspace's tags. With entityType alone, the list holds the tags offered on that type: every tag you created, plus the system and sender configuration tags whose entityTypes include it. With entityId too, it holds the tags on that one entity.
Errors:
400 validation_failed: a filter is unknown or sent in a combination its description rules out, orlimitorcursoris invalid.404 not_found: theentityIdis not in this workspace.
Open to any workspace member.
Parameters
| Name | In | Type | Required | Description |
|---|---|---|---|---|
limit | query | integer (int32) | optional | Tags per page, from 1 to 200. 50 by default. Keep the same value while you page. |
cursor | query | string | optional | The nextCursor of the previous page. Omit it for the first page. |
entityType | query | string | optional | Lists the tags that can go on this type: campaign, contact, mailbox, domain, reply, account, linkedin_account or person. With entityId, lists the tags on that one entity instead. |
entityId | query | integer (int64) | optional | The id of one campaign, contact, mailbox, domain, account, LinkedIn account or person, to list the tags on it. Needs entityType, and does not work with reply. |
includeUsage | query | boolean | optional | Set to true to add usage to each tag: how many entities of each type carry it. |
includeEntityIds | query | boolean | optional | Set to true to add entityIds to each tag: the ids of the campaigns that carry it. Needs entityType=campaign. |
systemKey | query | string | optional | Lists only the workspace's system tag with this key, such as champion, the tag that marks a person as a champion Kenso watches for a job change. Kenso creates the tag the first time you ask for it. Does not work with entityId. |
curl -X GET "https://api.ken.so/v1/tags?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 Tag. Each item has these fields. The response also carries pagination.
Show the 13 response fields and an example
The fields and an example are also on this endpoint's Markdown page.
Create a tag
/v1/tagstags.create- Permission
- The
workspace_settingspermission - Rate limit
- 4,800 requests a minute per API key
Creates a tag in the workspace. Assign it with POST /v1/tags/{tagId}/assignments.
Errors:
400 validation_failed:nameis missing, already used or a system tag name,coloris not a valid color, orentityTypesholds an unknown type.
Requires the workspace_settings permission.
Request body
application/json, optional.
| Field | Type | Required | Description |
|---|---|---|---|
name | string | required | The tag's name. Required, unique in the workspace ignoring case, and not the name of a system tag. |
description | string | optional | A note on what the tag means. Optional. |
color | string | optional | The tag's color: a hex value (#RGB, #RGBA, #RRGGBB or #RRGGBBAA) or an rgba(r, g, b, a) value. Omitted uses #E4D0FF. |
entityTypes | array of string | optional | Where Kenso offers the tag: any of campaign, contact, mailbox, domain, reply, account, linkedin_account and person. Omitted or empty means all of them. You cannot change it later. |
curl -X POST "https://api.ken.so/v1/tags" \
-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 '{
"name": "Hot lead",
"description": "Asked for a call or pricing",
"color": "#FFD6A5",
"entityTypes": [
"contact",
"reply"
]
}'Response 201
data is a Tag.
Show the 13 response fields and an example
The fields and an example are also on this endpoint's Markdown page.
Get a tag
/v1/tags/{tagId}tags.get- Permission
- Any workspace member except a Network member
- Rate limit
- 12,000 requests a minute per API key
Returns one tag of the workspace by its id.
Errors:
404 not_found: no tag of this workspace has the id, or the tag was deleted.
Open to any workspace member.
Parameters
| Name | In | Type | Required | Description |
|---|---|---|---|---|
tagId | path | integer (int64) | required | The tag's id, as GET /v1/tags returns it. |
curl -X GET "https://api.ken.so/v1/tags/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 Tag.
Show the 13 response fields and an example
The fields and an example are also on this endpoint's Markdown page.
Update a tag
/v1/tags/{tagId}tags.update- Permission
- The
workspace_settingspermission - Rate limit
- 4,800 requests a minute per API key
Changes a tag's name, color or description. The tag stays on everything that carries it.
Send a JSON object with any of name, color and description. Fields you leave out keep their value. name and color follow the rules of create and cannot be empty. A null description clears it. entityTypes cannot change.
Errors:
400 validation_failed: the body is not a JSON object or holds an unknown field orentityTypes, a value is invalid, or the tag is a system tag.404 not_found: no tag of this workspace has the id.
Requires the workspace_settings permission.
Request body
application/json, optional: object.
curl -X PATCH "https://api.ken.so/v1/tags/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 Tag.
Show the 13 response fields and an example
The fields and an example are also on this endpoint's Markdown page.
Delete a tag
/v1/tags/{tagId}tags.delete- Permission
- The
workspace_settingspermission - Rate limit
- 4,800 requests a minute per API key
Deletes a tag and removes it from the entities that carry it. A LinkedIn conversation can keep a deleted tag. You can still remove it there with DELETE /v1/tags/{tagId}/assignments.
Errors:
400 validation_failed: the tag is a system tag.404 not_found: no tag of this workspace has the id.
Requires the workspace_settings permission.
curl -X DELETE "https://api.ken.so/v1/tags/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 ContentAssign a tag to an entity
/v1/tags/{tagId}/assignmentstags.assign- Permission
- Any workspace member except a Network member
- Rate limit
- 4,800 requests a minute per API key
Puts a tag on one campaign, contact, mailbox, domain, account, LinkedIn account, person, email reply, LinkedIn conversation or Instagram conversation (a thread of the Instagram inbox, while the workspace has Instagram on).
Send entityType and the id field that type takes. Assigning a tag the entity already has changes nothing.
The caller needs edit access to the entity's page: Campaigns for a campaign or contact, Delivery for a mailbox, domain or LinkedIn account, Accounts for an account or person, and Inbox for a reply or a conversation.
Errors:
400 validation_failed:entityTypeis missing or unknown, its id field is missing, or the tag is a system tag or sender configuration tag whoseentityTypesdo not include this entity type.403 permission_denied: the caller lacks edit access to the entity's page.404 not_found: the tag or the entity is not in this workspace, the entity was deleted, or themsg_orthr_id belongs to another channel.
Open to any workspace member.
Parameters
| Name | In | Type | Required | Description |
|---|---|---|---|---|
Idempotency-Key | header | string | optional | A unique value, such as a UUID, that makes a retry safe. Send the same key when you retry. For 24 hours, a repeat of the same request with the same key gets the first response again, with the Idempotent-Replayed: true header, and Kenso does not run the action twice. The same key with a different request answers 422 idempotency_key_reused. Keys are per workspace and at most 200 characters long. A repeat sent while the first request is still running can get 503 service_unavailable with Retry-After. Retry it with the same key. Kenso does not store a 5xx response, so a retry after one runs the action again. |
Request body
application/json, optional.
| Field | Type | Required | Description |
|---|---|---|---|
entityType | string | required | The entity's type: campaign, contact, mailbox, domain, account, linkedin_account, person, reply, linkedin_conversation or instagram_conversation. Required. |
entityId | integer (int64) | optional | The entity's id. Required for every type except reply, linkedin_conversation and instagram_conversation. |
messageId | string | optional | For reply: the msg_ id of an email message, as GET /v1/threads/{threadId}/messages returns it. |
conversationId | string | optional | For linkedin_conversation: the thr_ id of a LinkedIn thread, as GET /v1/threads returns it. For instagram_conversation: the thr_ id of an Instagram thread (only that id names one). |
curl -X POST "https://api.ken.so/v1/tags/812/assignments" \
-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 '{
"entityType": "campaign",
"entityId": 812,
"messageId": "msg_ZW1haWw6NDAyMjg0LjJAZXhhbXBsZS5jb20",
"conversationId": "thr_2bX9kq4LmR7tW3vY"
}'Response 200
data is a TagAssignment.
Show the 5 response fields and an example
The fields and an example are also on this endpoint's Markdown page.
Remove a tag from an entity
/v1/tags/{tagId}/assignmentstags.unassign- Permission
- Any workspace member except a Network member
- Rate limit
- 4,800 requests a minute per API key
Takes a tag off one entity. Send the fields of assign as query parameters, not a body. The caller needs the same access as on assign. A deleted tag of the workspace can still come off a reply, a linkedin_conversation or an instagram_conversation.
Errors:
400 validation_failed:entityTypeis missing or unknown, or its id field is missing.403 permission_denied: the caller lacks edit access to the entity's page.404 not_found: the tag or the entity is not in this workspace.
Open to any workspace member.
Parameters
| Name | In | Type | Required | Description |
|---|---|---|---|---|
entityType | query | string | optional | The entity's type: campaign, contact, mailbox, domain, account, linkedin_account, person, reply, linkedin_conversation or instagram_conversation. Required. |
entityId | query | integer (int64) | optional | The entity's id. Required for every type except reply, linkedin_conversation and instagram_conversation. |
messageId | query | string | optional | For reply: the msg_ id of an email message, as GET /v1/threads/{threadId}/messages returns it. |
conversationId | query | string | optional | For linkedin_conversation: the thr_ id of a LinkedIn thread, as GET /v1/threads returns it. For instagram_conversation: the thr_ id of an Instagram thread (only that id names one). |
Idempotency-Key | header | string | optional | A unique value, such as a UUID, that makes a retry safe. Send the same key when you retry. For 24 hours, a repeat of the same request with the same key gets the first response again, with the Idempotent-Replayed: true header, and Kenso does not run the action twice. The same key with a different request answers 422 idempotency_key_reused. Keys are per workspace and at most 200 characters long. A repeat sent while the first request is still running can get 503 service_unavailable with Retry-After. Retry it with the same key. Kenso does not store a 5xx response, so a retry after one runs the action again. |
curl -X DELETE "https://api.ken.so/v1/tags/812/assignments" \
-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 TagAssignment.
Show the 5 response fields and an example
The fields and an example are also on this endpoint's Markdown page.
Assign a tag to many entities
/v1/tags/{tagId}/assignments/bulk-createtags.bulk-assign- Permission
- Any workspace member except a Network member
- Rate limit
- 480 requests a minute per API key
Puts a tag on up to 1,000 entities in one call. Each item has the fields, rules and access of a single assign. Items can mix entity types, run in request order, and fail on their own.
results has one entry per item, in request order, with a status of assigned, not_found, validation_failed, permission_denied or failed. After 5 unexpected failures in a row, Kenso marks the remaining items failed: retry those in a new call, with a new Idempotency-Key if you send one.
Errors:
400 validation_failed:itemsis empty, has more than 1,000 entries or holds a null entry. Kenso writes nothing.404 not_found: the tag is not in this workspace.
Open to any workspace member.
Parameters
| Name | In | Type | Required | Description |
|---|---|---|---|---|
Idempotency-Key | header | string | optional | A unique value, such as a UUID, that makes a retry safe. Send the same key when you retry. For 24 hours, a repeat of the same request with the same key gets the first response again, with the Idempotent-Replayed: true header, and Kenso does not run the action twice. The same key with a different request answers 422 idempotency_key_reused. Keys are per workspace and at most 200 characters long. A repeat sent while the first request is still running can get 503 service_unavailable with Retry-After. Retry it with the same key. Kenso does not store a 5xx response, so a retry after one runs the action again. |
Request body
application/json, optional.
| Field | Type | Required | Description |
|---|---|---|---|
items | array of TagAssignmentRequest | optional | From 1 to 1,000 items, each with the fields of a single assignment. |
curl -X POST "https://api.ken.so/v1/tags/812/assignments/bulk-create" \
-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": [
{
"entityType": "campaign",
"entityId": 812,
"messageId": "msg_ZW1haWw6NDAyMjg0LjJAZXhhbXBsZS5jb20",
"conversationId": "thr_2bX9kq4LmR7tW3vY"
}
]
}'Response 200
data is a TagAssignmentBulkResult.
Show the 3 response fields and an example
The fields and an example are also on this endpoint's Markdown page.
Remove a tag from many entities
/v1/tags/{tagId}/assignments/bulk-deletetags.bulk-unassign- Permission
- Any workspace member except a Network member
- Rate limit
- 480 requests a minute per API key
Takes a tag off up to 1,000 entities in one call, with the body and results of bulk assign and the rules of a single remove. A removed item has the status removed. A deleted tag of the workspace can still come off reply, linkedin_conversation and instagram_conversation items, and every other item then gets not_found.
Errors:
400 validation_failed:itemsis empty, has more than 1,000 entries or holds a null entry. Kenso removes nothing.404 not_found: the tag is not in this workspace.
Open to any workspace member.
Parameters
| Name | In | Type | Required | Description |
|---|---|---|---|---|
Idempotency-Key | header | string | optional | A unique value, such as a UUID, that makes a retry safe. Send the same key when you retry. For 24 hours, a repeat of the same request with the same key gets the first response again, with the Idempotent-Replayed: true header, and Kenso does not run the action twice. The same key with a different request answers 422 idempotency_key_reused. Keys are per workspace and at most 200 characters long. A repeat sent while the first request is still running can get 503 service_unavailable with Retry-After. Retry it with the same key. Kenso does not store a 5xx response, so a retry after one runs the action again. |
Request body
application/json, optional.
| Field | Type | Required | Description |
|---|---|---|---|
items | array of TagAssignmentRequest | optional | From 1 to 1,000 items, each with the fields of a single assignment. |
curl -X POST "https://api.ken.so/v1/tags/812/assignments/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 '{
"items": [
{
"entityType": "campaign",
"entityId": 812,
"messageId": "msg_ZW1haWw6NDAyMjg0LjJAZXhhbXBsZS5jb20",
"conversationId": "thr_2bX9kq4LmR7tW3vY"
}
]
}'Response 200
data is a TagAssignmentBulkResult.
Show the 3 response fields and an example
The fields and an example are also on this endpoint's Markdown page.
More in Contacts and companies:ContactsContact importsContact exportsBlocklistBlocklist rulesContact fieldsCompaniesCompany dataContact behaviorAll resources