Skip to Content
Contacts and companies

Tags

Tag definitions, and assigning them to records one at a time or in bulk.

Contacts and companies9 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
tagIdpathinteger (int64)requiredThe tag's 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 tags

GET/v1/tagstags.list
Permission
Any workspace member except a Network member
Rate limit
12,000 requests a minute per API key

Try it on developer.ken.so

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, or limit or cursor is invalid.
  • 404 not_found: the entityId is not in this workspace.

Open to any workspace member.

Parameters

NameInTypeRequiredDescription
limitqueryinteger (int32)optionalTags per page, from 1 to 200. 50 by default. Keep the same value while you page.
cursorquerystringoptionalThe nextCursor of the previous page. Omit it for the first page.
entityTypequerystringoptionalLists 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.
entityIdqueryinteger (int64)optionalThe 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.
includeUsagequerybooleanoptionalSet to true to add usage to each tag: how many entities of each type carry it.
includeEntityIdsquerybooleanoptionalSet to true to add entityIds to each tag: the ids of the campaigns that carry it. Needs entityType=campaign.
systemKeyquerystringoptionalLists 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.
Request
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

POST/v1/tagstags.create
Permission
The workspace_settings permission
Rate limit
4,800 requests a minute per API key

Try it on developer.ken.so

Creates a tag in the workspace. Assign it with POST /v1/tags/{tagId}/assignments.

Errors:

  • 400 validation_failed: name is missing, already used or a system tag name, color is not a valid color, or entityTypes holds an unknown type.

Requires the workspace_settings permission.

Request body

application/json, optional.

FieldTypeRequiredDescription
namestringrequiredThe tag's name. Required, unique in the workspace ignoring case, and not the name of a system tag.
descriptionstringoptionalA note on what the tag means. Optional.
colorstringoptionalThe tag's color: a hex value (#RGB, #RGBA, #RRGGBB or #RRGGBBAA) or an rgba(r, g, b, a) value. Omitted uses #E4D0FF.
entityTypesarray of stringoptionalWhere 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.
Request
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

GET/v1/tags/{tagId}tags.get
Permission
Any workspace member except a Network member
Rate limit
12,000 requests a minute per API key

Try it on developer.ken.so

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

NameInTypeRequiredDescription
tagIdpathinteger (int64)requiredThe tag's id, as GET /v1/tags returns it.
Request
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

PATCH/v1/tags/{tagId}tags.update
Permission
The workspace_settings permission
Rate limit
4,800 requests a minute per API key

Try it on developer.ken.so

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 or entityTypes, 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.

Request
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

DELETE/v1/tags/{tagId}tags.delete
Permission
The workspace_settings permission
Rate limit
4,800 requests a minute per API key

Try it on developer.ken.so

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.

Request
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

Response 204
HTTP/1.1 204 No Content

Assign a tag to an entity

POST/v1/tags/{tagId}/assignmentstags.assign
Permission
Any workspace member except a Network member
Rate limit
4,800 requests a minute per API key

Try it on developer.ken.so

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: entityType is missing or unknown, its id field is missing, or the tag is a system tag or sender configuration tag whose entityTypes do 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 the msg_ or thr_ id belongs to another channel.

Open to any workspace member.

Parameters

NameInTypeRequiredDescription
Idempotency-KeyheaderstringoptionalA 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.

FieldTypeRequiredDescription
entityTypestringrequiredThe entity's type: campaign, contact, mailbox, domain, account, linkedin_account, person, reply, linkedin_conversation or instagram_conversation. Required.
entityIdinteger (int64)optionalThe entity's id. Required for every type except reply, linkedin_conversation and instagram_conversation.
messageIdstringoptionalFor reply: the msg_ id of an email message, as GET /v1/threads/{threadId}/messages returns it.
conversationIdstringoptionalFor 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).
Request
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

DELETE/v1/tags/{tagId}/assignmentstags.unassign
Permission
Any workspace member except a Network member
Rate limit
4,800 requests a minute per API key

Try it on developer.ken.so

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

NameInTypeRequiredDescription
entityTypequerystringoptionalThe entity's type: campaign, contact, mailbox, domain, account, linkedin_account, person, reply, linkedin_conversation or instagram_conversation. Required.
entityIdqueryinteger (int64)optionalThe entity's id. Required for every type except reply, linkedin_conversation and instagram_conversation.
messageIdquerystringoptionalFor reply: the msg_ id of an email message, as GET /v1/threads/{threadId}/messages returns it.
conversationIdquerystringoptionalFor 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-KeyheaderstringoptionalA 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
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

POST/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

Try it on developer.ken.so

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

NameInTypeRequiredDescription
Idempotency-KeyheaderstringoptionalA 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.

FieldTypeRequiredDescription
itemsarray of TagAssignmentRequestoptionalFrom 1 to 1,000 items, each with the fields of a single assignment.
Request
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

POST/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

Try it on developer.ken.so

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

NameInTypeRequiredDescription
Idempotency-KeyheaderstringoptionalA 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.

FieldTypeRequiredDescription
itemsarray of TagAssignmentRequestoptionalFrom 1 to 1,000 items, each with the fields of a single assignment.
Request
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.


On this page