Core Concepts

These concepts form the foundation of the Carrot API integration model. Understand them before writing your first API calls.

What is a document?

A document is the root data structure for a traceability record. It registers and represents the full history of a logistics process or flow for a mass — from origin to final destination — in a transparent and auditable way. Each document receives a unique identifier and is classified by category, type, and subtype.

Documents can be related to other documents through events, allowing the platform to build an integrated view of connected processes. For example, a MassID tracking a waste batch through the supply chain is a document that stores identity and classification fields, while all state changes are represented by appended events on its timeline.

Reference: Documents API.

What story does a MassID need to tell?

Every MassID should tell a complete story — with a clear beginning, middle, and end. When you submit data to the Carrot API, ensure that the record is cohesive, traceable, and detailed enough to understand the origin of the mass, its journey, and its final destination.

A well-documented MassID includes information such as:

• Point of origin — where the waste was generated or collected
• Logistics steps — collection, weighing (gross and net weight), vehicle identification
• Transshipment points — intermediate transfers or staging areas
• Participants involved — every actor in the chain of custody
• Final destination — the recycling or composting facility

Each piece of information strengthens traceability, data integrity, and the perceived value of the resulting environmental credit. The more context you provide, the higher the confidence for credit buyers and auditors.

See Submitting a MassID for the step-by-step implementation flow.

Immutability by events

There is no update or delete endpoint. Instead, you add events to represent operational changes over time. The platform uses an event-sourced model: each submission is appended to the document timeline, and current state is derived from the event log.

This immutability is fundamental for the environmental credit market. Once data is recorded and credits are issued and traded, buyers need assurance that the underlying records are permanent and cannot be altered after the fact. Immutable data strengthens the credibility of the system for buyers, regulators, and auditors.

If you need to correct an error, do not attempt to edit the document. Instead, cancel it using a CANCEL event and create a new document with the corrected data, preserving the full traceability flow.

Reference: Events API · Error Handling.

Events and metadata

Events represent concrete operational actions performed on a document — for example, waste collection, weighing, transport, or drop-off at a recycling facility. Together, the events form the document's timeline: a chronologically ordered record of everything that happened to the mass.

Each event can carry metadata (also called attributes) — key-value pairs that provide additional context about what happened. Examples include date, location, vehicle license plate, operator identifier, or weight measurement. Metadata enriches the timeline and makes the traceability record more robust for audits and verification.

Some metadata fields are required by specific methodology rules, while others are recommended as best practices. The more detail you provide, the stronger the validation outcome.

Reference: Event Specification · Data Formats.

Event ordering

Event chronology matters. externalCreatedAt must be valid relative to existing timeline entries, so your integration should preserve source-system order and retries. The platform does not allow future-dated events — timestamps must reflect when the action occurred in the source system.

Visibility and privacy

Public visibility (isPublic) and searchable visibility (isPubliclySearchable) are part of the base model and can be adjusted through event flows.

Guide: Privacy & Masking.

Idempotency and resilience

Use deduplicationId for create/event retries and treat transient errors differently from validation errors.

Guide: Error Handling.