PUT group/…/members/…/…

Adds a user to a group.

Resource URL

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

The group ID is the unique identifier for the group.

To identify the invited user, a supported third party ID must be specified.

Parameters

Field	Type	Description
`group_id` required	String	The unique identifier of the group. Example value: `nYrK9udUc-UGvRS2kxaPtaB-0wzeHAJzM6vlL1te6wI`
`user_id` or `user_email` required	String	The user ID or email address of the prospective group member.
`setup` optional	Boolean	Set this to `true` if auto-setup is enabled for your account, and you want the invited user's account automatically to be set up if it does not exist yet. In this case you must also specify a real name for the account. If you do not provide a real name, the request will end in error.
`sendWelcomeEmail` optional	Boolean	Set this to `true` to send new users a standard Drillster welcome email. This is only applicable to newly created accounts. If the user already had a Drillster account, no welcome messages are ever sent.
`name` optional	String	The real name of the invited user. This should only be provided if the user does not have a Drillster account yet, and auto-setup is enabled for your account, and setup is set to `true`.
`locale` optional	String	The preferred language of the new user. If supported by Drillster, this language will be used if the user logs in to the web interface. If not provided, the calling user's locale will be used. The value must be a 🔗 ISO 639-1 language code. Alternatively, a locale code may be specified consisting of a two-letter language code (ISO 639-1), and two-letter country code (ISO 3166-1 alpha-2) separated by an underscore character. Example value: `fr` Please note: This should only be provided if the user does not have a Drillster account yet, and auto-setup is enabled for your account, and setup is set to `true`. The value is ignored otherwise.
`yearOfBirth` optional	Integer	The year of birth of the user, expressed in four digits. Example value: `1974` Please note: This should only be provided if the user does not have a Drillster account yet, and auto-setup is enabled for your account, and setup is set to `true`. The value is ignored otherwise.
`timeZone` optional	String	The time zone that the user resides in. Values are as defined by the 🔗 IANA Time Zone Database. This document provides a full list of time zone IDs. Example values: `America/Los_Angeles` `Europe/Amsterdam` `Asia/Jakarta` Please note: This should only be provided if the user does not have a Drillster account yet, and auto-setup is enabled for your account, and setup is set to `true`. The value is ignored otherwise.
`domicile` optional	String	The country the new user resides in. The value must be a two-character 🔗 ISO 3166-1 country code. Example value: `US` Please note: This should only be provided if the user does not have a Drillster account yet, and auto-setup is enabled for your account, and setup is set to `true`. The value is ignored otherwise.

💡 Good to know

The parameters must be appended to the URL, and not be included in the message body. For example: /api/2.1.1/group/0kIpT-yh7l6dF0w4EWkRYaB-0wzeHAJzM6vlL1te6wI/members/john.doe@drillster.com?setup=true&name=John+Doe

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 OK object containing a message stating that the user has successfully been invited.

Example request

PUT https://www.drillster.com/api/2.1.1/group/0kIpT-yh7l6dF0w4EWkRYaB-0wzeHAJzM6vlL1te6wI/members/john.doe@drillster.com

Response

{
  "description": "The user has been invited to the group."
}

Error responses

The following error situations are possible:

ID	Response code	Description
`no_user_specified`	400 (Bad request)	No user was specified in the request.
`name_missing`	400 (Bad request)	Unable to set up a new account, because no name is provided.
`locale_invalid`	400 (Bad request)	An invalid locale was specified. Only ISO 639-1 values are allowed.
`year_of_birth_invalid`	400 (Bad request)	An invalid year of birth was specified. Only 4-digit years are allowed.
`invalid_time_zone`	400 (Bad request)	An invalid time zone was specified. Only 🔗 these time zone IDs are allowed.
`residence_country_invalid`	400 (Bad request)	The given residence country code is invalid. Only ISO 3166-1 values are allowed.
`group_not_found`	404 (Not found)	Could not retrieve group details.
`already_invited`	400 (Bad request)	The given user is already invited to the group.
`invitation_quota_reached`	400 (Bad request)	The maximum number of members or invitations has been reached for this organization.
`privacy_storage_location_conflict`	400 (Bad request)	There is a conflict between the invited user's privacy data storage location and the required privacy data storage location of the organization.
`user_lacks_required_catalog_access`	403 (Forbidden)	The user lacks access to the catalog that this group is restricted to.
`error`	500 (Internal error)	Error while joining the group or setting up the new account.
`unknown_user`	404 (Not found)	Given user ID is not known.
`invalid_email_address`	400 (Bad request)	The given email address is not valid.
`email_address_missing`	400 (Bad request)	Unable to invite user, because no email address is provided.
`operation_not_allowed`	400 (Bad request)	The organization settings do not allow creating new group member accounts.
`no_user`	400 (Bad request)	Cannot add an unknown user to a group.
`duplicate_third_party`	400 (Bad request)	There is already an account with this third party id.
`duplicate_email`	400 (Bad request)	There is already an account with this email.

Last updated on 2025-04-18