Skip to navigation
API ReferenceGroups

Create a group

Creates a group for the specified employer.

Authentication

AuthorizationBearer
Authorization header using the Bearer scheme

Headers

X-Platform-IdstringOptional

The target platform id. Required only when calling with a dashboard (WorkOS AuthKit) access token instead of a platform API key — the token carries no platform claim, so the caller must say which platform it means. Ignored for platform API key / embed session token callers.

Request

This endpoint expects an object.
employer_idstringRequiredformat: "er_.+"

Identifier of the employer to create the group for. Prefixed with er_.

namestringRequired

Human-readable name of the group.

descriptionstring or nullOptional

Short description of the purpose or scope of the group.

Response

OK
idstringformat: "gr_.+"

Unique identifier for the group. Prefixed with gr_.

namestring

Human-readable name of the group.

statusenum

Current lifecycle state of the group, indicating its current progress. Possible values are:

  • pending: Group is being configured, may require a quote_intent or a setup_intent to be ready.
  • ready: Setup is complete, regardless of policy start dates employees could start enrolling into policies.
  • archived: Archived as the group is no longer active or in use for any reason. Employees can no longer be added to the group.
Allowed values:
group_typeenum

Indicates how policies are organized for this group.

  • single: exactly one policy is associated to the group.
  • bundled: multiple policies are bundled under the group.
  • undefined: type not yet determined or not applicable.
Allowed values:
enrolment_typeenum

Indicates how employees are enrolled into the group.

  • manual: employees must be enrolled through an API.
  • automatic: employees are enrolled automatically upon being created with the Employer.
Allowed values:
employer_idstringformat: "er_.+"

Identifier for the employer that owns this group. Prefixed with er_.

group_policy_idslist of strings
Group policy unique identifiers associated with this group.
group_quote_intent_idslist of strings
Group quote intent unique identifiers associated with this group.
group_policy_intent_idslist of strings
Group policy intent unique identifiers associated with this group.
descriptionstring or nullOptional

Short description of the purpose or scope of the group.

objectstringOptionalRead-only
The object type

Errors

400
Bad Request Error
404
Not Found Error