> ## Documentation Index
> Fetch the complete documentation index at: https://docs.givebutter.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Contact Tags

> How tags are added, replaced, and removed when you write to a contact through the API.

Givebutter gives you a few ways to set a contact's tags through the API, each suited to a different change. Some endpoints **add** tags, `tags/sync` and the contact update endpoint **replace** the whole set, and `tags/remove` takes specific tags off. This page covers what each one does, so you can pick the one that matches the change you want to make.

<Note>
  Writing `tags` on `PATCH /v1/contacts/{id}` **replaces** the contact's whole tag set, the same way `tags/sync` does. Send the complete list you want the contact to end up with, omit `tags` to leave the existing ones as they are, or use the [dedicated tag endpoints](#dedicated-tag-endpoints) below to add or remove individual tags.
</Note>

## Dedicated Tag Endpoints

Use these endpoints to manage a contact's tags without changing the rest of the contact record. Each one takes a `tags` array of at least one tag name, and any name that does not exist yet is created automatically. An empty array returns a `422`.

| Endpoint | What it does | Tags you don't list |
| - | - | - |
| `POST /v1/contacts/{id}/tags/add` | **Adds** the listed tags to the contact. | Left in place |
| `POST /v1/contacts/{id}/tags/sync` | **Replaces** the contact's entire tag set with exactly the tags you send. | **Removed** |
| `POST /v1/contacts/{id}/tags/remove` | **Removes** the listed tags from the contact. | Left in place |

<Note>
  Because `tags/sync` replaces the whole set, any tag you leave out of the request is removed. Each of these endpoints needs at least one tag name, so to clear all of a contact's tags, send an empty `tags` array to the [contact update endpoint](#tags-on-contact-update), or list the tags with `tags/remove`. To add tags without affecting the rest, use `tags/add`.
</Note>

For example, to add two tags to a contact while keeping any tags it already has:

<CodeGroup>
  ```bash cURL theme={null}
  curl https://api.givebutter.com/v1/contacts/{id}/tags/add \
    -X POST \
    -H "Authorization: Bearer YOUR_API_KEY" \
    -H "Content-Type: application/json" \
    -d '{"tags": ["Major Donor", "Volunteer"]}'
  ```

  ```javascript Node.js / JavaScript theme={null}
  const response = await fetch('https://api.givebutter.com/v1/contacts/{id}/tags/add', {
    method: 'POST',
    headers: {
      Authorization: 'Bearer YOUR_API_KEY',
      'Content-Type': 'application/json',
    },
    body: JSON.stringify({ tags: ['Major Donor', 'Volunteer'] }),
  });
  ```

  ```python Python theme={null}
  import requests

  requests.post(
      'https://api.givebutter.com/v1/contacts/{id}/tags/add',
      headers={'Authorization': 'Bearer YOUR_API_KEY'},
      json={'tags': ['Major Donor', 'Volunteer']},
  )
  ```
</CodeGroup>

## Tagging a Contact on Create

`POST /v1/contacts` runs deduplication before it creates. Givebutter first looks for an existing contact that matches on signals like email and phone. When it finds one, your request is matched to that existing contact instead of creating a new record, which is the common path when the same person is submitted more than once.

Any `tags` you include are **added** to the contact.

<Note>
  When the request matches an existing contact that already has tags, your tags are **added** to the ones already there. The existing tags are kept and nothing is removed. To replace the whole set or remove specific tags, use the update endpoint or the [dedicated tag endpoints](#dedicated-tag-endpoints).
</Note>

## Tags on Contact Update

`PATCH /v1/contacts/{id}` **replaces** a contact's tags with the `tags` array you send, the same as [`tags/sync`](#dedicated-tag-endpoints). Creating a contact **adds** tags instead, so reach for the update endpoint when you want the `tags` you send to become the contact's full set.

* `"tags": ["Major Donor", "Volunteer"]` makes those the contact's tags, replacing any it had before.
* `"tags": []` clears all of the contact's tags.
* Omitting `tags`, or sending `"tags": null`, leaves the contact's tags unchanged.

<Note>
  To add or remove specific tags without replacing the whole set, use the [dedicated tag endpoints](#dedicated-tag-endpoints) above: `tags/add` to add, `tags/remove` to remove, and `tags/sync` to replace.
</Note>


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.