Contact Tags Setup

Tags are the backbone of segmentation in GoHighLevel. This quick-start shows you how to add, remove, and bulk-manage tags on contacts through the API so you can trigger automations and build smart lists programmatically.

Prerequisites

Before working with Contact Tags, confirm you have:

• A GoHighLevel sub-account with existing contacts (or the ability to create them)
• A Private Integration Token with the contacts scope already configured
• At least one contact ID to work with (create a test contact via POST /contacts if needed)
• A REST client such as Postman, Insomnia, or curl

Set Up Authentication

Contact Tags use the same authentication as all contact endpoints. You need a Private Integration Token (PIT) with the contacts scope.

If you already have a PIT from the Contact CRUD setup, you can reuse it here. Tags are covered under the same scope.

If you need a new token, navigate to Settings > Integrations > Private Integrations in your sub-account. Create a new integration, enable the contacts scope, and save. Copy the token and store it securely.

Set your Authorization header to Bearer {your-pit-token} for every request. Your base URL is https://services.leadconnectorhq.com.

Make Your First Call

The most common operation is adding tags to a contact. Send a POST request to /contacts/{contactId}/tags:

POST /contacts/{contactId}/tags
Authorization: Bearer {your-pit-token}
Content-Type: application/json

{
  "tags": ["vip-client", "needs-followup"]
}

The tags parameter accepts an array of strings. Tags that do not exist in the system yet are created automatically when applied. There is no separate “create tag” endpoint.

To remove specific tags, send a DELETE request to /contacts/{contactId}/tags with the same body format:

DELETE /contacts/{contactId}/tags

{
  "tags": ["needs-followup"]
}

For bulk tag operations across multiple contacts, use POST /contacts/bulk/tags. Provide an array of contactIds along with the tags array and specify the action as either add or remove.

Handle the Response

A successful tag addition returns a 200 status with the updated tags array on the contact:

{
  "tags": ["vip-client", "needs-followup", "existing-tag"]
}

The response includes all tags currently on the contact, not just the ones you added. This lets you verify the full tag state in one call.

For bulk operations, the response confirms how many contacts were updated. If a contactId in your array is invalid, the API skips it and processes the rest. Check the response to confirm all expected contacts were modified.

Common errors: 400 means the tags array is missing or empty. 404 means the contactId does not exist. 401 means your token is invalid or lacks the contacts scope.

Test Your Setup

Walk through this sequence to confirm tag management is working:

1. Add tags to a test contact with POST /contacts/{id}/tags using two or three test tags
2. Verify the tags by reading the contact with GET /contacts/{id} and checking the tags field
3. Remove one tag with DELETE /contacts/{id}/tags and confirm only the specified tag was removed
4. Bulk add a tag to multiple contacts using POST /contacts/bulk/tags with two or more contact IDs
5. Verify bulk results by reading each contact and confirming the tag appears on all of them

If tags are not appearing on the contact record, confirm you are sending the tags array in the request body (not as query parameters). Tags are case-sensitive, so “VIP” and “vip” are treated as separate tags.

Next Steps

Read the full Contact Tags Guide for advanced patterns including tag-based automation triggers and smart list filtering. Combine tags with Campaign & Workflow to automatically enroll tagged contacts into sequences, or use Contact CRUD to apply tags at creation time via the upsert endpoint.