POST users

Creates a new user account. Depending on the context, the created user account is either a private account, or an account managed by the calling organization.

If the call to this endpoint is made in an unauthenticated way, the resulting account will be a private account. Private accounts are not associated with any organizations. If the request is made by one of an organization's administrators, the resulting account is set up as "managed by" that organization.

Resource URL


Field Description
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:
The full name of the user.

Example value: Alice Smith
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
Example value: fr
The year of birth of the user, expressed in four digits.

Example value: 1974
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
The country the new user resides in. The value must be a two-character πŸ”— ISO 3166-1 country code.

Example value: US
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
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.
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.
The ID that uniquely identifies the new user within the third-party. Contents restrictions apply. If a third-party ID is provided, the emailAddress is optional.


A 2.1.1 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.1.1 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.



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.
invalid_third_party_id 400 (Bad request) An invalid third party ID was specified. Contents restrictions apply.
locale_invalid 400 (Bad request) An invalid locale was specified. Only ISO 639-1 values 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.