Skip to main content

Managing Life Events & Choice Elections

This guide demonstrates how external carrier and benefit platforms query active coverage, trigger qualified life events, and submit participant election choices.

Workflow Overview​

1. Query Current Coverage ──► GET  /v1/participants/{id}/enrollments
                                     │
2. Trigger Life Event     ──► POST /v1/participants/{id}/enrollment-events
                                     │
3. Submit Elections       ──► POST /v1/participants/{id}/enrollment-events/{eventId}/elections

1. Querying Active Enrollments​

To view a participant's existing benefits, coverage tier, and premium allocations, invoke GET /v1/participants/{participantId}/enrollments:

curl -X GET "https://api.development.aptiaone.com/v1/participants/22222222-2222-2222-2222-222222222222/enrollments" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -H "Accept: application/json"

Response (200 OK)​

{
  "participantId": "22222222-2222-2222-2222-222222222222",
  "tenantId": "tenant-001",
  "coverageYear": 2026,
  "totalParticipantPreTaxCost": 3000.00,
  "totalParticipantPostTaxCost": 0.00,
  "totalPlanSponsorCost": 9120.00,
  "elections": [
    {
      "planId": "a1234567-89ab-cdef-0123-456789abcdef",
      "planName": "Comprehensive Health PPO",
      "planType": "Medical",
      "choiceId": "b2345678-9abc-def0-1234-56789abcdef0",
      "choiceName": "Employee + Spouse",
      "choiceType": "ELECTED",
      "tierId": "c3456789-abcd-ef01-2345-6789abcdef01",
      "tierName": "Employee + Spouse",
      "effectiveDate": "2026-01-01",
      "employeeCostPerPayPeriod": 125.00,
      "employerCostPerPayPeriod": 380.00,
      "employeeAnnualPreTaxCost": 3000.00,
      "employeeAnnualPostTaxCost": 0.00,
      "employerAnnualCost": 9120.00
    }
  ]
}

2. Initiating a Qualified Enrollment Event​

When an employee experiences a qualifying status change (e.g., Marriage, Birth of Child, or Annual Open Enrollment), initiate an event window:

curl -X POST "https://api.development.aptiaone.com/v1/participants/22222222-2222-2222-2222-222222222222/enrollment-events" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "enrollmentEventId": "f203a91b-8c4d-5e6f-0a1b-2c3d4e5f6a7b",
    "effectiveDate": "2026-05-01"
  }'

Response (201 Created)​

{
  "id": "e102f91a-7b3c-4d5e-9f0a-1b2c3d4e5f6a",
  "participantId": "22222222-2222-2222-2222-222222222222",
  "enrollmentEventId": "f203a91b-8c4d-5e6f-0a1b-2c3d4e5f6a7b",
  "enrollmentEventName": "Birth / Adoption of Child",
  "effectiveDate": "2026-05-01",
  "status": "Pending",
  "createdAt": "2026-04-10T14:15:00Z"
}

3. Submitting Choice Elections​

Submit the participant's elected plan and choice for the open event:

curl -X POST "https://api.development.aptiaone.com/v1/participants/22222222-2222-2222-2222-222222222222/enrollment-events/e102f91a-7b3c-4d5e-9f0a-1b2c3d4e5f6a/elections" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "planId": "a1234567-89ab-cdef-0123-456789abcdef",
    "choiceId": "b2345678-9abc-def0-1234-56789abcdef1",
    "tierId": "c3456789-abcd-ef01-2345-6789abcdef02",
    "dependentElections": [
      {
        "dependentId": "33333333-3333-3333-3333-333333333333"
      }
    ],
    "preview": false
  }'

Response (200 OK)​

{
  "participantEnrollmentEventId": "e102f91a-7b3c-4d5e-9f0a-1b2c3d4e5f6a",
  "planId": "a1234567-89ab-cdef-0123-456789abcdef",
  "choiceId": "b2345678-9abc-def0-1234-56789abcdef1",
  "tierId": "c3456789-abcd-ef01-2345-6789abcdef02",
  "status": "Confirmed",
  "effectiveDate": "2026-05-01",
  "costs": {
    "employeeCostPerPayPeriod": 145.50,
    "employerCostPerPayPeriod": 420.00,
    "annualEmployeePreTaxCost": 3492.00,
    "annualEmployeePostTaxCost": 0.00,
    "annualPlanSponsorCost": 10080.00
  },
  "coveredDependents": [
    "33333333-3333-3333-3333-333333333333"
  ]
}

4. Handling Tier Validation Errors​

The Aptia One election rules engine validates dependent prerequisites. If a user selects a Family tier without sufficient registered dependents, the API returns an actionable 422 Unprocessable Entity RFC 7807 response:

{
  "type": "https://developer.aptiaone.com/errors/invalid-election",
  "title": "Invalid Choice Election",
  "status": 422,
  "detail": "Selected coverage tier requires at least one registered child dependent.",
  "instance": "/v1/participants/22222222-2222-2222-2222-222222222222/enrollment-events/e102f91a-7b3c-4d5e-9f0a-1b2c3d4e5f6a/elections",
  "errors": [
    {
      "field": "choiceId",
      "message": "Tier 'Family' requires at least one registered child dependent. Call POST /v1/participants/{id}/dependents first."
    }
  ]
}