The tag endpoint replaces the complete set of tags on a waiver. It is not an append operation. An integration that sends one new tag without considering the current set can remove labels maintained by another workflow.
Choose an ownership model
Decide whether your integration owns every tag on the record or only a defined subset. Use short operational labels rather than participant answers or sensitive details. Document the convention so a booking integration and an internal review tool do not overwrite each other’s work.
The API trims, lowercases and deduplicates tags. The request permits at most 20 tags, with each string between 1 and 64 characters. Read the set-tags reference for the exact schema.
Build the whole intended set
Use waivers:read when reading the current record and waivers:write for the update. The following is an illustrative request shape; replace the path placeholder with the authorized record ID:
PUT /v1/waivers/{id}/tags
Authorization: Bearer YOUR_API_KEY
Content-Type: application/json
{"tags":["school-visit","morning-session"]}
Both labels become the intended set. Sending {"tags":[]} clears the set. Make that action explicit in your application rather than letting an empty input field accidentally remove everything.
Do not promise atomic append behavior
Reading the record, merging locally and writing back can still race with another writer. The contract does not declare a conditional-update mechanism for this endpoint. If several jobs maintain tags, coordinate writes in your own system or give one service responsibility for the complete set.
An illustrative application sequence is: acquire your own per-record work lock, read the current tags, calculate the complete intended set, write once, verify the returned normalized set and release the lock. That lock only coordinates writers that participate in your system; it cannot control unrelated dashboard edits.
Test loss and normalization cases
Test a record with existing labels, case differences, repeated labels and an intentional clear. Also simulate another writer changing tags between your read and update. Confirm the application does not describe a successful response as proof that nobody else’s label was lost.
Keep request IDs and the operational outcome in diagnostics without logging full participant payloads. A tag update does not change the wording or answers in the signed document. Use record retrieval and the record-handling guide for the other parts of the workflow.