Skip to content
Vitable Docs Vitable Docs Vitable Docs
Get started
API Reference
Employees
Enrollments

Submit benefit elections

employees.enrollments.submit_elections(stremployee_id, EnrollmentSubmitElectionsParams**kwargs) -> EnrollmentSubmitElectionsResponse
post/v1/employees/{employee_id}/enrollments/elect

Completes the benefits election process for all pending enrollments for an employee. Processes enrollment decisions: which benefits to enroll/waive, plan selections, and dependent coverage. Pending enrollments transition to enrolled or waived status based on elections.

ParametersExpand Collapse
employee_id: str
elections: Iterable[Election]

List of enrollment elections

decision: Literal["Enrolled", "Waived"]
  • Enrolled - Enrolled
  • Waived - Waived
Accepts one of the following:
"Enrolled"
"Waived"
enrollment_id: str

ID of the enrollment (enrl_*)

coverage_tier: Optional[CoverageTier]
  • Unspecified - Unspecified
  • EE - Ee
  • ES - Es
  • EC - Ec
  • EF - Ef
Accepts one of the following:
"Unspecified"
"EE"
"ES"
"EC"
"EF"
dependent_ids: Optional[SequenceNotStr[str]]

List of dependent IDs to include in coverage (dpnd_*)

selected_plan_id: Optional[str]

ID of the selected plan (plan_*). Required if decision is 'Enrolled'

ReturnsExpand Collapse
EnrollmentSubmitElectionsResponse = List[Enrollment]
id: str

Unique enrollment identifier with 'enrl_' prefix

benefit_product_id: str

ID of the benefit product (bprd_*)

created_at: datetime

Timestamp when the enrollment was created

formatdate-time
employee_id: str

ID of the employee (empl_*)

plan_year_id: str

ID of the plan year (plyr_*)

status: EnrollmentStatus
  • pending - Pending
  • enrolled - Enrolled
  • waived - Waived
  • inactive - Inactive
Accepts one of the following:
"pending"
"enrolled"
"waived"
"inactive"
updated_at: datetime

Timestamp when the enrollment was last updated

formatdate-time
coverage_end_date: Optional[date]

Date when coverage ends

formatdate
coverage_start_date: Optional[date]

Date when coverage begins

formatdate
coverage_tier: Optional[CoverageTier]
  • Unspecified - Unspecified
  • EE - Ee
  • ES - Es
  • EC - Ec
  • EF - Ef
Accepts one of the following:
"Unspecified"
"EE"
"ES"
"EC"
"EF"
decision: Optional[str]

Employee's election decision: 'enrolled' (accepted) or 'waived' (declined)

employee_contribution_cents: Optional[int]

Employee's monthly contribution in cents

employer_contribution_cents: Optional[int]

Employer's monthly contribution in cents

enrolled_dependents: Optional[List[EnrolledDependent]]

List of dependents included in this enrollment

dependent_id: str

ID of the dependent (dpnd_*)

first_name: str

Dependent's first name

last_name: str

Dependent's last name

relationship: Relationship
  • Spouse - Spouse
  • Child - Child
Accepts one of the following:
"Spouse"
"Child"
selected_plan_id: Optional[str]

ID of the selected plan (plan_*), if enrolled

selected_plan_name: Optional[str]

Name of the selected plan

Submit benefit elections
from vitable_connect_api import VitableConnectAPI

client = VitableConnectAPI(
    api_key="My API Key",
)
enrollments = client.employees.enrollments.submit_elections(
    employee_id="empl_abc123def456",
    elections=[{
        "decision": "Enrolled",
        "enrollment_id": "enrollment_id",
    }],
)
print(enrollments)
[
  {
    "id": "id",
    "benefit_product_id": "benefit_product_id",
    "created_at": "2019-12-27T18:11:19.117Z",
    "employee_id": "employee_id",
    "plan_year_id": "plan_year_id",
    "status": "pending",
    "updated_at": "2019-12-27T18:11:19.117Z",
    "coverage_end_date": "2019-12-27",
    "coverage_start_date": "2019-12-27",
    "coverage_tier": "Unspecified",
    "decision": "decision",
    "employee_contribution_cents": 0,
    "employer_contribution_cents": 0,
    "enrolled_dependents": [
      {
        "dependent_id": "dependent_id",
        "first_name": "first_name",
        "last_name": "last_name",
        "relationship": "Spouse"
      }
    ],
    "selected_plan_id": "selected_plan_id",
    "selected_plan_name": "selected_plan_name"
  }
]
Returns Examples
[
  {
    "id": "id",
    "benefit_product_id": "benefit_product_id",
    "created_at": "2019-12-27T18:11:19.117Z",
    "employee_id": "employee_id",
    "plan_year_id": "plan_year_id",
    "status": "pending",
    "updated_at": "2019-12-27T18:11:19.117Z",
    "coverage_end_date": "2019-12-27",
    "coverage_start_date": "2019-12-27",
    "coverage_tier": "Unspecified",
    "decision": "decision",
    "employee_contribution_cents": 0,
    "employer_contribution_cents": 0,
    "enrolled_dependents": [
      {
        "dependent_id": "dependent_id",
        "first_name": "first_name",
        "last_name": "last_name",
        "relationship": "Spouse"
      }
    ],
    "selected_plan_id": "selected_plan_id",
    "selected_plan_name": "selected_plan_name"
  }
]