POST users

POST Creates a new user account. The created user account is regular account, and not in any way associated with the organization of the user making this call.

Resource URL

https://www.drillster.com/api/2/users

Parameters

Field Description
emailAddress
optional

The email address of the user. The email address is used by Drillster to communicate with the user, and might be used by the user to login. An email address or a third-party identity must be provided, or both.

Example value: alice@example.com

name
required

The full name of the user.

Example value: Alice Smith

locale
optional

The preferred language of the 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

gender
optional

The gender of the user.

Possible values:

  • MALE
  • FEMALE

yearOfBirth
optional

The year of birth of the user, expressed in four digits.

Example value: 1974

timeZone
optional

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

domicile
optional

The country the new user resides in. The value must be a two-character ISO 3166-1 country code.

Example value: US

options
optional

An array of options to be taken into account when creating the new user account.

Currently supported options are:

  • SEND_WELCOME_EMAIL – whether to send the new user a welcome email
  • ADD_EXAMPLE_DRILL – whether to add an example drill to the user's repertoire

password
optional, unavailable

The password for the new user account. This feature is restricted to a very limited set of client applications and is in principle not available for general use.

New accounts are usually set up without a password, and users can set their own password in their profile screen, or request access through the “No password“ link.

thirdParty
optional

The identifier of the third-party that is setting up the new user account. The calling user must be authorized to use this third-party. A thirdPartyId must be provided, too.

thirdPartyId
optional

The ID that uniquely identifies the new user within the third-party. If a third-party ID is provided, the emailAddress is optional.

Response

A 2.0 User object with only the ID of the created user populated. This ID should be stored by the client to be able to refer to the user in future requests. If the user already exists, a 2.0 AccountAlreadyExistsError is returned. This error message contains the user ID.

Example request

In the below example it is assumed that the new user account does not yet exist in the Drillster system.

POST https://www.drillster.com/api/2/users
emailAddress=alice%40example.com
name=Alice+Smith
timeZone=America%2fChicago
yearOfBirth=1980
locale=en
domicile=US

Response

If the user did not previously exist, a User object with the user ID populated is returned:

{
  "type": "USER",
  "id" : "3mhUfNhHQzqTCN0oZLcsJg"
}

If the request is repeated (meaning that the user account will already exist), the following error response should be expected:

{
  "id" : "account_exists",
  "description" : "The given email address is linked to an existing account",
  "userId" : "3mhUfNhHQzqTCN0oZLcsJg"
}

Error responses

The following error situations are possible:

ID Response code Description
account_exists 400 (Bad request) An account already exists for the specified email address. The user ID for the existing account is given (see above example).
no_permission 403 (Forbidden) Caller does not have the permission to create new accounts.
email_address_not_specified 400 (Bad request) No email address was specified.
real_name_not_specified 400 (Bad request) No real name was specified.
email_address_invalid 400 (Bad request) An invalid email address was specified. Trying again with this email address will not help.
locale_invalid 400 (Bad request) An invalid locale was specified. Only ISO 639-1 values are allowed.
gender_invalid 400 (Bad request) An invalid gender was specified. Only male and female are allowed.
invalid_time_zone 400 (Bad request) An invalid time zone was specified. Only these time zone IDs are allowed.
year_of_birth_invalid 400 (Bad request) An invalid year of birth was specified. Only 4-digit years are allowed.
residence_country_invalid 400 (Bad request) The given residence country code is invalid. Only ISO 3166-1 values are allowed.
option_invalid 400 (Bad request) The given option or options are invalid.
domain_restricted 403 (Forbidden) The domain of the given email address may not be used for creating new accounts.