Event Stream


The event stream is a streaming data source that provides a serialized history of Socotra system events. It is useful for situations like:

  • Triggering integration processes, such as printing and sending an invoice afer it is issued

  • Created automated processes, such as a renewal process after a policy nears experation

  • Capturing data changes for maintaining an external database that includes Socotra data


See the Event Stream API topic for information about how to implement this feature.


The event stream is a paged mechanism. Start by querying for events, and then if more records are needed, requery using the pagingToken from the previous response to fetch more records.


For the first call to fetch events, do not include a pagingToken; instead include at least one filter criterion, such as startTimestamp or eventType.

The EventPageResponse will always include a pagingToken. You can use the pagingToken to get additional results for the same query. When making a call using the pagingToken, omit the original filter criteria. The pagingToken lasts forever: even if you reached the end of the result set, you can save the pagingToken to check for more results later.

On each call to the Event Stream, a different pagingToken may be returned.


There are two event stream query endpoints: Fetch Events and Fetch Attributed Events. The difference is that the latter endpoint will include the username of the user that initiated the event as part of the EventResponse.

Data Types

The event stream contract is to return objects of type EventResponse, each of which contains an EventStreamData object. Each actual data type returned will be a subtype of EventStreamData depending on what kind of event it is. The type can be identified using the type property on the EventResponse that contains the data.

Event Details

Policy Termination and Expiration

  • The policy.end event fires only for policies that expire when they reach their policy’s effectiveContractEndTimestamp. It will not fire when policies end due to cancellation.

  • The cancellation.issue event will fire for both manual cancellations and automatic cancellations due to lapse, unless the system is configured to use Legacy Lapsing and Reinstatment. Lapses can be distiguished from manual cancellations using the cancellationName property.

  • If a cancellation is issued for a future effective date, the cancellation.issue event will be fired immediately. There will be no additional event at that future effective date.

  • The policy.end.reminder event will not fire for policies that have been cancelled.

  • The policy.lapse event is a legacy event and is not fired unless using legacy cancellation processes. Use the cancellation.issue event instead.