Integration Overview

Integrations connect your platform to the Carrot Network so that Network Integrators can submit supply chain traceability data through the Carrot API. Each document represents a real-world traceability record — such as a MassID tracking a waste batch through the supply chain — built as an immutable event timeline verified by the digital Measurement, Reporting and Verification (dMRV) process.

This section covers the practical onboarding flow, implementation guides, and shared reference data you need before methodology-specific rules are applied.

Key concepts

Before diving into the API, three ideas shape every integration:

• Documents and events — A document is the root record for a traceability flow (e.g., a MassID tracking a waste batch). All state changes are represented by events appended to the document's timeline — there are no update or delete endpoints.

• Immutability — The platform uses an event-sourced model: each submission is appended, and current state is derived from the event log. If you need to correct a mistake, cancel the document with a CANCEL event and create a new one. This immutability underpins trust in the environmental credit market.

• Idempotency — Use deduplicationId on every create and event call so that retries don't produce duplicates. This, combined with ordered externalCreatedAt timestamps, makes integrations resilient to transient failures.

For the full explanation, see Core Concepts.

Integration model

At a high level, every integration follows the same base flow:

1. Authenticate with OAuth 2.0 client credentials.
2. Create a document (POST /documents).
3. Append timeline events (POST /documents/{documentId}/events), or submit multiple events at once (POST /documents/events).
4. Upload optional files through pre-signed attachment URLs.
5. Retrieve and validate final state (GET /documents/{id}).

See API Reference for endpoint-level contract details.

Prerequisites

• Carrot-issued clientId and clientSecret.
• A stable identifier strategy for externalId and deduplicationId.
• Event timestamp ordering from your source system.
• Retry and rate-limiting controls in your client.

Onboarding

To integrate with the Carrot Network, your platform goes through accreditation: you submit company and address information and sign an agreement. Once the process starts, Carrot issues test credentials so you can develop and validate your integration against test data. After accreditation is complete, Carrot issues production credentials for live data. See Environments for test vs production behavior and the go-live checklist.

How this section is organized

• Getting Started: first end-to-end flow, core concepts, and environment setup.
• Guides: task-focused implementation patterns.
• Reference: shared event/data constraints.
• Methodology Integration: methodology-specific events, attributes, and validation rules.

Migrating from a previous integration

If you are upgrading from an older integration or a different API version, note these current requirements:

• Document category — Use MassID (not Mass).
• Measure unit — Use kg (lowercase) for mass.
• Metadata keys — Use Title Case (e.g. Vehicle License Plate, Issue Date). See Data Formats.
• ACTOR events — Use the label field to identify participant roles (Waste Generator, Recycler, Processor, Hauler, Integrator). Do not send deprecated fields such as actor-type.
• Event names — Use the specific event names required by the methodology (e.g. PICK_UP, TRANSPORT_MANIFEST, WEIGHING, DROP_OFF, SORTING, RECYCLED, RECYCLING_MANIFEST). The OPEN event is not used; do not send it.

For the full event sequence and field requirements, see the methodology integration guides.