Contact Tags - Givebutter

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.

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 below to add or remove individual tags.

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

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, or list the tags with tags/remove. To add tags without affecting the rest, use tags/add.

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

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"]}'

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'] }),
});

import requests

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

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.

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.

Tags on Contact Update

PATCH /v1/contacts/{id} replaces a contact’s tags with the tags array you send, the same as tags/sync. 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.

To add or remove specific tags without replacing the whole set, use the dedicated tag endpoints above: tags/add to add, tags/remove to remove, and tags/sync to replace.

​Dedicated Tag Endpoints

​Tagging a Contact on Create

​Tags on Contact Update

Dedicated Tag Endpoints

Tagging a Contact on Create

Tags on Contact Update