Contact imports

Body: campaignId (required; another workspace's campaign is 404), companies (1 to 50, each { key?, name?, domain? } with a name or a domain, else 400 validation_failed on companies[i]) and perCompany (1 to 3, default 3). Send a longer list in parts of 50. Example: { "campaignId": 812, "companies": [{ "key": "row-2", "name": "Northwind", "domain": "northwind.com" }], "perCompany": 3 }. A company with a domain is the Kenso Search company that owns it: one Kenso Search also matches by the given name at that domain, else one whose website is the domain's home page. A company with only a page under the domain (notion.so/...) does not count, and no name match stands in for it. A company without a domain is found by a name only one company has. Unmatched companies say why (acme.com is not in Kenso Search, could not match notion.so: no company in Kenso Search has it as its own website, no domain, name matches 3 companies). A matched company lists up to perCompany people at it in the campaign's ICP (the titles, seniority, functions and exclusions of its live segments), best first, each with a one-line reason, and each person once in the whole answer, by Kenso id or LinkedIn URL (Kenso Search can hold one person twice); when the ICP finds too few, Ken fills the company from a looser search and marks those people weakMatch. No ICP ranks people by seniority, and icp is empty. signal is the company's latest hiring, funding or leadership change from the last 90 days. A company Kenso Search does not answer for in time is failed; retry it. Each person's contact is a POST /v1/contact-importssource: search contact: post the kept ones unchanged to add them (dedupe, blocklist and lead credits apply there). Nothing is stored and nothing is charged; the companies times perCompany count against the workspace's searchBrowseRows quota (429 quota_exceeded past it). Requires WriteAccess and the Import feature.

JSON source is campaign (copy from sourceCampaignId), search (a contacts array, at most 1,000), blitz (the same contacts array, at most 1,000, for people picked in the Blitz tab of Search; the run's surface is Blitz and it counts no Kenso Search work) or people (personIds, 1 to 1,000 workspace people; each becomes a contact with their name, email, title, LinkedIn URL and the company of their highest-priority account; needs the accounts feature and Accounts view, and with account scope own takes only people on the caller's accounts), event (eventId, optional roles and includeAccounts: an outbound event's attendees with an email or a LinkedIn URL, at most 5,000; rows whose company is a workspace account are left out unless includeAccounts is true, and then with account scope own only those on the caller's accounts are added; needs the accounts and event_outbound features and Accounts view) or sales_navigator (linkedinAccountId, a seat the caller connected, and url, a Sales Navigator lead search or lead list; its people with their name, current title, LinkedIn profile and company. One import reads at most 8 pages (about 200 to 400 people): a list it cannot read to the end imports nothing and is 400 validation_failed with code incomplete_read on url. Behind the sales_navigator feature, a seat without Sales Navigator is 409 sales_navigator_required). Where the linkedin_network feature is on, linkedin_connections (connectionIds, 1 to 1,000 ids from GET /v1/linkedin-connections; each becomes a contact with first and last name, title, headline, LinkedIn URL, seniority and Kenso Search's company name, domain, LinkedIn URL, industry and size; needs Accounts view; elsewhere it is an unknown source). Multipart source=csv uploads a CSV file into campaignId; its optional form field columnMappings (a JSON array of mappings, as for a Google Sheet) sets the columns, and a mapped column the header row lacks is 400 validation_failed; omitted, the header row is mapped by the import's aliases. Its optional form field emailsFoundByKen=true (staff only, otherwise 403 forbidden) stamps every imported email found_by_ken, so the cross-workspace Kenso DB lookup may serve it. Behind the csv_import_check feature (a field sent while it is off is 400 validation_failed on that field) the CSV create also takes the List check choices of a scan: fixes (a JSON array of missingKey, invalidEmail, noMx, catchAll, personalEmail, roleAddress, companyContacted, companyCap) drops the rows the List check flags for them and counts each under its key in the job's skipped; includeRecentlyContacted=true keeps the rows the campaign's recently-emailed window would skip, for this import only; cleanup=true cleans the name, email, title, company, domain, LinkedIn URL and phone cells as the scan's cleanup notes say. Omitted, they are off. JSON sourcegoogle_sheets (behind the google_sheets flag) reads spreadsheetId (an id or a Google Sheets URL) and the optional sheet with the caller's own Kenso Workspace Google connection; row 1 is the header and columnMappings work as for a CSV. No connection is 409 reconnect_required; a sheet not picked for Kenso is 409 sheet_not_shared. JSON sourceairtable (behind the airtable flag) reads every record of tableId (an id or name) in baseId, or of its viewId when set, with the workspace's Airtable token: the table's field names, primary field first, are the header and each record is a row of cell text. A table or view of more than 10,000 records is 400 validation_failed on tableId: import it in parts through views. No token is 409 not_connected; a token without the read scopes or access to the base is 409 scope_required. JSON sourcesaved_list (behind the saved_lists flag; elsewhere it is an unknown source) imports the members of savedListId: a list of this workspace (a private one only for its owner), a list shared with it, or a library list. The optional memberFilters (country, seniority, title, industry, headcountBand, hasSendableEmail) narrow the members. A company list with roles (1 to 20 titles) imports up to 5 people per company found by Kenso Search, for at most 500 companies; without roles each company is one company contact. findPeople must be absent or false. Members this list already put in the campaign are skipped, so a retry adds only the rest. A library list's cached Safe emails land Safe with no email charge on a paid plan; a Free workspace gets no emails from a library list. A member copied out of a library list follows the same rules in any list. columnMappings is refused: the list sets its own columns. More than 100,000 contacts is 400 validation_failed on memberFilters. Every source applies the import's dedupe, blocklist and contact limits. A JSON body over 10 MB is 413; the multipart CSV upload accepts up to 400 MB. Requires WriteAccess. Poll GET /v1/jobs/{jobId}?type=contact_import. linkedin_url (url, optional linkedinAccountId, maxLeads, postKinds) queues a LinkedIn import that needs the linkedin_url_import flag. Options: source=campaign takes importLimit (above 0), importOffset (0 or more), onlyImportQualifiedContacts, onlyImportValidContacts, deduplicateCampaignIds (1 to 50 campaigns of the workspace; others are not_found), deduplicationMode (none, by_email the default, or by_data), allowReimport, copyDataEnrichment and copyEmailEnrichment (keep the source's enrichment results; default false). source=search (not blitz) takes importLimit, triggerPostProcessing (default true) and tagIds (1 to 50 workspace contact tags put on every imported contact). A multipart CSV takes the form fields importLimit and tagIds (a JSON array, for example [3,4]). An option sent with a source that does not honor it, or with target=people, is 400 validation_failed on that field. source=segment copies one segment of the workspace (sourceSegmentId, from any campaign) into campaignId as a new segment with the source segment's name. copyQualification, copyEmailEnrichment and copyEmailVerification keep the source contacts' AI qualification, found emails and email verification (each default false). segmentId is refused (the copy makes its own segment); a segment name already in the campaign is 400, and another import into it in progress is 409. target is campaign (the default) or people. With people (behind the lead_intake feature, 404 when off, and Accounts edit) campaignId is optional and ignored: the rows of source csv (multipart, form field target=people), search, blitz, event, linkedin_connections, sales_navigator, google_sheets or airtable are queued and run through person intake as workspace people with source import. A row needs an email, a LinkedIn URL, or a name with a business company domain; others are skipped. The job's personImport reports the created, updated and skipped counts.

Body: source (required: csv, google_sheets or airtable), target (campaign, the default, or people), campaignId (required with target campaign: a campaign of the workspace, else 404), headers (the header row, 1 to 200 names of at most 500 characters) and sampleRows (up to 200 rows; a short row reads as blanks, extra cells are ignored, each cell at most 2,000 characters). keys (optional) holds the key columns of every row for the List check: rowCount (data rows in the file), cleanup (default true: each value first goes through the import's cleaner) and one list per mapped key field (email, profileUrl, companyDomain, companyName, companyLinkedinUrl, firstName, lastName, fullName, title, emailValidity), index-aligned, plus otherEmails (each further column mapped to email, up to 10 lists) and otherEmailValidity (the validity column mapped right after each, null where none). With target campaign every list sent has the same length, 1 to 25,000, and rowCount is at least that length (else 400 on keys); a larger file sends its first 25,000 rows and its check is truncated. A scan that sends keys skips the AI suggestions. Example: { "source": "csv", "campaignId": 42, "headers": ["Full Name", "Work contact"], "sampleRows": [["Ada Lovelace", "[email protected]"]], "keys": { "rowCount": 1, "fullName": ["Ada Lovelace"], "email": ["[email protected]"] } }. Returns 200 with columns, one per header in header order: index, csvColumn, targetField (a contact field key such as email, full_name or profile_url, custom_variable or skip), customVariableName (only for custom_variable), confidence (high: the header names the field or nearly every value is one; memory: this workspace mapped the header before; check: likely, confirm it; skip: not imported), reason (one short sentence), samples (up to 3 distinct values, each at most 120 characters) and cleanup (what the import's cleanup changes in the sample values, e.g. Cleans 3 of 10 sample values (casing, format), else null); listKind (company when no column is a person field and one is a company field, else people); and check, the List check, with keys and target campaign (else null): rows, scannedRows, truncated, cleanupApplied, always (what the import skips anyway: failedValidation, missingKey, blocklist, duplicateInFile, duplicateInCampaign, duplicateInOtherCampaign, first match wins), contacted (rows another campaign emailed inside the campaign's recently-emailed window), checks (optional fixes: invalidEmail, noMx, catchAll, personalEmail, roleAddress, companyContacted, companyCap), rowFlags ([rowIndex, mask]), noEmailRows, baselinePrior, bounce (expected, beforeFixes, band), willAdd, companyContactedDays, companyCap, domainsChecked, domainsTotal, titleMix and providerMix. Samples carry the 1-based data row; rows and row indexes are 0-based into the key lists. Kenso's own data only, no paid lookup. A field is suggested once, except email, email_validity and custom_variable. Target people suggests only the fields a people import stores: email, first_name, last_name, full_name, title, company_name, company_domain, phone_number and profile_url. Nothing is stored. Behind the csv_import_check flag (404 when off). Needs campaigns view and the import feature. Each call counts on the workspace's contactImportScans quota (30 a minute, 600 an hour, 5,000 a day; past it, 429 quota_exceeded with Retry-After).