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).
All participants (Waste Generator, Hauler, Processor, Recycler) have valid accreditation documents.

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. 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, which validates event addresses against accredited addresses using tiered distance thresholds).

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

{  "externalCreatedAt": "2024-12-05T11:02:47Z",  "isPublic": false,  "address": {    "city": "São Paulo",    "countryCode": "BR",    "countryState": "SP",    "latitude": -23.5613,    "longitude": -46.6563,    "name": "Sede",    "neighborhood": "Centro",    "number": "1000",    "street": "Avenida Exemplo",    "zipCode": "01001000"  },  "label": "Waste Generator",  "name": "ACTOR",  "participant": {    "id": "00000000-0000-4000-8000-00000000000a",    "countryCode": "BR",    "email": "wastegen@example.com",    "mobileNumber": "+5511000000001",    "name": "Acme Example Waste Generator",    "taxId": "11222333000181",    "taxIdType": "CNPJ",    "type": "COMPANY"  }}

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": "2024-12-05T11:02:47Z",  "isPublic": false,  "address": {    "city": "São Paulo",    "countryCode": "BR",    "countryState": "SP",    "latitude": -23.5613,    "longitude": -46.6563,    "name": "Sede",    "neighborhood": "Centro",    "number": "1000",    "street": "Avenida Exemplo",    "zipCode": "01001000"  },  "name": "Pick-up",  "participant": {    "id": "00000000-0000-4000-8000-00000000000a",    "countryCode": "BR",    "email": "wastegen@example.com",    "mobileNumber": "+5511000000001",    "name": "Acme Example Waste Generator",    "taxId": "11222333000181",    "taxIdType": "CNPJ",    "type": "COMPANY"  },  "metadata": {    "attributes": [      {        "isPublic": true,        "name": "Description",        "value": "Waste picked up by hauler Acme Example Hauler at Acme Example Waste Generator"      },      {        "isPublic": true,        "name": "Local Waste Classification ID",        "value": "04 02 20"      },      {        "isPublic": true,        "name": "Local Waste Classification Description",        "value": "Lodos do tratamento local de efluentes não abrangidas em 04 02 19"      },      {        "sensitive": true,        "isPublic": false,        "name": "Vehicle License Plate",        "value": "ABC1D23"      },      {        "isPublic": true,        "name": "Vehicle Type",        "value": "Truck"      },      {        "isPublic": false,        "name": "Driver Identifier",        "value": "00000000-0000-4000-8000-00000000d21f"      }    ]  }}

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.

{  "externalCreatedAt": "2024-12-05T11:02:47Z",  "isPublic": true,  "address": {    "city": "São Paulo",    "countryCode": "BR",    "countryState": "SP",    "latitude": -23.5613,    "longitude": -46.6563,    "name": "Sede",    "neighborhood": "Centro",    "number": "1000",    "street": "Avenida Exemplo",    "zipCode": "01001000"  },  "name": "Transport Manifest",  "participant": {    "id": "00000000-0000-4000-8000-00000000000a",    "countryCode": "BR",    "email": "wastegen@example.com",    "mobileNumber": "+5511000000001",    "name": "Acme Example Waste Generator",    "taxId": "11222333000181",    "taxIdType": "CNPJ",    "type": "COMPANY"  },  "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": "2024-02-10"      }    ]  },  "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": "2024-12-05T11:02:47Z",  "isPublic": true,  "address": {    "city": "São Paulo",    "countryCode": "BR",    "countryState": "SP",    "latitude": -23.5613,    "longitude": -46.6563,    "name": "Sede",    "neighborhood": "Centro",    "number": "1000",    "street": "Avenida Exemplo",    "zipCode": "01001000"  },  "name": "Weighing",  "participant": {    "id": "00000000-0000-4000-8000-00000000000a",    "countryCode": "BR",    "email": "wastegen@example.com",    "mobileNumber": "+5511000000001",    "name": "Acme Example Waste Generator",    "taxId": "11222333000181",    "taxIdType": "CNPJ",    "type": "COMPANY"  },  "value": 1201.925,  "metadata": {    "attributes": [      {        "isPublic": true,        "name": "Description",        "value": "Weighing captured at waste generator site"      },      {        "isPublic": true,        "name": "Weigh Capture Method",        "value": "Average Weight by Volume"      },      {        "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      }    ]  }}

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": "2024-12-05T11:02:47Z",  "isPublic": true,  "address": {    "city": "São Paulo",    "countryCode": "BR",    "countryState": "SP",    "latitude": -23.5613,    "longitude": -46.6563,    "name": "Sede",    "neighborhood": "Centro",    "number": "1000",    "street": "Avenida Exemplo",    "zipCode": "01001000"  },  "name": "Drop-off",  "participant": {    "id": "00000000-0000-4000-8000-00000000000d",    "countryCode": "BR",    "email": "recycler@example.com",    "mobileNumber": "+5511000000004",    "name": "Acme Example Recycler",    "taxId": "11222333000424",    "taxIdType": "CNPJ",    "type": "COMPANY"  },  "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": "2024-12-05T11:02:47Z",  "isPublic": true,  "address": {    "city": "São Paulo",    "countryCode": "BR",    "countryState": "SP",    "latitude": -23.5613,    "longitude": -46.6563,    "name": "Sede",    "neighborhood": "Centro",    "number": "1000",    "street": "Avenida Exemplo",    "zipCode": "01001000"  },  "name": "Sorting",  "participant": {    "id": "00000000-0000-4000-8000-00000000000c",    "countryCode": "BR",    "email": "processor@example.com",    "mobileNumber": "+5511000000003",    "name": "Acme Example Processor",    "taxId": "11222333000343",    "taxIdType": "CNPJ",    "type": "COMPANY"  },  "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": "2025-02-22T10:35:12.000Z",  "isPublic": true,  "address": {    "city": "São Paulo",    "countryCode": "BR",    "countryState": "SP",    "latitude": -23.5613,    "longitude": -46.6563,    "name": "Sede",    "neighborhood": "Centro",    "number": "1000",    "street": "Avenida Exemplo",    "zipCode": "01001000"  },  "name": "Recycled",  "participant": {    "id": "00000000-0000-4000-8000-00000000000d",    "countryCode": "BR",    "email": "recycler@example.com",    "mobileNumber": "+5511000000004",    "name": "Acme Example Recycler",    "taxId": "11222333000424",    "taxIdType": "CNPJ",    "type": "COMPANY"  },  "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

Must include (rule 19 — Recycling Manifest):

Field	Required?	Notes
Document number	Yes
Document type	Yes	Must be `CDF` for recyclers in Brazil.
Issue date	Yes
Attachments	Conditional	Required unless exemption justification provided.
Exemption justification	Conditional	When attachments are not available.

{  "externalCreatedAt": "2024-12-05T11:02:47Z",  "isPublic": true,  "address": {    "city": "São Paulo",    "countryCode": "BR",    "countryState": "SP",    "latitude": -23.5613,    "longitude": -46.6563,    "name": "Sede",    "neighborhood": "Centro",    "number": "1000",    "street": "Avenida Exemplo",    "zipCode": "01001000"  },  "name": "Recycling Manifest",  "participant": {    "id": "00000000-0000-4000-8000-00000000000d",    "countryCode": "BR",    "email": "recycler@example.com",    "mobileNumber": "+5511000000004",    "name": "Acme Example Recycler",    "taxId": "11222333000424",    "taxIdType": "CNPJ",    "type": "COMPANY"  },  "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": "2024-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.
RecycledID rules run (rewards distribution for supply chain participants).
C-BIOW credit tokens (Tokenized Recycling Credits) are generated upon credit order settlement.

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 — 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 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