Skip to content

Reimbursement requests

GET
/groups/{groupId}/reimbursements
curl --request GET \
--url 'https://app.grouperly.com/api/v2/groups/example/reimbursements?limit=50&status=SUBMITTED' \
--header 'Authorization: Bearer <token>'

Newest first. The person’s own, and those paid to a child they look after; every request in the group for an adult who approves expenses or handles the money, unless mine=true. A key reads as the leader who made it. Credit asked to be paid out is a request too (kind CREDIT_PAYOUT). A youth payee’s name only for an app with roster.youth.read (added in 2.44.0).

  • apiKey
    payments:read
  • appToken
    https://api.grouperly.com/reimbursements.read
groupId
required
string

The credential’s group

limit
integer
default: 50 >= 1 <= 200

Items per page

cursor
string

From the previous page’s nextCursor; opaque

status
string
Allowed values: SUBMITTED APPROVED READY_TO_PAY PAYING PAID DENIED WITHDRAWN

Only requests with this status (case-insensitive)

mine
boolean

Only the person’s own, even for the treasurer (default false)

OK

Media typeapplication/json
object
items
required
Array<object>
object
id
required
string
number
required

“Request 12”: a counter in each group

integer
kind
required

REIMBURSEMENT: paid back for something bought for the group. CREDIT_PAYOUT: credit asked to be paid out, approved by the treasurer alone. More may be added

string
status
required

SUBMITTED (waiting for step 1), APPROVED (waiting for step 2, the treasurer), READY_TO_PAY, PAYING (2.46.0: sent by direct deposit from the group’s bank, on its way), PAID, DENIED (it can be edited and sent again), WITHDRAWN. More may be added

string
step
required

The step it waits on: 1 or 2; null once both are done or it is closed

integer | null
amount
required
object
amount
required

A decimal string, e.g. “25.00”: never a float.

string
/^-?\d+\.\d{2}$/
currency
required

ISO 4217, e.g. “USD”.

string
/^[A-Z]{3}$/
eventId
required

The event it was for; null for anything else, or once the event was deleted

string | null
eventName
required

The event’s name when it was asked, kept if the event is deleted

string | null
memo
required

What was bought, or a payout’s note

string | null
payee
required

Who is paid: whoever asked, by their roster entry

object
contactId
required

Their roster entry; null once it is gone

string | null
name
required

Null for a youth unless the app has roster.youth.read; a key never gets a youth’s name

string | null
payoutMethod
required

RECORDED: the treasurer pays it outside Grouperly. CREDIT: credited to the payee’s account at the treasurer’s approval. ACH and CHECK (2.45.0): the person would like direct deposit or a mailed check from the group’s bank; the treasurer chooses in the end. More may be added

string
creditAccountId
required

A credit payout’s account (GET /credit)

string | null
creditOf
required
One of:
object
contactId
required

Their roster entry; null once it is gone

string | null
name
required

Null for a youth unless the app has roster.youth.read; a key never gets a youth’s name

string | null
fromRestricted
required

A payout of restricted credit, against a receipt and a note

boolean
receiptCount
required

Receipts sent with it. They are opened in Grouperly

integer
mine
required

The person asked for it

boolean
submittedAt
required

When it was last sent

string format: date-time
firstApprovedAt
required

Step 1

string | null format: date-time
approvedAt
required

Step 2, the treasurer

string | null format: date-time
deniedAt
required
string | null format: date-time
denyReason
required
string | null
withdrawnAt
required
string | null format: date-time
paidAt
required
string | null format: date-time
paid
required
One of:
object
method
required

How it was paid outside Grouperly (Cash, Check, Venmo, Zelle, Other), or Credit

string | null
reference
required

A check’s number, or a note

string | null
paidOn
required

The day it was paid

string | null format: date
nextCursor
required

Pass as ?cursor= for the next page; null on the last page.

string | null
Examplegenerated
{
"items": [
{
"id": "example",
"number": 1,
"kind": "example",
"status": "example",
"step": 1,
"amount": {
"amount": "example",
"currency": "example"
},
"eventId": "example",
"eventName": "example",
"memo": "example",
"payee": {
"contactId": "example",
"name": "example"
},
"payoutMethod": "example",
"creditAccountId": "example",
"creditOf": {
"contactId": "example",
"name": "example"
},
"fromRestricted": true,
"receiptCount": 1,
"mine": true,
"submittedAt": "2026-04-15T12:00:00Z",
"firstApprovedAt": "2026-04-15T12:00:00Z",
"approvedAt": "2026-04-15T12:00:00Z",
"deniedAt": "2026-04-15T12:00:00Z",
"denyReason": "example",
"withdrawnAt": "2026-04-15T12:00:00Z",
"paidAt": "2026-04-15T12:00:00Z",
"paid": {
"method": "example",
"reference": "example",
"paidOn": "2026-04-15"
}
}
],
"nextCursor": "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)

A query parameter is malformed or unknown (invalid_parameter, with parameter)

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

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