PUT group/…

Updates group details.

Subscription termination

Group memberships are more generically called subscriptions.

Subscriptions can be ended automatically. There are a few different ways to define when the subscriptions will end.

One-off a single date is set, at which all subscriptions that exist at that moment will end.
Annual a date is set, and every year all subscriptions that exist at that moment will end.
Monthly a day of the month is set, and every month all subscriptions that exist at that moment will end.
Duration a duration is set, and every subscription that exists for this duration will end.

How to configure this is explained in detail in the subscription parameters below.

To disable a previously configured subscription termination, submit subscriptionEndYear=0, without providing any other subscription parameters.

Resource URL

https://www.drillster.com/api/2.1.1/group/{group_id}

Parameters

Field	Type	Description
`group_id` required	String	The ID of the group. Example value: `pX3rn8LnXn5QM3mzwmSXDnDYeDpsnIqsHoXEKN2N3_B`.
`name` required	String	The name of the group.
`description` required	String	The group's description.
`iconKey` optional	String	A reference to a previously uploaded icon.
`catalogRestriction` optional	String	The ID of a catalog to restrict this group to. A restricted group only allows content from this catalog, and users having access to this catalog. A catalog restriction can only be set to a group if it currently does not contain any content (drills) or members.
`catalogRestrictionMode` optional	String	If a `catalogRestriction` is specified, the mode determines the requirement for users to join the group. Two modes exist: `REQUIRE` (default) A user must have access to the catalog in order to join the group. `GRANT` A user will be granted access to the catalog when he joins the group. The `GRANT` mode can only be used if the owner of the catalog has granted explicit permission to the organization of this group to use this mode.
`catalogRestrictionRemove` optional	Boolean	`true` must be specified to remove an existing restriction. A restriction can only be removed if the group is completely empty (no content and no members). `catalogRestriction` must not be specified.
`subscriptionEndYear` optional	Integer	The (4-digit) year to end the subscriptions. Required for one-off terminations. To remove any previously configured subscription termination settings, submit `0`.
`subscriptionEndMonth` optional	Integer	The month to end the subscriptions (`1` to `12`). Required for one-off and annual terminations.
`subscriptionEndDay` optional	Integer	The day of the month to end the subscriptions. Required for one-off, annual and monthly terminations. For monthly terminations, up to `28` can be specified, or `0` to indicate the last day of the month. For annual terminations, specifying leap day (29 February) is not allowed.
`subscriptionEndTime` optional	String	The time of the day to end the subscriptions. Can be specified for one-off, annual and monthly terminations. Format: `HH:MM`, using 24-hour notation. If omitted, midnight (`00:00`) is used. Example value: `18:30`
`subscriptionEndTimeZone` optional	String	The time zone of the configured subscription end date/time. Can be specified for one-off, annual and monthly terminations. Values are as defined by the 🔗 IANA Time Zone Database. This document provides a full list of time zone IDs. If omitted, the time zone of the account making the request is used. If the account has no configured time zone, the time zone of the account's organization is used. If the organization has no configured time zone, `UTC` is used.
`subscriptionDuration` optional	String	The maximum duration of the subscriptions. The subscription is terminated when it exists for this duration. The duration is specified in 🔗 ISO-8601 format, but without a time component. Example value: `P6M` (6 months)

If a PUT request has no body (i.e. the body is empty), it is still mandatory to include a Content-Length header (i.e. Content-Length: 0). Not all HTTP clients do this automatically. For more information, please see RFC 2616.

Response

A 2.1.1 Group object, reflecting the updates.

Error responses

The following error situations are possible:

ID	Response code	Description
`not_found`	404 (Not found)	Group not found
`invalid_name`	400 (Bad request)	Given group name is not valid
`invalid_description`	400 (Bad request)	Given group description is not valid
`icon_upload_failed`	500 (Internal error)	Could not process group icon
`invalid_group_id`	400 (Bad request)	Group ID is not valid
`invalid_catalog_restriction_mode`	400 (Bad request)	Catalog restriction mode is not valid
`group_not_empty`	400 (Bad request)	A restriction was set or removed, but the group is not empty
`no_permission`	403 (Forbidden)	No permission to change group details, no access to the provided restriction catalog, or the catalog restriction mode can not be used for this catalog.
`invalid_subscription_end_day`	400 (Bad request)	Invalid subscription end day specified
`invalid_subscription_end_month`	400 (Bad request)	Invalid subscription end month specified
`invalid_subscription_end_year`	400 (Bad request)	Invalid subscription end year specified
`invalid_subscription_end_date`	400 (Bad request)	Invalid subscription end date specified
`invalid_subscription_end_time`	400 (Bad request)	Invalid subscription end time specified
`invalid_time_zone`	400 (Bad request)	Invalid subscription end time zone specified
`invalid_subscription_duration`	400 (Bad request)	Invalid subscription duration specified
`invalid_subscription_end_configuration`	400 (Bad request)	Invalid combination of subscription duration and date fields specified