For AI agents: a documentation index is available at the root level at /llms.txt and /llms-full.txt. Append /llms.txt to any URL for a page-level index, or .md for the markdown version of any page.
Get access
Getting Started Key Concepts Integration Types Core Components Embed Hosted API API Reference
  • API Reference
    • Contribution Reports
    • Events and Webhooks
      • GETList all groups
      • POSTCreate a group
      • GETRetrieve a group
      • PUTUpdate a group
      • GETList employees in a group
      • POSTAdd an employee to a group
      • POSTCheck employee eligibility for a group
    • API Errors
Get access
LogoLogo
API ReferenceGroups

Create a group

POST
/groups
POST
/groups
$curl -X POST https://test.api.kota.io/groups \
>     -H "Authorization: Bearer <apiKey>" \
>     -H "Content-Type: application/json" \
>     -d '{
>  "employer_id": "er_3b1333d87d9d4fd6ad83ba7f6b0e951a",
>  "name": "string"
>}'
1{
2  "id": "gr_3b1333d87d9d4fd6ad83ba7f6b0e951a",
3  "name": "string",
4  "status": "pending",
5  "group_type": "undefined",
6  "employer_id": "er_3b1333d87d9d4fd6ad83ba7f6b0e951a",
7  "group_policy_ids": [
8    "gp_3b1333d87d9d4fd6ad83ba7f6b0e951a"
9  ],
10  "group_quote_intent_ids": [
11    "gqi_3b1333d87d9d4fd6ad83ba7f6b0e951a"
12  ],
13  "group_policy_intent_ids": [
14    "gpi_3b1333d87d9d4fd6ad83ba7f6b0e951a"
15  ],
16  "object": "string"
17}

Creates a group for the specified employer.

Previous

List all groups

Next

Retrieve a group

Built with

Authentication

AuthorizationBearer
Authorization header using the Bearer scheme

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:
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 null

Short description of the purpose or scope of the group.

objectstringRead-only
The object type

Errors

400
Bad Request Error
404
Not Found Error