GoHighLevel Contacts API

Add Tags

POST/contacts/:contactId/tags

POST /contacts/:contactId/tags Add one or more tags to a contact. Tags are the main way contacts get segmented for workflows, smart lists, and campaign entry. It takes 1 path parameter and 1 body field, requires the contacts.write scope and authenticates with a sub-account (location) token.

Request and authentication

Method: POST
Full URL: https://services.leadconnectorhq.com/contacts/:contactId/tags
Scopes: contacts.write
Token type: Sub-account (location) token
Accepted auth: OAuth Access Token, Private Integration Token
API version header: Version: 2021-07-28
Schema verified: 22 June 2026

Notes from the field

For tagging multiple contacts (CSV imports, mass updates), use `hylo_bulk_execute_ghl_api` with endpoint_name='contacts/add-tags'.
If you're about to call upsert-contact then add-tags, pass `tags` in the upsert body instead — one call instead of two.

This endpoint is safe to fan out in parallel, so a batch of records costs roughly one round trip instead of one per record. Hylo's bulk tools do that server-side and retry HighLevel's 429s with back-off.

Path parameters

Substituted into the URL. Required by definition.

Name	Type	Description
`contactId`required	`string`	Example: `sx6wyHhbFdRXh302LLNR`

Request body

JSON body fields. Nested objects are shown indented under their parent.

Name	Type	Description
`tags`required	`array`	Example: `minim,velit magna`

Response fields

Top-level fields returned on a successful call.

Name	Type	Description
`tags`	`array`	Example: `minim,velit magna`

Example request

Copy-paste ready. Swap YOUR_TOKEN for your access token or Private Integration Token, and the sample ID for your own.

curl -X POST 'https://services.leadconnectorhq.com/contacts/sx6wyHhbFdRXh302LLNR/tags' \
  -H 'Authorization: Bearer YOUR_TOKEN' \
  -H 'Version: 2021-07-28' \
  -H 'Content-Type: application/json' \
  -d '{
    "tags": [
      "minim",
      "velit magna"
    ]
  }'

Skip the schema lookup

Hylo gives your AI agent this schema — and the other 52 documented here — without you looking anything up. Ask in plain English; it picks the endpoint, fills the body, and can run the call against your own sub-account.

View pricing Read the setup guide

More contacts endpoints