With an authenticated user (see API: authentication) it is possible to add tags to and remove tags from a single person. Only the tags named in the request change; all other tags of the person stay as they are. This is the difference to sending tags to POST /api/v1/people (see API: People/Actions), which removes every tag that is not sent.
The user needs the permission to edit people.
API Call
HTTP-PATCH: https://{Cambuildr-Url}/api/v1/people/{person}/tags
{
"add": [
{ "id": 1234 }, // the tag id in CamBuildr
{ "screen_name": "Volunteer Vienna" }, // or the tag name
{ "id": 5678, "consent_accepted": true } // consentable tags need this parameter, see the note below
],
"remove": [
{ "id": 4321 },
{ "screen_name": "Newsletter Draft Group" }
]
}{person} is the person's ID or identifier in CamBuildr.
Parameters
add: the tags to add to the person.remove: the tags to remove from the person.
Send add, remove or both, with up to 100 tags each. Name each tag by its id (as a number) or its screen_name. Names are matched without regard to upper and lower case. The same tag cannot be in both lists.
Response
{
"error": false,
"tags": [ // all tags the person has after the request
{ "id": 1234, "screen_name": "Volunteer" },
{ "id": 2345, "screen_name": "Volunteer Vienna" }
],
"attached": [1234, 2345], // tags that were added by this request
"detached": [4321], // tags that were removed by this request
"pending_optin": [5678] // consents that wait for the person's confirmation by email
}Adding a tag the person already has, or removing a tag the person does not have, changes nothing and is not listed in attached or detached. The same request can therefore be sent again safely.
Notes
Unknown tags
A tag that does not exist in CamBuildr is refused with 422 Unprocessable Content, and nothing is changed. The response names the entry, for example "add.1": ["The tag does not exist."]. A new tag is only created from a screen_name in add when the user has the permission to administer tags.
Consentable tags
Consentable tags work as with POST /api/v1/people. A consentable tag in add is only set when it carries consent_accepted: true. Without the parameter it is ignored, and consent_accepted: false is respected.
If the tag requires double opt-in, a DOI email is sent to the person and the tag is listed in
pending_optin. The tag is set when the person clicks the confirmation link. Other tags in the same request are set immediately.If the tag does not require double opt-in, it is set immediately and the consent is logged with the tag's consent title and text.
A tag that grants consent to email tracking is always confirmed by email.
A consent can only be confirmed by email. If the person has no email address, the request is refused with 422 and nothing is changed.
Removing a consentable tag logs that the consent was withdrawn.
Errors
401 Unauthorized: the user does not have the permission to edit people.404 Not Found: there is no person with this ID or identifier, or the person is not in one of the user's campaigns.422 Unprocessable Content: the request is invalid, for example an unknown tag, a tag in both lists, or an empty request.