# User Groups

The Group Management API adheres to the [SCIM 2.0](https://scim.cloud/) protocol ***unless otherwise stated***, and provides management and provisioning of Groups and its members (Users) within a Program. Managing Groups requires that the acting User have a role of Program Manager or Administrator, and Group read and/or write access. {% admonition type="info" %}<b>User groups are SCIM groups only. Currently, this API does not support creating <a href="https://support.firstup.io/hc/en-us/articles/4412604456983-Overview-How-to-Use-Audiences"> audiences </a>.</b>{% /admonition %}


## Returns a list of Groups

 - [GET /scim/v2/Groups](https://developers.firstup.io/endpoints/openapi/user-groups/listgroups.md): Returns a list of all accessible Groups in the acting User's Program.

## Creates a Group

 - [POST /scim/v2/Groups](https://developers.firstup.io/endpoints/openapi/user-groups/creategroup.md): Creates and provisions a new Group of Users. The request should include any properties to be set on
the Group. Any property not provided would leave the value blank or use defaults.

The list of members could be empty or not present. Members are referenced with the identifierField,
by either:
- email
- id
- userName (the default if no identifierField is included)

This operation is asynchronous, the response will not include the list of members.

A JobId will be in the response's meta, to be able to get a JobReport (see the ad hoc endpoint below).

Indexing a Group's Users can take some time.

## Returns the details of the given Group, including its members

 - [GET /scim/v2/Groups/{group_id}](https://developers.firstup.io/endpoints/openapi/user-groups/detailgroup.md): Returns the group specified by the group_id. Groups are defined by the SCIM specification.

## Updates a Group

 - [PATCH /scim/v2/Groups/{group_id}](https://developers.firstup.io/endpoints/openapi/user-groups/patchgroup.md): Update an audience in the Program with partial changes using
SCIM PatchOp.

Add or remove selected fields of the audience.

The list of members in the Group is referenced using the identifierField, by either:
- email
- id
- userName (the default if no identifierField is included)

All operations are supported: add, remove, and replace.
{% admonition type="info" %}A replace replaces all the members of the Group by the value sent
(a full replace).{% /admonition %}
This operation is asynchronous, the response will not include the list of members.
A JobId will be in the response's meta, to be able to get a JobReport (see  GET /v2/Groups/JobReport/{jobId}.
{% admonition type="info" %} We advise refering to our  SCIM patching documentation before executing.
Refer to our  error responses documentation for detail on errors.{% /admonition %}

## Deletes a Group

 - [DELETE /scim/v2/Groups/{group_id}](https://developers.firstup.io/endpoints/openapi/user-groups/deletegroup.md): Delete an audience in the Program

## Updates a Group

 - [PUT /scim/v2/Groups/{group_id}](https://developers.firstup.io/endpoints/openapi/user-groups/updategroup.md): Updates and provisions an existing Group of Users. The request should include any properties to be set on
the Group. Any property not provided would leave the value blank or use defaults.

The list of members could be empty or not present. Members are referenced with the identifierField,
by either:
- email
- id
- userName (the default if no identifierField is included)

This operation is asynchronous, the response will not include the list of members.

A JobId will be in the response's meta, to be able to get a JobReport ( GET /v2/Groups/JobReport/{jobId}).

Indexing a Group's Users can take some time.

## Returns details on asynchronous jobs to modify a Group's members

 - [GET /v2/Groups/JobReport/{jobId}](https://developers.firstup.io/endpoints/openapi/user-groups/groupasyncjobreport.md): The calls to the POST, PUT or PATCH Groups Managements endpoints trigger a series of asynchronous jobs to create or update the list of the Group's members.

As these tasks are asynchronous, those API calls do not respond with the final list of the Group's members, but an unique Job identifier to inquire about the task.

This endpoint takes the jobId identifier, and returns details about the asynchronous job's execution.

The job could have already finished or still be running, and the response could include details on the number of members added, removed, processed, and error conditions (if any).