Skip to content

A playbook: its steps, guide and follow-up rules

GET
/groups/{groupId}/playbooks/{playbookId}
curl --request GET \
--url https://app.grouperly.com/api/v2/groups/example/playbooks/example \
--header 'Authorization: Bearer <token>'

The steps in order, each with when it’s due and who does it as data, not words, and the documents it links to that the person may open. Not found for one the person may not open (added in 2.39.0).

groupId
required
string

The credential’s group

playbookId
required
string

One of the group’s playbooks

OK

Media typeapplication/json
object
id
required
string
name
required
string
description
required
string | null
version
required

Goes up with every change to it or its steps

integer
stepCount
required
integer
responsibilityCount
required

Added in 2.55.0

integer
hasGuide
required
boolean
usedBy
required
Array<object>
object
target
required

ROLE, SERIES (a recurring event), EVENT, EVERY_EVENT, PROSPECT (each prospect, from 2.64.0), JOINING (each person who joins, from 2.64.0) SUBGROUP (each person added to a subgroup, from 2.65.0) or SUBGROUP_ITSELF (the subgroup’s own playbook, what it answers for, from 2.69.0). More may be added: skip one you don’t know

string
id
required

The role’s, recurring event’s, event’s or subgroup’s id; null for every event, each prospect or each person who joins

string | null
name
required

Its name, or “Every event”, “Each prospect”, “Each person who joins”, “Each person added to Lions”

string
updatedAt
required
string format: date-time
guideDocumentId
required

The guide, a library document (GET /documents/{documentId}), where the caller may open it; null otherwise

string | null
followUp
required

How Grouperly reminds people of its tasks and tells others when they run late

object
remindDaysBefore
required

A heads-up this many days before a task is due; null for none

integer | null
remindOnDueDay
required
boolean
remindEveryDays
required

While it’s overdue, a reminder every this many days; null for none

integer | null
escalateLeadersAfterDays
required

The run’s leaders hear after this many days overdue; null for never

integer | null
escalateWatchersAfterDays
required

Whoever watches progress hears after this many; null for never

integer | null
responsibilities
required

What its role answers for, in order: a playbook attached to a role with these is the role’s definition (added in 2.55.0)

Array<object>
object
id
required
string
order
required
integer
title
required

An outcome its role answers for, not a task: “The pack’s money is accounted for”

string
why
required

Markdown: why it matters

string | null
how
required

How it’s done: standing practices, a line each, not ticked off

Array<string>
skillIds
required

The how-tos it uses (GET /skills/{skillId})

Array<string>
steps
required

In order

Array<object>
object
id
required
string
order
required
integer
title
required
string
details
required

Markdown

string | null
doneWhen
required

What ‘done’ looks like

string | null
notes
required
string | null
when
required
object
timing
required

ANNUAL: by month/day each year. EVENT: offsetDays from the event’s START or END (anchor), negative before. RUN_START: right away when a run starts. ANYTIME: no set time

string
Allowed values: ANNUAL EVENT RUN_START ANYTIME
month
required

1–12, for ANNUAL

integer | null
day
required

1–31, for ANNUAL

integer | null
offsetDays
required

Days from the anchor, negative before it, for EVENT

integer | null
anchor
required

START or END of the event, for EVENT

string | null
Allowed values: START END
who
required
object
assignee
required

ROLE: whoever holds roleId now (for a role held in a subgroup type, its holder in the run’s subgroup or the event’s). RUNNERS: those running the event (its leaders and the roles of the subgroups that run it). ASSIGNED: whoever the run gives it to

string
Allowed values: ROLE RUNNERS ASSIGNED
roleId
required

The role, for ROLE (GET /roles)

string | null
documentIds
required

Library documents it links to that the caller may open (GET /documents/{documentId}): never a HEALTH one, and for a key or an app without roster.youth.read only those it could read anyway

Array<string>
responsibilityId
required

The playbook’s responsibility it delivers (responsibilities[].id), or null (added in 2.55.0)

string | null
skillIds
required

The how-tos it uses (GET /skills/{skillId}) (added in 2.55.0)

Array<string>
integrationIds
required

The outside systems it’s done in (GET /integrations/{integrationId}) (added in 2.55.0)

Array<string>
Example
{
"steps": [
{
"when": {
"timing": "ANNUAL",
"anchor": "START"
},
"who": {
"assignee": "ROLE"
}
}
]
}
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

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