BOLD Recycling Credit Integration Guide

Integration guide for BOLD Recycling Credit Application 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).
Accreditation documents on file for the Network Integrator, the Processor and the Recycler. Rule 4 checks these three only — a Hauler needs no accreditation, and a Waste Generator's is not required by this rule.

Field	Required value
`category`	`MassID`
`type`	`Organic`
`measureUnit`	`kg`
`value`	Greater than 0
`subtype`	A valid organic waste subtype
`isPublic`	Per your visibility requirements

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. Rule 4 — Participant Accreditations & Verifications — checks accreditation documents for the Integrator, Processor and Recycler only, and the Processor's and Recycler's accreditation must be valid on the evaluation date. Registering a Hauler or a Waste Generator does not require an accreditation document.

Participant	Required?	Conditions
Integrator	Yes	Must have an accreditation document.
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).

Every ACTOR event carries the participant and address identifiers. It carries no accreditation data: accreditation is not submitted through the API at all — it lives in the accreditation layer, and the verification pipeline reads it from there. Rule 7 — Geolocation Precision — compares an event's address against the accredited address of the participants that have an accreditation on file.

The payload shape is identical across actors — only the role identifier differs.

{  "externalCreatedAt": "2025-12-05T11:02:47Z",  "isPublic": true,  "preserveSensitiveData": true,  "addressId": "00000000-0000-4000-9000-00000000000a",  "label": "Waste Generator",  "name": "ACTOR",  "participantId": "00000000-0000-4000-8000-00000000000a"}

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)

{  "externalCreatedAt": "2025-12-05T11:02:47Z",  "isPublic": true,  "addressId": "00000000-0000-4000-9000-00000000000a",  "name": "Pick-up",  "participantId": "00000000-0000-4000-8000-00000000000a",  "metadata": {    "attributes": [      {        "isPublic": true,        "name": "Description",        "value": "Waste picked up at the waste generator site"      },      {        "isPublic": true,        "name": "Local Waste Classification ID",        "value": "02 01 03"      },      {        "isPublic": true,        "name": "Local Waste Classification Description",        "value": "Resíduos de tecidos vegetais"      },      {        "sensitive": true,        "isPublic": true,        "name": "Vehicle License Plate",        "value": "ABC1D23"      },      {        "isPublic": true,        "name": "Vehicle Type",        "value": "Truck"      },      {        "sensitive": true,        "isPublic": true,        "name": "Driver Identifier",        "value": "00000000-0000-4000-8000-00000000d21f"      }    ]  }}

3. Transport Manifest event — shipping documentation

The event remains required (rule 12 — Transport Manifest). For the standard submission with an attachment:

Field	Required?	Notes
Document number	Yes
Document type	Yes	Must be `MTR` for recyclers in Brazil.
Issue date	Yes
Attachments	Yes	Use the label `Transport Manifest`; upload via File Uploads.

Manifest exemptions

For both Transport Manifest (MTR) and Recycling Manifest (CDF), provide either the correctly labelled attachment or a non-empty Exemption Justification metadata attribute. Providing neither, providing both, or providing an attachment with no matching manifest label fails validation. The exemption path does not require the document number, document type, or issue date listed for the standard submission. It still requires the manifest event and the Recycler ACTOR event; the Recycling Manifest address must still match the Recycler's address.

Use the existing framework rules for manifest fields, attachments, and exemption justification as the criteria reference. Technical acceptance of a justification does not establish eligibility for an exemption: a missing PDF alone is not sufficient. Confirm the applicable evidence requirements and any case-specific decision with the methodology and accreditation teams before submitting an exemption. This guide grants no participant-specific exception. These shared requirements also apply to BOLD Carbon (CH₄).

The example below shows the standard attachment path.

{  "externalCreatedAt": "2025-12-05T11:02:47Z",  "isPublic": true,  "addressId": "00000000-0000-4000-9000-00000000000a",  "name": "Transport Manifest",  "participantId": "00000000-0000-4000-8000-00000000000a",  "value": 1201.925,  "metadata": {    "attributes": [      {        "isPublic": true,        "name": "Document Type",        "value": "MTR"      },      {        "isPublic": true,        "name": "Document Number",        "value": "DOC-EXAMPLE-0001"      },      {        "format": "DATE",        "isPublic": true,        "name": "Issue Date",        "value": "2025-02-09"      }    ]  },  "attachments": [    {      "fileName": "transport-manifest.pdf",      "isPublic": false,      "label": "Transport Manifest"    }  ]}

4. Weighing event(s) — mass measurement

Record weight measurements (rule 15 — Weighing):

Field	Required?	Notes
Event value	Yes	Net weight in kg, must be greater than 0.
Description	Yes	Weighing event description.
Gross weight	Yes	Must be greater than 0, in kg.
Tare	Yes	Container empty weight in kg (exemptions may apply per accreditation).
Container type	Yes	One of: Bag, Bin, Drum, Pail, Street Bin, Waste Box, or Truck.
Container quantity	Conditional	Required when container type is not Truck.
Container capacity	Conditional	Required for multi-container weighing.
Capture method	Yes	One of: Digital, Photo (Scale + Cargo), Manual, or Transport Manifest.
Scale type	Yes	Must match an approved scale type.
Scale ticket	Conditional	When required by recycler accreditation.
Vehicle license plate	Conditional	Required when container type is Truck.

Supports both single-step and two-step weighing processes.

{  "externalCreatedAt": "2025-12-05T11:02:47Z",  "isPublic": true,  "addressId": "00000000-0000-4000-9000-00000000000a",  "name": "Weighing",  "participantId": "00000000-0000-4000-8000-00000000000a",  "value": 1201.925,  "metadata": {    "attributes": [      {        "isPublic": true,        "name": "Description",        "value": "Weighing captured at waste generator site"      },      {        "isPublic": true,        "name": "Weighing Capture Method",        "value": "Digital"      },      {        "isPublic": true,        "name": "Scale Type",        "value": "Floor Scale"      },      {        "isPublic": true,        "name": "Container Type",        "value": "Drum"      },      {        "isPublic": true,        "name": "Container Quantity",        "value": 1      },      {        "format": "KILOGRAM",        "isPublic": true,        "name": "Container Capacity",        "value": 100      },      {        "format": "KILOGRAM",        "isPublic": true,        "name": "Gross Weight",        "value": 1211.925      },      {        "format": "KILOGRAM",        "isPublic": true,        "name": "Tare",        "value": 10      },      {        "sensitive": true,        "isPublic": true,        "name": "Vehicle License Plate",        "value": "ABC1D23"      }    ]  }}

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.

{  "externalCreatedAt": "2025-12-05T11:02:47Z",  "isPublic": true,  "addressId": "00000000-0000-4000-9000-00000000000d",  "name": "Drop-off",  "participantId": "00000000-0000-4000-8000-00000000000d",  "metadata": {    "attributes": [      {        "isPublic": true,        "name": "Description",        "value": "Waste deposited in Windrow number 1"      },      {        "isPublic": true,        "name": "Receiving Operator Identifier",        "value": "00000000-0000-4000-8000-00000000000c"      }    ]  }}

6. Sorting event — mass sorting

Must include (rule 17 — Mass Sorting):

Field	Required?	Notes
Description	Yes	Sorting event description.
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.

{  "externalCreatedAt": "2025-12-05T11:02:47Z",  "isPublic": true,  "addressId": "00000000-0000-4000-9000-00000000000c",  "name": "Sorting",  "participantId": "00000000-0000-4000-8000-00000000000c",  "value": 1189.906,  "metadata": {    "attributes": [      {        "isPublic": true,        "name": "Description",        "value": "Sorting factor determined by a third-party audit"      },      {        "format": "KILOGRAM",        "isPublic": true,        "name": "Gross Weight",        "value": 1201.925      },      {        "format": "KILOGRAM",        "isPublic": true,        "name": "Deducted Weight",        "value": 12.019      }    ]  }}

7. Recycled event — biological treatment completion

The Recycled event marks the end of the biological treatment 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.

{  "externalCreatedAt": "2026-02-22T10:35:12.000Z",  "isPublic": true,  "addressId": "00000000-0000-4000-9000-00000000000d",  "name": "Recycled",  "participantId": "00000000-0000-4000-8000-00000000000d",  "metadata": {    "attributes": [      {        "isPublic": true,        "name": "Description",        "value": "Composting process completed. The recycling completion date is recorded by a conservative estimate determined and verified by a third-party audit for the recycler"      }    ]  }}

8. Recycling Manifest event — recycling documentation

The event remains required (rule 19 — Recycling Manifest). For the standard submission with an attachment:

Field	Required?	Notes
Document number	Yes
Document type	Yes	Must be `CDF` for recyclers in Brazil.
Issue date	Yes
Attachments	Yes	Use the label `Recycling Manifest`.

For the alternative with Exemption Justification, see Manifest exemptions. The example below shows the standard attachment path.

{  "externalCreatedAt": "2025-12-05T11:02:47Z",  "isPublic": true,  "addressId": "00000000-0000-4000-9000-00000000000d",  "name": "Recycling Manifest",  "participantId": "00000000-0000-4000-8000-00000000000d",  "value": 1201.925,  "metadata": {    "attributes": [      {        "isPublic": true,        "name": "Document Type",        "value": "CDF"      },      {        "isPublic": true,        "name": "Document Number",        "value": "DOC-EXAMPLE-0002"      },      {        "format": "DATE",        "isPublic": true,        "name": "Issue Date",        "value": "2025-03-10"      }    ]  },  "attachments": [    {      "fileName": "recycling-manifest.pdf",      "isPublic": false,      "label": "Recycling Manifest"    }  ]}

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	Participant event addresses are validated against accredited addresses using tiered distance thresholds (≤2 km: GPS check, 2–30 km: address similarity review, >30 km: fail).

Post-validation

When all 19 rules pass:

A RecycledID certificate is issued, linked to the MassID, and published in the Carrot Registry.
Its C-BIOW credit tokens (Tokenized Recycling Credits) are minted when the certificate is recorded on the public registry, in the same transaction — see Registry Record Creation.
Rewards for supply chain participants are calculated and committed on-chain later, when a credit from that certificate is sold.

Common issues

Geolocation mismatch — Participant event addresses are validated against accredited addresses using tiered distance thresholds. Verify GPS accuracy.
Biological treatment timeframe — The Drop-off to Recycled window must be 60–180 days. Documents outside this range fail rule 18.
Missing accreditations — The Integrator, Processor and Recycler must have accreditation documents on file, and the Processor's and Recycler's must be valid and non-expired at the time the methodology runs, not at the time the event was submitted. Rule 4 does not check Hauler or Waste Generator accreditation.
Duplicate MassIDs — The uniqueness check (rule 1) prevents duplicate submissions. Use deduplicationId for 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