PUT group/…/members

PUT Adds a user to a group.

This user can be an existing Drillster user, or somebody who does not yet have a Drillster account in which case an account will be created on the fly. If the user is successfully added, he or she will receive anotification by email.

Resource URL

https://www.drillster.com/api/2/group/{group_id}/members/{user_id}

or

https://www.drillster.com/api/2/group/{group_id}/members/{user_email}

or

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

The group ID is the unique identifier for the group.

To identify the invited user, the user ID can be specified (if the user is an existing Drillster user, and the user ID is known), or the email address. The email address can be used for users with or without a Drillster account. If the user already has a Drillster account, the email address must be one of the email addresses configured in the account's profile. Alternatively, a supported third party ID may 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.

Currently supported language codes by Drillster are:

  • en
  • es
  • fr
  • de
  • nl
  • zh

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.

gender
optional
String

The gender of the user.

Possible values:

  • MALE
  • FEMALE

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.

The parameters must be appended to the URL, and not be included in the message body. For example:
/api/2/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.0 OK object containing a message stating that the user has successfully been invited.

Example request

PUT https://www.drillster.com/api/2/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_specified400 (Bad request)No user was specified in the request.
name_missing400 (Bad request)Unable to set up a new account, because no name is provided.
locale_invalid400 (Bad request)An invalid locale was specified. Only ISO 639-1 values are allowed.
gender_invalid400 (Bad request)An invalid gender was specified. Only MALE and FEMALE are allowed.
year_of_birth_invalid400 (Bad request)An invalid year of birth was specified. Only 4-digit years are allowed.
invalid_time_zone400 (Bad request)An invalid time zone was specified. Only these time zone IDs are allowed.
residence_country_invalid400 (Bad request)The given residence country code is invalid. Only ISO 3166-1 values are allowed.
group_not_found404 (Not found)Could not retrieve group details.
already_invited400 (Bad request)The given user is already invited to the group.
invitation_quota_reached400 (Bad request)The maximum number of members or invitations has been reached for this organization.
privacy_storage_location_conflict400 (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_access403 (Forbidden)The user lacks access to the catalog that this group is restricted to.
error500 (Internal error)Error while joining the group or setting up the new account.
unknown_user404 (Not found)Given user ID is not known.
invalid_email_address400 (Bad request)The given email address is not valid.
email_address_missing400 (Bad request)Unable to invite user, because no email address is provided.
operation_not_allowed400 (Bad request)The organization settings do not allow creating new group member accounts.
no_user400 (Bad request)Cannot add an unknown user to a group.
duplicate_third_party400 (Bad request)There is already an account with this third party id.
duplicate_email400 (Bad request)There is already an account with this email.