API Reference
Documents
Create and retrieve document records (MassIDs) in the Carrot API.
Documents are the core resource in Carrot API. A document (commonly a MassID) becomes the immutable container for traceability data, and all changes happen through appended events.
Create document
Authorization
OAuth2ClientCredentials AuthorizationBearer <token>
OAuth 2.0 Client Credentials authentication.
In: header
Header Parameters
Authorization*string
Authorization bearer token
Request Body
application/json
TypeScript Definitions
Use the request body type in TypeScript.
Response Body
application/json
curl -X POST "https://api.carrot.eco/documents" \ -H "Authorization: string" \ -H "Content-Type: application/json" \ -d '{ "category": "DOCUMENT", "externalCreatedAt": "2020-01-01T00:00:00.000Z", "isPublic": true, "isPubliclySearchable": true, "type": "ORGANIC" }'{
"id": "28b04f62-8fe2-4332-b854-fe8a922788b5"
}Empty
Empty
Empty
Use POST /documents to create a document with required baseline fields:
categoryexternalCreatedAtisPublicisPubliclySearchabletype- one of
participantIdorparticipant(required) - one of
addressIdoraddress(required)
Optional fields:
deduplicationIdto avoid duplicate submissions on retries.tags,title,shortTitle, and classification fields.
Retrieve document by id
Authorization
OAuth2ClientCredentials AuthorizationBearer <token>
OAuth 2.0 Client Credentials authentication.
In: header
Path Parameters
id*string
Document identifier
Header Parameters
Authorization*string
Authorization bearer token
Response Body
application/json
curl -X GET "https://api.carrot.eco/documents/string" \ -H "Authorization: string"{
"address": {
"city": "São Paulo",
"complement": "Apto. 50",
"countryCode": "BR",
"countryState": "São Paulo",
"latitude": -23.5489,
"longitude": -46.6388,
"name": "Edifício Jardins de Monet",
"neighborhood": "José Bonifácio",
"number": "500",
"street": "Rua das Colinas",
"zipCode": "08575720"
},
"author": {
"countryCode": "BR",
"name": "João da Fonseca",
"participantId": "28b04f62-8fe2-4332-b854-fe8a922788b5",
"taxId": "11111111111",
"taxIdType": "CPF",
"type": "COMPANY"
},
"category": "DOCUMENT",
"createdAt": "2020-01-01T00:00:00.000Z",
"currentValue": 1500,
"events": [
{
"address": {
"city": "São Paulo",
"complement": "Apto. 50",
"countryCode": "BR",
"countryState": "São Paulo",
"latitude": -23.5489,
"longitude": -46.6388,
"name": "Edifício Jardins de Monet",
"neighborhood": "José Bonifácio",
"number": "500",
"street": "Rua das Colinas",
"zipCode": "08575720"
},
"author": {
"countryCode": "BR",
"name": "João da Fonseca",
"participantId": "28b04f62-8fe2-4332-b854-fe8a922788b5",
"taxId": "11111111111",
"taxIdType": "CPF",
"type": "COMPANY"
},
"externalCreatedAt": "2020-01-01T00:00:00.000Z",
"externalId": "123456",
"id": "JrSRCUhKOxKyUujM2DkH9",
"isPublic": true,
"label": "Waste Generator",
"metadata": {},
"name": "Pick-up",
"participant": {
"businessName": "Compostagem Corporate LTDA",
"countryCode": "BR",
"email": "joaodaf.54@gmail.com",
"mobileNumber": "+551123456789",
"name": "João da Fonseca",
"taxId": "11111111111",
"taxIdType": "CPF",
"telephoneNumber": "+551146425858",
"type": "COMPANY"
},
"preserveSensitiveData": true,
"relatedDocument": {
"category": "string",
"documentId": "string",
"isPublic": true,
"type": "string"
},
"tags": [
"string"
],
"target": {
"externalCreatedAt": "2020-01-01T00:00:00.000Z",
"externalId": "b195f113-3edb-4208-bb0e-632c09732e2f",
"isPublic": true,
"isPubliclySearchable": true,
"subtype": "Wood",
"type": "ORGANIC",
"value": 0
},
"value": 1000
}
],
"externalCreatedAt": "2020-01-01T00:00:00.000Z",
"externalId": "123456",
"id": "28b04f62-8fe2-4332-b854-fe8a922788b5",
"isPublic": true,
"isPubliclySearchable": true,
"measurementUnit": "kg",
"parentDocumentId": "6sV74NaFq_hWLt6v5pWd5",
"participant": {
"businessName": "Compostagem Corporate LTDA",
"countryCode": "BR",
"email": "joaodaf.54@gmail.com",
"mobileNumber": "+551123456789",
"name": "João da Fonseca",
"taxId": "11111111111",
"taxIdType": "CPF",
"telephoneNumber": "+551146425858",
"type": "COMPANY"
},
"primaryAddress": {
"city": "São Paulo",
"complement": "Apto. 50",
"countryCode": "BR",
"countryState": "São Paulo",
"latitude": -23.5489,
"longitude": -46.6388,
"name": "Edifício Jardins de Monet",
"neighborhood": "José Bonifácio",
"number": "500",
"street": "Rua das Colinas",
"zipCode": "08575720"
},
"primaryParticipant": {
"businessName": "Compostagem Corporate LTDA",
"countryCode": "BR",
"email": "joaodaf.54@gmail.com",
"mobileNumber": "+551123456789",
"name": "João da Fonseca",
"taxId": "11111111111",
"taxIdType": "CPF",
"telephoneNumber": "+551146425858",
"type": "COMPANY"
},
"shortTitle": "MassID",
"status": "OPEN",
"subtype": "Wood",
"tags": [
"string"
],
"title": "MassID",
"type": "ORGANIC"
}Empty
Empty
Empty
Use GET /documents/{id} to fetch the full document payload, including:
- current status and value
- participant and address references
- complete event timeline
- public visibility flags
Design note: immutability
Document data is append-only in practice. There is no PATCH/PUT endpoint for document mutation and
no DELETE endpoint. Operational changes are represented as events.
For a production-oriented workflow, see Submitting a MassID.