Skip to content

Set a goal

POST
/groups/{groupId}/goals
curl --request POST \
--url https://app.grouperly.com/api/v2/groups/example/goals \
--header 'Authorization: Bearer <token>' \
--header 'Content-Type: application/json' \
--data '{ "roleId": "example", "subgroupId": "example", "title": "example", "why": "example", "startsOn": "2026-04-15", "endsOn": "2026-04-15", "parentGoalId": "example", "responsibilityId": "example" }'

A role’s goal, by its holders (in their subgroup, for a role held in one) or someone who sets goals; a subgroup’s own (subgroupId without roleId, 2.70.0), by its leaders or someone who sets goals; or the group’s own, by someone who sets goals. Its dates default to this calendar year. Add its key results with POST …/key-results (added in 2.55.0).

  • appToken
    https://api.grouperly.com/goals.write
groupId
required
string

The credential’s group

Media typeapplication/json
object
roleId

The role whose goal it is (GET /roles). Left out for a subgroup’s own or the group’s own

string
<= 64 characters
subgroupId

Which subgroup, for a role held in one subgroup of a type (required then); without roleId, the subgroup whose own goal it is (2.70.0)

string
<= 64 characters
title
required

An outcome, not a task: “Every scout who wants to go to camp goes”

string
<= 200 characters
why

Markdown: why it matters

string | null
<= 4000 characters
startsOn

The day it starts, YYYY-MM-DD; January 1 this year when a new goal leaves it out

string format: date
endsOn

The day it ends, on or after startsOn; December 31 this year when a new goal leaves it out

string format: date
parentGoalId

A goal of the group’s it serves (GET /goals), at most four levels deep and never one under it

string | null
<= 64 characters
responsibilityId

One of its role’s responsibilities it measures (GET /roles/{roleId}/responsibilities); a role’s goal only

string | null
<= 64 characters
Examplegenerated
{
"roleId": "example",
"subgroupId": "example",
"title": "example",
"why": "example",
"startsOn": "2026-04-15",
"endsOn": "2026-04-15",
"parentGoalId": "example",
"responsibilityId": "example"
}

Created

Media typeapplication/json
object
id
required
string
title
required
string
why
required

Markdown

string | null
owner
required
One of:
object
roleId
required
string
roleName
required
string
subgroupId
required

For a role held in one subgroup of a type

string | null
subgroupName
required
string | null
subgroup
required
One of:
object
subgroupId
required
string
subgroupName
required
string
parentGoalId
required

The goal it serves

string | null
responsibilityId
required

The role’s responsibility it measures (GET /roles/{roleId}/responsibilities)

string | null
startsOn
required
string format: date
endsOn
required
string format: date
status
required
string
Allowed values: ON_TRACK AT_RISK OFF_TRACK DONE DROPPED
keyResults
required
Array<object>
object
id
required
string
title
required
string
kind
required

NUMBER (with a unit, which may be “%”), MONEY (the group’s currency) or DONE (0 or 1)

string
Allowed values: NUMBER MONEY DONE
unit
required
string | null
startValue
required
number
targetValue
required
number
currentValue
required

Where it is now, from the last check-in

number
progress
required

From its start to its target, 0 to 1

number
dueOn
required
string | null format: date
progress
required

Its key results’ average, 0 to 1; null without any

number | null
lastCheckIn
required
One of:
object
at
required
string format: date-time
by
required

Who checked in, as roles name their holders: null for a youth, for an app without roster.youth.read

string | null
note
required

For the role’s holders, the role it reports to, and those who see progress or set goals

string | null
noteHidden
required

There’s a note this person may not read

boolean
canWrite
required

The person may change it and check in

boolean
Example
{
"status": "ON_TRACK",
"keyResults": [
{
"kind": "NUMBER"
}
]
}
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)

The body isn’t a JSON object of at most 16 KB, or a field is unknown, missing or malformed (invalid_body, with parameter); the dates, parent or responsibility don’t fit (invalid_body)

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. Also: the person doesn’t write this role’s goals, or the group’s (forbidden)

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