# Create and Update an Audience

The audiences API (user groups) allows the provisioning and management of Firstup audiences using SCIM.

The following use cases are examples of using our audience endpoints in a UI setting with a front-end user, and for back-end functions.

Whenever you modify group membership using POST, PUT, or PATCH, those operations are processed asynchronously. Rather than waiting for the full job to complete, the API returns immediately with a jobId. You can then use this jobId to:

* Check whether the job is still running or has finished.
* Get counts of members added, removed, or skipped.
* See error messages or skipped reasons (e.g., “already a member”).


See the [GET /v2/Groups/JobReport/{jobId}](/doorman/openapi/user-groups/groupasyncjobreport) API Reference for more details.

## Create a Basic Audience

If you already have a list of known users for your audience, you can create the audience with a single endpoint.

**Before you start**

Make sure you have one of the following user attributes for your users:

* The user `email`
* The user `id`
* The user `userName` (a backend function for user identification. Look [here](/doorman/openapi/user-management/createuser#user-management/createuser/t=request&path=username) for API ref.)


**Resources**

* To check which identifier to use, look [here](/doorman/openapi/user-management/createuser) for our users schema.
* To check your users setup, look [here](/usermanagementapi/user-managing#get-a-list-of-users) for docs guidance


**Endpoint**

POST SCIM/v2/groups
Build your post request:

1. Give your audience a name, example **Sales Dept**.
2. Give your audience a description, example **Group of Sales department employees**.
3. Give the user identifier value, example `userName`.
4. Give an external ID if necessary. For example, you may want this audience to integrate with another application, therefore an external ID can be used as an identifier.
5. Give the list of your users who will belong to this audience in the `members` object.


Note: This list is of each user's identifier (in our example their `userName`). An example of what this looks like: `"members" [ { "value": "username3" }, { "value": "username4" }, { "value": "username33" } ]`

**Example request**


```
{
  "displayName": "Sales Dept",
  "description": "Group of Sales department employees",
  "SocialChorus:1.0:Group": {
    "identifierField": "userName"
  },
  "externalId": "1234qweasd567",
  "members": [
    {
      "value": "username3"
    },
    {
      "value": "username4"
    },
    {
      "value": "username33"
    }
  ]
}
```

## Create an Audience by Role

Whilst you can't create an audience by a user attribute (example role), or create a dynamic audience, you can get a list of users by role, and then pass that list into your `POST` body request as a workarond flow.

**Workflow Overview**

1. Use the `GET /scim/v2/Users` endpoint with a SCIM filter to find all users assigned a specific role.
2. Copy each user's `userName` (the identifier - alternatively `Id` or `email`) and format your user list.
3. Use `POST /scim/v2/Groups` to create a static SCIM audience, supplying the list of users.


**Endpoints**

GET /SCIM/v2/users
POST /SCIM/v2/groups
### Step 1: GET Users by Role

Use `GET SCIM/v2/users` to fund users with a given role.


```
GET /scim/v2/Users?filter=roles.value eq "publisher"
Authorization: Bearer <your_token>
Accept: application/scim+json
```

**Filter syntax:**

* `roles.value eq {role name}` is the correct SCIM syntax.
* Our example is publisher. You can replace this with any valid role e.g. `community_admin`, `member`, etc.
* You can use the `GET /scim/v2/roles` [endpoint](/doorman/openapi/user-roles/listroles) to get a list of available roles in your program.


**Example Response**


```
{
  "totalResults": 2,
  "Resources": [
    {
      "id": "54415729",
      "userName": "aaatest",
      "roles": [
        {
          "type": "role",
          "value": "publisher"
        }
      ]
    },
    {
      "id": "54415730",
      "userName": "bbatest",
      "roles": [
        {
          "type": "role",
          "value": "publisher"
        }
      ]
    }
  ]
}
```

### Step 2: Create a Static Audience

Copy your list of users from your `GET` request. Make sure:

Use an identifier to define your audience members. In our example, we use `userName`, but `id` or `email` are also supported.

**Example**


```
"SocialChorus:1.0:Group": {
    "identifierField": "userName"
```

The list of users is an array of objects.

**Example:**


```
"members": [
    { "value": "aaatest" },
    { "value": "bbatest" }
  ]
```

* Name the audience (`displayName` required), give an audience `description` (optional), assign an `externalId` (optional).
* Execute the `POST` request.


**Example**


```
POST /scim/v2/Groups
Authorization: Bearer <your_token>
Content-Type: application/json
Accept: application/scim+json
```

**Request body**


```
{
  "displayName": "Publisher Audience",
  "description": "Static group of all users with the 'publisher' role",
  "externalId": "publisher-static-001",
  "SocialChorus:1.0:Group": {
    "identifierField": "userName"
  },
  "members": [
    { "value": "aaatest" },
    { "value": "bbatest" }
  ]
}
```

* This creates a **static audience**. It will **not automatically update** if users are later added or removed from the role.
* You must repeat the query and update the group manually (e.g., using the `PATCH /scim/v2/Groups/{group_id}` [endpoint](/doorman/openapi/user-groups/patchgroup)) to keep it current (see the example below).
* Supported identifier fields are: `userName` (default), `id`, or `email`.


## Update a Static Audience by Role

Static audiences do not update automatically. So if new users are assigned the role you previously filtered on (e.g., `publisher`), you'll need to manually update the audience to include them.

There are two supported methods:

* PATCH (Recommended): Modify audience membership incrementally (add/remove users).
* PUT (Caution): Replaces the entire group, including metadata and all members.


In our example, we'll use the safer PATCH method. For further guidance on SCIM patching, refer to our [SCIM patching guidance page](/usermanagementapi/scim-patch-operations).

**Workflow Overview**

1. Use the `GET /scim/v2/Groups` endpoint to find the audience's ID (`group_Id`).
2. Use the `GET /scim/v2/Users` endpoint with a SCIM filter to find all users assigned a specific role.
3. Copy each new user's `userName` (the identifier - alternatively `Id` or `email`).
4. Use `PATCH /scim/v2/Groups` to update the static SCIM audience.


**Endpoints**

GET /SCIM/v2/groups
GET /SCIM/v2/users
PATCH /SCIM/v2/groups
### Step 1: Get the Audience

Get the audience that needs updating, using the `GET /scim/v2/Groups` endpoint to list audiences. If known, filter by your audience name.


```
GET /scim/v2/Groups?filter=displayName eq "Publisher Audience"
Authorization: Bearer <your_token>
Accept: application/scim+json
```

In the response, copy over the `group_Id`.

### Step 2: GET Users by Role

Use `GET SCIM/v2/users` to fund users with a given role.


```
GET /scim/v2/Users?filter=roles.value eq "publisher"
Authorization: Bearer <your_token>
Accept: application/scim+json
```

**Filter syntax:**

* `roles.value eq {role name}` is the correct SCIM syntax.
* Our example is publisher. You can replace this with any valid role e.g. `community_admin`, `member`, etc.
* You can use the `GET /scim/v2/roles` [endpoint](/doorman/openapi/user-roles/listroles) to get a list of available roles in your program.


**Example Response**


```
{
  "totalResults": 2,
  "Resources": [
    {
      "id": "54415729",
      "userName": "aaatest",
      "roles": [
        {
          "type": "role",
          "value": "publisher"
        }
      ]
    },
    {
      "id": "54415730",
      "userName": "bbatest",
      "roles": [
        {
          "type": "role",
          "value": "publisher"
        }
      ]
    }
  ]
}
```

### Step 3: Update Audience

Use the recommended PATCH method to update your audience by adding or removing members.

1. Add your group_id to the `PATCH` endpoint. Example: `PATCH /scim/v2/Groups/115`
2. Add a patch operation to the body request.
3. Add your new members into the `PATCH` operation object.
4. Execute the `PATCH`.


**Request body example**


```
{
  "schemas": ["urn:ietf:params:scim:api:messages:2.0:PatchOp"],
  "Operations": [
    {
      "op": "add",
      "path": "members",
      "value": [
        { "value": "newuser" }
      ]
    }
  ],
  "SocialChorus:1.0:Group": {
    "identifierField": "userName"
  }
}
```

You can also use `"op": "remove"` or `"replace"` depending on the update type.