Skip to content

Change a roster entry's custom fields

PATCH
/groups/{groupId}/contacts/{contactId}/custom-fields
curl --request PATCH \
--url https://app.grouperly.com/api/v2/groups/example/contacts/example/custom-fields \
--header 'Authorization: Bearer <token>' \
--header 'Content-Type: application/json' \
--data '{ "values": { "additionalProperty": "example" } }'

Each key sent replaces that field’s value, null clears it, and a field not sent stays as it is. Values are checked against their fields (GET /field-definitions): a value that doesn’t fit, or a key that isn’t a field on this kind of entry, is a 400 invalid_body with parameter values, and nothing changes.

As editing the entry in Grouperly: the group’s leaders. A youth’s need roster.youth.write (first-party apps). A health form’s date can’t be changed through the API by a key or a partner app. Changing something sends contact.changed. Returns the entry’s fields as the caller now sees them (added in 2.34.0).

An app’s own fields (source APP, <slug>.<key>) only from that app’s token with app_data.rw too (insufficient_scope); another app’s are refused (forbidden), and nobody else changes them (2.41.0).

groupId
required
string

The credential’s group

contactId
required
string

A roster entry of the group (Contact.id)

Media typeapplication/json
object
values
required

The fields to change, by key (GET /field-definitions): each replaces its value, null clears it, and a field not sent stays as it is. Text as text, a number as a number, yes or no as true or false, a date as “YYYY-MM-DD”, a choice as its option’s value.

object
<= 100 properties
key
additional properties
string | number | boolean | null
Examplegenerated
{
"values": {
"additionalProperty": "example"
}
}

OK

Media typeapplication/json
object
contactId
required
string
customFields
required

Its custom fields that the caller sees now, by key, null where one isn’t set

object
key
additional properties
string | number | boolean | null
Examplegenerated
{
"contactId": "example",
"customFields": {
"additionalProperty": "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)

The body isn’t a JSON object of at most 16 KB, or a field is unknown, missing or malformed (invalid_body, 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. Also: the entry is a youth and the app hasn’t roster.youth.write (insufficient_scope), the person doesn’t lead the group (forbidden), a key or partner app sent a health form’s date (forbidden), or another app’s field (forbidden), or its own without app_data.rw (insufficient_scope)

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