cURL
POST https://api.hivemoderation.com/api/v1/user_tags/addAdd one or more tags to a patron. If the patron does not exist, they will be created automatically.
cURL
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"]
}'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.
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).
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.
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.
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.
JSON
{
"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": []
}JSON
{
"error": true,
"status": 400,
"error_code": "PARAM_REQUIRED",
"message": "user_tags_api_fields is required.",
"show_alert": false
}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.
