Add a contact to a list (add or update)

Adds ONE contact to a list from a flat JSON object: field names as keys, scalar values (string, number or boolean). This is the endpoint for automations (Zapier, Make, n8n, scripts) and the standard way to feed a running campaign: if campaigns in RUNNING, PAUSED or DRAFT status use the list, the contact is propagated to them asynchronously (usually within seconds, at the latest by the nightly reconciliation). Adding contacts consumes no credits. For more than one contact, use the batch route.

How keys are resolved

Each key is resolved in this order: (1) case-insensitively against the recognized names of the standard fields (First Name, Prénom, email_address, Company...); (2) against the standard field keys, ignoring case, spaces, _ and - (firstName, first_name and FIRSTNAME all work), and also as a prefix or suffix of a field key when the key has 3 characters or more; (3) against your existing custom variables (technical or display name); (4) a key whose name ends in id is never matched by its value and becomes a custom variable; (5) otherwise the VALUE is inspected: an email-looking value goes to email, 6 digits or more go to phone, a linkedin.com/in/ URL goes to linkedinUrlProfile, any other http(s):// URL goes to the company websiteUrl. Only when nothing matched is a new lead custom variable created (display name = the key, technical name derived from it) and reported in createdCustomVariables.

Pitfalls

• Use the exact keys listed below. Short or generic keys are fuzzy-matched: job lands in jobStartDate (a date, the request fails), last in lastContacted (the value is lost), year in yearsOfExperience, date in birthDate, note in the company notes, tag in the company tags.
• An unknown key whose value looks like a phone number (company registration number, order number, a date such as 2024-01-15) is stored in phone, not in a new custom variable. Declare the custom variable first with POST /lists/custom-variable: an existing variable is matched before the value is inspected.
• mobile maps to phone. Use mobilePhone for a mobile number.
• A standard field takes at most one key per contact. When two keys target the same field, the second one moves to the next matching field (a second email key can end up in emailVerified and be lost).
• Numeric fields (age, yearsOfExperience, employeeCount, foundedYear, annualRevenue) silently drop non-numeric values. Date fields (birthDate, jobStartDate) must be valid dates (use ISO 8601, for example 2021-03-01): an unparsable date makes the request fail.
• null and empty strings are ignored: this endpoint cannot clear a field. Arrays and objects are rejected (422).
• Every unknown key creates an account-wide custom variable that cannot be deleted through the API.

Standard keys

Contact: firstName, lastName, fullName, email, secondaryEmail, phone, mobilePhone, linkedinUrlProfile, twitterUrl, jobTitle, seniority, department, gender, age, birthDate, language, country, region, city, postalCode, address, timezone, jobStartDate, yearsOfExperience, education, skills (list separated by commas, semicolons or pipes), bio, profilePictureUrl. Company: companyName, companyDomain, companyEmail, websiteUrl, linkedinCompanyUrl, twitterCompanyUrl, logoUrl, industry, companySize, companyType, employeeCount, foundedYear, annualRevenue, notes, tags, techStack. The keys country, city, region, postalCode, address and timezone go to the contact: use Company Country, Company City or Company Address to fill the company ones.

Duplicates and idempotency

Before creating, the service looks in this list and the lists linked to it for a contact with the same email (exact comparison, case-sensitive), then with the same linkedinUrlProfile (exact string). If one is found, nothing is created: the response returns its leadId with duplicate: true. With updateIfExists=true the payload is applied to that contact instead (sent fields overwrite, absent fields are kept, identity fields included) and the response has updated: true. A contact without email and without LinkedIn URL is never deduplicated: retrying such a call creates a new contact each time. Send emails in lowercase and LinkedIn URLs in one canonical form.

The status code is 200 for a creation, an ignored duplicate and an update alike: read duplicate and updated.

Path ParametersCopy Anchor Link

Query ParametersCopy Anchor Link

Response BodyCopy Anchor Link