Skip to content

The custom fields kept on the group's members, events, subgroups or roles, or on the group itself

GET
/groups/{groupId}/field-definitions
curl --request GET \
--url 'https://app.grouperly.com/api/v2/groups/example/field-definitions?entity=MEMBER' \
--header 'Authorization: Bearer <token>'

Its template’s (a scout’s member ID) and the group’s own, in the order Grouperly’s forms show them, and only those the caller may see on someone: a key, as a leader, all but a health form’s dates; an app, what its person sees. A field kept only for youth only for an app with roster.youth.read. All of them, on one page (added in 2.34.0).

?entity=EVENT lists its events’ fields instead, and needs events.read too (insufficient_scope): every one for a key, for whoever runs the group’s events and for someone leading an event; those the whole group sees for anyone else (added in 2.37.0).

?entity=SUBGROUP, ROLE or GROUP lists its subgroups’, its roles’ or its own fields on itself, and needs groups.read, roles.read or groups.read too (insufficient_scope): every one for a key, for whoever changes those records, and for a subgroup’s leader; those the whole group sees for anyone else (added in 2.40.0).

groupId
required
string

The credential’s group

entity
string
Allowed values: MEMBER EVENT SUBGROUP ROLE GROUP

The kind of record: MEMBER (the default), EVENT (2.37.0), SUBGROUP, ROLE or GROUP (2.40.0)

OK

Media typeapplication/json
object
items
required
Array<object>
object
key
required

What its value is filed under: plain for the template’s (memberId), g. for the group’s own (2.34.0)

string
label
required
string
type
required

A date is “YYYY-MM-DD”; a select’s value is one of its options’ values

string
Allowed values: text number boolean select date url
help
required

Shown under it on the form

string | null
maxLength
required

For text: the most characters a value may have (null: 500)

integer | null
options
required

A select’s choices; null for any other type

Array<object> | null
object
value
required
string
label
required
string
appliesTo
required

A member field: kept for these kinds of entry, ADULT or YOUTH, or every one when empty. Empty on other records

Array<string>
Allowed values: ADULT YOUTH
subgroupTypes
required

A subgroup field: kept on subgroups of these types (SubgroupType.key), or on every one when empty. Empty on other records (added in 2.40.0)

Array<string>
visibility
required

Who sees its values: the record’s leaders; on a member, them, the person and their guardians; or whoever sees the record (a youth entry’s still only their leaders and guardians)

string
Allowed values: LEADERS PERSON GROUP
column
required

No longer used: Grouperly’s roster has shown no field columns since #673, and a field’s values are in each person’s details. Kept as stored, and still accepted

boolean
identifier
required

Names the person outside the group, such as a member number

boolean
health
required

A health form’s date: seen only by the group’s own owners and admins, the person and their guardians, and never by a key or a partner app

boolean
source
required

TEMPLATE: the group’s template. GROUP: the group’s own leaders. APP: an app installed in the group, which alone changes its values (added in 2.41.0). More may be added

string
app
required

For source APP, the app that keeps it; null for any other field (added in 2.41.0)

object
slug
required

Its key is .

string
name
required
string
familyFills
required

A member field the group lets families fill in: each person their own when they join, and a parent their child’s in Grouperly. Never required, and a leader can still change it. False on any other record, on the template’s fields (an ID, a form’s or training’s date: leaders keep them), and on an app’s field (added in 2.59.0)

boolean
nextCursor
required

Pass as ?cursor= for the next page; null on the last page.

string | null
Example
{
"items": [
{
"type": "text",
"appliesTo": [
"ADULT"
],
"visibility": "LEADERS"
}
]
}
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)

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