Assign or Remove Groups

Add a user to one or more groups and/or remove them from one or more groups in a single call. Groups are referenced by name.

PUT

/api/public/users/{user_id}/actions/change_group

Headers

Key	Value
Content-Type	application/json
Authorization	Bearer <Account API Key>

Path Parameter

• user_id (required): The numeric id of the user. Use List Users or Get a User to look it up from an email address.

Request body

At least one of assign_group or remove_group must contain a group name.

Field	Type	Description
assign_group (optional)	Array of String	Names of groups to add the user to.
remove_group (optional)	Array of String	Names of groups to remove the user from. Pass ["*"] to remove the user from every group.

Group names must match existing groups in the account exactly, as shown under Admin Console → Users → Groups (see Grouping users). Names that do not match any group are reported in invalid_groups and the rest of the request is still processed.

{
    "assign_group": ["Sales", "Support"],
    "remove_group": ["Trial"]
}

Example cURL

Assign and remove groups:

curl --location --request PUT '<BUILDER_URL>/api/public/users/83/actions/change_group' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer XXXXXXXXXXXXXXXXXXXXXXXXX' \
--data-raw '{
    "assign_group": ["Sales", "Support"],
    "remove_group": ["Trial"]
}'

Remove the user from all groups:

curl --location --request PUT '<BUILDER_URL>/api/public/users/83/actions/change_group' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer XXXXXXXXXXXXXXXXXXXXXXXXX' \
--data-raw '{
    "remove_group": ["*"]
}'

Responses

Status Code	Description	Response
200	Request processed. Check invalid_groups and failed_groups in the body for entries that were not applied.	application/json
400	Both assign_group and remove_group are empty	application/json
401	Unauthorized	application/json
404	User not found in this account	application/json
500	Internal Server Error	application/json

Response fields

Field	Type	Description
user_id	String	The user id from the request.
assigned_to	Array of String	Group names the user was successfully added to.
removed_from	Array of String	Group names the user was successfully removed from. Contains "*" when the wildcard was used.
invalid_groups	Array of String	Group names that do not exist in the account.
failed_groups	Array of Integer	Ids of groups where the operation failed.

Sample response

200 : Success

{
    "user_id": "83",
    "assigned_to": ["Sales", "Support"],
    "removed_from": ["Trial"],
    "invalid_groups": [],
    "failed_groups": []
}

200 : One of the group names does not exist

{
    "user_id": "83",
    "assigned_to": ["Sales"],
    "removed_from": [],
    "invalid_groups": ["Suport"],
    "failed_groups": []
}

404 : User not found

{
    "error": 404,
    "message": "User not found.",
    "reason": ""
}