41 "decision": "Find or Create Label by displayName: Wix returns the existing label of that name (newLabel false) or creates it, so a retry, resume or unknown outcome resends the same call. The crosswalk target is label.tagId, the V5 contact private-tag id; label.key is kept as evidence. Read back by key (GET /contacts/v4/labels/{key})."
42 },
43 "fallbacks": [
44 {
45 "classification": "cms",
46 "when": "Use for source segmentation rules that are not contact labels."
47 }
48 ],
49 "reliability": {
50 "status": "partially-reliable",
51 "flags": []
52 },
53 "pitfalls": [
54 {
55 "code": "source-segment-semantics",
56 "severity": "warning",
57 "summary": "Do not collapse dynamic segments or marketing automation state into static labels without review."
58 },
59 {
60 "code": "label-is-v5-tag",
61 "severity": "warning",
62 "summary": "VERIFIED LIVE 2026-10-27 : a V4 label is the V5 contact private tag. Find or Create Label returns label.tagId (5 chars, e.g. 'WCjva'); V5 tags.privateTags.tagIds takes that tagId, not the label key (a key is refused: 'expected 5 or less'). V4 shows the tag back in info.labelKeys."
63 },
64 {
65 "code": "matched-by-name",
66 "severity": "info",
67 "summary": "A label already on the target with the same displayName is adopted (newLabel false), not duplicated. Two source tags with the same name share one Wix label."
68 }
69 ],
70 "mappingGuidance": [
71 "Dependencies: no other modeled record must exist first; labels are standalone CRM objects and are written before crm/contact-label puts them on contacts.",
72 "Write label definitions with findOrCreateContactLabel; put them on contacts with crm/contact-label (assignContactLabels), never inside the contact upsert body (the default OVERWRITE upsert replaces a matched contact's existing tags)."
84 "note": "Find or Create Label: returns the label with this name or creates it; newLabel says which"
85 },
86 {
87 "type": "live-run",
88 "path": "anonymized-live-verification",
89 "note": "Verified live: create + query-back readback, safe mode on — 3/3 labels (MailPoet segments) created and read back"
90 },
91 {
92 "type": "live-run",
93 "path": "anonymized-live-verification",
94 "note": "Verified live 2026-10-27 (probe P1, throwaway site): find-or-create twice -> same key/tagId, newLabel true then false; GET by key reads it back; V5 update-tags with label.tagId puts it on a contact and V4 labelKeys shows the key; probe records deleted"