Skip to content

Add a task

POST
/groups/{groupId}/tasks
curl --request POST \
--url https://app.grouperly.com/api/v2/groups/example/tasks \
--header 'Authorization: Bearer <token>' \
--header 'Content-Type: application/json' \
--data '{ "title": "example", "details": "example", "dueOn": "2026-04-15", "userId": "example", "eventIds": [ "example" ], "roleIds": [ "example" ], "subgroupIds": [ "example" ], "isPrivate": true }'

As the person: assigned to someone in the group with an account (userId), or nobody; linked to events, roles and subgroups (eventIds, roleIds, subgroupIds). Whoever it’s assigned to hears, as in Grouperly; up for grabs, its places’ leaders do. A task with young people on it can’t be private (added in 2.72.0).

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

The credential’s group

Media typeapplication/json
object
title
required

What needs doing

string
<= 200 characters
details

Markdown: more on it

string | null
<= 4000 characters
dueOn

When it is due, YYYY-MM-DD

string | null format: date
userId

Who it is assigned to: one person in the group with an account (GET /members). Without one it is up for grabs for the people of what it is linked to, or, linked to nothing, yours

string | null
<= 64 characters
eventIds

Events it is linked to (GET /events): it shows on each one’s tasks, and their people see it unless it’s private

Array<string>
<= 20 items
roleIds

Roles it is linked to (GET /roles; their holders may take it): it shows on each one’s tasks, and their people see it unless it’s private

Array<string>
<= 20 items
subgroupIds

Subgroups it is linked to (GET /subgroups; their people may take it): it shows on each one’s tasks, and their people see it unless it’s private

Array<string>
<= 20 items
isPrivate

Only those on it and the leaders see it. A task with young people on it can’t be private

boolean
Examplegenerated
{
"title": "example",
"details": "example",
"dueOn": "2026-04-15",
"userId": "example",
"eventIds": [
"example"
],
"roleIds": [
"example"
],
"subgroupIds": [
"example"
],
"isPrivate": true
}

Created

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

OPEN (to do), IN_PROGRESS, STUCK, DONE or SKIPPED (won’t do)

string
Allowed values: OPEN IN_PROGRESS STUCK DONE SKIPPED
dueOn
required
string | null format: date
isPrivate
required

Only those on it and the leaders see it

boolean
assignedTo
required
One of:
object
userId
required

Null for someone on the roster without an account

string | null
name
required
string
assignedToHidden
required

It is assigned to a young person, and the app may not see young people (roster.youth.read)

boolean
links
required

What it is linked to: events, roles and subgroups, any number. It shows on each one’s tasks

Array<object>
object
type
required
string
Allowed values: event role subgroup
id
required
string
name
required
string
upForGrabs
required

Nobody has it and it is linked to somewhere: its places’ people may take it, and their leaders assign it

boolean
linkedToMe
required

Linked to a role they hold, a subgroup of theirs or an event they run

boolean
createdBy
required

Who made it; null for a young person, without roster.youth.read

string | null
createdAt
required
string format: date-time
updatedAt
required
string format: date-time
doneAt
required
string | null format: date-time
doneBy
required
string | null
stuck
required
One of:
object
at
required
string format: date-time
by
required

Who said it is stuck; null for a young person, without roster.youth.read

string | null
note
required

What is in the way

string | null
needs
required
One of:
object
type
required
string
Allowed values: person role subgroup
id
required

A person’s account or roster entry, a role’s or a subgroup’s id

string
name
required

Null for a young person, without roster.youth.read

string | null
needsMe
required

It is stuck and needs their input: theirs, a role they hold, or a subgroup they are in

boolean
checkedInAt
required

The last word from those on it

string | null format: date-time
followerCount
required
integer
following
required
boolean
mine
required

On their list: theirs to do

boolean
can
required
object
change
required

Change where it stands (STUCK with whose input it needs), check in

boolean
edit
required

Change its words, date or what it is linked to

boolean
assign
required

Assign it to someone

boolean
take
required

Take it while it is up for grabs

boolean
release
required

Put it back up for grabs

boolean
decline
required

Decline it: it is theirs, and they won’t do it

boolean
url
required

The task in Grouperly

string format: uri
details
required

Markdown

string | null
canComment
required
boolean
activity
required

Its feed, oldest first: comments and what changed

Array<object>
object
id
required
string
kind
required

CREATED, COMMENT, STATUS, ASSIGNED, TAKEN, GIVEN_BACK, HANDED_BACK, DUE, PLACE, EDITED, RAISED, CHECKED_IN or REVIEWED; more may come

string
body
required

A comment or note (Markdown); null once deleted

string | null
fromState
required
string | null
toState
required
string | null
by
required

Who did it; null for a young person, without roster.youth.read

string | null
at
required
string format: date-time
editedAt
required
string | null format: date-time
deleted
required
boolean
meetingId
required

The meeting (an event’s id) whose review of tasks did it

string | null
Example
{
"state": "OPEN",
"links": [
{
"type": "event"
}
],
"stuck": {
"needs": {
"type": "person"
}
}
}
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); a private task with young people on it, or a place that doesn’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: Tasks isn’t on for the person, or they may not add one there (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"
}
}