Termination

Overview

The Termination API suite provides a robust, discovery-driven workflow for ending consumer benefit coverage. By combining impact analysis, synchronous execution, and asynchronous status tracking, these endpoints ensure that offboarding is both accurate and transparent. The API handles the complexities of plan bundles, dependent coverage loss, and prorated financial adjustments.

Key Features

• Discovery-First Design: A single call retrieves all valid plans, dates, and reason codes needed to build a request.
• Dry-Run Capability: PREVIEW mode allows for full impact analysis (including financial and dependent loss) without committing changes.
• Multi-Strategy Processing: Supports SYNCHRONOUS for immediate updates and ASYNCHRONOUS for high-volume background processing.
• Retry Safety: Mandatory Idempotency-Key headers protect against duplicate processing during network retries.

Scopes & Permissions

Endpoint Summary

Discovery: Get Termination Form Data

GET /termination/form-data?consumer_id={uuid}

Retrieves the “menu” of valid options.

• Returns: available_plans, available_bundles, valid_termination_dates, and reason_codes.
• Use when: Building the user interface for a termination form.

Execution: Create Termination Request

POST /termination/requests

The core engine for both simulation and execution.

• Modes: PREVIEW (Dry-run, returns 200) or EXECUTE (Commit, returns 201).
• Processing: SYNCHRONOUS (Wait for result) or ASYNCHRONOUS (Queue for background).
• Key Body Fields: selected_plan_ids, termination_date, reason_code, Idempotency-Key.

Tracking: Get Termination Request

GET /termination/requests/{request_id}

Retrieves the full state of a specific request.

• Status Values: PENDING, PROCESSING, COMPLETED, FAILED.
• Key Fields: confirmation_number, allocation_jobs_scheduled, errors.

Auditing: List Termination Requests

GET /termination/requests?consumer_id={uuid}

Returns a paginated list of all termination activity for the consumer.

Core Concepts

Impact Analysis (Preview Mode)

In PREVIEW mode, the API identifies:

• affected_dependents: family members losing coverage.
• financial_impact: Prorated refunds or premium adjustments.
• validation_errors: Reasons why a request might fail (for example, date out of range).

Idempotency POST requests require an Idempotency-Key (UUID). If the client experiences a timeout, it should retry the exact same request with the same key to ensure the termination isn’t processed twice.

Error Handling