Skip to content

Rename, archive or move a subgroup, or change its roles

PATCH
/groups/{groupId}/subgroups/{subgroupId}
curl --request PATCH \
--url https://app.grouperly.com/api/v2/groups/example/subgroups/example \
--header 'Authorization: Bearer <token>' \
--header 'Content-Type: application/json' \
--data '{ "name": "example", "metadata": { "additionalProperty": "example" }, "archived": true, "roleIds": [ "example" ], "parentId": "example", "ledByRoleIds": [ "example" ] }'

Only the fields sent change. roleIds is for a subgroup made from roles: its people follow at once. Bringing back one whose type was removed is refused (type_removed): bring back the type (added in 2.33.0). parentId moves it inside another subgroup, taking the ones inside it along, or to the top with null; archiving one archives the ones inside it, and bringing it back brings them back; one inside an archived subgroup comes back with it (parent_archived) (2.36.0). metadata changes what its type keeps, a key at a time (2.40.0). ledByRoleIds chooses the roles held across the group that lead it: their holders are its leaders at once (2.57.0).

  • appToken
    https://api.grouperly.com/groups.write
groupId
required
string

The credential’s group

subgroupId
required
string

A subgroup in the group

Media typeapplication/json
object
name

Unique in its type

string
<= 60 characters
metadata

What its type keeps about it (a den’s rank), by key: each replaces its value, null removes it, and a key not sent stays. A type its vertical declares takes only its own keys, each of its kind (2.40.0)

object
<= 20 properties
key
additional properties
string | number | boolean | null
archived

True archives it: it keeps its history and takes no one new. false brings it back, unless its type was removed

boolean
roleIds

For a subgroup made from roles only: the roles it is made from now. Its people follow at once

Array<string>
<= 50 items
parentId

Move it inside this subgroup of the group (Subgroup.id), taking the ones inside it along, or to the top with null. At most three levels deep, never inside itself or one inside it (2.36.0)

string | null
<= 64 characters
ledByRoleIds

The roles held across the group whose holders lead it now (Role.id), replacing the ones that led it: whoever holds one is its LEADER while their term lasts, kept up to date. Not for a subgroup made from roles, nor an archived one; not a role held in a subgroup type (it leads its own: Role.leadsSubgroup) nor one for youth. Since 2.57.0

Array<string>
<= 20 items
Examplegenerated
{
"name": "example",
"metadata": {
"additionalProperty": "example"
},
"archived": true,
"roleIds": [
"example"
],
"parentId": "example",
"ledByRoleIds": [
"example"
]
}

OK

Media typeapplication/json
object
id
required
string
name
required

Unique in its type, e.g. “Wolf Den”

string
type
required
object
key
required

E.g. “den”

string
singular
required

E.g. “Den”

string
plural
required

E.g. “Dens”

string
metadata
required
One of:
object
archived
required

Kept for its history; takes no one new

boolean
memberCount
required
integer
leaderCount
required
integer
source
required

Picked: its leaders choose its people. roles: whoever holds roleIds, kept up to date (a PLC from Senior Patrol Leader and Patrol Leader); nobody puts people in it by hand, and its type is the hidden _roles (added in 2.33.0)

string
Allowed values: picked roles
roleIds
required

The roles a subgroup made from roles is made from (Role.id); empty for picked (added in 2.33.0)

Array<string>
parentId
required

The subgroup it sits inside (Subgroup.id), or null at the top: Popcorn Sale inside Fundraising. At most three levels. An audience, a shared document or a role held in a subgroup reaches the ones inside it too (added in 2.36.0)

string | null
ledByRoleIds
required

The roles held across the group that lead it (Role.id): whoever holds one is its LEADER while their term lasts, kept up to date, and stops being one after (unless an owner or admin made them a leader by hand). A role held in its type can lead its own as well (Role.leadsSubgroup). Empty for none, and always for a subgroup made from roles (added in 2.57.0)

Array<string>
customFields

The group’s custom fields on the subgroup that the caller may see (GET /field-definitions?entity=SUBGROUP), by key, null where one isn’t set: a key, whoever changes the group’s subgroups and the subgroup’s own leaders (and those of one it sits inside) see every one, anyone else those the whole group sees. On GET /subgroups and /subgroups/{subgroupId} (added in 2.40.0).

object
key
additional properties
string | number | boolean | null
Example
{
"source": "picked"
}
X-RateLimit-Limit
integer

Requests allowed per minute for this credential

X-RateLimit-Remaining
integer

Requests left in this window

X-RateLimit-Reset
integer

When the window ends (Unix seconds)

The body isn’t a JSON object of at most 16 KB, or a field is unknown, missing or malformed (invalid_body, with parameter), or roleIds for a subgroup whose people are picked, or a roleId isn’t one of the group’s roles, or it can’t move inside parentId (with parameter parentId), or ledByRoleIds names a role held in a subgroup type or one for youth, or the subgroup is archived (with parameter ledByRoleIds)

Media typeapplication/json
object
error
required
object
code
required

Stable and machine-readable: unauthorized, forbidden, insufficient_scope, key_owner_not_leader, app_not_installed, scope_not_allowed, app_suspended, rate_limited, not_found, invalid_parameter, invalid_body, invalid_profile, invalid_descriptor, no_profile, already_exists, not_a_member, wrong_holder, role_inactive, role_full, already_assigned, assignment_ended, version_not_current, nothing_to_pay, payments_not_ready, payload_too_large, first_party_only, terms_required, child_account, assistant_off, not_for_assistant, assistant_failed, not_a_draft, storage_full, made_from_roles, type_removed, invalid_reporting, led_by_role, unavailable, internal_error. New codes may be added.

string
message
required

For people; wording may change.

string
parameter

The query parameter (invalid_parameter) or body field (invalid_body, not_a_member, wrong_holder, invalid_reporting) at fault.

string
Examplegenerated
{
"error": {
"code": "example",
"message": "example",
"parameter": "example"
}
}
X-RateLimit-Limit
integer

Requests allowed per minute for this credential

X-RateLimit-Remaining
integer

Requests left in this window

X-RateLimit-Reset
integer

When the window ends (Unix seconds)

Missing, unknown, revoked or expired credential (unauthorized)

Media typeapplication/json
object
error
required
object
code
required

Stable and machine-readable: unauthorized, forbidden, insufficient_scope, key_owner_not_leader, app_not_installed, scope_not_allowed, app_suspended, rate_limited, not_found, invalid_parameter, invalid_body, invalid_profile, invalid_descriptor, no_profile, already_exists, not_a_member, wrong_holder, role_inactive, role_full, already_assigned, assignment_ended, version_not_current, nothing_to_pay, payments_not_ready, payload_too_large, first_party_only, terms_required, child_account, assistant_off, not_for_assistant, assistant_failed, not_a_draft, storage_full, made_from_roles, type_removed, invalid_reporting, led_by_role, unavailable, internal_error. New codes may be added.

string
message
required

For people; wording may change.

string
parameter

The query parameter (invalid_parameter) or body field (invalid_body, not_a_member, wrong_holder, invalid_reporting) at fault.

string
Examplegenerated
{
"error": {
"code": "example",
"message": "example",
"parameter": "example"
}
}

A key: wrong group (forbidden), missing scope (insufficient_scope), or its creator no longer leads the group (key_owner_not_leader). An app’s token: missing scope (insufficient_scope), the group hasn’t installed the app (app_not_installed) or allowed the scope (scope_not_allowed, the message has the consent link), the person may not do this in the group (forbidden), Grouperly paused the app (app_suspended), the person hasn’t accepted Grouperly’s current Terms (terms_required: refresh their token, then send them to the hub’s /account/welcome), or it’s a child’s account (child_account). A viewer token: the same, and forbidden in any group but its own

Media typeapplication/json
object
error
required
object
code
required

Stable and machine-readable: unauthorized, forbidden, insufficient_scope, key_owner_not_leader, app_not_installed, scope_not_allowed, app_suspended, rate_limited, not_found, invalid_parameter, invalid_body, invalid_profile, invalid_descriptor, no_profile, already_exists, not_a_member, wrong_holder, role_inactive, role_full, already_assigned, assignment_ended, version_not_current, nothing_to_pay, payments_not_ready, payload_too_large, first_party_only, terms_required, child_account, assistant_off, not_for_assistant, assistant_failed, not_a_draft, storage_full, made_from_roles, type_removed, invalid_reporting, led_by_role, unavailable, internal_error. New codes may be added.

string
message
required

For people; wording may change.

string
parameter

The query parameter (invalid_parameter) or body field (invalid_body, not_a_member, wrong_holder, invalid_reporting) at fault.

string
Examplegenerated
{
"error": {
"code": "example",
"message": "example",
"parameter": "example"
}
}
X-RateLimit-Limit
integer

Requests allowed per minute for this credential

X-RateLimit-Remaining
integer

Requests left in this window

X-RateLimit-Reset
integer

When the window ends (Unix seconds)

Not found (not_found)

Media typeapplication/json
object
error
required
object
code
required

Stable and machine-readable: unauthorized, forbidden, insufficient_scope, key_owner_not_leader, app_not_installed, scope_not_allowed, app_suspended, rate_limited, not_found, invalid_parameter, invalid_body, invalid_profile, invalid_descriptor, no_profile, already_exists, not_a_member, wrong_holder, role_inactive, role_full, already_assigned, assignment_ended, version_not_current, nothing_to_pay, payments_not_ready, payload_too_large, first_party_only, terms_required, child_account, assistant_off, not_for_assistant, assistant_failed, not_a_draft, storage_full, made_from_roles, type_removed, invalid_reporting, led_by_role, unavailable, internal_error. New codes may be added.

string
message
required

For people; wording may change.

string
parameter

The query parameter (invalid_parameter) or body field (invalid_body, not_a_member, wrong_holder, invalid_reporting) at fault.

string
Examplegenerated
{
"error": {
"code": "example",
"message": "example",
"parameter": "example"
}
}
X-RateLimit-Limit
integer

Requests allowed per minute for this credential

X-RateLimit-Remaining
integer

Requests left in this window

X-RateLimit-Reset
integer

When the window ends (Unix seconds)

Its type already has a subgroup with that name (already_exists), or its type was removed (type_removed), or it sits inside an archived subgroup (parent_archived), or ledByRoleIds was sent for a subgroup made from roles (made_from_roles)

Media typeapplication/json
object
error
required
object
code
required

Stable and machine-readable: unauthorized, forbidden, insufficient_scope, key_owner_not_leader, app_not_installed, scope_not_allowed, app_suspended, rate_limited, not_found, invalid_parameter, invalid_body, invalid_profile, invalid_descriptor, no_profile, already_exists, not_a_member, wrong_holder, role_inactive, role_full, already_assigned, assignment_ended, version_not_current, nothing_to_pay, payments_not_ready, payload_too_large, first_party_only, terms_required, child_account, assistant_off, not_for_assistant, assistant_failed, not_a_draft, storage_full, made_from_roles, type_removed, invalid_reporting, led_by_role, unavailable, internal_error. New codes may be added.

string
message
required

For people; wording may change.

string
parameter

The query parameter (invalid_parameter) or body field (invalid_body, not_a_member, wrong_holder, invalid_reporting) at fault.

string
Examplegenerated
{
"error": {
"code": "example",
"message": "example",
"parameter": "example"
}
}
X-RateLimit-Limit
integer

Requests allowed per minute for this credential

X-RateLimit-Remaining
integer

Requests left in this window

X-RateLimit-Reset
integer

When the window ends (Unix seconds)

Rate limited (rate_limited)

Media typeapplication/json
object
error
required
object
code
required

Stable and machine-readable: unauthorized, forbidden, insufficient_scope, key_owner_not_leader, app_not_installed, scope_not_allowed, app_suspended, rate_limited, not_found, invalid_parameter, invalid_body, invalid_profile, invalid_descriptor, no_profile, already_exists, not_a_member, wrong_holder, role_inactive, role_full, already_assigned, assignment_ended, version_not_current, nothing_to_pay, payments_not_ready, payload_too_large, first_party_only, terms_required, child_account, assistant_off, not_for_assistant, assistant_failed, not_a_draft, storage_full, made_from_roles, type_removed, invalid_reporting, led_by_role, unavailable, internal_error. New codes may be added.

string
message
required

For people; wording may change.

string
parameter

The query parameter (invalid_parameter) or body field (invalid_body, not_a_member, wrong_holder, invalid_reporting) at fault.

string
Examplegenerated
{
"error": {
"code": "example",
"message": "example",
"parameter": "example"
}
}
X-RateLimit-Limit
integer

Requests allowed per minute for this credential

X-RateLimit-Remaining
integer

Requests left in this window

X-RateLimit-Reset
integer

When the window ends (Unix seconds)

Retry-After
integer

Seconds to wait

An app’s token for someone new, while Grouperly’s sign-in can’t be reached (unavailable); try again

Media typeapplication/json
object
error
required
object
code
required

Stable and machine-readable: unauthorized, forbidden, insufficient_scope, key_owner_not_leader, app_not_installed, scope_not_allowed, app_suspended, rate_limited, not_found, invalid_parameter, invalid_body, invalid_profile, invalid_descriptor, no_profile, already_exists, not_a_member, wrong_holder, role_inactive, role_full, already_assigned, assignment_ended, version_not_current, nothing_to_pay, payments_not_ready, payload_too_large, first_party_only, terms_required, child_account, assistant_off, not_for_assistant, assistant_failed, not_a_draft, storage_full, made_from_roles, type_removed, invalid_reporting, led_by_role, unavailable, internal_error. New codes may be added.

string
message
required

For people; wording may change.

string
parameter

The query parameter (invalid_parameter) or body field (invalid_body, not_a_member, wrong_holder, invalid_reporting) at fault.

string
Examplegenerated
{
"error": {
"code": "example",
"message": "example",
"parameter": "example"
}
}