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.

CustomEventRef
required
type string

optional
schedule EventScheduleRef?
EventScheduleRef
required
anchor Enum policyStart | policyEnd | termStart | segmentStart
offset map<string,int>
suppressOnStatuses Enum[] cancelled | cancelPending | delinquent | doNotRenew | expired | inGap | onRisk | pending

optional
alignment Enum? weekStart | monthStart | yearStart
cadence EventCadenceRef?
EventCadenceRef
required
durationBasis Enum years | months | weeks | days | hours
intervalDuration int

optional
limit int?

Options:

  • anchor: policyStart, policyEnd, termStart, or segmentStart

  • alignment: (optional) weekStart, monthStart, or yearStart

  • 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.

Fetch Scheduled Policy Events
fetchScheduledPolicyEvents
GET /event/{tenantLocator}/events/schedules/policy/{policyLocator}
    Request Parameters:
    NamePositionTypeRequired
    tenantLocatorpathuuidrequired
    policyLocatorpathstringrequired
    Security Group:events   Permission:read
ScheduledPolicyEvent
required
policyLocator string
transactionLocator string
eventId string

optional
nextEventTime 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

2026-10-29

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 to policyStart 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

2026-05-14

custom.event.type.anniversary

2027-05-14

custom.event.type.anniversary

2028-05-14

custom.event.type.anniversary

2029-05-14

custom.event.type.anniversary

2030-05-14

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

2026-06-05

custom.event.type.otherMonthEvent

2026-08-05

custom.event.type.otherMonthEvent

2026-10-05

custom.event.type.otherMonthEvent

2026-12-05

custom.event.type.otherMonthEvent

2027-02-05

custom.event.type.otherMonthEvent

2027-04-05

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

2026-06-05

custom.event.type.otherMonthEvent

2026-08-05

custom.event.type.otherMonthEvent

2026-10-05

custom.event.type.otherMonthEvent

2026-12-05

custom.event.type.otherMonthEvent

2027-02-05

custom.event.type.otherMonthEvent

2027-04-05

custom.event.type.otherMonthEvent