> For the complete documentation index, see [llms.txt](https://polser.gitbook.io/polser-docs/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://polser.gitbook.io/polser-docs/api-docs/api-reference/contacts.md).

# Contacts

## Create or update a contact

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

Create or update a contact in Polser with the provided profile details.

**Headers**

| Name          | Value              |
| ------------- | ------------------ |
| Content-Type  | `application/json` |
| Authorization | `your-api-key`     |

**Body**

Identify the contact with exactly one of:

* `phone`: unique phone number for the contact
* `bsuid`: Business-Scoped User ID from WhatsApp webhook events

```json
{
  "contact": {
    "phone": "+44XXXXXXXXX",
    "bsuid": "NP.0000000000000002", // If the recipient uses a username to hide the phone
    "name": "John Smith",
    "labels": "Newsletter Subscriber, Future Candidate",
    "enhanced_data": {
      "Outstanding payments": [
        {
          "text": "INV-2812381_456",
          "description": "Since 13 Aug 2024",
          "link": "www.google.com"
        }
      ],
      "Other data": [
        {
          "text": "CRM ID",
          "description": "View details",
          "link": "www.google.com"
        }
      ]
    }
  },
  "overrideLabels": true
}
```

`overrideLabels` sits at the same level as `contact` and `removeLabels`, not inside `contact`. Set it to `true` to replace all of the contact's labels with the ones in `labels`. Leave it out or set it to `false` to add the labels and keep the existing ones. With `overrideLabels: true`, the contact ends up with exactly the labels in `labels`, and a name listed in both `labels` and `removeLabels` is kept.

### Remove labels from a contact

You can remove specific labels from a contact in the same call you use to create or update it. Add a `removeLabels` field next to `contact`. It takes a list of label names or a single comma-separated text.

* Names must match exactly, including capital letters.
* Only the labels you list are removed. Every other label stays on the contact.
* If the contact does not have a label you list, nothing happens and no error is returned.
* The label itself is not deleted. It stays in your account and on other contacts.
* If the same name is in both `labels` and `removeLabels`, the label stays.

Example: move a contact from "Status: Pending" to "Status: Enrolled".

```json
{
  "contact": {
    "phone": "+44XXXXXXXXX",
    "name": "John Smith",
    "labels": "Status: Enrolled"
  },
  "removeLabels": ["Status: Pending", "Status: Waitlist"]
}
```

The response shows the contact's full list of labels after the update, so removed labels no longer appear.

## Export contacts

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

Export all your contacts in CSV format, including all the additional data points you may have synced from third party integrations.

**Headers**

| Name          | Value              |
| ------------- | ------------------ |
| Content-Type  | `application/json` |
| Authorization | `your-api-key`     |

**Body**

***email*** is the recipients email to which Polser will send the exported contacts list.

```
{
    "email": "your-email@yourdomain.io"
}
```

## Delete a contact

<mark style="color:red;">`DELETE`</mark> `/contacts/{contact_id}`

Delete a contact and all the related data by providing a phone number or a BSUID. **Warning**: there is no way to recover this data so be mindful when using this operation.

**Headers**

| Name          | Value              |
| ------------- | ------------------ |
| Content-Type  | `application/json` |
| Authorization | `your-api-key`     |

**URL Parameters**

| Name        | Value                                                                                                                                               |
| ----------- | --------------------------------------------------------------------------------------------------------------------------------------------------- |
| contact\_id | <p><code>34XXXXXXXXXXX</code></p><p><code>NP.0000000000000002</code></p><p>Phone number with country code but without the plus sign, or a BSUID</p> |

**Response**

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

```json
{
    "message": "Contact deleted"
}
```

The contact was deleted successfully, along with any messages they exchanged with Polser.
{% endtab %}

{% tab title="400" %}

```json
{
    "error": "Phone number is required"
}
```

The request is missing the phone number of the contact.

```json
{
    "error": "Contact does not exist"
}
```

The customer with the phone number provided could not be found.
{% endtab %}

{% tab title="401" %}

<pre class="language-json"><code class="lang-json"><strong>{
</strong>    "error": "Unauthorized"
}
</code></pre>

The API key is missing or incorrect.
{% endtab %}
{% endtabs %}