Privacy & Masking

The Carrot platform is designed to make supply chain logistics transparent and publicly verifiable. However, some data is sensitive for business or privacy reasons. This guide covers the privacy controls available at the document and event metadata levels.

Visibility flags are set when creating a document (see Documents API) and can be adjusted through UPDATE events (see Event Specification).

Visibility controls

• isPublic: controls whether data is visible on public surfaces such as the Carrot Registry.
• isPubliclySearchable: controls whether records can be found through public search.

The isPublic flag appears at four levels on the write path, and is required at each of them:

• Document level — isPublic on document create, controlling the document itself.
• Event level — isPublic on each event, controlling visibility of the entire event.
• Attachment level — isPublic on each entry of the event's attachments array, which is what governs the attachment rows in the table below.
• Metadata attribute level — isPublic on each entry of metadata.attributes, which overrides event-level visibility for that attribute.

Lower levels can override higher ones — e.g. an attribute can be marked private inside a public event. Override precedence is applied by the Carrot platform.

The target and updates objects carry their own isPublic for the document they create or modify. relatedDocument.isPublic is different: it controls whether the mirrored event written on the related document is public, not that document's own visibility. It is required when bidirectional is true.

When a document or event is marked as public (isPublic: true), anyone with the document ID can view it on the Carrot Registry (registry.carrot.eco). When private (isPublic: false), the data is hidden from public view but remains accessible to auditors for compliance verification.

Participant identity

Visibility flags govern the event and its metadata. The identity of the participant behind the event is governed separately by preserveSensitiveData, a boolean accepted on every event.

A participant's visibility is decided once for the whole document, from every event that mentions it. When the participant is a company, setting preserveSensitiveData: true on any of those events forces its identity private everywhere in the document — name, taxId, taxIdType, and the address coordinates are suppressed — while the events themselves remain publicly visible. Municipality and state are not suppressed.

Send the field explicitly on every ACTOR event. Use false for Processors, Recyclers and Network Integrators, and true for Waste Generators, haulers, Waste Managers and every other supply chain role. A participant that is both a hauler and a processor or recycler in the same document is the exception: leave the field out on every event that mentions it, and it can be named on the public document page. Leaving the field out applies the role's default: Processors, Recyclers and Network Integrators can be named, as long as every supply chain role the participant holds in the document is one of these, with one exception for haulers described below; the other supply chain roles are not named by default. true on any ACTOR event keeps the participant unnamed on every public surface.

Carrot's public MassID surface is stricter. Among other conditions, it requires isPublic: true on every ACTOR event that names the participant, and among the supply chain roles it names only Processors, Recyclers and Network Integrators: a participant that holds any other supply chain role in the document is never named there, whatever the flags say.

A role that can be named is therefore permission, not a guarantee. Send the flags this guide specifies, then read the published document to see the outcome rather than predicting it from the role. If a name you expected is missing, check that payload against this guide first — the role, the event's isPublic, and preserveSensitiveData. Once all three match what the guide asks for, the withholding is the surface's decision rather than something to chase by changing flags, so do not build display logic that assumes a role that can be named appears by name.

The two flags answer different questions, and confusing them is the most expensive mistake on this page:

• isPublic decides whether the event is published. An ACTOR event sent as isPublic: false drops out of the public timeline entirely — the step disappears, not just the name — and is flagged in audit, because every ACTOR event is expected to be public.
• preserveSensitiveData decides whether the participant behind the event is named. The step stays on the timeline; the company behind it does not appear.

Keeping a participant unnamed is a job for preserveSensitiveData. It is never a job for isPublic: false.

The field is also accepted on relatedDocument, where it is rejected when bidirectional is false — as are eventName and eventLabel, since there is no mirrored event to describe.

Per-role visibility policy

The following defaults apply across all methodologies:

• Processor, Recycler and Network Integrator data must be public.
• Generator and hauler data — company information, addresses, PII — must be private.
• A participant that is both the hauler and the recycler or processor in the same document follows the recycler or processor default and can be named on the public document page.
• On the public document page, haulers, bin custodians and Waste Managers are not named by default: their roles appear while their names are withheld, and sending preserveSensitiveData: false names them there. Carrot's public MassID surface never names a Waste Generator, hauler, bin custodian or Waste Manager, whatever the flags say.
• Open-text fields must never contain sensitive data, regardless of event visibility.

A Waste Manager is withheld for re-identification, not because its own participation is sensitive. It is contracted by a generator to choose the destination, so where it serves a single generator in a municipality, naming it names that generator — and municipality and state are public.

When one participant holds several roles

Participants routinely hold more than one role: a hauler with its own sorting facility is both hauler and Processor, and a recycler that also sorts is both Processor and Recycler. The flag is sent per event, but a company resolves to one answer across the whole document.

• Send preserveSensitiveData: true on every ACTOR event of a Waste Generator or hauler. One true anywhere in the document is enough to make that participant private throughout it, so sending it consistently costs nothing.
• The case to think about is a company that is your hauler and your Recycler or Processor. It follows the Recycler or Processor default on the public document page, so hiding its hauling appearance protects nothing: leave the field out on every event that mentions it. A single true there overrides the exception and makes the company private everywhere.
• A Waste Generator is never affected by that case. It stays private whatever else it does in the same document.

The full resolution order, first match wins:

1. preserveSensitiveData: true on any occurrence → private everywhere in the document.
2. Waste Generator → private. Rule 3 never applies to it.
3. Hauler together with Recycler or Processor → public.
4. preserveSensitiveData: false on any occurrence → public.
5. The role default; roles that disagree resolve private.

For methodology-specific recommendations, follow the isPublic flags in the canonical examples:

• BOLD Recycling — MassID Event Reference
• BOLD Carbon — MassID Event Reference

Sensitive data handling

For metadata attributes that contain sensitive or personal data (e.g. license plates, driver identifiers), you have two options:

• Full privacy — Set isPublic: false to hide the data entirely from public surfaces.
• Partial masking — Send the full value, set isPublic: true, and set sensitive: true in the metadata. The platform applies masking on public surfaces — a plate sent as ABC-1234 appears as AB****34 — while preserving the full value for auditors.

Masking always covers a single contiguous run in the middle of the value: at least 4 characters and at least half the value, leaving at most 8 characters visible, split between the start and the end.

Only string values are masked. A non-string attribute marked sensitive is treated as private, and its value is omitted entirely from public surfaces.

Do not pre-mask or redact values in your payload. Send the complete data and let the platform handle the masking.

sensitive is a signal you send, not the mechanism that keeps a value off Carrot's own public surfaces. The public MassID API and the registry metadata document publish a fixed set of attributes maintained in Carrot's code, so an attribute you add is not published there whether or not you flag it. Set the flag correctly regardless — it is what governs masking on the public document page — but do not treat it as the guarantee.

See Data Formats for the sensitive attribute and mask format conventions.

Common private data patterns

The following table lists data fields that partners commonly configure as private, along with the rationale for each:

If you are unsure whether a field should be private or use partial masking, consult the Carrot team for guidance specific to your use case.

Practical masking strategy

1. Keep sensitive values private by default.
2. Expose only the minimum fields required by your business and public workflows.
3. Use sensitive: true for fields that need to be publicly visible in masked form.
4. Audit public payloads regularly to ensure no unintended data exposure.

Related references:

• Core Concepts — Visibility and privacy
• Events API
• Data Formats