Documents
Create and retrieve document records (MassIDs) in the Carrot API.
Last updated on
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 OAuth 2.0 Client Credentials authentication.
In: header
Header Parameters
Request Body
application/json
TypeScript Definitions
Use the request body type in TypeScript.
Response Body
application/json
curl -X POST "https://example.com/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"}Use POST /documents to create a document with required baseline fields:
categoryexternalCreatedAtisPublicisPubliclySearchabletypeparticipantId— a participant resolved via the Participants APIaddressId— an address resolved via the Participants API
Sending full participant or address objects inline instead of participantId/addressId is deprecated
and will be removed in a future release. Resolve participants and addresses first, then reference them by ID.
Optional fields:
deduplicationIdto avoid duplicate submissions on retries.tags,title,shortTitle, and classification fields.
Retrieve document by id
Authorization
OAuth2ClientCredentials OAuth 2.0 Client Credentials authentication.
In: header
Path Parameters
Document identifier
Header Parameters
Response Body
application/json
curl -X GET "https://example.com/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"}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.