Event Specification
Canonical reference for the built-in event categories — purpose, common fields, and ordering constraints.
Last updated on
This page is the canonical reference for event modeling at the macro/base level.
Built-in logical event categories
| Type | Purpose |
|---|---|
ACTOR | Grants or updates participant roles/permissions on a document timeline. |
CLOSE | Closes the document for future updates (except specific relation flows). |
CANCEL | Cancels the document and blocks future actions. Requires a reason. |
RELATED | Creates relation links between documents. |
UPDATE | Updates selected document visibility-related fields. |
OUTPUT | Conventional name for an event that creates a downstream document. |
CUSTOM | Methodology/application-specific event names. |
A downstream document is created by the presence of the target object on any event, not by the
event name — OUTPUT is the conventional name for that pattern, and it is handled as a CUSTOM
event.
A CANCEL event must carry a metadata.attributes entry named reason with a non-empty value;
omitting it returns 400 with The reason metadata is required for CANCEL events.
For implementation patterns using specific event categories, see:
ACTOR: Permissions guideCANCEL/CLOSE: Error Handling guideRELATED/OUTPUT: Submitting a MassIDUPDATE: Privacy & Masking guideCUSTOM: Defined per methodology — see the methodology integration guides for specific events and validation rules.
Common event fields
Most event payloads share these core fields:
nameexternalCreatedAtisPublicmetadataparticipantId(or an inlineparticipantobject, which find-or-creates the record)addressId(or an inlineaddressobject, which find-or-creates the record)
Every event must carry exactly one of participantId/participant and exactly one of
addressId/address. Sending both forms, or neither, fails with 400 VALIDATION_ERROR
(You must pass participantId or participant field, not both, not neither). The rule is identical on
the single-event and batch endpoints.
- optional
attachments - optional
deduplicationId
Give every ACTOR event a label — the label is the participant's role. The schema does not enforce it, so this is a platform requirement rather than a request-validation one. Each methodology integration guide defines its allowed labels and required order. Do not use deprecated role fields such as actor-type.
An absent or unrecognized label is not an error. The event is accepted, but the participant
contributes no reward share and its name is withheld from the public record — a failure you will only
notice downstream. MassID-document labels are Bin Custodian, Hauler, Integrator, Processor,
Recycler, and Waste Generator (Integrator normalizes to the role Network Integrator).
CUSTOM events
CUSTOM events accept any event name — Network Integrators can define and send whatever operational events fit their workflow. The platform does not restrict CUSTOM event names at the API level.
Methodologies define their own expected CUSTOM event vocabularies and validate them through application rules. See the relevant methodology integration guide for the specific events and validation rules that apply.
Ordering and propagation constraints
- Event timestamps must remain chronologically consistent.
- Propagation behavior is constrained and should be explicitly validated in integration tests.
- Use deterministic retry patterns to avoid duplicate timeline entries.
Endpoint reference: Events API.