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.

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 for API ref.)

Resources

• To check which identifier to use, look here for our users schema.
• To check your users setup, look here for docs guidance

Endpoint

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

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 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) 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.

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

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 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.