One role and who holds it now
const url = 'https://app.grouperly.com/api/v2/groups/example/roles/example';const options = {method: 'GET', headers: {Authorization: 'Bearer <token>'}};
try { const response = await fetch(url, options); const data = await response.json(); console.log(data);} catch (error) { console.error(error);}curl --request GET \ --url https://app.grouperly.com/api/v2/groups/example/roles/example \ --header 'Authorization: Bearer <token>'Include=pastHolders adds who held it before: its emeritus, with the years as precisely as they were entered (added in 2.51.0).
Authorizations
Section titled “Authorizations”Parameters
Section titled “Parameters”Path Parameters
Section titled “Path Parameters”The credential’s group
A role in the group
Query Parameters
Section titled “Query Parameters”Comma-separated related data to add: pastHolders. Anything else is a 400.
Responses
Section titled “Responses”OK
object
How many may hold it at once; null for any number
Lower comes first
Only active roles take new holders
Held in one subgroup of this type (GET /subgroup-types), each holder in their own: a Patrol Leader in each patrol. maxHolders then counts in each subgroup. Null for a role held across the whole group (2.29.0)
That type’s key, e.g. “patrol”, which POST and PATCH take (2.29.0)
What holding it gives, by key: group permissions for a role held across the whole group, subgroup permissions (good in each holder’s own subgroup) for one held in a subgroup type. Holding it gives exactly these. Empty for none (2.32.0)
The role it reports to (Role.id), or null at the top of the org chart. It gives nothing of that role’s permissions; an overdue playbook task goes to the role above first (2.38.0)
For a role held in a subgroup type: whoever holds it leads the subgroup their term names, as its LEADER while the term lasts (a Den Leader leads their den). Always false for a role held across the group, which leads the subgroups in leadsSubgroupIds. Adults only: a youth holder leads nothing by a role (added in 2.57.0)
For a role held across the group: the subgroups in use whose LEADER whoever holds it is (Subgroup.id), as each subgroup’s ledByRoleIds says. Empty for a role held in a type (added in 2.57.0)
Everyone who holds it now with an account. Someone on the roster given it before joining is left out until they have one.
Who holds it now with an account, earliest first. An app without roster.youth.read isn’t told which youth hold it: they’re counted in holderCount but not listed.
object
The subgroup they hold it in, for a role held in one subgroup of a type; null otherwise (2.29.0)
The group’s custom fields on the role that the caller may see (GET /field-definitions?entity=ROLE), by key, null where one isn’t set: a key and whoever changes the group’s roles see every one, anyone else those the whole group sees. On GET /roles and /roles/{roleId} (added in 2.40.0).
object
Present only with include=pastHolders.
object
The account that held it, or the one its roster entry has linked to since; null for someone on the roster without one
The roster entry that held it (GET /contacts/{contactId}), while it is on the roster; null for a term held by an account
The account’s name; for someone on the roster without an account, their name only with roster.read (null otherwise)
When the term began, as precisely as startPrecision says; null when nobody remembers
DAY, YEAR (only the year is known: read startedAt for its year), or UNKNOWN
When it ended, as precisely as endPrecision says; null when nobody remembers
DAY, YEAR or UNKNOWN, as startPrecision
How it ended. A REMOVED term leaves no emeritus and is never listed
The subgroup it was held in, for a role held in one subgroup of a type
Example
{ "category": "LEADERSHIP", "pastHolders": [ { "startPrecision": "DAY", "endPrecision": "DAY", "endedAs": "COMPLETED" } ]}Headers
Section titled “Headers”Requests allowed per minute for this credential
Requests left in this window
When the window ends (Unix seconds)
A query parameter is malformed or unknown (invalid_parameter, with parameter)
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)
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" }}