Skip to content
GrouperlyGrouperly Docs

Change a position

PATCH
/groups/{groupId}/positions/{positionId}
curl --request PATCH \
  --url https://app.grouperly.com/api/v2/groups/example/positions/example \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '{ "name": "example", "description": "example", "category": "LEADERSHIP", "maxHolders": 1, "sortOrder": 1, "active": true }'

Only the fields sent change. A position is never deleted here: make it inactive instead, which keeps who held it.

Authorizations

Section titled “Authorizations”
  • appToken
    https://api.grouperly.com/positions.write

Parameters

Section titled “Parameters”

Path Parameters

Section titled “Path Parameters”
groupId
required
string

The credential’s group

positionId
required
string

A position in the group

Request Bodyrequired

Section titled “Request Bodyrequired”
Media typeapplication/json
object
name

Unique in the group, e.g. “Treasurer”

string
<= 100 characters
description

What the position is responsible for

string | null
<= 2000 characters
category

Defaults to GENERAL

string
Allowed values: LEADERSHIP OFFICER COORDINATOR COMMITTEE VOLUNTEER GENERAL
maxHolders

How many people may hold it at once; null for any number (the default)

integer | null
>= 1 <= 1000
sortOrder

Lower comes first; defaults to 0

integer
<= 10000
active

Still needed: only active positions take new holders (a new position is active)

boolean

Responses

Section titled “Responses”

200

Section titled “200”

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 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
Example
{
  "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”

The body isn’t a JSON object of at most 16 KB, or a field is unknown, missing or malformed (invalid_body, 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)

404

Section titled “404”

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, 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)

409

Section titled “409”

The group already has a position with that name (already_exists)

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