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. You can define policy-specific events (“Policy Events”) or events that are more broadly applicable across a tenant (“Tenant Events”). Each of these two types of custom scheduled events has a distinct configuration and set of API endpoints.

Policy Events

Policy-scoped custom scheduled events can be used to send notifications and trigger tasks such as:

  • 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

Policy-scoped custom scheduled events are configured through the Custom Events configuration object found at the top level of the ConfigurationRef.

CustomEventRef
required
type string

optional
schedule EventScheduleRef?
EventScheduleRef
required
anchor Enum policyStart | policyEnd | termStart | segmentStart

optional
alignment Enum? weekStart | monthStart | yearStart
cadence EventCadenceRef?
offset map<string,int>?
suppressOnStatuses Enum[]? pending | expired | cancelled | cancelPending | onRisk | delinquent | doNotRenew
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 schedules the event before the anchor date

  • cadence: (optional) defines the cadence between and max number of occurrences 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

Policy-scoped event schedules are created upon issuance of transactions that create a new term, such as new business or renewals, with the exception of segmentStart, which may also be scheduled upon issuance of a change or reinstatement transaction.

An events schedule is controlled 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: Creates a recurring event based on a given interval, including 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 scheduled, policy-scoped 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
    Response:ScheduledPolicyEvent[]
    Security Group:events   Permission:read
ScheduledPolicyEvent
required
policyLocator string
transactionLocator string
triggerState Enum BLOCKED | COMPLETE | ERROR | NONE | NORMAL | PAUSED
customEventId 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 sent 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

Tenant Events

Tenant-scoped custom events are not tied to any specific policy and support tenant-wide activity, accommodating use cases such as:

  • Running nightly data synchronization

  • Triggering tenant-wide notifications

  • Initiating periodic administrative tasks

Unlike policy-scoped events, tenant-scoped events can be manually triggered (scheduled) by an API request.

Configuration

Tenant-scoped custom scheduled events are configured through the TenantCustomEventRef configuration object found at the top level of the ConfigurationRef.

TenantCustomEventRef
required
isPersisted boolean
type string

optional
schedule TenantEventScheduleRef?

  • type must begin with the prefix custom in order to prevent conflicts with internal system events.

  • isPersisted defaults to true and determines whether the event record is stored in the database for later retrieval through the fetch event API endpoints (e.g. single, list)

TenantEventScheduleRef
optional
alignment Enum? weekStart | monthStart | yearStart
cadence EventCadenceRef?
offset map<string,int>?
EventCadenceRef
required
durationBasis Enum years | months | weeks | days | hours
intervalDuration int

optional
limit int?

Options

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

  • offset: (optional) map of durationBasis and duration quantity (e.g. { "months" : 1 }) - Note: A negative offset schedules the event before the anchor date

  • cadence: (required) defines the cadence between and max number of occurrences to be scheduled

Behavior

  • alignment: Adjusts the base to the start of a week/month/year relative to the anchor selected.

  • offset: Shifts event date relative to the anchor.

  • cadence: Creates a recurring event based on a given interval, including a limit on how many times it should recur, if desired. If omitted, the event will only occur once.

API

You can manually schedule a tenant-scoped custom event using the Schedule Tenant Events API endpoint, supporting the ability to trigger events on-demand from external systems or for ad-hoc administrative tasks.

Use the Fetch Scheduled Tenant Events API endpoint to retrieve the next scheduled instance of each custom tenant-scoped event.

Fetch Scheduled Tenant Events
fetchScheduledTenantEvents
GET /event/{tenantLocator}/events/schedules/tenant
    Request Parameters:
    NamePositionTypeRequired
    tenantLocatorpathuuidrequired
    Response:ScheduledTenantEvent[]
    Security Group:events   Permission:read
ScheduledTenantEvent
required
triggerState Enum BLOCKED | COMPLETE | ERROR | NONE | NORMAL | PAUSED
customEventId string
scheduledEventId string

optional
nextEventTime datetime?

Sample Request

{
  "requests": [
    {
      "eventTypeId": "custom.tenant.data_sync",
      "eventTime": "2023-10-27T10:00:00Z",
      "scheduleId": "manual-sync-001",
      "data": {
        "sourceSystem": "externalCRM",
        "forceFullSync": true
      }
    }
  ]
}

Note that the optional data payload allows you to pass information to your event logic.

Examples

Example #1 - Manually-Triggered Data Sync Event

Suppose a developer needs to create an event that can be called by an external system to initiate a data synchronization process for the tenant.

Here’s an example configuration:

"tenantCustomEvents": {
  "tenantDataSync": {
    "type": "custom.tenant.data_sync",
    "isPersisted": false
  }
}

No schedule is configured since this event will be manually triggered through the Schedule Tenant Events API endpoint.

Example #2 - Scheduled Monthly Report Generation

For a tenant-wide report to be generated on the first of each month, a developer could configure a tenant event like this:

"tenantCustomEvents": {
  "monthlyReportGenerator": {
    "type": "scheduled.tenant.monthly_report",
    "schedule": {
      "alignment": "monthStart",
      "cadence": {
        "intervalDuration": 1,
        "durationBasis": "months"
      }
    }
  }
}

An event listener could be deployed to initiate report production logic.