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 |
The catalog
Section titled “The catalog”GET /groups/{groupId}/awards lists the group’s awards on one page. Archived ones are left out.
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) orTRAINING(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,ADULTSorANYONE. 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:grouperlyorfile(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’sfileonce 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.
Who has earned what
Section titled “Who has earned what”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) |
# Everything earned since September 1curl -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}awardIdis the step, badge, award or training earned.presentedOnisnulluntil 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.
Granting
Section titled “Granting”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 }awardIdis 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:trueemails 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`);Changing or taking back a grant
Section titled “Changing or taking back a grant”PATCH /groups/{groupId}/awards/grants/{grantId}changesearnedOnorpresentedOn, each today or before."presentedOn": nullmarks 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' }, }) );}Errors
Section titled “Errors”| 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.