BOLD Recycling Integration Guide v1.0.0
Integration guide for BOLD Recycling Application (MvA) v1.0.0 — expected events, required fields, and validation requirements.
This guide explains how to submit MassID documents that satisfy BOLD Recycling rules. It covers the expected event sequence, required fields per event, and common validation issues.
For the base API flow, see Submitting a MassID. For the complete rules catalog, see BOLD Recycling Rules.
Prerequisites
- Completed the Quick Start flow.
- Familiar with Core Concepts (document model, event ordering, idempotency).
- All participants (Waste Generator, Hauler, Processor, Recycler) have valid accreditation documents.
Document creation
Create the document with these required qualifications (validated by rule 5 — MassID Qualifications):
| Field | Required value |
|---|---|
category | MassID |
type | Organic |
measureUnit | kg |
value | Greater than 0 |
subtype | A valid organic waste subtype |
isPublic | Per your visibility requirements |
Reference: Documents API.
Expected event sequence
Submit events in chronological order via POST /documents/{documentId}/events. See
Event Specification for common event fields.
The following sequence reflects the order validated by the BOLD Recycling rules:
Required participant roles
| Role | ACTOR label | Purpose |
|---|---|---|
| Waste Generator | Waste Generator | Source of the waste material |
| Hauler | Hauler | Transports waste from origin to facility |
| Recycler | Recycler | Operates the recycling or composting facility |
| Processor | Processor | Processes sorted material (may be the same entity as recycler) |
1. ACTOR events — participant registration
Register each participant with an ACTOR event. Each must have a valid accreditation document
(rule 4 — Participant Accreditations & Verifications).
| Participant | Required? | Conditions |
|---|---|---|
| Integrator | Yes | Must have valid accreditation with valid dates. |
| Waste Generator | Conditional | Required if waste origin is identified (rule 8). Omit if origin unidentified. |
| Hauler | Conditional | Required for most vehicle types (rule 9). Optional for cart or sludge pipes. |
| Processor | Yes | Exactly one processor required (rule 13). |
| Recycler | Yes | Exactly one recycler required (rule 14). |
Each ACTOR event must include the participant's accreditation data and address (used by rule 7 — Geolocation Precision for 2000 m radius validation).
2. PICK_UP event — waste collection
The PICK_UP event captures vehicle and driver information:
| Field | Required? | Validated by |
|---|---|---|
| Vehicle type | Yes | Rule 10 — Vehicle Identification |
| License plate / ID | Conditional | By vehicle type (rule 10) |
| Driver identifier | Conditional | By vehicle type (rule 11) |
| Exemption justification | Conditional | When driver ID not required (rule 11) |
3. TRANSPORT_MANIFEST event — shipping documentation
Must include (rule 12 — Transport Manifest):
| Field | Required? | Notes |
|---|---|---|
| Document number | Yes | |
| Document type | Yes | Must be MTR for recyclers in Brazil. |
| Issue date | Yes | |
| Attachments | Yes | Upload via File Uploads. |
4. WEIGHING event(s) — mass measurement
Record weight measurements (rule 15 — Weighing):
| Field | Required? | Notes |
|---|---|---|
| Event value | Yes | Weight in kg. |
| Container type | Yes | |
| Capture method | Yes | |
| Scale type | Yes | |
| Scale ticket | Conditional | When required by recycler accreditation. |
Supports both single-step and two-step weighing processes.
5. DROP_OFF event — delivery to recycling facility
Must include (rule 16 — Drop-off At Recycling Facility):
| Field | Required? | Notes |
|---|---|---|
| Receiving operator | Yes | Operator identifier at the facility. |
| Address | Yes | Must match the recycler's accredited address. |
6. SORTING event — mass sorting
Must include (rule 17 — Mass Sorting):
| Field | Required? | Notes |
|---|---|---|
| Gross weight | Yes | Total weight before deductions. |
| Deducted weight | Yes | Weight of contaminants/non-target material. |
| Sorting factor | Yes | Calculated from gross and deducted weight. |
| Event value | Yes | Must be correctly calculated from sorting data. |
7. RECYCLED event — composting completion
The RECYCLED event marks the end of the composting cycle. The timestamp is validated against the DROP_OFF event (rule 18 — Composting Cycle Timeframe):
- Time between DROP_OFF and RECYCLED must be 60–180 days.
8. RECYCLING_MANIFEST event — recycling documentation
Must include (rule 19 — Recycling Manifest):
| Field | Required? | Notes |
|---|---|---|
| Document number | Yes | |
| Document type | Yes | |
| Issue date | Yes | |
| Attachments | Conditional | Required unless exemption justification provided. |
| Exemption justification | Conditional | When attachments are not available. |
Event and rule mapping
CUSTOM event names
| Event Name | Purpose | Validated by |
|---|---|---|
| PICK_UP | Waste collection from generator site | — |
| TRANSPORT_MANIFEST | Transport documentation attachment | — |
| WEIGHING | Weight capture at a calibrated scale | — |
| DROP_OFF | Delivery to the recycling/processing facility | — |
| SORTING | Waste sorting with contamination deduction | — |
| RECYCLED | Confirms composting or recycling completion | — |
| RECYCLING_MANIFEST | Final recycling documentation attachment | — |
ACTOR label vocabulary
| Label | Description | Validated by |
|---|---|---|
| WASTE_GENERATOR | Source of the waste material | — |
| HAULER | Transports waste from origin to facility | — |
| RECYCLER | Operates the recycling or composting facility | — |
| PROCESSOR | Processes sorted material | — |
Additional validations
| Rule | What it checks |
|---|---|
| 1 | No duplicate MassID exists with the same drop-off + pick-up + recycler + waste generator + license plate combination. |
| 2 | MassID is not already linked to a RecycledID or credit order. |
| 3 | RECYCLED event occurred on or after January 1st of the previous year. |
| 6 | Local waste classification matches a valid Ibama code (recyclers in Brazil). |
| 7 | All participant event addresses are within 2000 m of their accredited addresses. |
Post-validation
When all 19 rules pass, the platform:
- Issues a RecycledID certificate linked to the MassID.
- Runs RecycledID rules (rewards distribution for supply chain participants).
- Generates C-BIOW credit tokens (Tokenized Recycling Credits) upon credit order settlement.
Common issues
- Geolocation mismatch — Participant event addresses must be within 2000 m of their accredited addresses. Verify GPS accuracy.
- Composting timeframe — The DROP_OFF to RECYCLED window must be 60–180 days. Documents outside this range fail rule 18.
- Missing accreditations — All participants must have valid, non-expired accreditation documents at the time of event submission.
- Duplicate MassIDs — The uniqueness check (rule 1) prevents duplicate submissions. Use
deduplicationIdfor retries, not re-submissions. - Ibama codes — For recyclers in Brazil, local waste classification must match a valid Ibama code. Validate before submission.
View rules catalog · View app reference · Base integration flow