# Groups

The data required for the group and the group's subscribers is broken down in the [Groups](https://ideonapi.gitbook.io/enrollment/implementation-resources/mapping-guides/groups) mapping guide.

In order to load the group:

1. [Formulate the Request](#formulate-the-request)
2. [Send Request / Receive Response](#send-request-receive-response)
3. [Check the Status](#check-the-status)

## Formulate the Request

The Group object tells Ideon about the company that is being transferred over for management.

#### Group Request Body:

{% code title="POST /groups" %}

```json
{
    "group": {
        "external_identifier": "Group1",
        "employer": {
            "organization_name": "An Interesting Company",
            "fein": "222222222",
            "established_date": "1999-08-13",
            "employer_type": "private_sector"
        },
        "primary_location": {
            "external_identifier": "Location1",
            "type": "physical",
            "employer_address": {
                "address_line_1": "30 W Live Oak Ave",
                "city": "Defuniak Springs",
                "state": "FL",
                "zip": "32435",
                "fips_county_code": "12131"
            }
        }
    }
}
```

{% endcode %}

## Send Request / Receive Response

The request is sent to Ideon using a [POST to the /groups](https://app.swaggerhub.com/apis/VericredEnrollments/Enrollments/0.3.0#/info) endpoint. 

Ideon will provide one of two responses to the requestor. 

* The first option is that the request was received successfully and the group was created on our system: `201 - Resource Created Successfully`. 
* The second option is that syntax and semantic errors exist: i.e. `422 - Unprocessable Entity`. This includes the violation of carrier specific business rules. 

### Success

If the request passes validation, the requestor will be informed of the successful receipt, and provided a copy of the group. 

In the response body the requestor will find UUIDs associated with resources that are used to manage subscriber and dependent enrollments: `group.id`, `group.primary_location.id`, and `group.secondary_locations.id`.

Ideon will process the request with the carrier after the full data load is complete. The requestor should [check the status](#check-the-status) of the request to determine if the carrier has accepted or rejected the enrollment.

#### Group Response Body:

```json
{
    "group":
    {
        "external_identifier": "Group1",
        "id": "f507a6f2-cb43-48a4-9064-e279f564623d",
        ...
        "primary_location": {
            "external_identifier": "Location1",
            "id": "eb15f823-826a-4265-8ca5-22c2c61c1808",
            ...
        },
        "secondary_locations": [{
            "external_identifier": "Location2",
            "id": "eb15f823-826a-4265-8ca5-22c2c61c1808",
            ...
        }]
    }
}
```

### Errors

If errors are detected in the request body based on the expectations of the carrier receiving the enrollment then a response indicating the errors will be returned.

#### Error Response Body:

```json
{
    "errors": [{
        "error_type": "invalid_request.parameter_required",
        "message": "The parameter is missing and is required",
        "parameter": "group.employer.primary_location.address_line_1"
    }]
}
```

## Check the Status

A request can be made via a [GET /groups/{id}](https://app.swaggerhub.com/apis/VericredEnrollments/Enrollments/0.3.0#/Groups/Retrieve%20a%20Group) to retrieve the status of the group. Once a group is received, and prior to transmission, the status of the group and subscribers will be `pending`. Ideon will transmit the group to the carrier in the carriers proprietary format. After transmission to the carrier, the group's `status` will be `submitted`. After submission a group can move to one of three states: `pending`, `synced`, or `errors`.

Qualifying Life Events also have a status with a similar function, so that the delivery to each carrier can be verified independently.

### Synced

The status will be marked as `synced` if all `pending` and `submitted` member transactions are successfully received by the carrier. 

#### Group Status Response Body:

```json
{
    "status": "synced",
    "status_datetime": "2019-01-25T23:20:50Z",
    "group": {...}
}
```

### Errors

The status of the group will be marked `errors` when a carrier provides errors based on the processing of the group enrollment process. Errors indicate action needs to be taken by the platform to update enrollment information at the group or member level. Errors reported on the group are a summary of errors for all members as well as specific to the group. Common group errors include:

* Account structure (plan offerings, classes, departments, etc.) doesn't match carrier expectations
* Carrier is reporting a member missing from the group
* A data element like salary or first name does not match the carrier's provided value

#### Group Status Response Body:

```json
{
    "status": "errors",
    "status_datetime": "2019-01-25T23:20:50Z",
    "errors": [{
        "error_type": "carrier_error",
        "message": "Invalid plan and subgroup combination",
        "parameter": "group.member{}.coverage"
    }],
    "group": {...}
}
```

### Pending

A group is `pending` after it is initially loaded. The group will also be `pending` when the state of any member is `pending.`

#### Group Status Response Body:

```json
{
    "status": "pending",
    "status_datetime": "2019-01-25T23:20:50Z",
    "group": {...}
}
```