Skip to content

Awards

A group’s awards are what its people earn: the steps of a ladder (belts, levels, ranks), the badges in a collection, one-off awards, and training. Some come with the group’s template when it chooses its kind, and the group adds its own.

Scope Allows Who
awards.read The catalog, and who has earned what Any member. A group key with read reads too
awards.write Granting, changing a grant’s days, and taking one back Whoever keeps the group’s awards: its owners and admins, and anyone whose role carries Grant awards. An app’s token only

GET /groups/{groupId}/awards lists the group’s awards on one page. Archived ones are left out.

Terminal window
curl -s https://app.grouperly.com/api/v2/groups/$GROUP_ID/awards \
-H "Authorization: Bearer $GROUPERLY_KEY"
{
"items": [
{
"id": "award-1",
"kind": "LADDER",
"name": "Belts",
"description": null,
"icon": "🥋",
"audience": "YOUTH",
"fromTemplate": false,
"keptIn": "grouperly",
"earned": 14,
"items": [
{ "id": "step-1", "name": "White", "description": null, "icon": null, "fromTemplate": false, "retired": false, "earned": 9 },
{ "id": "step-2", "name": "Yellow", "description": null, "icon": null, "fromTemplate": false, "retired": false, "earned": 5 }
]
},
{
"id": "award-2",
"kind": "AWARD",
"name": "Volunteer of the Year",
"description": null,
"icon": "🏅",
"audience": "ADULTS",
"fromTemplate": false,
"keptIn": "grouperly",
"earned": 2,
"items": []
}
],
"nextCursor": null
}
  • kind: LADDER (steps in order: the highest earned is where someone is), COLLECTION (badges, each earned on its own), AWARD (a one-off) or TRAINING (a course, kept apart from awards). More kinds may be added: skip one you don’t know.
  • items: a ladder’s steps in order, or a collection’s badges. Empty for an award or training.
  • audience: YOUTH, ADULTS or ANYONE. A step or badge is for whoever its ladder or collection is for.
  • fromTemplate: it came with the group’s template, rather than being one the group made.
  • keptIn: grouperly or file (since 2.74.0). A template can say an award’s progress is kept in a file the group brings in, such as a troop’s ranks and merit badges; it’s file once the group has brought one in. Such an award isn’t granted through the API (below).
  • retired: a step or badge no longer given, kept for whoever has it.
  • earned: how many have earned it, youth included. A ladder’s or collection’s counts its steps or badges together.

GET /groups/{groupId}/awards/grants lists grants, the latest earned first. It’s a list, with limit and cursor, and it takes:

Parameter Gives
contactId One person’s: the id of their roster entry, from GET /groups/{groupId}/contacts
awardId One step, badge, award or training’s. A ladder’s or collection’s id gives all of its steps’ or badges’
since Those earned on or after a day (YYYY-MM-DD)
Terminal window
# Everything earned since September 1
curl -s "https://app.grouperly.com/api/v2/groups/$GROUP_ID/awards/grants?since=2026-09-01" \
-H "Authorization: Bearer $GROUPERLY_KEY"
{
"items": [
{ "id": "grant-1", "awardId": "step-2", "contactId": "contact-1", "earnedOn": "2026-10-24", "presentedOn": null }
],
"nextCursor": null
}
  • awardId is the step, badge, award or training earned.
  • presentedOn is null until it’s handed out.
  • A leader’s note on a grant is never included.

Whose you get is whose the caller could see in Grouperly:

  • An app’s token: the person’s own and their children’s. Everyone’s when they’re a leader, they keep the awards, or the group lets members see each other’s awards.
  • Youth: a youth’s grants go only to an app with roster.youth.read, and each read is logged (see Youth). So in an app without it, a parent sees no child’s.
  • A group key reads as the leader who made it: every adult’s, never a youth’s. A key’s reads are listed in the group’s Settings → Exports.

POST /groups/{groupId}/awards/{awardId}/grants, with the app’s token for someone who keeps the group’s awards:

{ "contactIds": ["contact-1", "contact-2"], "earnedOn": "2026-10-31", "tell": true }
  • awardId is a step, badge, award or training. A ladder or collection itself can’t be granted: grant one of its steps or badges.
  • contactIds: up to 200 people on the roster.
  • earnedOn: the day they earned it, today or before.
  • tell: true emails each person granted it a congratulations, as granting in Grouperly does. A youth’s goes to their parents, and to them if they have their own login. Nothing is sent without it.
  • Granting to a youth also needs roster.youth.write, and is logged.
  • An award kept in a file (keptIn: file) isn’t granted here: 409 kept_in_file. A grant made in Grouperly would fall out of step with where the award is kept, and Grouperly’s own screens refuse the same way.

It answers 201 with what it did:

{ "granted": 1, "already": [{ "contactId": "contact-2", "earnedOn": "2026-09-12" }], "notFor": [], "told": 1 }
  • already: people who had it already. Theirs stays as it was.
  • notFor: people it isn’t for, who were left out: an adult for a youth’s award, or a youth for an adults’ one.
  • Neither is an error. The answer has no grant ids: read them back with ?awardId=.

With the SDK:

import { createGrouperlyClient, unwrap } from '@grouperly/sdk';
const grouperly = createGrouperlyClient({ token: () => auth.getAccessToken() });
const outcome = unwrap(
await grouperly.POST('/groups/{groupId}/awards/{awardId}/grants', {
params: { path: { groupId, awardId } },
body: { contactIds, earnedOn: '2026-10-31', tell: true },
})
);
console.log(`${outcome.granted} granted, ${outcome.already.length} had it already`);
  • PATCH /groups/{groupId}/awards/grants/{grantId} changes earnedOn or presentedOn, each today or before. "presentedOn": null marks it still to present. It answers with the grant.
  • DELETE /groups/{groupId}/awards/grants/{grantId} takes it back, and answers { "id": "grant-1" }.

Either needs roster.youth.write for a youth’s grant.

A grant that came from the group’s file keeps its earnedOn and can’t be taken back (409 kept_in_file): change it where it’s kept. Its presentedOn is still the group’s to set.

For example, after a ceremony, mark everything earned since September 1 as presented that day:

import { allItems, unwrap } from '@grouperly/sdk';
for await (const grant of allItems((cursor) =>
grouperly.GET('/groups/{groupId}/awards/grants', {
params: { path: { groupId }, query: { since: '2026-09-01', cursor } },
})
)) {
if (grant.presentedOn) continue;
unwrap(
await grouperly.PATCH('/groups/{groupId}/awards/grants/{grantId}', {
params: { path: { groupId, grantId: grant.id } },
body: { presentedOn: '2026-10-30' },
})
);
}
Status Code When
400 invalid_body A ladder or collection rather than one of its steps or badges, an archived one, someone not on the roster, or a day after today
401 unauthorized A group key on awards.write: changing awards takes an app’s token
403 insufficient_scope The scope is missing, or a youth without roster.youth.write
403 forbidden The person doesn’t keep the group’s awards
404 not_found The award or grant isn’t the group’s
409 kept_in_file Granting an award kept in a file, or changing earnedOn on, or taking back, a grant that came from it

Every endpoint, field and response is in the API reference, under Awards.