Add a contact to a list

POST 
/lists/list/:listId/contacts

Adds a single contact to a list from a flat JSON object — field names as keys, values as strings, numbers or booleans. This is the simplest way to push contacts from your automations (Zapier, Make, n8n...).

If the list is used by one or several campaigns, the contact is automatically added to those campaigns.

Keys are resolved automatically, with the same detection as a file import (by name, then by content):

• contact fields (see the list below — human-readable names like First Name work too),
• company fields (companyName, websiteUrl, industry...),
• your existing custom variables (by technical or display name).

Any unrecognized key automatically creates a new custom variable on your account and stores the value in it.

Contact fields

Predefined fields of a contact. They are stored on the contact itself (not as custom variables) and are available as {{variables}} in your campaigns.

Key	Type	Description
firstName	string	First name
lastName	string	Last name
fullName	string	Full name
email	string	Email address — used for duplicate detection
phone	string	Phone number
linkedinUrlProfile	string	LinkedIn profile URL — used for duplicate detection
gender	string	Gender
language	string	Language
jobTitle	string	Job title
seniority	string	Seniority level
department	string	Department
jobStartDate	string	Start date of the current position (ISO 8601 date, e.g. 2021-03-01)
yearsOfExperience	number	Years of professional experience
education	string	Education / degree
bio	string	Short biography
country	string	Country
region	string	Region / state
city	string	City
postalCode	string	Postal code
address	string	Street address
timezone	string	Timezone

Duplicate detection

If the list already contains a contact with the same email or the same linkedinUrlProfile, nothing is created: the response returns the existing contact's leadId with duplicate: true. A criterion only applies when both the payload and the existing contact have a value for it — so a retry of the same call is always safe.

With updateIfExists=true, a duplicate is updated instead of ignored: the fields of the payload overwrite the existing contact's values (fields you don't send are left untouched), and the response carries updated: true. This makes the endpoint a full add-or-update.

Request

Responses

200

Contact added

404

List not found

422

Invalid body (empty contact, or a field value is not a string/number/boolean)