Rename, archive or move a subgroup, or change its roles
const url = 'https://app.grouperly.com/api/v2/groups/example/subgroups/example';const options = { method: 'PATCH', headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'}, body: '{"name":"example","metadata":{"additionalProperty":"example"},"archived":true,"roleIds":["example"],"parentId":"example","ledByRoleIds":["example"]}'};
try { const response = await fetch(url, options); const data = await response.json(); console.log(data);} catch (error) { console.error(error);}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).
Authorizations
Section titled “Authorizations”Parameters
Section titled “Parameters”Path Parameters
Section titled “Path Parameters”The credential’s group
A subgroup in the group
Request Bodyrequired
Section titled “Request Bodyrequired”object
Unique in its type
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
True archives it: it keeps its history and takes no one new. false brings it back, unless its type was removed
For a subgroup made from roles only: the roles it is made from now. Its people follow at once
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)
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
Examplegenerated
{ "name": "example", "metadata": { "additionalProperty": "example" }, "archived": true, "roleIds": [ "example" ], "parentId": "example", "ledByRoleIds": [ "example" ]}Responses
Section titled “Responses”OK
object
Unique in its type, e.g. “Wolf Den”
object
E.g. “den”
E.g. “Den”
E.g. “Dens”
Kept for its history; takes no one new
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)
The roles a subgroup made from roles is made from (Role.id); empty for picked (added in 2.33.0)
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)
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)
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
Example
{ "source": "picked"}Headers
Section titled “Headers”Requests allowed per minute for this credential
Requests left in this window
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)
object
object
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.
For people; wording may change.
The query parameter (invalid_parameter) or body field (invalid_body, not_a_member, wrong_holder, invalid_reporting) at fault.
Examplegenerated
{ "error": { "code": "example", "message": "example", "parameter": "example" }}Headers
Section titled “Headers”Requests allowed per minute for this credential
Requests left in this window
When the window ends (Unix seconds)
Missing, unknown, revoked or expired credential (unauthorized)
object
object
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.
For people; wording may change.
The query parameter (invalid_parameter) or body field (invalid_body, not_a_member, wrong_holder, invalid_reporting) at fault.
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
object
object
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.
For people; wording may change.
The query parameter (invalid_parameter) or body field (invalid_body, not_a_member, wrong_holder, invalid_reporting) at fault.
Examplegenerated
{ "error": { "code": "example", "message": "example", "parameter": "example" }}Headers
Section titled “Headers”Requests allowed per minute for this credential
Requests left in this window
When the window ends (Unix seconds)
Not found (not_found)
object
object
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.
For people; wording may change.
The query parameter (invalid_parameter) or body field (invalid_body, not_a_member, wrong_holder, invalid_reporting) at fault.
Examplegenerated
{ "error": { "code": "example", "message": "example", "parameter": "example" }}Headers
Section titled “Headers”Requests allowed per minute for this credential
Requests left in this window
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)
object
object
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.
For people; wording may change.
The query parameter (invalid_parameter) or body field (invalid_body, not_a_member, wrong_holder, invalid_reporting) at fault.
Examplegenerated
{ "error": { "code": "example", "message": "example", "parameter": "example" }}Headers
Section titled “Headers”Requests allowed per minute for this credential
Requests left in this window
When the window ends (Unix seconds)
Rate limited (rate_limited)
object
object
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.
For people; wording may change.
The query parameter (invalid_parameter) or body field (invalid_body, not_a_member, wrong_holder, invalid_reporting) at fault.
Examplegenerated
{ "error": { "code": "example", "message": "example", "parameter": "example" }}Headers
Section titled “Headers”Requests allowed per minute for this credential
Requests left in this window
When the window ends (Unix seconds)
Seconds to wait
An app’s token for someone new, while Grouperly’s sign-in can’t be reached (unavailable); try again
object
object
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.
For people; wording may change.
The query parameter (invalid_parameter) or body field (invalid_body, not_a_member, wrong_holder, invalid_reporting) at fault.
Examplegenerated
{ "error": { "code": "example", "message": "example", "parameter": "example" }}