POST https://api.hivemoderation.com/api/v1/user_tags/add

Add one or more tags to a patron. If the patron does not exist, they will be created automatically.

Example Request

curl -X POST https://api.hivemoderation.com/api/v1/user_tags/add
-H "Authorization: token <API_KEY>"
-H "Content-Type: application/json"
-d '{
"patron_id": "user_abc123",
"user_tags_api_fields": ["vip", "newsletter"]
}'

Request Headers

Header	Type	Required	Description
Authorization	string	Yes	API key from Hive Moderation Dashboard (per-application).
Content-Type	string	Yes	Submit JSON data in the request body.

Request Body Parameters

Parameter	Type	Required	Description
patron_id	string	Yes	The unique identifier for the patron.
user_tags_api_fields	array	Yes	Array of tag api_field strings to add.

Notes:

If a tag api_field does not exist in the application, it will be reported under failed, not added.
If a tag is already on the patron, it will be reported under pre_existing, not added. No duplicate is created.
If the patron does not exist, they will be created before tags are applied.
Response messages now reflect all possible dynamic outcomes (see table below).

Responses

Response Fields

Field	Type	Always Returned	Description
message	string	Yes	Human-readable result summary.
patron_id	string	Yes	The patron ID provided in the request.
added_tag_ids	array	Yes	Tag IDs successfully added to the patron.
pre_existing_tag_ids	array	Yes	api_fields already associated with the patron, not duplicated.
failed	array	Yes	api_fields that could not be processed, including error message.

Updated Response Messages

/user_tags/add

Scenario	Message
All tags added successfully	Successfully added tags to patron.
Added + some already exist	Successfully added tags to patron. Some tags may already exist on patron.
Added + some failed	Some tags were added. Some tags failed to add.
Added + some already exist + some failed	Some tags were added. Some tags may already exist on patron. Some tags failed to add.
All tags already exist	No tags were added. All tags already exist on patron.
All tags already exist + some failed	No tags were added. Some tags may already exist on patron. Some tags failed to add.
All tags failed to add	No tags were added. All tags failed to add.

/user_tags/remove

Scenario	Message
All tags removed successfully	Successfully removed tags from patron.
Removed + some don't exist	Successfully removed tags from patron. Some tags may not exist on patron.
Removed + some failed	Some tags were removed. Some tags failed to remove.
Removed + some don't exist + some failed	Some tags were removed. Some tags may not exist on patron. Some tags failed to remove.
All tags don't exist	No tags were removed. All tags do not exist on patron.
All tags don't exist + some failed	No tags were removed. Some tags do not exist on patron. Some tags failed to remove.
All tags failed to remove	No tags were removed. All tags failed to remove.

Example Success

{
  "message": "Successfully added tags to patron. Some tags may already exist on patron.",
  "patron_id": "user_abc123",
  "added_tag_ids": ["vip"],
  "pre_existing_tag_ids": ["newsletter"],
  "failed": []
}

Example Error Response

{
  "error": true,
  "status": 400,
  "error_code": "PARAM_REQUIRED",
  "message": "user_tags_api_fields is required.",
  "show_alert": false
}

Common Errors

Status Code	Error Code	Description
400	PARAM_REQUIRED	A required parameter is missing or empty.
400	INVALID_PATRON	No patron matches the provided patron_id (remove endpoint only).
403	INVALID_API_KEY	No application matches the provided API key.