Delinquency plan workflows

Every delinquency plan is associated with one or more delinquency reasons and one or more workflows.

  • A delinquency reason is a reason the policy or account is considered delinquent. For example:
    • A policy could become delinquent because it is "past due", meaning that some payment has been received, but the full amount due as of today has not been received.
    • A policy could become delinquent because it is "not taken", meaning the insured opted to not take the policy and never sent any payment.
  • A delinquency workflow is a set of events to execute to address a delinquency.

Delinquency plans associate reasons with workflow. For example, in the base configuration "Standard Delinquency Plan":

  • When a delinquency occurs for a reason of past due, the "Standard Delinquency" workflow is used.
  • When a delinquency occurs for a reason of not taken, the "Cancel Immediately" workflow is used.

The DelinquencyPlanReason resource

Information about delinquency plan reasons is managed by the DelinquencyPlanReason resource. Every DelinquencyPlanReason resource has the following attributes:

  • delinquencyReason - A code from the DelinquencyReason typelist
  • workflowType - A code from the Workflow typelist identifying the associated workflow type

For example, one of the delinquency reasons associated with the base configuration's "Standard Delinquency Plan" is Past Due. It is associated with the Standard Delinquency workflow type. The corresponding DelinquencyPlanReason resource looks like this:

{
    "attributes": {
        "delinquencyReason": {
            "code": "PastDue",
            "name": "Past Due"
        },
        "id": "bc:S44YUDkjCADvyTOFPU9ZY",
        "workflowType": {
            "code": "StdDelinquency",
            "name": "Standard Delinquency"
        }
    }
}

The DelinquencyPlanEvent resource

A delinquency plan workflow usually consists of a series of events. Each event is managed by a DelinquencyPlanEvent resource. Every DelinquencyPlanEvent resource has the following attributes:

  • eventName - The event name
    • This must be a code from the DelinquencyEventName typelist
  • triggerBasis - The basis for the triggering of this event (such as the delinquency's Inception Date)
    • This must be a code from the DelinquencyTriggerBasis typelist
  • offsetDays - The target date of the event, in terms of the number of days before or after the trigger basis date
  • automatic - A flag indicating whether the workflow can advance to the event automatically or if approval is required
  • relativeOrder - An optional integer used to specify the order of execution when multiple events have the same trigger basis and offset days

For example, in the base configuration's "Standard Delinquency Plan", the Past Due reason is associated with the Standard Delinquency workflow type. The first event for this workflow type is "Dunning Letter 1", which triggers automatically 0 days after the delinquency inception date. In the "Standard Delinquency Plan", the DelinquencyPlanReason resource corresponding to "Dunning Letter 1" looks like this:

"attributes": {
    "automatic": true,
    "eventName": {
        "code": "DunningLetter1",
        "name": "Dunning Letter 1"
    },
    "id": "bc:SWsCS5Rm-ml617OwUPINi",
    "offsetDays": 0,
    "relativeOrder": 0,
    "triggerBasis": {
        "code": "Inception",
        "name": "Inception Date"
    }
}

Restrictions and limitations

You can create and modify a delinquency plan reason or event only when the delinquency plan is not in use.

For a given delinquency plan, each reason and each event must be unique. You cannot have a delinquency plan with two or more identical reasons, or two or more identical events.

Querying for reasons and events

Use the following endpoints to query for delinquency plan reasons and events:

Endpoint Description
GET admin/v1/delinquency-plans/{id}/reasons Returns all reasons for the given delinquency plan
GET admin/v1/delinquency-plans/{id}/reasons/{rid} Returns the given reason for the given delinquency plan
GET admin/v1/delinquency-plans/{id}/reasons/{reasonId}/events For the given delinquency plan, returns all events in the workflow for the given reason
GET admin/v1/delinquency-plans/{id}/reasons/{reasonId}/events/{eventId} For the given delinquency plan, returns the given event in the workflow for the given reason

For example, the following call returns all reasons for the base configuration's "Standard Delinquency Plan" (bc:202). For the sake of clarity, only the first two reasons are shown.

GET /admin/v1/delinquency-plans/bc:202/reasons

{
    "count": 3,
    "data": [
        {
            "attributes": {
                "delinquencyReason": {
                    "code": "NotTaken",
                    "name": "Not Taken"
                },
                "id": "bc:S9ruPKWuQFg_q8YM-p8HR",
                "workflowType": {
                    "code": "CancelImmediately",
                    "name": "Cancel Immediately"
                }
            }
        },
        {
            "attributes": {
                "delinquencyReason": {
                    "code": "PastDue",
                    "name": "Past Due"
                },
                "id": "bc:S44YUDkjCADvyTOFPU9ZY",
                "workflowType": {
                    "code": "StdDelinquency",
                    "name": "Standard Delinquency"
                }
            }
        },
        ...

The following call returns all events for the Standard Delinquency reason in the base configuration's "Standard Delinquency Plan" (bc:202). For the sake of clarity, only the first two events are shown.

{
    "count": 7,
    "data": [
        {
            "attributes": {
                "automatic": false,
                "eventName": {
                    "code": "Collections",
                    "name": "Collections"
                },
                "id": "bc:SYqYgo3X991EELnynjjcj",
                "offsetDays": 45,
                "triggerBasis": {
                    "code": "Inception",
                    "name": "Inception Date"
                }
            }
        },
        {
            "attributes": {
                "automatic": true,
                "eventName": {
                    "code": "DunningLetter1",
                    "name": "Dunning Letter 1"
                },
                "id": "bc:SWsCS5Rm-ml617OwUPINi",
                "offsetDays": 0,
                "relativeOrder": 0,
                "triggerBasis": {
                    "code": "Inception",
                    "name": "Inception Date"
                }
            }
        },
        ...

Creating reasons and events

Use the following endpoints to create delinquency plan reasons and events:

Endpoint Description
POST admin/v1/delinquency-plans/{id}/reasons Add a reason to the given delinquency plan
POST admin/v1/delinquency-plans/{id}/reasons/{reasonId}/events For the given delinquency plan, add an event to the given reason's workflow

When adding a reason to a delinquency plan, you must specify:

  • delinquencyReason
  • workflowType

For example, the following request adds a Past Due reason, associated with the Standard Delinquency workflow, to delinquency plan bc:1221.

POST /admin/v1/delinquency-plans/bc:1221/reasons

{
  "data": {
    "attributes": {
        "delinquencyReason": {
            "code": "PastDue"
        },
        "workflowType": {
            "code": "StdDelinquency"
        }
    }
  }
}

When adding an event to a delinquency plan reason's workflow, you must specify:

  • automatic
  • eventName
  • triggerBasis

You do not have to specify offsetDays. However, there is no default value for this field. If you omit it from the POST, the attribute is set to NULL. BillingCenter will treat a NULL offset as if it were a 0, except in the case where there is a tie between a 0-offset event and a NULL-offset event. In this case, the 0-offset event wins the tie.

For example, the following request add a "Dunning Letter 1" event to the Past Due reason (bc:999) of delinquency plan bc:1221. The event is automatic, with a trigger basis of Inception Date and an offset of 7 days.

POST /admin/v1/delinquency-plans/bc:1221/reasons/bc:999/events

{
  "data": {
    "attributes": {
        "automatic": true,
        "eventName": {
            "code": "DunningLetter1"
        },
        "triggerBasis": {
            "code": "Inception"
        },
        "offsetDays": 7
    }
  }
}

Modifying reasons and events

Use the following endpoints to PATCH delinquency plan reasons and events:

Endpoint Description
PATCH admin/v1/delinquency-plans/{id}/reasons/{rid} Modifies the given reason in the given delinquency plan
PATCH admin/v1/delinquency-plans/{id}/reasons/{reasonId}/events/{eventId} For the given delinquency plan, modifies the given event in the given reason's workflow

You can PATCH delinquency plan reasons and events only for delinquency plans that are not in use.

For example, the following requests modify the reason and event created in the previous examples.

PATCH /admin/v1/delinquency-plans/bc:1221/reasons/bc:999

{
  "data": {
    "attributes": {
        "delinquencyReason": {
            "code": "NotTaken"
        }
    }
  }
}
PATCH /admin/v1/delinquency-plans/bc:1221/reasons/bc:999/events/bc:1001

{
  "data": {
    "attributes": {
        "offsetDays": 10
    }
  }
}

Use the following endpoints to delete delinquency plan reasons and events:

Endpoint Description
PATCH admin/v1/delinquency-plans/{id}/reasons/{rid} Deletes the given reason in the given delinquency plan
PATCH admin/v1/delinquency-plans/{id}/reasons/{reasonId}/events/{eventId} For the given delinquency plan, deletes the given event in the given reason's workflow

You can delete delinquency plan reasons and events only for delinquency plans that are not in use.

For example, the following requests deletes the reason and event created in the previous examples.

DELETE /admin/v1/delinquency-plans/bc:1221/reasons/bc:999

<no request body>
DELETE /admin/v1/delinquency-plans/bc:1221/reasons/bc:999/events/bc:1001

<no request body>