Skip to content

One role and who holds it now

GET
/groups/{groupId}/roles/{roleId}
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).

groupId
required
string

The credential’s group

roleId
required
string

A role in the group

include
string

Comma-separated related data to add: pastHolders. Anything else is a 400.

OK

Media typeapplication/json
object
id
required
string
name
required
string
description
required
string | null
category
required
string
Allowed values: LEADERSHIP OFFICER COORDINATOR COMMITTEE VOLUNTEER GENERAL
maxHolders
required

How many may hold it at once; null for any number

integer | null
sortOrder
required

Lower comes first

integer
active
required

Only active roles take new holders

boolean
subgroupTypeId
required

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)

string | null
subgroupType
required

That type’s key, e.g. “patrol”, which POST and PATCH take (2.29.0)

string | null
permissions
required

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)

Array<string>
reportsToId
required

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)

string | null
leadsSubgroup
required

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)

boolean
leadsSubgroupIds
required

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)

Array<string>
holderCount
required

Everyone who holds it now with an account. Someone on the roster given it before joining is left out until they have one.

integer
holders
required

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.

Array<object>
object
assignmentId
required
string
userId
required
string
name
required
string | null
startedAt
required
string format: date-time
subgroupId
required

The subgroup they hold it in, for a role held in one subgroup of a type; null otherwise (2.29.0)

string | null
createdAt
required
string format: date-time
updatedAt
required
string format: date-time
customFields

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
key
additional properties
string | number | boolean | null
pastHolders

Present only with include=pastHolders.

Array<object>
object
assignmentId
required
string
userId
required

The account that held it, or the one its roster entry has linked to since; null for someone on the roster without one

string | null
contactId
required

The roster entry that held it (GET /contacts/{contactId}), while it is on the roster; null for a term held by an account

string | null
name
required

The account’s name; for someone on the roster without an account, their name only with roster.read (null otherwise)

string | null
startedAt
required

When the term began, as precisely as startPrecision says; null when nobody remembers

string | null format: date-time
startPrecision
required

DAY, YEAR (only the year is known: read startedAt for its year), or UNKNOWN

string
Allowed values: DAY YEAR UNKNOWN
endedAt
required

When it ended, as precisely as endPrecision says; null when nobody remembers

string | null format: date-time
endPrecision
required

DAY, YEAR or UNKNOWN, as startPrecision

string
Allowed values: DAY YEAR UNKNOWN
endedAs
required

How it ended. A REMOVED term leaves no emeritus and is never listed

string
Allowed values: COMPLETED RESIGNED
subgroupId
required

The subgroup it was held in, for a role held in one subgroup of a type

string | null
Example
{
"category": "LEADERSHIP",
"pastHolders": [
{
"startPrecision": "DAY",
"endPrecision": "DAY",
"endedAs": "COMPLETED"
}
]
}
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)

A query parameter is malformed or unknown (invalid_parameter, with parameter)

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)

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