Events

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

Create event

curl -X POST "https://example.com/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"}

Use POST /documents/{documentId}/events to append one event to a document timeline. Prefer referencing the event's participant and address by participantId/addressId; the inline participant/address form is still supported and find-or-creates the record. See Participants.

Batch events

curl -X POST "https://example.com/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"    }  ]}

Use POST /documents/events to create multiple events for a document in a single request. The body takes exactly one of:

• documentId — append the events to an existing document; or
• document — a full document payload, creating the document and its events in the same request.

Supplying both or neither returns 400 (Exactly one of documentId or document must be provided).

Each event in the batch follows the same schema as the single-event endpoint above, with one extra check the single-event endpoint does not have: participant and address identities are checked for conflicts across the events in the batch, so the same identity carrying different data fails.

The identity rule itself is the same on both endpoints — every event must carry exactly one of participantId/participant and exactly one of addressId/address. The single-event endpoint delegates to this one after running that check itself.

Logical event types

The current schema defines six discriminated event schemas (CloseEvent, ActorEvent, CancelEvent, RelatedEvent, UpdateEvent, CustomEvent). Any event name the API does not reserve is handled as a CUSTOM event, OUTPUT included.

Creating a downstream document is triggered by the presence of the target object on any event, not by the event name. Both endpoints report the created document as targetDocumentId — on the event's entry in the batch response, and alongside documentId and eventId in the single-event response. Note that the single-event response schema does not declare it, so a generated client may drop it; read it from the raw body if you need it.

CANCEL events require metadata.attributes to include an entry named reason with a non-empty value; omitting it returns 400 (The reason metadata is required for CANCEL events). The name is lowercase reason — the one exception to the Title Case convention for metadata attribute names, and the validator matches it exactly, so Reason is not recognised.

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. A repeated value on the same document is rejected with 409 CONFLICT_ERROR, never replayed — see Error Handling.

Related documents

A RELATED event's relatedDocument.bidirectional defaults to true, which writes the mirrored event on the related document. When bidirectional is true, isPublic is required on the related document. When it is false there is no mirrored event to describe, so eventName, eventLabel, and preserveSensitiveData are all rejected.

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