{"openapi":"3.0.4","info":{"title":"Kenso API: Contacts","version":"1.1","description":"The Contacts endpoints of the Kenso API, with every component they use. The full spec is https://api.ken.so/v1/docs/openapi.json. Every request sends `Authorization: Bearer <your API key>` and `Ken-Version: 2026-11-02`."},"servers":[{"url":"https://api.ken.so"}],"security":[{"Bearer":[]}],"tags":[{"name":"contacts","description":"A contact is a person in one of your campaigns, with their profile, company, email and phone status, and the\ncounts of what Kenso sent them and how they responded. Add contacts with <c>POST\n/v1/campaigns/{campaignId}/contacts</c> or a contact import, then list, search, update, pause or delete them\nhere. A deleted contact leaves every list and read, and bulk-restore brings it back.","x-displayName":"Contacts"}],"paths":{"/v1/contacts":{"get":{"tags":["contacts"],"summary":"List contacts","description":"Returns the workspace's contacts, ordered by id. Deleted contacts are left out. The query parameters narrow\nthe list to one campaign, segment or company, an email address, a person (`personId`: their contact in each\ncampaign they are in), a name search, a qualified or do-not-contact state, or a creation time range.\n            \n`sort=createdAt` lists by each contact's `createdAt`, oldest first, and `sort=-createdAt` newest\nfirst. Keep the same `sort` while you page: a cursor from another order is refused.\n            \nEach contact on a page counts against the workspace's daily allowance of API read rows. Past it, the call\nreturns `429 quota_exceeded` with a `Retry-After` header. To filter on more than one\ncampaign, on contact fields or on another sort order, use `POST /v1/contacts/search`.\n            \nA contact has about 95 properties. `fields` names the ones you read, for example\n`fields=id,email,companyName`, and each contact then holds only those: the page is smaller and faster.\nWithout `fields` every property is returned.\n            \nErrors:\n            \n- `400 validation_failed`: `limit` is not between 1 and 1,000, `sort` is not `createdAt` or\n  `-createdAt`, `cursor` is not valid or comes from another `sort`, `createdBefore` is\n  not later than `createdAfter`, or `fields` names something that is not a top-level contact property.\n- `429 quota_exceeded`: the workspace used up its API read rows for the day.\n            \nRequires Campaigns view.\n\nRate limit: 12,000 calls a minute per API key, on top of the workspace limits.","operationId":"contacts.list","parameters":[{"name":"campaignId","in":"query","description":"Only contacts in this campaign.","schema":{"type":"integer","format":"int64"}},{"name":"companyId","in":"query","description":"Only contacts at this company, matched on the contact's `companyId`.","schema":{"type":"integer","format":"int64"}},{"name":"segmentId","in":"query","description":"Only contacts in this campaign segment.","schema":{"type":"integer","format":"int64"}},{"name":"email","in":"query","description":"Only contacts that have this email address. The match is exact and ignores case.","schema":{"type":"string"}},{"name":"personId","in":"query","description":"Only the contacts of this person, one per campaign they are in.","schema":{"type":"integer","format":"int64"}},{"name":"q","in":"query","description":"Free-text search on the first name, last name, full name and email addresses. It matches any part of a value and\nignores case.","schema":{"type":"string"}},{"name":"isQualified","in":"query","description":"True keeps only qualified contacts, false only unqualified ones. Omitted keeps both.","schema":{"type":"boolean"}},{"name":"doNotContact","in":"query","description":"True keeps only do-not-contact contacts, false only the others. Omitted keeps both.","schema":{"type":"boolean"}},{"name":"createdAfter","in":"query","description":"Only contacts created at or after this time, in UTC.","schema":{"type":"string","format":"date-time"}},{"name":"createdBefore","in":"query","description":"Only contacts created before this time, in UTC. Must be later than `createdAfter`.","schema":{"type":"string","format":"date-time"}},{"name":"sort","in":"query","description":"The order, by each contact's `createdAt`: `createdAt` lists oldest first and `-createdAt` newest\nfirst. Omitted keeps the id order. Keep the same `sort` while you page.","schema":{"type":"string"}},{"name":"limit","in":"query","description":"Contacts per page, from 1 to 1000. Default 50.","schema":{"maximum":1000,"minimum":1,"type":"integer","format":"int32","default":50}},{"name":"cursor","in":"query","description":"The `nextCursor` of the previous page. Omitted starts at the first page.","schema":{"type":"string"}},{"name":"fields","in":"query","description":"The contact properties to return, as a comma-separated list of top-level names, for example\n`id,email,companyName`. Each contact then holds only those. Omitted returns every property.","schema":{"type":"string"}},{"name":"Ken-Version","in":"header","description":"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 value that is not a version, such as `2027-01-01` or `2026-11-2`, answers `400 unsupported_version`, whose `details` list the supported versions.","schema":{"enum":["2026-11-02","1.1"],"type":"string"},"examples":{"default":{"value":"2026-11-02","x-disabled":false}}},{"name":"X-Ken-Workspace-Id","in":"header","description":"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`.","schema":{"type":"integer","format":"int64"}}],"responses":{"200":{"description":"OK","headers":{"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ContactListResponse"}}}},"400":{"description":"Bad Request","headers":{"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Failure"}}},"x-ken-error-codes":["unsupported_version","validation_failed","workspace_required"]},"401":{"description":"Unauthorized","headers":{"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/UnauthorizedError"}}},"x-ken-error-codes":["unauthenticated"]},"404":{"description":"Not Found","headers":{"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Failure"}}},"x-ken-error-codes":["not_found"]},"429":{"description":"Too Many Requests","headers":{"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/TooManyRequestsError"}},"text/plain":{"schema":{"$ref":"#/components/schemas/RateLimitedText"}}},"x-ken-error-codes":["quota_exceeded","rate_limited"]}},"x-ken-permission":{"kind":"page","page":"campaigns","access":"view","summary":"Campaigns view"},"x-ken-rate-limit":{"limit":12000,"windowSeconds":60,"per":"api_key"}}},"/v1/campaigns/{campaignId}/contacts":{"post":{"tags":["contacts"],"summary":"Add contacts to a campaign","description":"Adds up to 1,000 people to a campaign, or updates them when the campaign already has them. A row matches an\nexisting contact of the campaign by email, or by LinkedIn URL for a row without an email in a campaign\nwith only LinkedIn steps. `results` reports each row in request order: `created`,\n`updated`, `skipped` or `failed`, with a `reason` and `message` when the row\nwas not saved.\n            \nKenso saves the rows in batches of 100. A later batch can fail after earlier ones saved, and a retry of the\nsame body is safe. A row on the workspace blocklist is not saved: it is `failed` with reason\n`blocklisted`. A row that matches a contact already marked do-not-contact is `updated` with\n`sendable` false. A contact the plan has no allowance left for is added unqualified, with\n`sendable` false.\n            \nOn Kenso Lifetime, the new contacts in each batch count against the license's contacts (one pool across its\nworkspaces). When a batch would pass them, the call still answers 200: every row of that batch, updates\nincluded, is `failed` with reason `limit_reached`, and its `message` starts with\n`[LIFETIME_CONTACT_LIMIT_REACHED]`. Batches saved before it stay saved. A batch that only updates contacts\nthe campaign already has is not refused.\n            \nA row with `useKenEmail` and no email takes a recently verified address from Kenso's email database when\nit has one, free, for the first 25 such rows of the request. A row with `emailValidity`\n`safe` qualifies a new contact in a campaign without AI qualification and uses one contact from\nthe plan's allowance.\n            \nA row with a malformed `customImageUrl` or `customVideo` or a bad custom variable key fails before\nanything is written. When the workspace does not have campaign images or campaign videos, the contact\nis saved and the row fails. A batch that would take the campaign past 50 custom variables fails every\nrow in it.\n            \nErrors:\n            \n- `400 validation_failed`: `contacts` is missing or empty, or holds more than 1,000 rows.\n- `404 not_found`: no campaign with this id in the workspace.\n            \nRequires Campaigns edit.\n\nRate limit: 480 calls a minute per API key, on top of the workspace limits.","operationId":"contacts.create","parameters":[{"name":"campaignId","in":"path","description":"The campaign to add the contacts to.","required":true,"schema":{"type":"integer","format":"int64"}},{"name":"Ken-Version","in":"header","description":"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 value that is not a version, such as `2027-01-01` or `2026-11-2`, answers `400 unsupported_version`, whose `details` list the supported versions.","schema":{"enum":["2026-11-02","1.1"],"type":"string"},"examples":{"default":{"value":"2026-11-02","x-disabled":false}}},{"name":"X-Ken-Workspace-Id","in":"header","description":"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`.","schema":{"type":"integer","format":"int64"}}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreateCampaignContactsRequest"}}}},"responses":{"200":{"description":"OK","headers":{"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ContactBulkResultResponse"}}}},"400":{"description":"Bad Request","headers":{"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Failure"}}},"x-ken-error-codes":["unsupported_version","validation_failed","workspace_required"]},"401":{"description":"Unauthorized","headers":{"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/UnauthorizedError"}}},"x-ken-error-codes":["unauthenticated"]},"404":{"description":"Not Found","headers":{"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Failure"}}},"x-ken-error-codes":["not_found"]},"429":{"description":"Too Many Requests","headers":{"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/TooManyRequestsError"}},"text/plain":{"schema":{"$ref":"#/components/schemas/RateLimitedText"}}},"x-ken-error-codes":["rate_limited"]}},"x-ken-permission":{"kind":"page","page":"campaigns","access":"edit","summary":"Campaigns edit"},"x-ken-rate-limit":{"limit":480,"windowSeconds":60,"per":"api_key"}}},"/v1/contacts/{contactId}":{"get":{"tags":["contacts"],"summary":"Get a contact","description":"Returns one contact with two fields the list, search and update responses leave out: `dataFlags`, signals\nabout the contact's data such as a job change, and `personalEmails`, personal addresses found for\nthe person. Kenso never sends to, verifies or exports a personal address. It also returns `linkedInWait` when\nthe contact's LinkedIn connection request cannot go out yet, with the reason and a message ready to show.\n            \nA read of one contact does not count against the workspace's API read rows.\n            \nErrors:\n            \n- `404 not_found`: no contact with this id in the workspace, or the contact is deleted.\n            \nRequires Campaigns view.\n\nRate limit: 12,000 calls a minute per API key, on top of the workspace limits.","operationId":"contacts.get","parameters":[{"name":"contactId","in":"path","description":"The contact id.","required":true,"schema":{"type":"integer","format":"int64"}},{"name":"Ken-Version","in":"header","description":"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 value that is not a version, such as `2027-01-01` or `2026-11-2`, answers `400 unsupported_version`, whose `details` list the supported versions.","schema":{"enum":["2026-11-02","1.1"],"type":"string"},"examples":{"default":{"value":"2026-11-02","x-disabled":false}}},{"name":"X-Ken-Workspace-Id","in":"header","description":"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`.","schema":{"type":"integer","format":"int64"}}],"responses":{"200":{"description":"OK","headers":{"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ContactDetailResponse"}}}},"400":{"description":"Bad Request","headers":{"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Failure"}}},"x-ken-error-codes":["unsupported_version","workspace_required"]},"401":{"description":"Unauthorized","headers":{"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/UnauthorizedError"}}},"x-ken-error-codes":["unauthenticated"]},"404":{"description":"Not Found","headers":{"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Failure"}}},"x-ken-error-codes":["not_found"]},"429":{"description":"Too Many Requests","headers":{"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/TooManyRequestsError"}},"text/plain":{"schema":{"$ref":"#/components/schemas/RateLimitedText"}}},"x-ken-error-codes":["rate_limited"]}},"x-ken-permission":{"kind":"page","page":"campaigns","access":"view","summary":"Campaigns view"},"x-ken-rate-limit":{"limit":12000,"windowSeconds":60,"per":"api_key"}},"patch":{"tags":["contacts"],"summary":"Update a contact","description":"Changes the fields you send and returns the updated contact. A field you leave out stays as it is, and null\nclears a text field. A field the body does not define is refused.\n            \n`outreachLanguage` sets the language Ken writes to the contact in, as a locale such as `fr-FR` or\n`es-MX` or a language code such as `de`. Kenso locks a language you set, so no import,\nenrichment or reply changes it. Null clears the language and unlocks it.\n            \n`customVariables` is an object of string or null values. A string sets that key, null or an empty string\nremoves it, and keys you leave out stay. A key new to the campaign is added to the campaign's custom\nvariables. The object itself cannot be null.\n            \n`customImageUrl` is the contact's own image, shown in emails as `{{custom_image}}`: a public https\nURL of at most 2,048 characters. Kenso downloads and hosts the image. `customVideo` is the\ncontact's own video, shown as `{{custom_video}}`: a Loom, YouTube, Vimeo, Wistia, Vidyard,\nSendspark or HeyGen share link or embed code, at most 20,480 characters, on a contact in a campaign.\nAn empty string or null clears either one.\n            \nErrors:\n            \n- `400 validation_failed`: the body is not a JSON object, a field is unknown or invalid,\n  `isQualified` or `doNotContact` is null, the email is already another contact's or is\n  one of the contact's personal addresses, or the workspace does not have campaign images or\n  campaign videos. The error names the field.\n- `404 not_found`: no contact with this id in the workspace, or the contact is deleted.\n- `409 video_in_use`: a sent or queued email step uses the contact's current video, so it cannot change.\n  The old video stays.\n            \nRequires Campaigns edit.\n\nRate limit: 4,800 calls a minute per API key, on top of the workspace limits.","operationId":"contacts.update","parameters":[{"name":"contactId","in":"path","description":"The contact id.","required":true,"schema":{"type":"integer","format":"int64"}},{"name":"Ken-Version","in":"header","description":"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 value that is not a version, such as `2027-01-01` or `2026-11-2`, answers `400 unsupported_version`, whose `details` list the supported versions.","schema":{"enum":["2026-11-02","1.1"],"type":"string"},"examples":{"default":{"value":"2026-11-02","x-disabled":false}}},{"name":"X-Ken-Workspace-Id","in":"header","description":"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`.","schema":{"type":"integer","format":"int64"}}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/UpdateContactBody"}}},"required":true},"responses":{"200":{"description":"OK","headers":{"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ContactResponse"}}}},"400":{"description":"Bad Request","headers":{"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Failure"}}},"x-ken-error-codes":["unsupported_version","validation_failed","workspace_required"]},"401":{"description":"Unauthorized","headers":{"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/UnauthorizedError"}}},"x-ken-error-codes":["unauthenticated"]},"404":{"description":"Not Found","headers":{"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Failure"}}},"x-ken-error-codes":["not_found"]},"409":{"description":"Conflict","headers":{"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Failure"}}},"x-ken-error-codes":["video_in_use"]},"429":{"description":"Too Many Requests","headers":{"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/TooManyRequestsError"}},"text/plain":{"schema":{"$ref":"#/components/schemas/RateLimitedText"}}},"x-ken-error-codes":["rate_limited"]}},"x-ken-permission":{"kind":"page","page":"campaigns","access":"edit","summary":"Campaigns edit"},"x-ken-rate-limit":{"limit":4800,"windowSeconds":60,"per":"api_key"}},"delete":{"tags":["contacts"],"summary":"Delete a contact","description":"Deletes the contact. Kenso keeps the record, so `POST /v1/contacts/bulk-restore` can bring it back. A\ndeleted contact leaves every list and read, and its campaign sends it nothing more.\n            \nErrors:\n            \n- `404 not_found`: no contact with this id in the workspace, or the contact is deleted.\n            \nRequires Campaigns edit.\n\nRate limit: 4,800 calls a minute per API key, on top of the workspace limits.","operationId":"contacts.delete","parameters":[{"name":"contactId","in":"path","description":"The contact id.","required":true,"schema":{"type":"integer","format":"int64"}},{"name":"Ken-Version","in":"header","description":"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 value that is not a version, such as `2027-01-01` or `2026-11-2`, answers `400 unsupported_version`, whose `details` list the supported versions.","schema":{"enum":["2026-11-02","1.1"],"type":"string"},"examples":{"default":{"value":"2026-11-02","x-disabled":false}}},{"name":"X-Ken-Workspace-Id","in":"header","description":"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`.","schema":{"type":"integer","format":"int64"}}],"responses":{"204":{"description":"No Content","headers":{"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"}}},"400":{"description":"Bad Request","headers":{"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Failure"}}},"x-ken-error-codes":["unsupported_version","workspace_required"]},"401":{"description":"Unauthorized","headers":{"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/UnauthorizedError"}}},"x-ken-error-codes":["unauthenticated"]},"404":{"description":"Not Found","headers":{"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Failure"}}},"x-ken-error-codes":["not_found"]},"429":{"description":"Too Many Requests","headers":{"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/TooManyRequestsError"}},"text/plain":{"schema":{"$ref":"#/components/schemas/RateLimitedText"}}},"x-ken-error-codes":["rate_limited"]}},"x-ken-permission":{"kind":"page","page":"campaigns","access":"edit","summary":"Campaigns edit"},"x-ken-rate-limit":{"limit":4800,"windowSeconds":60,"per":"api_key"}}},"/v1/contacts/bulk-delete":{"post":{"tags":["contacts"],"summary":"Delete contacts in bulk","description":"Deletes up to 1,000 contacts in one call, as the single delete does. `succeeded` lists the ids this call\ndeleted. An id that is not a contact in the workspace is in `failed` with code `not_found`\nand nothing changes for it.\n            \nErrors:\n            \n- `400 validation_failed`: `ids` is missing or empty, holds more than 1,000 ids, or holds an id that\n  is not positive.\n            \nRequires Campaigns edit.\n\nRate limit: 480 calls a minute per API key, on top of the workspace limits.","operationId":"contacts.bulk-delete","parameters":[{"name":"Ken-Version","in":"header","description":"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 value that is not a version, such as `2027-01-01` or `2026-11-2`, answers `400 unsupported_version`, whose `details` list the supported versions.","schema":{"enum":["2026-11-02","1.1"],"type":"string"},"examples":{"default":{"value":"2026-11-02","x-disabled":false}}},{"name":"X-Ken-Workspace-Id","in":"header","description":"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`.","schema":{"type":"integer","format":"int64"}}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/BulkDeleteContactsRequest"}}}},"responses":{"200":{"description":"OK","headers":{"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ContactBulkResultResponse"}}}},"400":{"description":"Bad Request","headers":{"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Failure"}}},"x-ken-error-codes":["unsupported_version","validation_failed","workspace_required"]},"401":{"description":"Unauthorized","headers":{"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/UnauthorizedError"}}},"x-ken-error-codes":["unauthenticated"]},"404":{"description":"Not Found","headers":{"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Failure"}}},"x-ken-error-codes":["not_found"]},"429":{"description":"Too Many Requests","headers":{"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/TooManyRequestsError"}},"text/plain":{"schema":{"$ref":"#/components/schemas/RateLimitedText"}}},"x-ken-error-codes":["rate_limited"]}},"x-ken-permission":{"kind":"page","page":"campaigns","access":"edit","summary":"Campaigns edit"},"x-ken-rate-limit":{"limit":480,"windowSeconds":60,"per":"api_key"}}},"/v1/contacts/bulk-pause":{"post":{"tags":["contacts"],"summary":"Pause sequences for contacts","description":"Stops the campaign sequence of up to 1,000 contacts. Each paused contact gets `sequenceStopReason`\n`paused` and a `sequenceStoppedAt` time, and its pending unsent steps are cancelled. A\npaused contact is not do-not-contact and stays in its campaign. Resume it with <c>POST\n/v1/contacts/bulk-resume</c>.\n            \n`succeeded` lists every id that is paused after the call, including contacts that were already paused, so\na retry is safe. Every other id is in `failed` with one of these codes:\n            \n- `already_stopped`: the sequence already stopped for another reason, which stays.\n- `do_not_contact`: the contact is do-not-contact.\n- `not_found`: the id is not a contact in the workspace, the contact is deleted, or it is in no campaign.\n- `internal_error`: the pause failed. Retry that id.\n            \nErrors:\n            \n- `400 validation_failed`: `ids` is missing or empty, holds more than 1,000 ids, or holds an id that\n  is not positive.\n            \nRequires Campaigns edit and the `launch` permission.\n\nRate limit: 480 calls a minute per API key, on top of the workspace limits.\n\nNeeds the `pause_leads` feature on your workspace. Until it is on, calls answer 404.","operationId":"contacts.bulk-pause","parameters":[{"name":"Ken-Version","in":"header","description":"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 value that is not a version, such as `2027-01-01` or `2026-11-2`, answers `400 unsupported_version`, whose `details` list the supported versions.","schema":{"enum":["2026-11-02","1.1"],"type":"string"},"examples":{"default":{"value":"2026-11-02","x-disabled":false}}},{"name":"X-Ken-Workspace-Id","in":"header","description":"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`.","schema":{"type":"integer","format":"int64"}}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/BulkContactSequenceRequest"}}}},"responses":{"200":{"description":"OK","headers":{"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ContactBulkResultResponse"}}}},"400":{"description":"Bad Request","headers":{"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Failure"}}},"x-ken-error-codes":["unsupported_version","validation_failed","workspace_required"]},"401":{"description":"Unauthorized","headers":{"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/UnauthorizedError"}}},"x-ken-error-codes":["unauthenticated"]},"404":{"description":"Not Found","headers":{"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Failure"}}},"x-ken-error-codes":["not_found"]},"429":{"description":"Too Many Requests","headers":{"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/TooManyRequestsError"}},"text/plain":{"schema":{"$ref":"#/components/schemas/RateLimitedText"}}},"x-ken-error-codes":["rate_limited"]}},"x-ken-features":["pause_leads"],"x-ken-permission":{"kind":"page","page":"campaigns","access":"edit","features":["launch"],"summary":"Campaigns edit and the `launch` permission"},"x-ken-rate-limit":{"limit":480,"windowSeconds":60,"per":"api_key"}}},"/v1/contacts/bulk-resume":{"post":{"tags":["contacts"],"summary":"Resume sequences for paused contacts","description":"Restarts the campaign sequence of up to 1,000 paused contacts. Only a stop with `sequenceStopReason`\n`paused` is cleared. Kenso plans the next steps of resumed contacts on its next planning pass,\nabout every 10 minutes, and a held LinkedIn step picks up within the hour.\n            \n`succeeded` lists the ids this call resumed. Every other id is in `failed` with one of these codes:\n            \n- `not_paused`: the sequence is running, or it stopped for another reason, which stays.\n- `not_found`: the id is not a contact in the workspace.\n            \nErrors:\n            \n- `400 validation_failed`: `ids` is missing or empty, holds more than 1,000 ids, or holds an id that\n  is not positive.\n            \nRequires Campaigns edit and the `launch` permission.\n\nRate limit: 480 calls a minute per API key, on top of the workspace limits.","operationId":"contacts.bulk-resume","parameters":[{"name":"Ken-Version","in":"header","description":"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 value that is not a version, such as `2027-01-01` or `2026-11-2`, answers `400 unsupported_version`, whose `details` list the supported versions.","schema":{"enum":["2026-11-02","1.1"],"type":"string"},"examples":{"default":{"value":"2026-11-02","x-disabled":false}}},{"name":"X-Ken-Workspace-Id","in":"header","description":"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`.","schema":{"type":"integer","format":"int64"}}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/BulkContactSequenceRequest"}}}},"responses":{"200":{"description":"OK","headers":{"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ContactBulkResultResponse"}}}},"400":{"description":"Bad Request","headers":{"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Failure"}}},"x-ken-error-codes":["unsupported_version","validation_failed","workspace_required"]},"401":{"description":"Unauthorized","headers":{"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/UnauthorizedError"}}},"x-ken-error-codes":["unauthenticated"]},"404":{"description":"Not Found","headers":{"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Failure"}}},"x-ken-error-codes":["not_found"]},"429":{"description":"Too Many Requests","headers":{"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/TooManyRequestsError"}},"text/plain":{"schema":{"$ref":"#/components/schemas/RateLimitedText"}}},"x-ken-error-codes":["rate_limited"]}},"x-ken-permission":{"kind":"page","page":"campaigns","access":"edit","features":["launch"],"summary":"Campaigns edit and the `launch` permission"},"x-ken-rate-limit":{"limit":480,"windowSeconds":60,"per":"api_key"}}},"/v1/contacts/bulk-update":{"post":{"tags":["contacts"],"summary":"Update contacts in bulk","description":"Updates up to 1,000 contacts in one call. Each item is a `contactId` plus any fields <c>PATCH\n/v1/contacts/{contactId}</c> accepts, with the same rules. Items that change only the contact's own fields\n(names, title, LinkedIn URL, location, outreach language, do-not-contact) are written together. The other\nitems run one at a time in request order. A problem with one item fails only that item.\n            \n`results` has one entry per item in request order. Its `status` is `updated`, `not_found`\n(no such contact in the workspace), `validation_failed` (a field is invalid), `video_in_use`\n(a sent or queued step uses the contact's video) or `failed`. After 5 failed items in a row,\nKenso stops running items one at a time and marks each remaining one `failed` with a message asking you\nto retry it. Items written together keep their own result.\n            \nErrors:\n            \n- `400 validation_failed`: nothing was written, because `items` is empty, holds more than 1,000\n  entries, holds an entry that is not an object or has no positive `contactId`, or repeats a\n  `contactId`.\n            \nRequires Campaigns edit.\n\nRate limit: 480 calls a minute per API key, on top of the workspace limits.","operationId":"contacts.bulk-update","parameters":[{"name":"Ken-Version","in":"header","description":"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 value that is not a version, such as `2027-01-01` or `2026-11-2`, answers `400 unsupported_version`, whose `details` list the supported versions.","schema":{"enum":["2026-11-02","1.1"],"type":"string"},"examples":{"default":{"value":"2026-11-02","x-disabled":false}}},{"name":"X-Ken-Workspace-Id","in":"header","description":"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`.","schema":{"type":"integer","format":"int64"}}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/BulkUpdateContactsBody"}}},"required":true},"responses":{"200":{"description":"OK","headers":{"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ContactBulkUpdateResultResponse"}}}},"400":{"description":"Bad Request","headers":{"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Failure"}}},"x-ken-error-codes":["unsupported_version","validation_failed","workspace_required"]},"401":{"description":"Unauthorized","headers":{"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/UnauthorizedError"}}},"x-ken-error-codes":["unauthenticated"]},"404":{"description":"Not Found","headers":{"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Failure"}}},"x-ken-error-codes":["not_found"]},"429":{"description":"Too Many Requests","headers":{"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/TooManyRequestsError"}},"text/plain":{"schema":{"$ref":"#/components/schemas/RateLimitedText"}}},"x-ken-error-codes":["rate_limited"]}},"x-ken-permission":{"kind":"page","page":"campaigns","access":"edit","summary":"Campaigns edit"},"x-ken-rate-limit":{"limit":480,"windowSeconds":60,"per":"api_key"}}},"/v1/contacts/bulk-restore":{"post":{"tags":["contacts"],"summary":"Restore deleted contacts","description":"Brings back up to 1,000 deleted contacts, the undo of a delete. Each contact returns to the campaign and\nsegment it was deleted from, with its emails and fields unchanged. Nothing is charged and no\nenrichment runs again.\n            \nA restored contact in an active campaign can get its next email steps again. LinkedIn steps that stopped while\nthe contact was deleted stay stopped. A contact your client removed during a lead list approval comes\nback too, and the approval does not change.\n            \n`succeeded` lists the ids this call restored, and `restored` counts them. Every other id is in\n`failed` with one of these codes:\n            \n- `not_deleted`: the contact is not deleted, so nothing changed. `skipped` counts these, and a retry\n  of an id already restored returns this code.\n- `not_found`: the id is not a contact in the workspace.\n- `internal_error`: the restore failed. Retry that id.\n            \nErrors:\n            \n- `400 validation_failed`: `ids` is missing or empty, holds more than 1,000 ids, or holds an id that\n  is not positive.\n            \nRequires Campaigns edit.\n\nRate limit: 480 calls a minute per API key, on top of the workspace limits.","operationId":"contacts.bulk-restore","parameters":[{"name":"Ken-Version","in":"header","description":"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 value that is not a version, such as `2027-01-01` or `2026-11-2`, answers `400 unsupported_version`, whose `details` list the supported versions.","schema":{"enum":["2026-11-02","1.1"],"type":"string"},"examples":{"default":{"value":"2026-11-02","x-disabled":false}}},{"name":"X-Ken-Workspace-Id","in":"header","description":"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`.","schema":{"type":"integer","format":"int64"}}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/BulkRestoreContactsRequest"}}}},"responses":{"200":{"description":"OK","headers":{"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ContactBulkRestoreResultResponse"}}}},"400":{"description":"Bad Request","headers":{"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Failure"}}},"x-ken-error-codes":["unsupported_version","validation_failed","workspace_required"]},"401":{"description":"Unauthorized","headers":{"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/UnauthorizedError"}}},"x-ken-error-codes":["unauthenticated"]},"404":{"description":"Not Found","headers":{"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Failure"}}},"x-ken-error-codes":["not_found"]},"429":{"description":"Too Many Requests","headers":{"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/TooManyRequestsError"}},"text/plain":{"schema":{"$ref":"#/components/schemas/RateLimitedText"}}},"x-ken-error-codes":["rate_limited"]}},"x-ken-permission":{"kind":"page","page":"campaigns","access":"edit","summary":"Campaigns edit"},"x-ken-rate-limit":{"limit":480,"windowSeconds":60,"per":"api_key"}}},"/v1/contacts/search":{"post":{"tags":["contacts"],"summary":"Search contacts","description":"Finds contacts with the list filters plus more: several campaigns at once, field conditions in `filters`,\na set of contact ids, `readyOnly` for the contacts a campaign can send to now,\n`awaitingFirstEmail` for the ready leads its `readyLeadCount` counts, and the email security gateway\nor mailbox host of each contact's first Safe or Verified email. Deleted contacts are left out.\n            \nResults are ordered by contact id unless you set `sort`. Keep the same body and `sort` while you\npage with `cursor`. The response has no total count. Each contact on a page counts against the\nworkspace's API read rows, as on the list. `fields` names the contact properties to return, as on the list.\n            \nErrors:\n            \n- `400 validation_failed`: a body field breaks its rule. Examples: more than 50 `campaignIds` or\n  1,000 `contactIds`, `readyOnly` or `awaitingFirstEmail` without exactly one campaign, an\n  unknown `sort` field, `direction` without `sort`, a bad `limit` or `cursor`,\n  `createdBefore` not later than `createdAfter`, a name in `fields` that is not a top-level\n  contact property, a `behaviorTag` condition without\n  the `behavior_signals` feature, or a gateway or mailbox filter on a workspace without\n  security gateways. The error names the field.\n- `429 quota_exceeded`: the workspace used up its API read rows for the day.\n            \nRequires Campaigns view.\n\nRate limit: 12,000 calls a minute per API key, on top of the workspace limits.","operationId":"contacts.search","parameters":[{"name":"Ken-Version","in":"header","description":"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 value that is not a version, such as `2027-01-01` or `2026-11-2`, answers `400 unsupported_version`, whose `details` list the supported versions.","schema":{"enum":["2026-11-02","1.1"],"type":"string"},"examples":{"default":{"value":"2026-11-02","x-disabled":false}}},{"name":"X-Ken-Workspace-Id","in":"header","description":"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`.","schema":{"type":"integer","format":"int64"}}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/SearchContactsRequest"}}}},"responses":{"200":{"description":"OK","headers":{"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ContactListResponse"}}}},"400":{"description":"Bad Request","headers":{"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Failure"}}},"x-ken-error-codes":["unsupported_version","validation_failed","workspace_required"]},"401":{"description":"Unauthorized","headers":{"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/UnauthorizedError"}}},"x-ken-error-codes":["unauthenticated"]},"404":{"description":"Not Found","headers":{"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Failure"}}},"x-ken-error-codes":["not_found"]},"429":{"description":"Too Many Requests","headers":{"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/TooManyRequestsError"}},"text/plain":{"schema":{"$ref":"#/components/schemas/RateLimitedText"}}},"x-ken-error-codes":["quota_exceeded","rate_limited"]}},"x-ken-permission":{"kind":"page","page":"campaigns","access":"view","summary":"Campaigns view"},"x-ken-rate-limit":{"limit":12000,"windowSeconds":60,"per":"api_key"}}},"/v1/contacts/{contactId}/events":{"get":{"tags":["contacts"],"summary":"List a contact's events","description":"Returns the contact's timeline, newest first: emails sent, opened and clicked, replies, bounces, unsubscribes,\nand video activity. Filter it by event `type` and by time with `occurredAfter` and\n`occurredBefore`.\n            \nA cursor works only with the `limit` of the page that returned it.\n            \nErrors:\n            \n- `400 validation_failed`: `limit` is not between 1 and 200, `cursor` is not valid, was issued\n  for another `limit` or is past page 10,000, or the time range is reversed or longer than 366\n  days.\n- `404 not_found`: no contact with this id in the workspace.\n            \nRequires Campaigns view.\n\nRate limit: 12,000 calls a minute per API key, on top of the workspace limits.","operationId":"contacts.events","parameters":[{"name":"contactId","in":"path","description":"The contact id.","required":true,"schema":{"type":"integer","format":"int64"}},{"name":"type","in":"query","description":"Only events of this type, such as `email_sent`, `email_opened`, `contact_replied` or\n`video_event`. A video activity such as `video_watched` keeps only that activity. Omitted returns every\ntype.","schema":{"type":"string"}},{"name":"occurredAfter","in":"query","description":"Only events at or after this time, in UTC.","schema":{"type":"string","format":"date-time"}},{"name":"occurredBefore","in":"query","description":"The end of the range, in UTC. Kenso returns events up to one day after this time. Must be later than\n`occurredAfter`, and the range can span at most 366 days.","schema":{"type":"string","format":"date-time"}},{"name":"limit","in":"query","description":"Events per page, from 1 to 200. Default 50.","schema":{"maximum":200,"minimum":1,"type":"integer","format":"int32","default":50}},{"name":"cursor","in":"query","description":"The `nextCursor` of the previous page. It works only with the same `limit`.","schema":{"type":"string"}},{"name":"Ken-Version","in":"header","description":"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 value that is not a version, such as `2027-01-01` or `2026-11-2`, answers `400 unsupported_version`, whose `details` list the supported versions.","schema":{"enum":["2026-11-02","1.1"],"type":"string"},"examples":{"default":{"value":"2026-11-02","x-disabled":false}}},{"name":"X-Ken-Workspace-Id","in":"header","description":"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`.","schema":{"type":"integer","format":"int64"}}],"responses":{"200":{"description":"OK","headers":{"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ContactEventListResponse"}}}},"400":{"description":"Bad Request","headers":{"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Failure"}}},"x-ken-error-codes":["unsupported_version","validation_failed","workspace_required"]},"401":{"description":"Unauthorized","headers":{"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/UnauthorizedError"}}},"x-ken-error-codes":["unauthenticated"]},"404":{"description":"Not Found","headers":{"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Failure"}}},"x-ken-error-codes":["not_found"]},"429":{"description":"Too Many Requests","headers":{"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/TooManyRequestsError"}},"text/plain":{"schema":{"$ref":"#/components/schemas/RateLimitedText"}}},"x-ken-error-codes":["rate_limited"]}},"x-ken-permission":{"kind":"page","page":"campaigns","access":"view","summary":"Campaigns view"},"x-ken-rate-limit":{"limit":12000,"windowSeconds":60,"per":"api_key"}}},"/v1/contacts/{contactId}/website-pages":{"get":{"tags":["contacts"],"summary":"List the contact's company website pages","description":"Returns the pages Kenso holds for the website of the contact's company, each with its text as markdown. The\nlist puts the home page first, then the about, pricing, product, customer and careers pages, then the\nrest, newest first within each type. Pages without content are left out.\n            \nThe list holds at most 50 pages and has no further pages.\n            \nErrors:\n            \n- `404 not_found`: no contact with this id in the workspace.\n            \nRequires Campaigns view.\n\nRate limit: 12,000 calls a minute per API key, on top of the workspace limits.","operationId":"contacts.list-website-pages","parameters":[{"name":"contactId","in":"path","description":"The contact id.","required":true,"schema":{"type":"integer","format":"int64"}},{"name":"Ken-Version","in":"header","description":"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 value that is not a version, such as `2027-01-01` or `2026-11-2`, answers `400 unsupported_version`, whose `details` list the supported versions.","schema":{"enum":["2026-11-02","1.1"],"type":"string"},"examples":{"default":{"value":"2026-11-02","x-disabled":false}}},{"name":"X-Ken-Workspace-Id","in":"header","description":"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`.","schema":{"type":"integer","format":"int64"}}],"responses":{"200":{"description":"OK","headers":{"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ContactWebsitePageListResponse"}}}},"400":{"description":"Bad Request","headers":{"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Failure"}}},"x-ken-error-codes":["unsupported_version","workspace_required"]},"401":{"description":"Unauthorized","headers":{"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/UnauthorizedError"}}},"x-ken-error-codes":["unauthenticated"]},"404":{"description":"Not Found","headers":{"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Failure"}}},"x-ken-error-codes":["not_found"]},"429":{"description":"Too Many Requests","headers":{"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/TooManyRequestsError"}},"text/plain":{"schema":{"$ref":"#/components/schemas/RateLimitedText"}}},"x-ken-error-codes":["rate_limited"]}},"x-ken-permission":{"kind":"page","page":"campaigns","access":"view","summary":"Campaigns view"},"x-ken-rate-limit":{"limit":12000,"windowSeconds":60,"per":"api_key"}}}},"components":{"securitySchemes":{"Bearer":{"type":"http","description":"Enter: Bearer {your Kenso API key}. Create one in the Kenso app under Settings > Integrations > API Keys.","scheme":"bearer","bearerFormat":"Opaque API key"}},"headers":{"RateLimit-Limit":{"description":"The request limit of the rate limit this request is closest to reaching: your plan's limit for this kind of call, your API key's own limit, or the operation's own limit, whichever has the fewest requests left.","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"The requests left under that limit. `0` on a `429`.","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"The seconds until that limit resets.","schema":{"type":"integer"}}},"schemas":{"ApiKeyError":{"required":["error"],"type":"object","properties":{"error":{"type":"string","description":"A sentence for people that says what went wrong. It can change, so do not parse it."}},"additionalProperties":false,"description":"The body the API key check in front of the operations answered until November 2026, instead of the error body (`Failure`): `{ \"error\": \"Invalid or revoked API key\" }` on a `401`, `{ \"error\": \"Rate limit exceeded\" }` on a `429` and `{ \"error\": \"Authentication is temporarily unavailable\" }` on a `503`. It has no `code`, so branch on the HTTP status."},"BulkContactSequenceRequest":{"required":["ids"],"type":"object","properties":{"ids":{"type":"array","items":{"type":"integer","format":"int64"},"description":"Required. From 1 to 1,000 contact ids in the workspace."}},"additionalProperties":false,"description":"The contacts whose campaign sequence to pause or resume.","example":{"ids":[90125,90126,90131]}},"BulkDeleteContactsRequest":{"required":["ids"],"type":"object","properties":{"ids":{"type":"array","items":{"type":"integer","format":"int64"},"description":"Required. From 1 to 1,000 contact ids in the workspace."}},"additionalProperties":false,"description":"The contacts to delete.","example":{"ids":[90125,90126,90131]}},"BulkRestoreContactsRequest":{"required":["ids"],"type":"object","properties":{"ids":{"type":"array","items":{"type":"integer","format":"int64"},"description":"Required. From 1 to 1,000 contact ids in the workspace."}},"additionalProperties":false,"description":"The deleted contacts to restore.","example":{"ids":[90125,90126,90131]}},"BulkUpdateContactItemBody":{"required":["contactId"],"type":"object","properties":{"firstName":{"type":"string","description":"First name. Null clears it.","nullable":true},"lastName":{"type":"string","description":"Last name. Null clears it.","nullable":true},"title":{"type":"string","description":"Job title. Null clears it.","nullable":true},"linkedInUrl":{"type":"string","description":"LinkedIn profile URL. Null clears it.","nullable":true},"location":{"type":"string","description":"Location. Null clears it.","nullable":true},"email":{"type":"string","description":"The contact's email address. It must be valid, not another contact's address and not one of the contact's\npersonal addresses. Null removes it.","nullable":true},"isQualified":{"type":"boolean","description":"True or false to mark the contact qualified or not. Null is refused."},"doNotContact":{"type":"boolean","description":"True to mark the contact do-not-contact, so Kenso sends it nothing, or false to clear that. Null is refused."},"outreachLanguage":{"type":"string","description":"The language Ken writes to the contact in: a locale such as `fr-FR` or `es-MX`, or a language code\nsuch as `de`. Kenso locks it, so no import, enrichment or reply changes it. Null clears and unlocks it.","nullable":true},"customVariables":{"type":"object","additionalProperties":{"type":"string","nullable":true},"description":"Values to merge into the contact's custom variables, by key. A string sets the key, and null or an empty\nstring removes it. Keys you leave out stay. The object itself cannot be null."},"customImageUrl":{"type":"string","description":"The contact's own image, shown in emails as `{{custom_image}}`: a public https URL of at most 2,048\ncharacters, which Kenso downloads and hosts. An empty string or null clears it. Needs campaign images on the\nworkspace.","nullable":true},"customVideo":{"type":"string","description":"The contact's own video, shown in emails as `{{custom_video}}`: a Loom, YouTube, Vimeo, Wistia, Vidyard,\nSendspark or HeyGen share link or embed code, at most 20,480 characters. An empty string or null clears it.\nNeeds campaign videos on the workspace and a contact in a campaign. While a sent or queued step uses the\ncurrent video, it cannot change.","nullable":true},"contactId":{"type":"integer","description":"Required. The contact to update. Each contact id can appear only once in a request.","format":"int64"}},"additionalProperties":false,"description":"One contact to update: its `contactId` plus any field `PATCH /v1/contacts/{contactId}` accepts, with the\nsame rules."},"BulkUpdateContactsBody":{"required":["items"],"type":"object","properties":{"items":{"type":"array","items":{"$ref":"#/components/schemas/BulkUpdateContactItemBody"},"description":"Required. From 1 to 1,000 items, run in request order."}},"additionalProperties":false,"description":"The contacts to update in one call.","example":{"items":[{"contactId":90125,"title":"SVP of Engineering","customVariables":{"open_roles":"15 engineering roles"}},{"contactId":90131,"doNotContact":true}]}},"ComparisonOperator":{"enum":["equals","not_equals","contains","not_contains","starts_with","ends_with","greater_than","greater_than_or_equal","less_than","less_than_or_equal","between","in","not_in","is_null","is_not_null"],"type":"string","description":"How a filter condition compares a field with its value. The legacy API takes the integer: 0 Equals, 1 NotEquals, 2\nContains, 3 NotContains, 4 StartsWith, 5 EndsWith, 6 GreaterThan, 7 GreaterThanOrEqual, 8 LessThan, 9\nLessThanOrEqual, 10 Between, 11 In, 12 NotIn, 13 IsNull, 14 IsNotNull. Ken-Version 1.1 takes the name in snake_case\n(`not_equals`), or the integer."},"Contact":{"type":"object","properties":{"id":{"type":"integer","description":"The contact id.","format":"int64"},"campaignId":{"type":"integer","description":"The campaign the contact is in. Null when the contact is in no campaign.","format":"int64","nullable":true},"segmentId":{"type":"integer","description":"The campaign segment the contact is in.","format":"int64","nullable":true},"campaignListId":{"type":"integer","description":"The import list that added the contact to its campaign. Each import makes one list. Pass it as `listId`\nto export the contacts of that import.","format":"int64","nullable":true},"companyId":{"type":"integer","description":"The id of the contact's company record.","format":"int64","nullable":true},"companyName":{"type":"string","description":"Company name.","nullable":true},"companyEmailName":{"type":"string","description":"The company name as Ken writes it in emails: a short form without taglines, trademark signs or text in\nbrackets.","nullable":true},"firstName":{"type":"string","description":"First name.","nullable":true},"lastName":{"type":"string","description":"Last name.","nullable":true},"email":{"type":"string","description":"The contact's first email address. The address `emailValidity` describes can be a later one.","nullable":true},"linkedInUrl":{"type":"string","description":"LinkedIn profile URL.","nullable":true},"profileUrn":{"type":"string","description":"The LinkedIn member id of the profile, such as a Sales Navigator id, when Kenso knows it.","nullable":true},"isOpenLink":{"type":"boolean","description":"True when the LinkedIn profile is an Open Profile, which any LinkedIn member can message without a connection.\nNull when unknown.","nullable":true},"jsonGeoLocation":{"type":"string","description":"The LinkedIn profile's location details as a JSON string.","nullable":true},"title":{"type":"string","description":"Job title.","nullable":true},"isQualified":{"type":"boolean","description":"True when the contact is qualified for its campaign."},"doNotContact":{"type":"boolean","description":"True when the contact is marked do-not-contact. Kenso sends nothing to a do-not-contact contact."},"sequenceStoppedAt":{"type":"string","description":"When the contact's sequence in its campaign stopped, in UTC. Do-not-contact does not set it. Omitted while the\nsequence runs.","format":"date-time","nullable":true},"sequenceStopReason":{"type":"string","description":"Why the sequence stopped: `paused` (a member paused the contact), `account_play` (the contact\nmatched an active account play after a step), `promoted` (the contact's company was promoted to\nAccounts), or a reason from a campaign imported from another tool (`migration_finished`,\n`migration_paused`, `migration_pending`). New reasons can appear. Omitted while the sequence runs.","nullable":true},"isDecisionMaker":{"type":"boolean","description":"True when Kenso's data marks the person as a decision maker."},"qualityScore":{"type":"integer","description":"The contact's lead quality score in its campaign. Null until Kenso scores the contact.","format":"int32","nullable":true},"qualityReasoning":{"type":"string","description":"Ken's explanation of `qualityScore`. Null without a score.","nullable":true},"leadQualityScoreId":{"type":"integer","description":"The id of the lead quality score behind `qualityReasoning`; absent with no reasoning.","format":"int64","nullable":true},"profileImage":{"type":"string","description":"URL of the person's profile photo. Null when Kenso has no real photo.","nullable":true},"qualificationResponse":{"type":"string","description":"Ken's latest AI qualification answer for the contact.","nullable":true},"qualificationResponseId":{"type":"integer","description":"The id of the qualification answer behind `qualificationResponse`; absent with no answer.","format":"int64","nullable":true},"segmentationReasoning":{"type":"string","description":"Ken's latest explanation of why the contact is in its segment.","nullable":true},"experiencesJson":{"type":"string","description":"The person's work history as a JSON string.","nullable":true},"customVariables":{"type":"object","additionalProperties":{"type":"string"},"description":"The contact's custom variable values by key, for the keys the campaign defines. Keys without a value are left\nout. Null when there are none.","nullable":true},"emailsSent":{"type":"integer","description":"Emails sent to the contact. The six email counts are omitted until the contact has email stats.","format":"int32","nullable":true},"clicks":{"type":"integer","description":"Clicks on links in emails to the contact.","format":"int32","nullable":true},"replies":{"type":"integer","description":"Email replies from the contact.","format":"int32","nullable":true},"unsubscribes":{"type":"integer","description":"Campaigns the contact unsubscribed from, 0 or 1 for a contact in one campaign.","format":"int32","nullable":true},"bounces":{"type":"integer","description":"Emails to the contact that bounced.","format":"int32","nullable":true},"positiveReplies":{"type":"integer","description":"Campaigns where the contact sent an interested reply, 0 or 1 for a contact in one campaign.","format":"int32","nullable":true},"connectionRequestsSent":{"type":"integer","description":"LinkedIn connection requests sent to the contact and confirmed. The four LinkedIn counts are omitted when the\ncontact has no LinkedIn steps and no confirmed LinkedIn send.","format":"int32","nullable":true},"connectionsAccepted":{"type":"integer","description":"1 when the contact accepted the campaign's LinkedIn connection request, else 0.","format":"int32","nullable":true},"linkedInMessagesSent":{"type":"integer","description":"LinkedIn messages and InMails sent to the contact and confirmed.","format":"int32","nullable":true},"linkedInReplies":{"type":"integer","description":"1 when the contact replied on LinkedIn in the campaign, else 0.","format":"int32","nullable":true},"headline":{"type":"string","description":"LinkedIn headline.","nullable":true},"location":{"type":"string","description":"Location as the profile writes it.","nullable":true},"city":{"type":"string","description":"City.","nullable":true},"state":{"type":"string","description":"State or region.","nullable":true},"country":{"type":"string","description":"Country name.","nullable":true},"countryIso2":{"type":"string","description":"Two-letter ISO 3166 country code, such as `DE`.","nullable":true},"companyLogo":{"type":"string","description":"URL of the company logo. Null when Kenso has no real logo.","nullable":true},"emailEnrichmentProviders":{"type":"array","items":{"type":"string"},"description":"The email finder that found the contact's first email address, as a list of slugs, such as `ken` for\nKenso's own email database. Null when the address did not come from a finder.","nullable":true},"linkedInUrlNameMismatch":{"type":"boolean","description":"True when the LinkedIn URL looks like someone else's: its name part does not match the contact's first and\nlast name, or it is not a personal profile URL."},"segmentName":{"type":"string","description":"Name of the contact's segment.","nullable":true},"missingRequiredVariableKeys":{"type":"array","items":{"type":"string"},"description":"The variables the campaign requires for sending that the contact has no value for: custom variable keys, and\nimage or video variables that are not ready. Null when none are missing.","nullable":true},"linkedInSendBlockedReason":{"type":"string","description":"Why the contact's LinkedIn sequence is held: `missing_required_variables: <names>` names the `{{name}}`\ntokens in a LinkedIn step's message or InMail subject that nothing fills, so Kenso stopped the sequence at that\nstep instead of sending them as written. Fix the step's text or give the token a fallback. Null when nothing is\nheld.","nullable":true},"emailValidity":{"allOf":[{"$ref":"#/components/schemas/EmailValidity"}],"description":"The verdict of the contact's first email address that is Safe or Verified: `safe` or `verified`.\nNull when no address of the contact is Safe or Verified."},"emailFromKenPool":{"type":"boolean","description":"True when the address `emailValidity` describes came free from Kenso's own email database. Omitted\nwithout a Safe or Verified email.","nullable":true},"companyDomain":{"type":"string","description":"Company website domain.","nullable":true},"companySize":{"type":"string","description":"Employee count range, such as `51-200`.","nullable":true},"companyType":{"type":"string","description":"Company type.","nullable":true},"companyIndustry":{"type":"string","description":"Industry.","nullable":true},"companyLocation":{"type":"string","description":"Company location.","nullable":true},"companyTechnologies":{"type":"string","description":"Technologies the company uses, as one text value.","nullable":true},"companyLinkedInUrl":{"type":"string","description":"Company LinkedIn page URL.","nullable":true},"companyLinkedInIdent":{"type":"string","description":"The company's LinkedIn identifier.","nullable":true},"companyEmployeeCount":{"type":"integer","description":"Number of employees.","format":"int32","nullable":true},"companySpecialities":{"type":"string","description":"The company's specialities, as one text value.","nullable":true},"companyDescription":{"type":"string","description":"Company description.","nullable":true},"companyCrunchBaseUrl":{"type":"string","description":"Company Crunchbase URL.","nullable":true},"companyJsonLocation":{"type":"string","description":"The company's location details as a JSON string.","nullable":true},"companyFoundedYear":{"type":"integer","description":"Year the company was founded.","format":"int32","nullable":true},"headquartersCity":{"type":"string","description":"City of the company headquarters.","nullable":true},"headquartersState":{"type":"string","description":"State or region of the company headquarters.","nullable":true},"headquartersCountry":{"type":"string","description":"Country of the company headquarters.","nullable":true},"seniorityLevel":{"type":"string","description":"Seniority level.","nullable":true},"function":{"type":"string","description":"Job function, such as sales or engineering.","nullable":true},"yearsOfExperience":{"type":"number","description":"Years of work experience.","format":"float","nullable":true},"languages":{"type":"string","description":"Languages the person lists, as one text value.","nullable":true},"outreachLanguage":{"type":"string","description":"The locale Ken writes to the contact in, such as `fr-FR`, or a two-letter language code such as\n`de`. Omitted until Ken picks one. `PATCH` sets it by hand and locks it.","nullable":true},"outreachFormality":{"allOf":[{"$ref":"#/components/schemas/OutreachFormality"}],"description":"The register Ken writes to the contact in: `formal` or `informal`. Omitted when the language's\ndefault applies."},"outreachLanguageSource":{"allOf":[{"$ref":"#/components/schemas/OutreachLanguageSource"}],"description":"Where the outreach language came from: `manual` (a member set it), `reply` (the language the contact\nreplied in), `declared` (a language the contact lists), `country` (the contact's country), `hq`\n(the company headquarters' country) or `default` (the campaign's language)."},"outreachLanguageConfidence":{"type":"number","description":"How sure Ken is of the outreach language, from 0 to 1. A language a member set is 1, and the campaign's\ndefault language is 0.","format":"float","nullable":true},"outreachLanguageLocked":{"type":"boolean","description":"True when a member set the language. No import, enrichment or reply replaces it."},"phoneNumber":{"type":"string","description":"The contact's first phone number.","nullable":true},"phoneNumberValidity":{"allOf":[{"$ref":"#/components/schemas/PhoneNumberValidity"}],"description":"How sure Kenso is that `phoneNumber` works. Omitted without a phone number."},"phoneCountryAssumed":{"type":"boolean","description":"True when Kenso added the country code itself: a number stored without one was read as a US number (+1). Treat\nit as unverified."},"lastJobTitle":{"type":"string","description":"Title of the most recent job in the work history.","nullable":true},"lastJobDescription":{"type":"string","description":"Description of the most recent job in the work history.","nullable":true},"employmentType":{"type":"string","description":"Employment type of the current job, such as full-time.","nullable":true},"employmentLocation":{"type":"string","description":"Location of the current job.","nullable":true},"summary":{"type":"string","description":"The profile summary.","nullable":true},"skills":{"type":"string","description":"Skills, as one text value.","nullable":true},"education":{"type":"string","description":"Education, as one text value.","nullable":true},"personalizationLineIds":{"type":"object","additionalProperties":{"type":"integer","format":"int64"},"description":"The id of the AI line behind each personalization field, keyed like those fields (`personalization1` to\n`personalization20`). Rate a line with AI feedback as `ai_line:{id}`. Absent when the contact has no lines.","nullable":true},"createdAt":{"type":"string","description":"When Kenso created the contact, in UTC.","format":"date-time"},"updatedAt":{"type":"string","description":"When the contact last changed, in UTC.","format":"date-time"},"accountPlay":{"allOf":[{"$ref":"#/components/schemas/ContactAccountPlay"}],"description":"The contact's account play status in its campaign. Omitted when no account play holds, stops or counts the\ncontact, and for a caller without Accounts view."},"securityGateway":{"allOf":[{"$ref":"#/components/schemas/ContactSecurityGateway"}],"description":"The email security gateway in front of the contact's first Safe or Verified email, the address Kenso sends to.\nOmitted when the workspace does not have security gateways."},"mailboxProvider":{"allOf":[{"$ref":"#/components/schemas/ContactMailboxProvider"}],"description":"The host of that email's mailbox, such as Google Workspace. Omitted when the workspace does not have security\ngateways."},"customVideo":{"allOf":[{"$ref":"#/components/schemas/ContactCustomVideo"}],"description":"The contact's own video, shown in emails as `{{custom_video}}`. Null when the contact has none or the\nworkspace does not have campaign videos. Set it with `customVideo` on <c>PATCH\n/v1/contacts/{contactId}</c>."}},"additionalProperties":{},"description":"A contact: one person in a campaign, with their profile, company, email and phone status, and outreach counts.\nWhen Ken wrote personalization lines for the contact, each one is an extra top-level field named\n`personalization1` to `personalization20`.","example":{"id":90125,"campaignId":4821,"segmentId":1207,"campaignListId":3305,"companyId":22841,"companyName":"Northwind Labs","companyEmailName":"Northwind","firstName":"Amanda","lastName":"Chen","email":"amanda.chen@northwind.example.com","linkedInUrl":"https://www.linkedin.com/in/amanda-chen-northwind","title":"VP of Engineering","isQualified":true,"doNotContact":false,"isDecisionMaker":true,"qualityScore":86,"qualityReasoning":"Leads a 40-person engineering team at a 120-person B2B SaaS company that is hiring engineers.","segmentationReasoning":"VP of Engineering, which matches the Engineering leaders segment.","customVariables":{"open_roles":"12 engineering roles"},"emailsSent":2,"clicks":0,"replies":1,"unsubscribes":0,"bounces":0,"positiveReplies":1,"headline":"VP of Engineering at Northwind Labs","location":"Austin, Texas, United States","city":"Austin","state":"Texas","country":"United States","countryIso2":"US","companyLogo":"https://cdn.example.com/companies/22841/logo.png","linkedInUrlNameMismatch":false,"segmentName":"Engineering leaders","emailValidity":"safe","emailFromKenPool":false,"companyDomain":"northwind.example.com","companySize":"51-200","companyIndustry":"Software Development","companyLocation":"Austin, Texas, United States","companyEmployeeCount":120,"companyDescription":"Northwind Labs builds developer onboarding software for engineering teams.","companyFoundedYear":2017,"headquartersCity":"Austin","headquartersState":"Texas","headquartersCountry":"United States","seniorityLevel":"VP","function":"Engineering","yearsOfExperience":14,"outreachLanguage":"en-US","outreachLanguageSource":"country","outreachLanguageConfidence":0.8,"outreachLanguageLocked":false,"phoneCountryAssumed":false,"createdAt":"2026-09-23T15:02:11Z","updatedAt":"2026-10-13T16:22:05Z"}},"ContactAccountPlay":{"type":"object","properties":{"status":{"type":"string","description":"What the account play does to the contact. `skipped`: held before the campaign's first step, because the\ncontact's company is in an active account play. A contact that already got a step stops at its next send.\n`stopped`: the sequence stopped for good. `would_skip`: protection only counts the match, and\nsending does not change."},"accountId":{"type":"integer","description":"The account whose play matches now. Omitted on a stopped contact whose account left the active stages. For a\ncaller who works only their own accounts, this field, `accountName` and `accountStage` are omitted\nwhen the caller does not own the account.","format":"int64","nullable":true},"accountName":{"type":"string","description":"The account name.","nullable":true},"accountStage":{"type":"string","description":"The account's stage: `warming`, `engaged`, `meeting_booked` or `in_deal`.","nullable":true}},"additionalProperties":false,"description":"How an account play affects the contact in its campaign."},"ContactBulkError":{"type":"object","properties":{"code":{"type":"string","description":"A stable error code, such as `not_found`, `validation_failed`, `not_deleted`,\n`not_paused`, `already_stopped`, `do_not_contact`, `video_in_use` or\n`internal_error`. Each operation lists the codes it returns."},"message":{"type":"string","description":"A readable explanation."}},"additionalProperties":false,"description":"The error for one contact or row of a bulk call."},"ContactBulkFailure":{"type":"object","properties":{"id":{"type":"integer","description":"The contact id. Omitted for a row Kenso refused before saving it.","format":"int64","nullable":true},"index":{"type":"integer","description":"The row's position in the request, from 0. Only on `POST /v1/campaigns/{campaignId}/contacts`.","format":"int32","nullable":true},"error":{"allOf":[{"$ref":"#/components/schemas/ContactBulkError"}],"description":"Why the contact or row failed."}},"additionalProperties":false,"description":"One contact or row a bulk call did not change, and why."},"ContactBulkRestoreResult":{"type":"object","properties":{"restored":{"type":"integer","description":"How many contacts this call restored: the length of `succeeded`.","format":"int32"},"skipped":{"type":"integer","description":"How many ids were not deleted, so nothing changed: the `not_deleted` entries of `failed`.","format":"int32"},"succeeded":{"type":"array","items":{"type":"integer","format":"int64"},"description":"Ids of the contacts this call restored."},"failed":{"type":"array","items":{"$ref":"#/components/schemas/ContactBulkFailure"},"description":"One entry for each id the call did not restore, with the reason."}},"additionalProperties":false,"description":"The outcome of restoring deleted contacts.","example":{"restored":2,"skipped":1,"succeeded":[90125,90126],"failed":[{"id":90131,"error":{"code":"not_deleted","message":"The contact is not deleted, so nothing changed."}}]}},"ContactBulkRestoreResultResponse":{"type":"object","properties":{"success":{"type":"boolean","description":"Always true on a success."},"data":{"allOf":[{"$ref":"#/components/schemas/ContactBulkRestoreResult"}],"description":"The result of the operation."}},"additionalProperties":false,"description":"The body of a successful operation that returns one result. The result is in `data`."},"ContactBulkResult":{"type":"object","properties":{"succeeded":{"type":"array","items":{"type":"integer","format":"int64"},"description":"Ids of the contacts the call changed or saved."},"failed":{"type":"array","items":{"$ref":"#/components/schemas/ContactBulkFailure"},"description":"One entry for each contact or row the call did not change, with the reason."},"results":{"type":"array","items":{"$ref":"#/components/schemas/ContactCreateRowResult"},"description":"One item per input row of `POST /v1/campaigns/{campaignId}/contacts`, in request order. Only that call\nreturns it.","nullable":true}},"additionalProperties":false,"description":"The outcome of a bulk contact call: the ids that succeeded and the ones that failed.","example":{"succeeded":[90125,90126],"failed":[{"id":90131,"error":{"code":"not_found","message":"No contact with this id in the workspace."}}]}},"ContactBulkResultResponse":{"type":"object","properties":{"success":{"type":"boolean","description":"Always true on a success."},"data":{"allOf":[{"$ref":"#/components/schemas/ContactBulkResult"}],"description":"The result of the operation."}},"additionalProperties":false,"description":"The body of a successful operation that returns one result. The result is in `data`."},"ContactBulkUpdateItemResult":{"type":"object","properties":{"contactId":{"type":"integer","description":"The item's contact id.","format":"int64"},"status":{"type":"string","description":"The item's outcome: `updated`, `not_found` (no such contact in the workspace),\n`validation_failed` (a field is invalid), `video_in_use` (a sent or queued step uses the contact's\nvideo, so it cannot change) or `failed` (retry the item)."},"error":{"type":"string","description":"A readable explanation when the item was not updated. Null on success.","nullable":true}},"additionalProperties":false,"description":"The outcome of one item of a bulk contact update."},"ContactBulkUpdateResult":{"type":"object","properties":{"updated":{"type":"integer","description":"How many items were updated.","format":"int32"},"failed":{"type":"integer","description":"How many items were not updated, for any reason.","format":"int32"},"results":{"type":"array","items":{"$ref":"#/components/schemas/ContactBulkUpdateItemResult"},"description":"One result per item, in request order."}},"additionalProperties":false,"description":"The outcome of a bulk contact update, with one result per item.","example":{"updated":1,"failed":1,"results":[{"contactId":90125,"status":"updated"},{"contactId":90131,"status":"not_found","error":"No contact with this id in the workspace."}]}},"ContactBulkUpdateResultResponse":{"type":"object","properties":{"success":{"type":"boolean","description":"Always true on a success."},"data":{"allOf":[{"$ref":"#/components/schemas/ContactBulkUpdateResult"}],"description":"The result of the operation."}},"additionalProperties":false,"description":"The body of a successful operation that returns one result. The result is in `data`."},"ContactCreateRowResult":{"type":"object","properties":{"index":{"type":"integer","description":"The row's position in `contacts`, from 0.","format":"int32"},"status":{"type":"string","description":"What Kenso did with the row: `created` (a new contact), `updated` (the campaign already had the\ncontact), `skipped` or `failed`."},"id":{"type":"integer","description":"The contact id, when Kenso saved the row.","format":"int64","nullable":true},"reason":{"type":"string","description":"Why a row was skipped or failed: `duplicate` (an earlier row or an existing contact), `blocklisted`\n(on the workspace blocklist), `already_contacted` (in another campaign, or emailed\ninside the campaign's recently-emailed window), `limit_reached` (the plan's contact allowance is used\nup), `invalid_email`, `excluded` (a campaign exclusion rule such as an excluded country),\n`validation` (another field rule) or `other`. On Kenso Lifetime, `limit_reached` also means the\nlicense's contacts (one pool across its workspaces) are used up.","nullable":true},"message":{"type":"string","description":"For a skipped or failed row, a readable explanation.","nullable":true},"sendable":{"type":"boolean","description":"On a saved row, false when the contact will not get campaign steps: it is do-not-contact, or Kenso added it\nunqualified, for example because no contact allowance was left.","nullable":true}},"additionalProperties":false,"description":"What Kenso did with one row of `POST /v1/campaigns/{campaignId}/contacts`."},"ContactCustomVideo":{"type":"object","properties":{"status":{"type":"string","description":"The video's state: `pending` while Kenso prepares the thumbnail, `ready` when emails can show the\nvideo, or `failed`."},"provider":{"type":"string","description":"The video host: `loom`, `youtube`, `vimeo`, `wistia`, `vidyard`, `sendspark` or\n`heygen`.","nullable":true},"source":{"type":"string","description":"How the video was set: `import` (a contact import), `api` (this API) or `mcp` (Ken or another\nAI assistant), or, for a generated video, the service that made it: `sendspark`, `heygen` or\n`vidyard`. New values can appear."},"watchUrl":{"type":"string","description":"The link where the video plays.","nullable":true},"previewUrl":{"type":"string","description":"A thumbnail image URL for showing the video in your own app. It works for a short time only. Null until the\nthumbnail is ready.","nullable":true},"previewExpiresAt":{"type":"string","description":"When `previewUrl` stops working, in UTC. Read the contact again for a new one.","format":"date-time","nullable":true},"error":{"allOf":[{"$ref":"#/components/schemas/ContactCustomVideoError"}],"description":"Why the video failed. Null unless `status` is `failed`."}},"additionalProperties":false,"description":"The contact's own video, the one emails show as `{{custom_video}}`."},"ContactCustomVideoError":{"type":"object","properties":{"code":{"type":"string","description":"A stable error code."},"detail":{"type":"string","description":"A readable explanation.","nullable":true}},"additionalProperties":false,"description":"Why the contact's video failed."},"ContactDetail":{"type":"object","properties":{"id":{"type":"integer","description":"The contact id.","format":"int64"},"campaignId":{"type":"integer","description":"The campaign the contact is in. Null when the contact is in no campaign.","format":"int64","nullable":true},"segmentId":{"type":"integer","description":"The campaign segment the contact is in.","format":"int64","nullable":true},"campaignListId":{"type":"integer","description":"The import list that added the contact to its campaign. Each import makes one list. Pass it as `listId`\nto export the contacts of that import.","format":"int64","nullable":true},"companyId":{"type":"integer","description":"The id of the contact's company record.","format":"int64","nullable":true},"companyName":{"type":"string","description":"Company name.","nullable":true},"companyEmailName":{"type":"string","description":"The company name as Ken writes it in emails: a short form without taglines, trademark signs or text in\nbrackets.","nullable":true},"firstName":{"type":"string","description":"First name.","nullable":true},"lastName":{"type":"string","description":"Last name.","nullable":true},"email":{"type":"string","description":"The contact's first email address. The address `emailValidity` describes can be a later one.","nullable":true},"linkedInUrl":{"type":"string","description":"LinkedIn profile URL.","nullable":true},"profileUrn":{"type":"string","description":"The LinkedIn member id of the profile, such as a Sales Navigator id, when Kenso knows it.","nullable":true},"isOpenLink":{"type":"boolean","description":"True when the LinkedIn profile is an Open Profile, which any LinkedIn member can message without a connection.\nNull when unknown.","nullable":true},"jsonGeoLocation":{"type":"string","description":"The LinkedIn profile's location details as a JSON string.","nullable":true},"title":{"type":"string","description":"Job title.","nullable":true},"isQualified":{"type":"boolean","description":"True when the contact is qualified for its campaign."},"doNotContact":{"type":"boolean","description":"True when the contact is marked do-not-contact. Kenso sends nothing to a do-not-contact contact."},"sequenceStoppedAt":{"type":"string","description":"When the contact's sequence in its campaign stopped, in UTC. Do-not-contact does not set it. Omitted while the\nsequence runs.","format":"date-time","nullable":true},"sequenceStopReason":{"type":"string","description":"Why the sequence stopped: `paused` (a member paused the contact), `account_play` (the contact\nmatched an active account play after a step), `promoted` (the contact's company was promoted to\nAccounts), or a reason from a campaign imported from another tool (`migration_finished`,\n`migration_paused`, `migration_pending`). New reasons can appear. Omitted while the sequence runs.","nullable":true},"isDecisionMaker":{"type":"boolean","description":"True when Kenso's data marks the person as a decision maker."},"qualityScore":{"type":"integer","description":"The contact's lead quality score in its campaign. Null until Kenso scores the contact.","format":"int32","nullable":true},"qualityReasoning":{"type":"string","description":"Ken's explanation of `qualityScore`. Null without a score.","nullable":true},"leadQualityScoreId":{"type":"integer","description":"The id of the lead quality score behind `qualityReasoning`; absent with no reasoning.","format":"int64","nullable":true},"profileImage":{"type":"string","description":"URL of the person's profile photo. Null when Kenso has no real photo.","nullable":true},"qualificationResponse":{"type":"string","description":"Ken's latest AI qualification answer for the contact.","nullable":true},"qualificationResponseId":{"type":"integer","description":"The id of the qualification answer behind `qualificationResponse`; absent with no answer.","format":"int64","nullable":true},"segmentationReasoning":{"type":"string","description":"Ken's latest explanation of why the contact is in its segment.","nullable":true},"experiencesJson":{"type":"string","description":"The person's work history as a JSON string.","nullable":true},"customVariables":{"type":"object","additionalProperties":{"type":"string"},"description":"The contact's custom variable values by key, for the keys the campaign defines. Keys without a value are left\nout. Null when there are none.","nullable":true},"emailsSent":{"type":"integer","description":"Emails sent to the contact. The six email counts are omitted until the contact has email stats.","format":"int32","nullable":true},"clicks":{"type":"integer","description":"Clicks on links in emails to the contact.","format":"int32","nullable":true},"replies":{"type":"integer","description":"Email replies from the contact.","format":"int32","nullable":true},"unsubscribes":{"type":"integer","description":"Campaigns the contact unsubscribed from, 0 or 1 for a contact in one campaign.","format":"int32","nullable":true},"bounces":{"type":"integer","description":"Emails to the contact that bounced.","format":"int32","nullable":true},"positiveReplies":{"type":"integer","description":"Campaigns where the contact sent an interested reply, 0 or 1 for a contact in one campaign.","format":"int32","nullable":true},"connectionRequestsSent":{"type":"integer","description":"LinkedIn connection requests sent to the contact and confirmed. The four LinkedIn counts are omitted when the\ncontact has no LinkedIn steps and no confirmed LinkedIn send.","format":"int32","nullable":true},"connectionsAccepted":{"type":"integer","description":"1 when the contact accepted the campaign's LinkedIn connection request, else 0.","format":"int32","nullable":true},"linkedInMessagesSent":{"type":"integer","description":"LinkedIn messages and InMails sent to the contact and confirmed.","format":"int32","nullable":true},"linkedInReplies":{"type":"integer","description":"1 when the contact replied on LinkedIn in the campaign, else 0.","format":"int32","nullable":true},"headline":{"type":"string","description":"LinkedIn headline.","nullable":true},"location":{"type":"string","description":"Location as the profile writes it.","nullable":true},"city":{"type":"string","description":"City.","nullable":true},"state":{"type":"string","description":"State or region.","nullable":true},"country":{"type":"string","description":"Country name.","nullable":true},"countryIso2":{"type":"string","description":"Two-letter ISO 3166 country code, such as `DE`.","nullable":true},"companyLogo":{"type":"string","description":"URL of the company logo. Null when Kenso has no real logo.","nullable":true},"emailEnrichmentProviders":{"type":"array","items":{"type":"string"},"description":"The email finder that found the contact's first email address, as a list of slugs, such as `ken` for\nKenso's own email database. Null when the address did not come from a finder.","nullable":true},"linkedInUrlNameMismatch":{"type":"boolean","description":"True when the LinkedIn URL looks like someone else's: its name part does not match the contact's first and\nlast name, or it is not a personal profile URL."},"segmentName":{"type":"string","description":"Name of the contact's segment.","nullable":true},"missingRequiredVariableKeys":{"type":"array","items":{"type":"string"},"description":"The variables the campaign requires for sending that the contact has no value for: custom variable keys, and\nimage or video variables that are not ready. Null when none are missing.","nullable":true},"linkedInSendBlockedReason":{"type":"string","description":"Why the contact's LinkedIn sequence is held: `missing_required_variables: <names>` names the `{{name}}`\ntokens in a LinkedIn step's message or InMail subject that nothing fills, so Kenso stopped the sequence at that\nstep instead of sending them as written. Fix the step's text or give the token a fallback. Null when nothing is\nheld.","nullable":true},"emailValidity":{"allOf":[{"$ref":"#/components/schemas/EmailValidity"}],"description":"The verdict of the contact's first email address that is Safe or Verified: `safe` or `verified`.\nNull when no address of the contact is Safe or Verified."},"emailFromKenPool":{"type":"boolean","description":"True when the address `emailValidity` describes came free from Kenso's own email database. Omitted\nwithout a Safe or Verified email.","nullable":true},"companyDomain":{"type":"string","description":"Company website domain.","nullable":true},"companySize":{"type":"string","description":"Employee count range, such as `51-200`.","nullable":true},"companyType":{"type":"string","description":"Company type.","nullable":true},"companyIndustry":{"type":"string","description":"Industry.","nullable":true},"companyLocation":{"type":"string","description":"Company location.","nullable":true},"companyTechnologies":{"type":"string","description":"Technologies the company uses, as one text value.","nullable":true},"companyLinkedInUrl":{"type":"string","description":"Company LinkedIn page URL.","nullable":true},"companyLinkedInIdent":{"type":"string","description":"The company's LinkedIn identifier.","nullable":true},"companyEmployeeCount":{"type":"integer","description":"Number of employees.","format":"int32","nullable":true},"companySpecialities":{"type":"string","description":"The company's specialities, as one text value.","nullable":true},"companyDescription":{"type":"string","description":"Company description.","nullable":true},"companyCrunchBaseUrl":{"type":"string","description":"Company Crunchbase URL.","nullable":true},"companyJsonLocation":{"type":"string","description":"The company's location details as a JSON string.","nullable":true},"companyFoundedYear":{"type":"integer","description":"Year the company was founded.","format":"int32","nullable":true},"headquartersCity":{"type":"string","description":"City of the company headquarters.","nullable":true},"headquartersState":{"type":"string","description":"State or region of the company headquarters.","nullable":true},"headquartersCountry":{"type":"string","description":"Country of the company headquarters.","nullable":true},"seniorityLevel":{"type":"string","description":"Seniority level.","nullable":true},"function":{"type":"string","description":"Job function, such as sales or engineering.","nullable":true},"yearsOfExperience":{"type":"number","description":"Years of work experience.","format":"float","nullable":true},"languages":{"type":"string","description":"Languages the person lists, as one text value.","nullable":true},"outreachLanguage":{"type":"string","description":"The locale Ken writes to the contact in, such as `fr-FR`, or a two-letter language code such as\n`de`. Omitted until Ken picks one. `PATCH` sets it by hand and locks it.","nullable":true},"outreachFormality":{"allOf":[{"$ref":"#/components/schemas/OutreachFormality"}],"description":"The register Ken writes to the contact in: `formal` or `informal`. Omitted when the language's\ndefault applies."},"outreachLanguageSource":{"allOf":[{"$ref":"#/components/schemas/OutreachLanguageSource"}],"description":"Where the outreach language came from: `manual` (a member set it), `reply` (the language the contact\nreplied in), `declared` (a language the contact lists), `country` (the contact's country), `hq`\n(the company headquarters' country) or `default` (the campaign's language)."},"outreachLanguageConfidence":{"type":"number","description":"How sure Ken is of the outreach language, from 0 to 1. A language a member set is 1, and the campaign's\ndefault language is 0.","format":"float","nullable":true},"outreachLanguageLocked":{"type":"boolean","description":"True when a member set the language. No import, enrichment or reply replaces it."},"phoneNumber":{"type":"string","description":"The contact's first phone number.","nullable":true},"phoneNumberValidity":{"allOf":[{"$ref":"#/components/schemas/PhoneNumberValidity"}],"description":"How sure Kenso is that `phoneNumber` works. Omitted without a phone number."},"phoneCountryAssumed":{"type":"boolean","description":"True when Kenso added the country code itself: a number stored without one was read as a US number (+1). Treat\nit as unverified."},"lastJobTitle":{"type":"string","description":"Title of the most recent job in the work history.","nullable":true},"lastJobDescription":{"type":"string","description":"Description of the most recent job in the work history.","nullable":true},"employmentType":{"type":"string","description":"Employment type of the current job, such as full-time.","nullable":true},"employmentLocation":{"type":"string","description":"Location of the current job.","nullable":true},"summary":{"type":"string","description":"The profile summary.","nullable":true},"skills":{"type":"string","description":"Skills, as one text value.","nullable":true},"education":{"type":"string","description":"Education, as one text value.","nullable":true},"personalizationLineIds":{"type":"object","additionalProperties":{"type":"integer","format":"int64"},"description":"The id of the AI line behind each personalization field, keyed like those fields (`personalization1` to\n`personalization20`). Rate a line with AI feedback as `ai_line:{id}`. Absent when the contact has no lines.","nullable":true},"createdAt":{"type":"string","description":"When Kenso created the contact, in UTC.","format":"date-time"},"updatedAt":{"type":"string","description":"When the contact last changed, in UTC.","format":"date-time"},"accountPlay":{"allOf":[{"$ref":"#/components/schemas/ContactAccountPlay"}],"description":"The contact's account play status in its campaign. Omitted when no account play holds, stops or counts the\ncontact, and for a caller without Accounts view."},"securityGateway":{"allOf":[{"$ref":"#/components/schemas/ContactSecurityGateway"}],"description":"The email security gateway in front of the contact's first Safe or Verified email, the address Kenso sends to.\nOmitted when the workspace does not have security gateways."},"mailboxProvider":{"allOf":[{"$ref":"#/components/schemas/ContactMailboxProvider"}],"description":"The host of that email's mailbox, such as Google Workspace. Omitted when the workspace does not have security\ngateways."},"customVideo":{"allOf":[{"$ref":"#/components/schemas/ContactCustomVideo"}],"description":"The contact's own video, shown in emails as `{{custom_video}}`. Null when the contact has none or the\nworkspace does not have campaign videos. Set it with `customVideo` on <c>PATCH\n/v1/contacts/{contactId}</c>."},"dataFlags":{"type":"object","additionalProperties":{},"description":"Signals about the contact's data by name, such as `jobChange` or `previousEmployerEmail`, each an\nobject with details such as `currentCompanyDomain` and `detectedAt`. New names can appear. Empty\nwhen there are none."},"personalEmails":{"type":"array","items":{"$ref":"#/components/schemas/PersonalEmail"},"description":"Personal email addresses found for the person, newest first. They are for you to read: Kenso never sends to,\nverifies or exports them. Empty when there are none."},"linkedInWait":{"allOf":[{"$ref":"#/components/schemas/ContactLinkedInWait"}],"description":"Why the contact's LinkedIn connection request cannot go out yet. Omitted when nothing holds it."}},"additionalProperties":{},"description":"A contact as `GET /v1/contacts/{contactId}` returns it: every contact field, plus its data flags and personal\nemails.","example":{"id":90125,"campaignId":4821,"segmentId":1207,"campaignListId":3305,"companyId":22841,"companyName":"Northwind Labs","companyEmailName":"Northwind","firstName":"Amanda","lastName":"Chen","email":"amanda.chen@northwind.example.com","linkedInUrl":"https://www.linkedin.com/in/amanda-chen-northwind","title":"VP of Engineering","isQualified":true,"doNotContact":false,"isDecisionMaker":true,"qualityScore":86,"qualityReasoning":"Leads a 40-person engineering team at a 120-person B2B SaaS company that is hiring engineers.","segmentationReasoning":"VP of Engineering, which matches the Engineering leaders segment.","customVariables":{"open_roles":"12 engineering roles"},"emailsSent":2,"clicks":0,"replies":1,"unsubscribes":0,"bounces":0,"positiveReplies":1,"headline":"VP of Engineering at Northwind Labs","location":"Austin, Texas, United States","city":"Austin","state":"Texas","country":"United States","countryIso2":"US","companyLogo":"https://cdn.example.com/companies/22841/logo.png","linkedInUrlNameMismatch":false,"segmentName":"Engineering leaders","emailValidity":"safe","emailFromKenPool":false,"companyDomain":"northwind.example.com","companySize":"51-200","companyIndustry":"Software Development","companyLocation":"Austin, Texas, United States","companyEmployeeCount":120,"companyDescription":"Northwind Labs builds developer onboarding software for engineering teams.","companyFoundedYear":2017,"headquartersCity":"Austin","headquartersState":"Texas","headquartersCountry":"United States","seniorityLevel":"VP","function":"Engineering","yearsOfExperience":14,"outreachLanguage":"en-US","outreachLanguageSource":"country","outreachLanguageConfidence":0.8,"outreachLanguageLocked":false,"phoneCountryAssumed":false,"createdAt":"2026-09-23T15:02:11Z","updatedAt":"2026-10-13T16:22:05Z","dataFlags":{"previousEmployerEmail":{"email":"amanda.chen@oldco.example.com","currentCompanyDomain":"northwind.example.com","detectedAt":"2026-10-14T09:41:27Z","source":"loopster"}},"personalEmails":[{"email":"amanda.chen@mail.example.org","source":"loopster","foundAt":"2026-10-14T09:41:27Z"}]}},"ContactDetailResponse":{"type":"object","properties":{"success":{"type":"boolean","description":"Always true on a success."},"data":{"allOf":[{"$ref":"#/components/schemas/ContactDetail"}],"description":"The result of the operation."}},"additionalProperties":false,"description":"The body of a successful operation that returns one result. The result is in `data`."},"ContactEvent":{"type":"object","properties":{"id":{"type":"string","description":"The event id, a string. Video activity ids start with `ve_`."},"type":{"type":"string","description":"The event type as Kenso recorded it, such as `email_sent`, `email_opened`, `email_clicked`,\n`contact_replied`, `email_bounced` or `contact_unsubscribed`. Video activity is\n`video_event`. New types can appear.","nullable":true},"occurredAt":{"type":"string","description":"When the event happened, in UTC.","format":"date-time"},"campaignId":{"type":"integer","description":"The campaign the event belongs to. Null when it has none.","format":"int64","nullable":true},"kind":{"type":"string","description":"Which video activity a `video_event` is: `video_viewed`, `video_played`, `video_watched`,\n`video_liked` or `video_cta_clicked`. Omitted on every other type.","nullable":true}},"additionalProperties":false,"description":"One event on a contact's timeline, such as an email sent, a click, a reply or a video view.","example":{"id":"558120","type":"contact_replied","occurredAt":"2026-10-13T16:22:05Z","campaignId":4821}},"ContactEventListResponse":{"type":"object","properties":{"success":{"type":"boolean","description":"Always true on a success."},"data":{"type":"array","items":{"$ref":"#/components/schemas/ContactEvent"},"description":"The items on this page."},"pagination":{"allOf":[{"$ref":"#/components/schemas/Pagination"}],"description":"Where this page ends and how to get the next one."}},"additionalProperties":false,"description":"The body of a successful list operation: one page of results in `data`, and `pagination` to get the next\npage."},"ContactLinkedInWait":{"type":"object","properties":{"reason":{"type":"string","description":"Why it waits. `pending_invite_cap`: the LinkedIn accounts that can send it have reached the sent invites not\nyet accepted that LinkedIn allows open, so Kenso holds new connection requests until that drops below the limit.\nNew reasons can appear."},"message":{"type":"string","description":"The explanation, ready to show to a person."},"linkedinAccountId":{"type":"integer","description":"The LinkedIn account the request waits on. Null when the contact is not tied to one account and every account of\nthe campaign is at the cap.","format":"int64","nullable":true},"pendingInvites":{"type":"integer","description":"That account's sent invites not yet accepted. Null when linkedinAccountId is.","format":"int32","nullable":true},"pendingInviteCap":{"type":"integer","description":"How many open invites Kenso lets that account have before it holds new connection requests.","format":"int32"}},"additionalProperties":false,"description":"A LinkedIn step of the contact that waits, and why."},"ContactListResponse":{"type":"object","properties":{"success":{"type":"boolean","description":"Always true on a success."},"data":{"type":"array","items":{"$ref":"#/components/schemas/Contact"},"description":"The items on this page."},"pagination":{"allOf":[{"$ref":"#/components/schemas/Pagination"}],"description":"Where this page ends and how to get the next one."}},"additionalProperties":false,"description":"The body of a successful list operation: one page of results in `data`, and `pagination` to get the next\npage."},"ContactMailboxProvider":{"type":"object","properties":{"status":{"type":"string","description":"Detection result. `detected`: the host was found, and `slug` and `name` say which.\n`unknown`: the domain was checked and no known host matched, or the contact has no email. `pending`:\nthe domain is not checked yet."},"slug":{"type":"string","description":"Short id of the host, such as `google_workspace`. Returned only when `status` is `detected`.","nullable":true},"name":{"type":"string","description":"Display name of the host. Returned only when `status` is `detected`.","nullable":true}},"additionalProperties":false,"description":"The host of a contact's mailbox, such as Google Workspace or Microsoft 365."},"ContactResponse":{"type":"object","properties":{"success":{"type":"boolean","description":"Always true on a success."},"data":{"allOf":[{"$ref":"#/components/schemas/Contact"}],"description":"The result of the operation."}},"additionalProperties":false,"description":"The body of a successful operation that returns one result. The result is in `data`."},"ContactSearchFilterCondition":{"type":"object","properties":{"field":{"type":"string","description":"The contact field to compare, such as `FirstName`, `Title`, `ContactCompany.Industry`,\n`Emails.EmailValidity`, `lead_quality_score` or `behaviorTag`."},"operator":{"allOf":[{"$ref":"#/components/schemas/ComparisonOperator"}],"description":"The comparison: `equals`, `not_equals`, `contains`, `not_contains`, `starts_with`,\n`ends_with`, `greater_than`, `greater_than_or_equal`, `less_than`,\n`less_than_or_equal`, `between`, `in`, `not_in`, `is_null` or `is_not_null`.\nThe integer, from 0 (`equals`) to 14 (`is_not_null`) in that order, works too."},"value":{"description":"The value to compare with."},"dataType":{"allOf":[{"$ref":"#/components/schemas/DataType"}],"description":"The type of `value`: `string`, `number`, `boolean`, `date_time`, `guid` or\n`enum`. The integer, from 0 (`string`) to 5 (`enum`) in that order, works too."}},"additionalProperties":false,"description":"One field condition of a contact filter."},"ContactSearchFilterGroup":{"type":"object","properties":{"operator":{"allOf":[{"$ref":"#/components/schemas/LogicalOperator"}],"description":"How the condition and the child groups combine: `and` or `or`. The integer (0 or 1) works too."},"conditions":{"allOf":[{"$ref":"#/components/schemas/ContactSearchFilterCondition"}],"description":"The group's field condition."},"children":{"type":"array","items":{"$ref":"#/components/schemas/ContactSearchFilterGroup"},"description":"Nested groups, each combined with this group's condition by `operator`."}},"additionalProperties":false,"description":"A group of contact filters: one condition plus child groups, joined by `operator`."},"ContactSecurityGateway":{"type":"object","properties":{"status":{"type":"string","description":"Detection result. `detected`: a gateway was found, and `slug` and `name` say which.\n`none`: no gateway was found, or the contact has no email or a free email address. `pending`: the\ndomain is not checked yet."},"slug":{"type":"string","description":"Short id of the gateway, such as `proofpoint`. Returned only when `status` is `detected`.","nullable":true},"name":{"type":"string","description":"Display name of the gateway. Returned only when `status` is `detected`.","nullable":true}},"additionalProperties":false,"description":"The email security gateway that filters mail to a contact's address."},"ContactWebsitePage":{"type":"object","properties":{"pageType":{"type":"string","description":"The kind of page: `home`, `about`, `pricing`, `contact`, `blog`,\n`blog_articles`, `services`, `products`, `testimonials`, `case_studies`,\n`results`, `portfolio`, `gallery`, `reviews`, `privacy_policy`,\n`terms_of_service`, `careers`, `team` or `other`. New values can appear."},"url":{"type":"string","description":"The page URL. Omitted when unknown.","nullable":true},"title":{"type":"string","description":"The page title. Omitted when unknown.","nullable":true},"markdown":{"type":"string","description":"The page content as markdown, at most 20,000 characters."},"scrapedAt":{"type":"string","description":"When the page was captured, in UTC: the date of the archive copy, the time Kenso read the live page, or the\ntime of the upload.","format":"date-time"},"source":{"type":"string","description":"Where the page came from: `archive` (a copy from a public web archive), `live` (Kenso read the live\nsite) or `imported` (text from a CSV upload). New values can appear."}},"additionalProperties":false,"description":"One page of the website of the contact's company.","example":{"pageType":"about","url":"https://northwind.example.com/about","title":"About Northwind Labs","markdown":"# About Northwind Labs\n\nNorthwind Labs builds developer onboarding software for engineering teams. Founded in 2017 in Austin, Texas.","scrapedAt":"2026-09-23T15:20:04Z","source":"live"}},"ContactWebsitePageListResponse":{"type":"object","properties":{"success":{"type":"boolean","description":"Always true on a success."},"data":{"type":"array","items":{"$ref":"#/components/schemas/ContactWebsitePage"},"description":"The items on this page."},"pagination":{"allOf":[{"$ref":"#/components/schemas/Pagination"}],"description":"Where this page ends and how to get the next one."}},"additionalProperties":false,"description":"The body of a successful list operation: one page of results in `data`, and `pagination` to get the next\npage."},"CreateCampaignContactRequest":{"required":["firstName","lastName"],"type":"object","properties":{"email":{"type":"string","description":"The contact's email address. Required, unless the campaign has only LinkedIn steps: then send an email or a\n`linkedin.com/in/` profile URL.","nullable":true},"firstName":{"type":"string","description":"First name. Required."},"lastName":{"type":"string","description":"Last name. Required."},"title":{"type":"string","description":"Job title.","nullable":true},"linkedInUrl":{"type":"string","description":"LinkedIn profile URL, such as `https://www.linkedin.com/in/ada-lovelace`. Kenso drops a Sales Navigator id\nURL (`linkedin.com/in/ACw...`), because no LinkedIn step can reach it.","nullable":true},"companyName":{"type":"string","description":"Company name. A row needs this or `companyDomain`.","nullable":true},"companyDomain":{"type":"string","description":"Company website domain, such as `acme.com`. A row needs this or `companyName`.","nullable":true},"customImageUrl":{"type":"string","description":"Public https URL of the contact's own image, shown in emails as `{{custom_image}}`. Kenso downloads and hosts\nit. An empty string clears it. Needs campaign images on the workspace.","nullable":true},"customVideo":{"type":"string","description":"The contact's own video, shown in emails as `{{custom_video}}`: a Loom, YouTube, Vimeo, Wistia, Vidyard,\nSendspark or HeyGen share link or embed code. An empty string clears it. Needs campaign videos on the workspace.","nullable":true},"customVariables":{"type":"object","additionalProperties":{"type":"string","nullable":true},"description":"Custom variables as an object of string values, such as `{ \"rd_first_line\": \"Loved your talk\" }`. Kenso\nnormalizes each key like a CSV column name and merges the values into the contact's custom variables. A key new to\nthe campaign joins its custom variables with AI context off. A null or empty value removes that key from an\nexisting contact. At most 50 keys.","nullable":true},"emailValidity":{"allOf":[{"$ref":"#/components/schemas/EmailValidity"}],"description":"Optional. Send `safe` for an email you already verified. In a campaign without AI qualification, Kenso then\nqualifies a new contact and spends one contact allowance. Omitted keeps the verdict Kenso already has for an\nexisting email. `verification_error` is refused."},"useKenEmail":{"type":"boolean","description":"True on a row with no email: Kenso fills the email from its own email database when it holds a recently verified\naddress for the person at the company's domain. Free, for the first 25 such rows of a request. A row still\nwithout an email fails, unless the campaign has only LinkedIn steps.","nullable":true}},"additionalProperties":false,"description":"One contact to add to a campaign. A row whose email the campaign already has updates that contact."},"CreateCampaignContactsRequest":{"required":["contacts"],"type":"object","properties":{"contacts":{"type":"array","items":{"$ref":"#/components/schemas/CreateCampaignContactRequest"},"description":"Required. From 1 to 1,000 contacts, processed in request order."}},"additionalProperties":false,"description":"The contacts to add to a campaign.","example":{"contacts":[{"email":"amanda.chen@northwind.example.com","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":"priya.shah@northwind.example.com","firstName":"Priya","lastName":"Shah","title":"Engineering Manager","companyName":"Northwind Labs","companyDomain":"northwind.example.com"}]}},"DataType":{"enum":["string","number","boolean","date_time","guid","enum"],"type":"string","description":"The type of a filter condition's value. The legacy API takes the integer: 0 String, 1 Number, 2 Boolean, 3 DateTime,\n4 Guid, 5 Enum. Ken-Version 1.1 takes the name in snake_case (`date_time`), or the integer."},"EmailValidity":{"enum":["unknown","invalid","risky","verified","safe","catch_all","verification_error"],"type":"string","description":"How sure Kenso is that an email address reaches a real mailbox: `unknown`, `invalid`, `risky`,\n`verified`, `safe` or `catch_all` (the domain accepts every address, so the mailbox cannot be\nconfirmed)."},"ErrorAccount":{"type":"object","properties":{"accountId":{"type":"integer","description":"The account's id.","format":"int64"},"name":{"type":"string","description":"The account's name."},"stakeholderId":{"type":"integer","description":"The person's stakeholder id on this account.","format":"int64"}},"additionalProperties":false,"description":"An account named in an error detail."},"ErrorBody":{"type":"object","properties":{"code":{"type":"string","description":"Stable error code, such as `validation_failed` or `not_found`. Branch on this value."},"message":{"type":"string","description":"A sentence for people that explains the error. It can change, so do not parse it."},"details":{"type":"array","items":{"$ref":"#/components/schemas/ErrorDetail"},"description":"One entry per problem, naming the field or limit it is about. Omitted when there are none.","nullable":true},"requestId":{"type":"string","description":"The id of this request: the same value as the `X-Correlation-Id` response header. Quote it when you write\nto contact@ken.so."},"docUrl":{"type":"string","description":"The page on this code in the developer docs, which says what it means and how to fix it. The errors guide for a\ncode that has no page of its own.","readOnly":true},"refusal":{"allOf":[{"$ref":"#/components/schemas/Refusal"}],"description":"On a `402`, the plan rule or usage limit that refused the request and how to lift it. Omitted otherwise."},"impact":{"allOf":[{"$ref":"#/components/schemas/InvalidationImpact"}],"description":"On a `409` that refuses a change because it would clear stored AI output (a prompt edit, a restore or a\nreset), how much the change would clear. Omitted otherwise."},"surface":{"type":"string","description":"Set only by the voice ticket's `409` (code `voice_conversation_active`): the chat the person's other\nvoice conversation runs in, `support`, `ken` or `onboarding`. Omitted on every other error.","nullable":true}},"additionalProperties":false,"description":"What went wrong in a request."},"ErrorDetail":{"type":"object","properties":{"field":{"type":"string","description":"The request field, header or limit the problem is about, such as `name` or `Ken-Version`."},"code":{"type":"string","description":"Stable code for this problem, such as `required` or `invalid`."},"message":{"type":"string","description":"A sentence for people that explains this problem."},"count":{"type":"integer","description":"On `export_limit_exceeded`, how many rows match the export. Omitted otherwise.","format":"int32","nullable":true},"index":{"type":"integer","description":"The position of the refused item in the request's list. Omitted otherwise.","format":"int32","nullable":true},"limit":{"type":"integer","description":"On `export_limit_exceeded`, the row limit the export ran with. On a `quota_exceeded` detail whose\n`field` names a quota, that quota's limit. On a `rate_limited` detail from your workspace's rate\nlimits, the limit that was hit. Omitted otherwise.","format":"int32","nullable":true},"resetAt":{"type":"string","description":"On some `quota_exceeded` details, when the quota frees up, in UTC. It is the same instant as the top-level\n`quotaResetAt`. On a `rate_limited` detail from your workspace's rate limits, when that limit resets.\nOmitted otherwise.","format":"date-time","nullable":true},"retryAfterSeconds":{"type":"integer","description":"On those `quota_exceeded` details and on most `rate_limited` details, the seconds to wait. It is the\nsame value as the `Retry-After` header. Omitted otherwise.","format":"int32","nullable":true},"inboxId":{"type":"integer","description":"The inbox the problem is about. Omitted otherwise.","format":"int64","nullable":true},"domainId":{"type":"integer","description":"The domain the problem is about. Omitted otherwise.","format":"int64","nullable":true},"domainName":{"type":"string","description":"The name of that domain, or the domain name the request gave. Omitted otherwise.","nullable":true},"accountId":{"type":"integer","description":"On `domain_taken`, `already_stakeholder` and `previously_removed`, the existing account to use\ninstead. Omitted otherwise.","format":"int64","nullable":true},"personId":{"type":"integer","description":"On `email_taken` and `linkedin_url_taken`, the existing person to use instead. Omitted otherwise.","format":"int64","nullable":true},"stakeholderId":{"type":"integer","description":"The account stakeholder the problem is about. Omitted otherwise.","format":"int64","nullable":true},"championId":{"type":"integer","description":"Not used. Always omitted.","format":"int64","nullable":true},"callTaskId":{"type":"integer","description":"On `call_task_exists`, the open call task that already holds the person's slot. Omitted otherwise.","format":"int64","nullable":true},"status":{"type":"string","description":"On `invalid_transition`, the current status. Omitted otherwise.","nullable":true},"allowed":{"type":"array","items":{"type":"string"},"description":"On `out_of_range`, the allowed values. On `invalid_transition`, the statuses the change is allowed\nfrom. Omitted otherwise.","nullable":true},"scope":{"type":"string","description":"On a `permission_denied` for an account owner change, the account scope the call needs (`all`). On\n`sending_paused`, what the pause covers: `inbox`, `domain` or `workspace`. Omitted otherwise.","nullable":true},"removedAt":{"type":"string","description":"On `previously_removed`, when a person removed the stakeholder, in UTC. Omitted otherwise.","format":"date-time","nullable":true},"page":{"type":"string","description":"On `permission_denied`, the page the call needs, such as `campaigns`. Omitted otherwise.","nullable":true},"required":{"type":"string","description":"On `permission_denied`, the access `page` needs: `view` or `edit`. Omitted otherwise.","nullable":true},"feature":{"type":"string","description":"On `permission_denied`, the permission the call needs, such as `launch`. Omitted otherwise.","nullable":true},"runId":{"type":"integer","description":"On `committee_run_active` and `run_not_finding`, the committee run the problem is about. Omitted\notherwise.","format":"int64","nullable":true},"mergedIntoId":{"type":"integer","description":"On `person_merged`, the person the merged person now lives on. On `account_merged`, the account the\nmerged account now lives on. Omitted otherwise.","format":"int64","nullable":true},"accounts":{"type":"array","items":{"$ref":"#/components/schemas/ErrorAccount"},"description":"On `person_on_accounts`, the accounts that block the change. Omitted otherwise.","nullable":true},"stage":{"type":"string","description":"On `stage_in_use` and `system_stage`, the opportunity stage key the problem is about. Omitted otherwise.","nullable":true},"opportunityCount":{"type":"integer","description":"On `stage_in_use`, how many opportunities are in that stage. Omitted otherwise.","format":"int32","nullable":true},"rule":{"type":"string","description":"On `guardrail_violation`, the contact limit rule the change breaks. Omitted otherwise.","nullable":true},"nextAllowedAt":{"type":"string","description":"On `guardrail_violation`, the first `dueAt` that passes every contact limit, in UTC. On a refused\nsend, when to retry. Omitted otherwise, and when waiting does not clear it.","format":"date-time","nullable":true},"fix":{"type":"string","description":"On a refused send, what to do next, in plain words. Omitted otherwise.","nullable":true},"opensAt":{"type":"string","description":"On `outside_calling_hours`, when the person's calling window opens, in UTC. Omitted otherwise.","format":"date-time","nullable":true},"currentVersion":{"type":"integer","description":"On a knowledge file's `version_conflict`, the file's current version. Omitted otherwise.","format":"int32","nullable":true},"provider":{"type":"string","description":"On a CRM connection error (`provider_error`, `exchange_failed`, `already_connected`,\n`account_mismatch` or `provider_unavailable`), the CRM it is about. Omitted otherwise.","nullable":true},"sharedWithMaster":{"type":"boolean","description":"True on a `quota_exceeded` detail when the shared limit of the white-label master workspace was hit, so\n`limit` is the limit of the whole white-label account. Omitted otherwise. The master's id is never sent.","nullable":true},"stepId":{"type":"integer","description":"On `link_reputation_blocked`, the saved sequence step that holds the blocked link. Omitted otherwise, and\nfor a step the save would have created.","format":"int64","nullable":true},"stepOrder":{"type":"integer","description":"On `link_reputation_blocked`, the `stepOrder` of that step. Omitted otherwise.","format":"int32","nullable":true},"url":{"type":"string","description":"On `link_reputation_blocked`, the blocked link as the step's copy writes it. Omitted otherwise.","nullable":true},"key":{"type":"string","description":"On `unfilled_template_key`, the template key the text still holds, such as `first_name` for\n`{first_name}`. Omitted otherwise.","nullable":true},"marker":{"type":"string","description":"On `unfilled_template_key`, that key as the text writes it, such as `{first_name}` or `[company]`.\nOmitted otherwise.","nullable":true},"retryAt":{"type":"string","description":"On a warm path Start's `guardrail_connector_monthly`, `guardrail_account_monthly`,\n`guardrail_connector_cooldown` and `guardrail_handoff_weekly`, when the limit frees up, in UTC. Omitted\notherwise.","format":"date-time","nullable":true},"workspaceId":{"type":"integer","description":"On `last_admin`, a workspace that needs a new admin before the account can be deleted. On\n`new_admin_not_found`, the workspace of the refused choice. Omitted otherwise.","format":"int64","nullable":true},"workspaceName":{"type":"string","description":"On `last_admin`, the name of that workspace. Omitted otherwise.","nullable":true},"class":{"type":"string","description":"On a `rate_limited` detail from your workspace's rate limits, the class of call that hit its limit:\n`read`, `write`, `bulk`, `heavy` or `sensitive`. Omitted otherwise.","nullable":true},"window":{"type":"string","description":"On that detail, the window whose limit was hit: `minute`, `day` or `bulkItemsDay`. Omitted\notherwise.","nullable":true}},"additionalProperties":false,"description":"One problem in an error: the field or limit it is about, a stable `code` and a `message`. The other fields\nappear only with the codes their descriptions name."},"Failure":{"type":"object","properties":{"success":{"type":"boolean","description":"Always false on an error."},"error":{"allOf":[{"$ref":"#/components/schemas/ErrorBody"}],"description":"What went wrong."},"quotaResetAt":{"type":"string","description":"When the quota that refused the request frees up, in UTC. Set on some quota refusals. Omitted otherwise.","format":"date-time","nullable":true},"currentVersion":{"type":"integer","description":"The current revision of a workflow draft, on a draft save's `409 version_conflict`. Read the workflow\nagain, then send this value as `baseVersion`. Omitted otherwise.","format":"int32","nullable":true},"current":{"allOf":[{"$ref":"#/components/schemas/MeetingRepNotesCurrent"}],"description":"Your meeting notes and their version as stored now, on a meeting notes save's `409 version_conflict`.\nMerge your change, then save again with `baseVersion` set to `current.repNotesVersion`. Omitted\notherwise."},"refusal":{"allOf":[{"$ref":"#/components/schemas/Refusal"}],"description":"A copy of `error.refusal`, set on some billing refusals. Omitted otherwise."},"message":{"type":"string","description":"A copy of `error.message`, set together with `refusal`. Omitted otherwise.","nullable":true},"lookalikeSeeds":{"description":"How Kenso read each seed of a lookalike search, on its `422 no_usable_seeds`:\n`{resolved: [{input, companyId, personId, name, domain}], unresolved: [{input, reason}]}`. Use it to show\nwhy no seed was usable. Omitted otherwise."}},"additionalProperties":false,"description":"The body of every error, with a 4xx or 5xx status. Branch on `error.code`."},"InvalidationImpact":{"type":"object","properties":{"qualificationResponses":{"type":"integer","description":"Stored qualification answers the change would clear.","format":"int32"},"qualifiedFlags":{"type":"integer","description":"Contacts whose qualified result the change would clear.","format":"int32"},"segmentationReasoning":{"type":"integer","description":"Stored segmentation explanations the change would clear.","format":"int32"},"segmentationAssignmentsKept":{"type":"integer","description":"Contacts that keep their segment.","format":"int32"},"segmentationAssignmentsReset":{"type":"integer","description":"Contacts that go back to the default segment.","format":"int32"},"personalizationLines":{"type":"integer","description":"Personalized lines the change would clear.","format":"int32"},"personalizationLeads":{"type":"integer","description":"Contacts that would lose their personalized lines.","format":"int32"},"rewritingLines":{"type":"integer","description":"Rewritten lines the change would clear.","format":"int32"},"rewritingLeads":{"type":"integer","description":"Contacts that would lose their rewritten lines.","format":"int32"}},"additionalProperties":false,"description":"How much stored AI output a change would clear in each AI step of a campaign, and how many segment assignments it\nkeeps or resets."},"LogicalOperator":{"enum":["and","or"],"type":"string","description":"How a filter group joins its condition and child groups: AND (all must match) or OR (any one matches). The legacy API\ntakes the integer, 0 for AND and 1 for OR; Ken-Version 1.1 takes `and` or `or`, or the integer."},"MeetingRepNotesCurrent":{"type":"object","properties":{"repNotes":{"type":"string","description":"Your notes as stored now. Empty before your first save."},"repNotesVersion":{"type":"integer","description":"The stored notes' version. Send it as `baseVersion` when you save again.","format":"int32"}},"additionalProperties":false,"description":"Your meeting notes as Kenso stores them now, sent with a `409 version_conflict` on a notes save."},"OutreachFormality":{"enum":["formal","informal"],"type":"string","description":"The register Ken writes to a contact in: `formal` (such as vous or usted) or `informal` (such as tu or\ntú). Null uses the language's default."},"OutreachLanguageSource":{"enum":["manual","reply","declared","country","hq","default"],"type":"string","description":"Where a contact's outreach language came from, strongest first."},"Pagination":{"type":"object","properties":{"nextCursor":{"type":"string","description":"Send this value as `cursor` to get the next page. Omitted on the last page.","nullable":true},"hasMore":{"type":"boolean","description":"True when more items follow this page. Stop paging when it is false."},"total":{"type":"integer","description":"Deprecated: the same number as `totalCount`. Read `totalCount`.","format":"int32","nullable":true,"deprecated":true},"totalCount":{"type":"integer","description":"The number of items that match the list's filters, across all pages. Omitted when the list does not count them.","format":"int32","nullable":true},"isTotalCapped":{"type":"boolean","description":"True when `totalCount` stopped counting at its cap, so more items match than it says. Keep paging with\n`hasMore`. Omitted when `totalCount` is exact. Only `GET /v1/threads` with `q` caps its total.","nullable":true}},"additionalProperties":false,"description":"Where a list page ends and how to get the next page."},"PersonalEmail":{"type":"object","properties":{"email":{"type":"string","description":"The address."},"source":{"type":"string","description":"The data source that found the address."},"foundAt":{"type":"string","description":"When Kenso stored the address, in UTC.","format":"date-time"}},"additionalProperties":false,"description":"A personal email address found for the contact."},"PhoneNumberValidity":{"enum":["unknown","invalid","risky","verified","valid"],"type":"string","description":"How sure Kenso is that a phone number works: `unknown`, `invalid`, `risky`, `verified` or\n`valid`."},"RateLimitedText":{"type":"string","description":"The gateway's plain-text body of a `429` over the operation's own limit, until November 2026: `Number of requests exceeded. Please try again later.`","example":"Number of requests exceeded. Please try again later."},"Refusal":{"type":"object","properties":{"code":{"type":"string","description":"Stable refusal code in upper case, such as `CAMPAIGN_LIMIT_REACHED` or `INSUFFICIENT_CREDITS`."},"metric":{"type":"string","description":"What the limit counts: `Campaigns`, `Leads`, `Emails`, `LinkedInSeats` or `AiCredits`,\n`jobs_export_rows` or `funding_export_rows` for an export allowance, `credit_pack_credits`,\n`credit_spend_usd_7d`, `domains` or `mailboxes` for a limit on a new paying workspace, or for a\nKenso Lifetime cap its key: `workspaces`, `inboxes`, `contacts`, `email_verifications_day`,\n`email_verifications_month`, `people_results_day`, `company_results_day`,\n`funding_results_day`, `job_post_results_day`, `website_visits_month` or\n`visitor_lookups_day`. Omitted when a plan rule, not a count, refused the request.","nullable":true},"used":{"type":"integer","description":"How much of the limit is used, in the unit of `metric`. Omitted when the refusal has no count.","format":"int32","nullable":true},"limit":{"type":"integer","description":"The limit, in the unit of `metric`. Omitted when the refusal has no count.","format":"int32","nullable":true},"remaining":{"type":"integer","description":"How much of the limit is left, in the unit of `metric`. Omitted when the refusal has no count.","format":"int32","nullable":true},"planType":{"type":"string","description":"The workspace's plan as its snake plan id, for example `free`, `legacy_core` or `growth`."},"remedy":{"type":"string","description":"What lifts the refusal: `Upgrade`, `BuyAddOn`, `UpdatePaymentMethod` or `ContactSupport`.\n`None` means no action of yours lifts it."},"unlocksAt":{"type":"string","description":"When the limit lifts by itself, in UTC: for a limit on a new paying workspace once it has paid an invoice, and for\na Kenso Lifetime daily or monthly cap its reset (00:00 UTC, or the 1st of the month). Omitted on every other\nrefusal.","format":"date-time","nullable":true},"requiredMillicredits":{"type":"integer","description":"On a credit refusal, the millicredits the action needed. 1,000 millicredits are one credit. Omitted on every\nother refusal.","format":"int64","nullable":true},"availableMillicredits":{"type":"integer","description":"On a credit refusal, the millicredits available. On `FREE_CREDITS_NOT_ELIGIBLE`, only the credits that may\npay for inboxes and domains. Omitted on every other refusal.","format":"int64","nullable":true},"restrictedMillicredits":{"type":"integer","description":"On `FREE_CREDITS_NOT_ELIGIBLE`, the free and bonus millicredits in the balance that cannot pay for inboxes\nand domains. Omitted on every other refusal.","format":"int64","nullable":true},"feature":{"type":"string","description":"On `PLAN_FEATURE_NOT_AVAILABLE`, the plan feature the plan does not include, in snake case (for example\n`website_visitor_id`). Omitted on every other refusal.","nullable":true},"requiredPlan":{"type":"string","description":"On `PLAN_FEATURE_NOT_AVAILABLE`, the cheapest plan that includes `feature`, in snake case (for example\n`growth`). For a feature the self-serve trial locks (`browser_runs`), the trial's own plan,\nwhich paying for unlocks it. Omitted on every other refusal.","nullable":true},"requiredTier":{"type":"integer","description":"On a Kenso Lifetime refusal, the lowest tier that lifts it: the next tier with a higher cap, or the lowest tier\nthat includes `feature`. Omitted at the top tier, when no tier includes the feature, and on every other\nrefusal.","format":"int32","nullable":true},"upgradeUrl":{"type":"string","description":"On a Kenso Lifetime refusal that a higher tier lifts, the AppSumo page where the buyer upgrades their license.\nOmitted until Kenso has read that page from AppSumo, when no tier lifts the refusal, and on every other refusal.","nullable":true}},"additionalProperties":false,"description":"Why a plan rule or usage limit refused the request, and how to lift it."},"SearchContactsRequest":{"type":"object","properties":{"campaignIds":{"type":"array","items":{"type":"integer","format":"int64"},"description":"Only contacts in these campaigns, at most 50 ids.","nullable":true},"companyId":{"type":"integer","description":"Only contacts at this company, matched on the contact's `companyId`.","format":"int64","nullable":true},"segmentId":{"type":"integer","description":"Only contacts in this campaign segment.","format":"int64","nullable":true},"email":{"type":"string","description":"Only contacts that have this email address. The match is exact and ignores case.","nullable":true},"q":{"type":"string","description":"Free-text search on the first name, last name, full name and email addresses. It matches any part of a value and\nignores case.","nullable":true},"isQualified":{"type":"boolean","description":"True keeps only qualified contacts, false only unqualified ones. Omitted keeps both.","nullable":true},"doNotContact":{"type":"boolean","description":"True keeps only do-not-contact contacts, false only the others. Omitted keeps both.","nullable":true},"createdAfter":{"type":"string","description":"Only contacts created at or after this time, in UTC.","format":"date-time","nullable":true},"createdBefore":{"type":"string","description":"Only contacts created before this time, in UTC. Must be later than `createdAfter`.","format":"date-time","nullable":true},"filters":{"type":"array","items":{"$ref":"#/components/schemas/ContactSearchFilterGroup"},"description":"Field conditions joined with AND or OR, at most 20 groups. A `behaviorTag` condition needs the\n`behavior_signals` feature on the workspace.","nullable":true},"readyOnly":{"type":"boolean","description":"True keeps only the contacts the campaign can send to now. Needs exactly one id in `campaignIds`. Default\nfalse."},"awaitingFirstEmail":{"type":"boolean","description":"True keeps only the campaign's ready leads still waiting for their first email: the leads its\n`readyLeadCount` counts. Narrower than `readyOnly`, which also keeps leads already emailed. Needs exactly\none id in `campaignIds`. Default false."},"contactIds":{"type":"array","items":{"type":"integer","format":"int64"},"description":"Only these contacts, at most 1,000 ids.","nullable":true},"securityGateway":{"type":"array","items":{"type":"string"},"description":"Only contacts whose first Safe or Verified email sits behind one of these email security gateways: a gateway slug\nsuch as `proofpoint`, or `none` or `pending`. At most 100 values, and any one matches. Needs\nsecurity gateways on the workspace.","nullable":true},"mailboxProvider":{"type":"array","items":{"type":"string"},"description":"Only contacts whose mailbox host is one of these: a host slug such as `google_workspace`, or `unknown`\nor `pending`. At most 100 values, and any one matches. Needs security gateways on the workspace.","nullable":true},"sort":{"type":"string","description":"Sort field: `name`, `email`, `company`, `title`, `location`, `leadQualityScore`,\n`emailsSent`, `totalClicks`, `replies`, `unsubscribes`, `bounces` or\n`yearsOfExperience`. Omitted sorts by contact id.","nullable":true},"direction":{"type":"string","description":"Sort direction, `asc` or `desc`, sent only with `sort`. Omitted sorts ascending.","nullable":true},"limit":{"type":"integer","description":"Contacts per page, from 1 to 200. Default 50.","format":"int32","nullable":true},"cursor":{"type":"string","description":"The `nextCursor` of the previous page, sent with the same filters and `sort`. Omitted starts at the first\npage.","nullable":true},"fields":{"type":"array","items":{"type":"string"},"description":"The contact properties to return, as a list of top-level names, for example\n`[\"id\", \"email\", \"companyName\"]`. Each contact then holds only those. Omitted or empty returns every property.","nullable":true}},"additionalProperties":false,"description":"Filters, sort and paging for a contact search. Every property is optional.","example":{"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}},"TooManyRequestsError":{"oneOf":[{"$ref":"#/components/schemas/Failure"},{"$ref":"#/components/schemas/ApiKeyError"}],"description":"The JSON body of a `429`: the error body (`Failure`), with code `rate_limited` or `quota_exceeded`, over your workspace's rate limits, your API key's own limit, the operation's own limit or a usage quota. Until November 2026, over your API key's own limit the API key check answered `{ \"error\": \"Rate limit exceeded\" }` (`ApiKeyError`), and over the operation's own limit the gateway answered plain text (`RateLimitedText`): `Number of requests exceeded. Please try again later.` A client built against those answers keeps working: handle each shape. Wait the `Retry-After` seconds."},"UnauthorizedError":{"oneOf":[{"$ref":"#/components/schemas/Failure"},{"$ref":"#/components/schemas/ApiKeyError"}],"description":"The body of a `401`: the error body (`Failure`), whose `code` says what is wrong with the credential. Until November 2026, when the API key was not valid (unknown, expired or revoked, or its member no longer active), the API key check in front of the operations answered `{ \"error\": \"Invalid or revoked API key\" }` (`ApiKeyError`), and a request with no API key got a `401` that has no body. A client built against those answers keeps working: handle both shapes and a `401` with no body."},"UpdateContactBody":{"type":"object","properties":{"firstName":{"type":"string","description":"First name. Null clears it.","nullable":true},"lastName":{"type":"string","description":"Last name. Null clears it.","nullable":true},"title":{"type":"string","description":"Job title. Null clears it.","nullable":true},"linkedInUrl":{"type":"string","description":"LinkedIn profile URL. Null clears it.","nullable":true},"location":{"type":"string","description":"Location. Null clears it.","nullable":true},"email":{"type":"string","description":"The contact's email address. It must be valid, not another contact's address and not one of the contact's\npersonal addresses. Null removes it.","nullable":true},"isQualified":{"type":"boolean","description":"True or false to mark the contact qualified or not. Null is refused."},"doNotContact":{"type":"boolean","description":"True to mark the contact do-not-contact, so Kenso sends it nothing, or false to clear that. Null is refused."},"outreachLanguage":{"type":"string","description":"The language Ken writes to the contact in: a locale such as `fr-FR` or `es-MX`, or a language code\nsuch as `de`. Kenso locks it, so no import, enrichment or reply changes it. Null clears and unlocks it.","nullable":true},"customVariables":{"type":"object","additionalProperties":{"type":"string","nullable":true},"description":"Values to merge into the contact's custom variables, by key. A string sets the key, and null or an empty\nstring removes it. Keys you leave out stay. The object itself cannot be null."},"customImageUrl":{"type":"string","description":"The contact's own image, shown in emails as `{{custom_image}}`: a public https URL of at most 2,048\ncharacters, which Kenso downloads and hosts. An empty string or null clears it. Needs campaign images on the\nworkspace.","nullable":true},"customVideo":{"type":"string","description":"The contact's own video, shown in emails as `{{custom_video}}`: a Loom, YouTube, Vimeo, Wistia, Vidyard,\nSendspark or HeyGen share link or embed code, at most 20,480 characters. An empty string or null clears it.\nNeeds campaign videos on the workspace and a contact in a campaign. While a sent or queued step uses the\ncurrent video, it cannot change.","nullable":true}},"additionalProperties":false,"description":"The fields to change on a contact. Every field is optional: a field you leave out stays as it is, and null clears\na text field. A field not listed here is refused.","example":{"title":"SVP of Engineering","location":"Austin, Texas, United States","isQualified":true,"doNotContact":false,"outreachLanguage":"en-US","customVariables":{"open_roles":"15 engineering roles"}}}}}}