Custom Scheduled Events
Overview
Custom Scheduled Events are configurable time-based triggers that are not linked to specific workflows such as delinquency or auto-renewal. They can be used to remind and trigger tasks like:
Processing inflation calculations and other anniversary-based riders.
Triggering notices and reminders to customers a specified number of days prior to the policy anniversary.
Notifying downstream systems that the impact of some mid-term transaction has, or is about to, come into effect.
Like other events, these custom scheduled events are emitted to the event stream and in conjunction with webhooks can be used to trigger workflows, send notifications, or update external systems.
Socotra supports the configuration of any number of named event types for each product. However, implementors are encouraged to be thoughtful and deliberate when defining custom events, particularly those that recur on a scheduled basis. Limiting configuration to only essential events helps maintain system clarity, avoids unnecessary processing overhead, and reduces the risk of unintended interactions or noise in downstream systems.
Configuration
Custom Scheduled Events are configured via Custom Events found at the top level of the ConfigurationRef.
requiredtype stringoptionalschedule EventScheduleRef?
requiredanchor Enum policyStart | policyEnd | termStart | segmentStartoffset map<string,int>suppressOnStatuses Enum[] cancelled | cancelPending | delinquent | doNotRenew | expired | inGap | onRisk | pendingoptionalalignment Enum? weekStart | monthStart | yearStartcadence EventCadenceRef?
requireddurationBasis Enum years | months | weeks | days | hoursintervalDuration intoptionallimit int?
Options:
anchor:
policyStart
,policyEnd
,termStart
, orsegmentStart
alignment: (optional)
weekStart
,monthStart
, oryearStart
offset: (optional) map of durationBasis and duration quantity (e.g.
{ "months" : 1 }
) - Note: A negative offset scheudles the event before the anchor date.cadence: (optional) defines the cadence between and max number of occurances to be scheduled
suppressOnStatus: (optional) list of policy statuses that should suppress firing (e.g.
["cancelled" or "expired"]
)
Add scheduled events to the optional scheduledEvents
array of the ProductRef.
Behavior
Event schedules are created upon issuance of transactions that create a new term, i.e. New Business or Renewals, with the exception of segmentStart
which may also be schedueld upon issuance of a change
or reinstatement
transaction.
An events schedule is controled based on the provided configuration properties, which work as follows:
anchor: Used to determine where to start the schedule from, i.e. the start of the policy, the term or segment start etc.
alignment: Adjusts the base to the start of a week/month/year relative to the
anchor
selected.offset: Shifts event date relative to anchor, or realigned anchor if used.
cadence: Makes the event recurring on a given interval, including a a limit on how many times it should recur, if desired. If omitted, the event will only occur once.
suppressOnStatus: Allows control to suppress the event from firing if the policy is in a specific status, such as
cancelled
.
API
Once schedueld these events can be fetched using the Fetch Scheduled Policy Events API endpoint. This endpoint allows you to retrieve the next scheduled instance of each custom event for a specific policy, including their scheduled dates and types.
GET /event/{tenantLocator}/events/schedules/policy/{policyLocator}
Name | Position | Type | Required |
---|---|---|---|
tenantLocator | path | uuid | required |
policyLocator | path | string | required |
requiredpolicyLocator stringtransactionLocator stringeventId stringoptionalnextEventTime datetime?
Example Use Cases and Configuration
Example #1 - (basic) Single event, some time after policy start
Suppose you want to trigger a one-time customer service survey to be setnt to customers 25 days after the policy start date. You can configure a custom event like this:
{
"customEvents": {
"CustomerSurvey": {
"type": "custom.event.type.customerSurvey",
"schedule": {
"anchor": "policyStart"
"offset": {
"days": 25
}
}
}
}
}
In this case, a policy effective from 2026-01-04
would have the following event(s) scheduled:
Event Schedule |
Event Type |
---|---|
|
custom.event.type.customerSurvey |
Example #2 - (moderate) Recurring event upon every anniversary
A 10-year term, where the implementer requires an event each year on the anniversary of the policy effective date.
{
"customEvents": {
"Anniversary": {
"type": "custom.event.type.anniversary",
"schedule": {
"anchor": "policyStart"
"offset": {
"years": 1
},
"cadence": {
"intervalDuration": 1,
"durationBasis": "years"
}
}
}
}
}
The
anchor
is set topolicyStart
so the event will be scheduled from the policy effective date.The
offset
is set to one year, so the first event will be scheduled for one year after the policy effective date.The
cadence
is set to recur every year, so the event will be scheduled for each anniversary of the policy effective date.
In this case, a policy effective from 2025-05-14
to 2030-05-14
would have the following events scheduled:
Event Schedule |
Event Type |
---|---|
|
custom.event.type.anniversary |
|
custom.event.type.anniversary |
|
custom.event.type.anniversary |
|
custom.event.type.anniversary |
|
custom.event.type.anniversary |
Example #3 - (advanced) Recurring, day of every other month event
A 2-year term, where the implementer requires an event on the 5th day of every other month, beginning the 1st full month after the policy is effective, for the first year of the policy.
{
"customEvents": {
"Anniversary": {
"type": "custom.event.type.otherMonthEvent",
"schedule": {
"anchor": "policyStart",
"alignment": "monthStart",
"offset": {
"days": 5
},
"cadence": {
"intervalDuration": 2,
"durationBasis": "months",
"limit": 6
}
}
}
}
}
In this case, a policy effective from 2026-05-14
to 2028-05-14
would have the following events scheduled:
Event Schedule |
Event Type |
---|---|
|
custom.event.type.otherMonthEvent |
|
custom.event.type.otherMonthEvent |
|
custom.event.type.otherMonthEvent |
|
custom.event.type.otherMonthEvent |
|
custom.event.type.otherMonthEvent |
|
custom.event.type.otherMonthEvent |
Example #3 - (advanced) Recurring, day of every other month event
A 2-year term, where the implementer requires an event on the 5th day of every other month, beginning the 1st full month after the policy is effective, for the first year of the policy.
{
"customEvents": {
"Anniversary": {
"type": "custom.event.type.otherMonthEvent",
"schedule": {
"anchor": "policyStart",
"alignment": "monthStart",
"offset": {
"days": 5
},
"cadence": {
"intervalDuration": 2,
"durationBasis": "months",
"limit": 6
}
}
}
}
}
In this case, a policy effective from 2026-05-14
to 2028-05-14
would have the following events scheduled:
Event Schedule |
Event Type |
---|---|
|
custom.event.type.otherMonthEvent |
|
custom.event.type.otherMonthEvent |
|
custom.event.type.otherMonthEvent |
|
custom.event.type.otherMonthEvent |
|
custom.event.type.otherMonthEvent |
|
custom.event.type.otherMonthEvent |