> 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/remove-a-contact.md).

# Remove a Contact

Permanently remove one contact from a list, by email, LinkedIn URL, phone or name.

<mark style="color:green;">`POST`</mark> `/remove_contact`

Permanently removes a single contact from a list. The list itself is kept.

{% hint style="danger" %}
**This cannot be undone.** Removed contacts are deleted, not archived. Send `dry_run: true` first to see how many contacts match without removing any.
{% endhint %}

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

{% hint style="warning" %}
**Every match is removed.** If two contacts in the list share the name you pass, both are removed. Email and LinkedIn URL identify one person; a full name may not. When a name is all you have, use `dry_run` first and check `rows_matched`.
{% endhint %}

## Headers

| Name         | Value              |
| ------------ | ------------------ |
| Content-Type | `application/json` |

## Body

| Name                  | Type    | Description                                                                      |
| --------------------- | ------- | -------------------------------------------------------------------------------- |
| `api_key`             | string  | **Required.** Your API key.                                                      |
| `listname`            | string  | **Required.** The list to remove the contact from. One word, not `list_name`.    |
| `email`               | string  | The contact's email address.                                                     |
| `person_linkedin_url` | string  | The contact's LinkedIn profile URL.                                              |
| `phone_number`        | string  | The contact's phone number, in any format.                                       |
| `person_name`         | string  | The contact's full name.                                                         |
| `dry_run`             | boolean | Default `false`. When `true`, reports what would be removed and removes nothing. |

Pass **at least one** of `email`, `person_linkedin_url`, `phone_number` or `person_name`. Passing none returns `422`. Passing several matches a contact that satisfies **any** of them.

## How matching works

You do not need to match the stored formatting.

| Field                 | What is ignored                                                                                                                                     |
| --------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------- |
| `email`               | Case and surrounding spaces. Matched against every column Parvenu stores an email in, so a contact is found whichever way it was added to the list. |
| `person_linkedin_url` | `https://`, `http://`, `www.` and a trailing slash, plus case. `linkedin.com/in/jane-doe` matches `https://www.linkedin.com/in/jane-doe/`.          |
| `phone_number`        | Country code, spaces, brackets and dashes. `416-555-0123` matches a stored `+1 (416) 555-0123`.                                                     |
| `person_name`         | Case and repeated spaces. Also matches a contact whose first and last name together make the name, even when no full name is stored.                |

## Response

| Field               | Description                                                 |
| ------------------- | ----------------------------------------------------------- |
| `status`            | `success`, or `not_found` when nothing in the list matched. |
| `data.rows_matched` | How many contacts matched.                                  |
| `data.rows_removed` | How many were removed. `0` on a dry run.                    |
| `data.matched_on`   | Which identifier fields were used.                          |
| `data.dry_run`      | Whether this was a dry run.                                 |
| `credits_used`      | Always `0`.                                                 |

`not_found` is not an error. It means nothing in that list matched and nothing was removed. Check the list name and the spelling of the identifier.

## Example

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

```json
{
  "api_key": "your_api_key",
  "listname": "Roofing Owners in California",
  "email": "jane@example.com"
}
```

{% endtab %}

{% tab title="Output" %}

```json
{
  "status": "success",
  "data": {
    "list_name": "Roofing Owners in California",
    "rows_matched": 1,
    "rows_removed": 1,
    "matched_on": ["email"],
    "dry_run": false
  },
  "credits_used": 0,
  "credits_remaining": 448.5,
  "message": "Removed 1 contact."
}
```

{% endtab %}
{% endtabs %}

## Example: checking first

A name can match more than one contact, so check before removing.

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

```json
{
  "api_key": "your_api_key",
  "listname": "Roofing Owners in California",
  "person_name": "Jane Doe",
  "dry_run": true
}
```

{% endtab %}

{% tab title="Output" %}

```json
{
  "status": "success",
  "data": {
    "list_name": "Roofing Owners in California",
    "rows_matched": 2,
    "rows_removed": 0,
    "matched_on": ["person_name"],
    "dry_run": true
  },
  "credits_used": 0,
  "credits_remaining": 448.5,
  "message": "2 contacts would be removed. Nothing has been removed."
}
```

{% endtab %}
{% endtabs %}

Two contacts share that name. Repeating the call without `dry_run` would remove both.