Skip to content

Rename, remove or bring back a subgroup type

PATCH
/groups/{groupId}/subgroup-types/{type}
curl --request PATCH \
--url https://app.grouperly.com/api/v2/groups/example/subgroup-types/example \
--header 'Authorization: Bearer <token>' \
--header 'Content-Type: application/json' \
--data '{ "singular": "example", "plural": "example", "archived": true }'

Only the fields sent change; its key never does. Removing a type (archived: true) archives its subgroups with it at the same moment, and bringing it back (archived: false) restores those, while a subgroup archived on its own before stays archived. Nothing is deleted: events, members and documents stay. archived: false also adds a template’s type the group hasn’t used. Leaders and Parents are built in and can’t be changed (added in 2.31.0).

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

The credential’s group

type
required
string

A subgroup type of the group, by its key (GET /subgroup-types), e.g. “patrol”

Media typeapplication/json
object
singular

The name of one, e.g. “Patrol”

string
<= 60 characters
plural

The name of several, e.g. “Patrols”

string
<= 60 characters
archived

True removes the type and archives its subgroups with it; false brings it back with those subgroups, or adds a template’s type the group hasn’t used. Nothing is deleted.

boolean
Examplegenerated
{
"singular": "example",
"plural": "example",
"archived": true
}

OK

Media typeapplication/json
object
key
required

Unique in the group: a vertical’s type keeps its key (“den”, “patrol”, “committee”); the built-ins are “leaders” and “parents”

string
singular
required
string
plural
required
string
membership
required

ONE_PER_PERSON: a person is a member of at most one subgroup of the type (dens). OVERLAPPING: any number (committees). AUTOMATIC: the built-ins, worked out from the roster and never added to.

string
Allowed values: ONE_PER_PERSON OVERLAPPING AUTOMATIC
who
required

Who may be a member; leaders are always adults

string
Allowed values: YOUTH ADULTS ANYONE
source
required

VERTICAL: the group’s vertical’s; GROUP: its own; BUILTIN: Leaders and Parents

string
Allowed values: VERTICAL GROUP BUILTIN
archived
required

Removed by its leaders, with the subgroups removed with it; listed only with ?archived=true, and brought back by PATCH (2.31.0)

boolean
Example
{
"membership": "ONE_PER_PERSON",
"who": "YOUTH",
"source": "VERTICAL"
}
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 the type is built in (Leaders, Parents)

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)

Someone holds a role held in this type (role_held): end their terms, or change where that role is held, first. Or a subgroup of another type sits inside one of its subgroups (holds_other_types): move it out, or archive it, first (2.36.0)

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"
}
}