> For the complete documentation index, see [llms.txt](https://developer.parvenu.io/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://developer.parvenu.io/manage-lists/add-a-contact.md).

# Add a Contact

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

<mark style="color:green;">`POST`</mark> `/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.

{% hint style="info" %}
**Free.** `credits_used` is always `0`.
{% endhint %}

{% hint style="success" %}
**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.
{% endhint %}

For more than one contact, use [Add Contacts in Bulk](/manage-lists/add-contacts-in-bulk.md). 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](#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](/manage-lists/update-a-contact.md).

## 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

{% tabs %}
{% tab title="Input" %}

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

{% endtab %}

{% tab title="Output" %}

```json
{
  "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
  }
}
```

{% endtab %}
{% endtabs %}

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.