Add a Contact

Add one contact you already have to a list, without enriching it.

POST /add_contact

Adds one contact to listname from data you already hold — a CRM record, a form fill, a row from your own spreadsheet. Nothing is looked up. The contact lands in the list with exactly the fields you send, ready to enrich.

Free. credits_used is always 0.

No duplicates. If the list already has this contact, the two are combined instead of added twice. Blank fields on the stored contact are filled from what you send, and fields that already have a value keep it.

For more than one contact, use Add Contacts in Bulk. It takes the same fields and the same rules.

Headers

Name	Value
Content-Type	application/json

Body

Name	Type	Description
api_key	string	Required. Your API key.
listname	string	Required. The list to add to. One word, not list_name.
contact	object	Required. The contact's fields. See Contact fields below.
create_list	boolean	Default true. Creates the list when it does not exist. Set false to get not_found instead.
dry_run	boolean	Default false. When true, reports what would be added and writes nothing. No list is created.

Contact fields

Every contact needs at least one identifier: email, person_linkedin_url, person_name, organization_name, domain, company_website, company_linkedin_url or place_id. A company with no person on it is a valid contact.

Field	Type	Notes
person_name	string	Full name.
first_name	string
last_name	string
current_title	string	Job title.
email	string	Work email.
email_status	string	The status of email, if you know it.
personal_email	string
personal_email_status	string
person_linkedin_url	string	LinkedIn profile URL.
phone_number	string
city	string
state	string
postal_code	string
country	string
country_code	string
organization_name	string	Company name.
domain	string	Company domain, e.g. acmeroofing.com.
company_website	string	Company website URL.
company_linkedin_url	string	Company LinkedIn page URL.
industry	string
company_phone	string
headcount	integer	Exact employee count, 1 or more. Also fills company_size when you do not send one.
company_size	string	One of 1-10, 11-50, 51-200, 201-500, 501-1000, 1001-5000, 5001-10000, 10001+.
company_description	string
company_tech_stack	array of strings	Tool names, e.g. ["HubSpot", "QuickBooks"].
place_id	string	Google's id for a Maps listing.
rating	number	Maps rating, 0 to 5.
review_count	integer	Maps review count.
google_maps_url	string

Any other field name is rejected, and the reason names the field. The log, list_name and the results of AI and ICP enrichments cannot be set through this endpoint — they are written by Parvenu.

If the list already has this contact

A contact counts as already in the list when it shares any of these with a stored contact: the email, the LinkedIn profile URL, the name together with the company, or the Maps place_id. For a company with no person on it, the same company LinkedIn page, website or company name counts.

The two are combined, not duplicated:

• A field that is blank on the stored contact is filled in from what you sent.

• A field with a value on the stored contact keeps that value.

That contact is counted in rows_merged rather than rows_added. To change a value that is already stored, use Update a Contact.

History

Every contact this call touches gets one line in its history: Add to List - Parvenu - Added ✅ ... - 0 Credits - API for a new contact, or Merged into existing contact for a combined one.

Response

Field	Description
status	success, or not_found when the list does not exist and create_list is false.
data.list_name	The list.
data.list_created	true when the list did not exist and was made.
data.rows_received	How many contacts were sent. Always 1 here.
data.rows_added	How many were added as new contacts.
data.rows_merged	How many were combined with a contact the list already had.
data.rows_rejected	Contacts that could not be added, each as {index, reason}.
data.dry_run	Whether this was a dry run.
credits_used	Always 0.

A contact that cannot be added — no identifier, an unknown field name, a value in the wrong format — returns an error whose message gives the reason.

Example

Input

{
  "api_key": "your_api_key",
  "listname": "Q4 Roofers",
  "contact": {
    "person_name": "Jane Doe",
    "email": "[email protected]",
    "current_title": "Owner",
    "organization_name": "Acme Roofing",
    "domain": "acmeroofing.com",
    "city": "Sacramento",
    "state": "California"
  }
}

Output

{
  "status": "success",
  "credits_used": 0.0,
  "credits_remaining": 6041.2,
  "message": "Added to 'Q4 Roofers': 0 new, 1 combined with contacts already there.",
  "data": {
    "list_name": "Q4 Roofers",
    "list_created": false,
    "rows_received": 1,
    "rows_added": 0,
    "rows_merged": 1,
    "rows_rejected": [],
    "dry_run": false
  }
}

Jane was already in the list, so she was combined rather than added twice. Any of these fields that were blank on her stored contact are now filled in; the rest kept their values.