Events

Events are the primary mechanism for evolving document state. After a document is created, all relevant changes are recorded as new events.

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.

address?

Event address (do not use with addressId)

addressId?string

Event address ID (do not use with address)

attachments?array<>

Event attachments. These attachments must be uploaded first through the attachment upload endpoint, then referenced by file name.

deduplicationId?string

Identifier that prevents event duplication by integrator

externalCreatedAt*string

Event creation date in the source system. The externalCreatedAt value must be earlier than now and equal to or later than the previous event date, preserving event ordering.

externalId?string

Event identifier in the source system

isPublic*boolean

Indicates whether the event can be viewed on the public page

label?string

Event label

metadata?

Event metadata composed of arbitrary key/value pairs, including objects and arrays, used to store additional event data

name*string

Event name. Changes document status to CLOSE. After that, further events are rejected except RELATED.

participant?

Event participant (do not use with participantId)

participantId?string

Event participant ID (do not use with participant)

preserveSensitiveData?boolean

Indicates whether sensitive event data should be preserved

propagateEvent?boolean

Indicates whether the event should be propagated to related documents

relatedDocument?

Information about the document to relate with this event. Can only be used when propagateEvent != true and requires read permission on the related document.

target?

Document to be created from the current event

value?number

Value that updates the document current value

address?

Event address (do not use with addressId)

addressId?string

Event address ID (do not use with address)

attachments?array<>

Event attachments. These attachments must be uploaded first through the attachment upload endpoint, then referenced by file name.

deduplicationId?string

Identifier that prevents event duplication by integrator

externalCreatedAt*string

Event creation date in the source system. The externalCreatedAt value must be earlier than now and equal to or later than the previous event date, preserving event ordering.

externalId?string

Event identifier in the source system

isPublic*boolean

Indicates whether the event can be viewed on the public page

label?string

Event label

metadata?

Event metadata composed of arbitrary key/value pairs, including objects and arrays, used to store additional event data

name*string

Event name. Adding an ACTOR event updates document permissions for the participant. ACTOR requires a label, used as the participant role.

participant?

Event participant (do not use with participantId)

participantId?string

Event participant ID (do not use with participant)

preserveSensitiveData?boolean

Indicates whether sensitive event data should be preserved

propagateEvent?boolean

Indicates whether the event should be propagated to related documents

relatedDocument?

Information about the document to relate with this event. Can only be used when propagateEvent != true and requires read permission on the related document.

target?

Document to be created from the current event

permissions?array<>

List of participant permissions on the document

address?

Event address (do not use with addressId)

addressId?string

Event address ID (do not use with address)

attachments?array<>

Event attachments. These attachments must be uploaded first through the attachment upload endpoint, then referenced by file name.

deduplicationId?string

Identifier that prevents event duplication by integrator

externalCreatedAt*string

Event creation date in the source system. The externalCreatedAt value must be earlier than now and equal to or later than the previous event date, preserving event ordering.

externalId?string

Event identifier in the source system

isPublic*boolean

Indicates whether the event can be viewed on the public page

label?string

Event label

metadata?

Event metadata composed of arbitrary key/value pairs, including objects and arrays, used to store additional event data

name*string

Event name. Adding a CANCEL event changes document status to CANCELLED. After cancellation, subsequent events are rejected.

participant?

Event participant (do not use with participantId)

participantId?string

Event participant ID (do not use with participant)

preserveSensitiveData?boolean

Indicates whether sensitive event data should be preserved

propagateEvent?boolean

Indicates whether the event should be propagated to related documents

relatedDocument?

Information about the document to relate with this event. Can only be used when propagateEvent != true and requires read permission on the related document.

target?

Document to be created from the current event

value?number

Value that updates the document current value

address?

Event address (do not use with addressId)

addressId?string

Event address ID (do not use with address)

attachments?array<>

Event attachments. These attachments must be uploaded first through the attachment upload endpoint, then referenced by file name.

deduplicationId?string

Identifier that prevents event duplication by integrator

externalCreatedAt*string

Event creation date in the source system. The externalCreatedAt value must be earlier than now and equal to or later than the previous event date, preserving event ordering.

externalId?string

Event identifier in the source system

isPublic*boolean

Indicates whether the event can be viewed on the public page

label?string

Event label

metadata?

Event metadata composed of arbitrary key/value pairs, including objects and arrays, used to store additional event data

name*string

Event name. Adding a RELATED event requires relatedDocument with the target document information.

participant?

Event participant (do not use with participantId)

participantId?string

Event participant ID (do not use with participant)

preserveSensitiveData?boolean

Indicates whether sensitive event data should be preserved

propagateEvent?boolean

Indicates whether the event should be propagated to related documents

relatedDocument*

Information about the document to relate with this event. Can only be used when propagateEvent != true and requires read permission on the related document.

target?

Document to be created from the current event

value?number

Value that updates the document current value

address?

Event address (do not use with addressId)

addressId?string

Event address ID (do not use with address)

attachments?array<>

Event attachments. These attachments must be uploaded first through the attachment upload endpoint, then referenced by file name.

deduplicationId?string

Identifier that prevents event duplication by integrator

externalCreatedAt*string

Event creation date in the source system. The externalCreatedAt value must be earlier than now and equal to or later than the previous event date, preserving event ordering.

externalId?string

Event identifier in the source system

isPublic*boolean

Indicates whether the event can be viewed on the public page

label?string

Event label

metadata?

Event metadata composed of arbitrary key/value pairs, including objects and arrays, used to store additional event data

name*string

Event name. UPDATE allows changing specific document fields.

participant?

Event participant (do not use with participantId)

participantId?string

Event participant ID (do not use with participant)

preserveSensitiveData?boolean

Indicates whether sensitive event data should be preserved

propagateEvent?boolean

Indicates whether the event should be propagated to related documents

relatedDocument?

Information about the document to relate with this event. Can only be used when propagateEvent != true and requires read permission on the related document.

target?

Document to be created from the current event

updates?

Fields of the original document to update

address?

Event address (do not use with addressId)

addressId?string

Event address ID (do not use with address)

attachments?array<>

Event attachments. These attachments must be uploaded first through the attachment upload endpoint, then referenced by file name.

deduplicationId?string

Identifier that prevents event duplication by integrator

externalCreatedAt*string

Event creation date in the source system. The externalCreatedAt value must be earlier than now and equal to or later than the previous event date, preserving event ordering.

externalId?string

Event identifier in the source system

isPublic*boolean

Indicates whether the event can be viewed on the public page

label?string

Event label

metadata?

Event metadata composed of arbitrary key/value pairs, including objects and arrays, used to store additional event data

name*string

Event name. Any value is allowed, enabling custom actions without predefined rules.

participant?

Event participant (do not use with participantId)

participantId?string

Event participant ID (do not use with participant)

preserveSensitiveData?boolean

Indicates whether sensitive event data should be preserved

propagateEvent?boolean

Indicates whether the event should be propagated to related documents

relatedDocument?

Information about the document to relate with this event. Can only be used when propagateEvent != true and requires read permission on the related document.

target?

Document to be created from the current event

value?number

Value that updates the document current value

Response Body

`application/json`

curl -X POST "https://api.carrot.eco/documents/string/events" \  -H "Authorization: string" \  -H "Content-Type: application/json" \  -d '{    "externalCreatedAt": "2020-01-01T00:00:00.000Z",    "isPublic": true,    "name": "CLOSE"  }'

{
  "documentId": "28b04f62-8fe2-4332-b854-fe8a922788b5",
  "eventId": "JrSRCUhKOxKyUujM2DkH9"
}

Empty

Use POST /documents/{documentId}/events to append one event to a document timeline.

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.

document?

Document data associated with the events

documentId?string

Document ID

events*array<>

List of events to create in the document

Response Body

`application/json`

curl -X POST "https://api.carrot.eco/documents/events" \  -H "Authorization: string" \  -H "Content-Type: application/json" \  -d '{    "events": [      {        "externalCreatedAt": "2020-01-01T00:00:00.000Z",        "isPublic": true,        "name": "Pick-up"      }    ]  }'

{
  "documentId": "28b04f62-8fe2-4332-b854-fe8a922788b5",
  "events": [
    {
      "eventId": "string",
      "targetDocumentId": "string"
    }
  ]
}

Empty

Use POST /documents/events to create multiple events for a document in a single request. Each event in the batch follows the same schema and validation rules as the single-document endpoint above.

Logical event types

Type	Purpose
`ACTOR`	Adds a participant role on the document and can update permissions.
`CLOSE`	Closes the document for future updates (except specific relation workflows).
`CANCEL`	Cancels the document and blocks future actions.
`RELATED`	Links this document to another document.
`UPDATE`	Updates specific document visibility fields.
`SPLIT`	Creates a new document with part of the original value. No dedicated schema — represented via `target` payload fields.
`OUTPUT`	Creates a new downstream document from current data. No dedicated schema — represented via `target` payload fields.
`CUSTOM`	Methodology-specific event names not covered by built-in types.

The current schema defines six discriminated event schemas (CloseEvent, ActorEvent, CancelEvent, RelatedEvent, UpdateEvent, CustomEvent). SPLIT and OUTPUT do not have their own schemas and are instead represented through event data using the target payload fields.

Ordering and consistency

externalCreatedAt must be before current time.
externalCreatedAt must be equal to or later than the last recorded event.
Use deduplicationId when retrying event submissions.

Event propagation

When propagateEvent is enabled, propagation applies only one relationship level deep. Some event combinations are restricted (for example, propagated events cannot send value).

For complete event definitions and methodology alignment, see Event Specification.

Create event

Authorization

Path Parameters

Header Parameters

Request Body

Response Body

`application/json`

Batch events

Authorization

Header Parameters

Request Body

Response Body

`application/json`

Logical event types

Ordering and consistency

Event propagation

On this page

Events

201application/json

400

401

504

201application/json

400

401

504

On this page

`application/json`

`application/json`