API ReferenceGroups

Add an employee to a group

Adds an existing employee to a group. The employee must belong to the same employer as the group. If there is a group_policy associated with the group, a corresponding enrolment_intent will be created for the employee.

Authentication

AuthorizationBearer
Authorization header using the Bearer scheme

Path parameters

group_idstringRequiredformat: "gr_.+"

Headers

Idempotency-KeystringOptional

Unique key to ensure idempotent requests. If the same key is used for multiple identical & successful requests, the same response will be returned. Read more here

Request

This endpoint expects an object.
employee_idstringRequiredformat: "ee_.+"
Employee Id
create_enrolment_intentsboolean or nullOptional

Controls whether enrolment intents are automatically created for the employee. Defaults to true for hosted platforms. When true on a hosted platform, the response includes an enrolment_intent_id. For non-hosted platforms, the enrolment_intent_id is not included in the response, subscribe to the enrolment_intent.processing webhook to be notified when the enrolment intent is created.

policy_configurationobjectOptional

Policy configuration for the employee in this group. Leave null to use group defaults.

Response

OK
idstringformat: "ee_.+"
Unique identifier for the employee.
group_idstringformat: "gr_.+"
Unique identifier for the group.
policieslist of objects
List of policies associated with the employee in this group.
enrolmentslist of objects
List of enrolments associated with the employee in this group.
eligibility_statusenum

Eligibility status for the employee in this group. Pending = no eligibility check performed (no group policy), Eligible = employee meets provider’s eligibility criteria, Ineligible = employee does not meet eligibility criteria (e.g., age restrictions).

Allowed values:
enrolment_statusenum
Enrolment status for the employee in this group. Derived from policy and enrolment intent statuses.
scheduled_group_transitionslist of objects
List of scheduled group transitions for the employee. Only includes pending transitions.
objectstringRead-only
The object type
desired_policy_start_datedate or null

The desired date for the employee’s policy to start. This date is not guaranteed to be honored by the insurance provider and may be adjusted based on provider-specific rules and requirements.

enrolment_datedate or null
The date on which the employee agreed to enrol into the group's policies. This date may be used by some insurance providers to determine the policy start date.

Errors

400
Bad Request Error
404
Not Found Error