Skip to content
GrouperlyGrouperly Docs

Positions and who holds them now

GET
/groups/{groupId}/positions
curl --request GET \
  --url 'https://app.grouperly.com/api/v2/groups/example/positions?limit=50&category=LEADERSHIP' \
  --header 'Authorization: Bearer <token>'

In the order Grouperly shows them: by sort order, then name.

Authorizations

Section titled “Authorizations”

Parameters

Section titled “Parameters”

Path Parameters

Section titled “Path Parameters”
groupId
required
string

The credential’s group

Query Parameters

Section titled “Query Parameters”
limit
integer
default: 50 >= 1 <= 200

Items per page

cursor
string

From the previous page’s nextCursor; opaque

active
boolean

True: only active positions; false: only inactive ones

category
string
Allowed values: LEADERSHIP OFFICER COORDINATOR COMMITTEE VOLUNTEER GENERAL

Only positions in this category (case-insensitive)

Responses

Section titled “Responses”

200

Section titled “200”

OK

Media typeapplication/json
object
items
required
Array<object>
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 positions take new holders

boolean
holderCount
required

Everyone who holds it now

integer
holders
required

Who holds it now, 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
createdAt
required
string format: date-time
updatedAt
required
string format: date-time
nextCursor
required

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

string | null
Example
{
  "items": [
    {
      "category": "LEADERSHIP"
    }
  ]
}

Headers

Section titled “Headers”
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)

400

Section titled “400”

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, position_inactive, position_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, 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) at fault.

string
Examplegenerated
{
  "error": {
    "code": "example",
    "message": "example",
    "parameter": "example"
  }
}

Headers

Section titled “Headers”
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)

401

Section titled “401”

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, position_inactive, position_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, 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) at fault.

string
Examplegenerated
{
  "error": {
    "code": "example",
    "message": "example",
    "parameter": "example"
  }
}

403

Section titled “403”

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)

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, position_inactive, position_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, 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) at fault.

string
Examplegenerated
{
  "error": {
    "code": "example",
    "message": "example",
    "parameter": "example"
  }
}

Headers

Section titled “Headers”
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)

429

Section titled “429”

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, position_inactive, position_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, 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) at fault.

string
Examplegenerated
{
  "error": {
    "code": "example",
    "message": "example",
    "parameter": "example"
  }
}

Headers

Section titled “Headers”
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

503

Section titled “503”

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, position_inactive, position_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, 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) at fault.

string
Examplegenerated
{
  "error": {
    "code": "example",
    "message": "example",
    "parameter": "example"
  }
}