POST groups

Creates a new group.

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.

Resource URL

https://www.drillster.com/api/2.1.1/groups

Parameters

Field Type Description
name
required		 String The name of the new group.
description
required		 String A description of the new group.
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.
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.
subscriptionEndYear
optional		 Integer The (4-digit) year to end the subscriptions. Required for one-off terminations.
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)

Response

A 2.1.1 Group object including the newly assigned group ID.

Error responses

The following error situations are possible:

ID Response code Description
name_missing 400 (Bad request) No group name specified
description_missing 400 (Bad request) No group description specified
invalid_catalog_restriction_mode 400 (Bad request) Catalog restriction mode is not valid
no_permission 403 (Forbidden) Caller is not allowed to create groups, 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

 

Last updated on