Create a role
const url = 'https://app.grouperly.com/api/v2/groups/example/roles';const options = { method: 'POST', headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'}, body: '{"name":"example","description":"example","category":"LEADERSHIP","maxHolders":1,"sortOrder":1,"subgroupType":"example","leadsSubgroup":true,"permissions":["example"],"reportsToId":"example"}'};
try { const response = await fetch(url, options); const data = await response.json(); console.log(data);} catch (error) { console.error(error);}curl --request POST \ --url https://app.grouperly.com/api/v2/groups/example/roles \ --header 'Authorization: Bearer <token>' \ --header 'Content-Type: application/json' \ --data '{ "name": "example", "description": "example", "category": "LEADERSHIP", "maxHolders": 1, "sortOrder": 1, "subgroupType": "example", "leadsSubgroup": true, "permissions": [ "example" ], "reportsToId": "example" }'Authorizations
Section titled “Authorizations”Parameters
Section titled “Parameters”Path Parameters
Section titled “Path Parameters”The credential’s group
Request Bodyrequired
Section titled “Request Bodyrequired”object
Unique in the group, e.g. “Treasurer”
What the role is responsible for
Defaults to GENERAL
How many people may hold it at once; null for any number (the default)
Lower comes first; defaults to 0
Held in one subgroup of this type: a key from GET /subgroup-types (e.g. “patrol”), and each term names the subgroup. null for a role held across the whole group (the default). It can’t change while anyone holds the role (role_held). Since 2.29.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). Not for a role held across the whole group (a subgroup names those in its ledByRoleIds), nor one for youth. Only an owner or admin sets it. Since 2.57.0
What holding it gives, replacing what it carried: for a role held across the whole group, any of member_details, expiry_dates (since 2.56.0: whose training, registrations and the like run out, for an adult holding it; a health form’s only for the group’s own owners and admins), money, see_books (since 2.48.0: the books, read-only), contacts (since 2.49.0: the group’s contacts, the ones kept for leaders too), approve_expenses (since 2.42.0: the first approval of a reimbursement), add_people, announce, events, fundraisers (since 2.50.0: start and manage every fundraiser, without running every event), photos, store, subgroups, assign_roles, playbooks, progress, confirm_parents (since 2.43.0: deciding requests to be listed as the parent of a child or teen, for an adult holding it), integrations (since 2.52.0: setting up the outside systems the group works in), goals (since 2.53.0: writing any role’s goals and the group’s own), awards (since 2.62.0: keeping the group’s awards and granting them), recruiting (since 2.63.0: Recruiting, on Grouperly Plus: the people thinking about joining and their first emails); for one held in a subgroup type, any of subgroup_attendees, subgroup_message, subgroup_events, subgroup_members, subgroup_awards (since 2.75.0: what its people have earned and are working on, for an adult holding it) (subgroup_progress is kept for later). Empty gives nothing (the default). The caller must hold each one (beyond_your_permissions). Since 2.32.0
The role it reports to (Role.id), or null for the top of the org chart (the default). One of the group’s roles, never itself or one that reports to it, and a reporting line has at most 6 levels (invalid_reporting). It gives nothing of that role’s permissions. Since 2.38.0
Responses
Section titled “Responses”Created
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)
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 reportsToId isn’t one of the group’s roles or makes a reporting line longer than 6 levels (invalid_reporting)
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. Also: the role would carry a permission the person can’t use themselves (beyond_your_permissions)
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)
The group already has a role with that name (already_exists)
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" }}