Users

>>>

POST /api/v1/users
Create new user

Params

Param name Description
email
optional , blank allowed

Validations:

  • Must be a String
mobile
optional , blank allowed

Validations:

  • Must be a String
origin_id
optional , blank allowed

ID in the previous database

Validations:

  • Must be a String
username
optional , blank allowed

username will be mandatory only if multiple users share same email

Validations:

  • Must be a String
encrypted_password
optional , blank allowed

Encrypted password in the previous database

Validations:

  • Must be a String
custom_pepper
optional , blank allowed

The pepper which have been used to encrypt the password

Validations:

  • Must be a String
google_id
optional , blank allowed

UID of a Google account linked to this user

Validations:

  • Must be a String
apple_id
optional , blank allowed

UID of an Apple account linked to this user

Validations:

  • Must be a String
email_confirmed
optional , blank allowed

Wether the user email have already been confirmed or not

Validations:

  • Must be one of: true, false, true, false.
given_name
optional , blank allowed

Validations:

  • Must be a String
family_name
optional , blank allowed

Validations:

  • Must be a String
non_latin_given_name
optional , blank allowed

Validations:

  • Must be a String
non_latin_family_name
optional , blank allowed

Validations:

  • Must be a String
male
optional , blank allowed

Gender: Wether the user is a male or female

Validations:

  • Must be one of: true, false, true, false.
birthdate
optional , blank allowed

Validations:

  • Must be a String
primary_country
optional , blank allowed

Alpha2 code of the country where the user do most of its Vipassana activity just give address country if you are not sure

Validations:

  • Must be a String
old_student
optional , blank allowed

Have the user already completed a 10day course?

Validations:

  • Must be one of: true, false, true, false.
is_at
optional , blank allowed

Is the user an assistant teacher?

Validations:

  • Must be one of: true, false, true, false.
at_code
optional , blank allowed

Assistant teacher code, for example AD5, YNP, NJ

Validations:

  • Must be a String
is_cct
optional , blank allowed

Is the user an children course teacher?

Validations:

  • Must be one of: true, false, true, false.
student_account_app
optional , blank allowed

Which student app should be used. If not provided, it will be automatically detected from primary_country

Validations:

  • Must be one of: mycourses, do_student_account.
password_required
optional , blank allowed

If the user is required to setup a password (otherwise they might only sign in with external providers such as google or office365)

Validations:

  • Must be one of: true, false, true, false.
require_mfa_from_date
optional , blank allowed

Date after which the user will have to set up MFA for her account. Format must be YYYY-MM-DD. Users are automatically emailed when a date is set and reminded one week before the date.

Validations:

  • Must be a String
office365_id
optional , blank allowed

UID of an Office365 account linked to this user. Can be updated only if the current value is blank.

Validations:

  • Must be a String
office365_email
optional , blank allowed

Office365 email of this user, something like [email protected]

Validations:

  • Must be a String
locale
optional , blank allowed

Locale for confirmation and MFA emails (en, fr, de, hi…)

Validations:

  • Must be a String

Returns

Code: 200

Description:

User object in JSON format with the keys: id, email, birthdate, given_name, family_name, non_latin_given_name, non_latin_family_name, primary_country, male, invited_to_url, username, old_student, office365_email, duplicates_ids, student_account_app, is_at, at_code, is_cct, mobile, confirmed, sign_up_complete, session_info, student_account_url, mfa_set_up

Param name Description

Code: 422

Description:

Validation errors in format: {error: {field_name: ["error message 1", "error message 2"]}}

Param name Description

Code: 401

Description:

Unauthorized - invalid or missing OAuth token

Param name Description
>>>

POST /api/v1/users/create_bulk
Create multiple users. Used for migration

Params

Param name Description
users
optional

Users to import

Validations:

  • Must be an Array of nested elements
users[vis_id]
optional , blank allowed

ID in VIS database. In case some of the users you try to create have already been created before. So the API call is idempotent

Validations:

  • Must be a String
users[invite]
optional , blank allowed

Wether to invite users without any authentication strategy

Validations:

  • Must be one of: true, false, true, false.
users[locale]
optional , blank allowed

Locale for invitation and MFA emails (en, fr, de, hi…)

Validations:

  • Must be a String
users[invited_to_url]
optional , blank allowed

Customize the url to redirect the user afer invitation is accepted. Default to OauthApplication home_page

Validations:

  • Must be a String
users[email]
optional , blank allowed

Validations:

  • Must be a String
users[mobile]
optional , blank allowed

Validations:

  • Must be a String
users[origin_id]
optional , blank allowed

ID in the previous database

Validations:

  • Must be a String
users[username]
optional , blank allowed

username will be mandatory only if multiple users share same email

Validations:

  • Must be a String
users[encrypted_password]
optional , blank allowed

Encrypted password in the previous database

Validations:

  • Must be a String
users[custom_pepper]
optional , blank allowed

The pepper which have been used to encrypt the password

Validations:

  • Must be a String
users[google_id]
optional , blank allowed

UID of a Google account linked to this user

Validations:

  • Must be a String
users[apple_id]
optional , blank allowed

UID of an Apple account linked to this user

Validations:

  • Must be a String
users[email_confirmed]
optional , blank allowed

Wether the user email have already been confirmed or not

Validations:

  • Must be one of: true, false, true, false.
users[given_name]
optional , blank allowed

Validations:

  • Must be a String
users[family_name]
optional , blank allowed

Validations:

  • Must be a String
users[non_latin_given_name]
optional , blank allowed

Validations:

  • Must be a String
users[non_latin_family_name]
optional , blank allowed

Validations:

  • Must be a String
users[male]
optional , blank allowed

Gender: Wether the user is a male or female

Validations:

  • Must be one of: true, false, true, false.
users[birthdate]
optional , blank allowed

Validations:

  • Must be a String
users[primary_country]
optional , blank allowed

Alpha2 code of the country where the user do most of its Vipassana activity just give address country if you are not sure

Validations:

  • Must be a String
users[old_student]
optional , blank allowed

Have the user already completed a 10day course?

Validations:

  • Must be one of: true, false, true, false.
users[is_at]
optional , blank allowed

Is the user an assistant teacher?

Validations:

  • Must be one of: true, false, true, false.
users[at_code]
optional , blank allowed

Assistant teacher code, for example AD5, YNP, NJ

Validations:

  • Must be a String
users[is_cct]
optional , blank allowed

Is the user an children course teacher?

Validations:

  • Must be one of: true, false, true, false.
users[student_account_app]
optional , blank allowed

Which student app should be used. If not provided, it will be automatically detected from primary_country

Validations:

  • Must be one of: mycourses, do_student_account.
users[password_required]
optional , blank allowed

If the user is required to setup a password (otherwise they might only sign in with external providers such as google or office365)

Validations:

  • Must be one of: true, false, true, false.
users[require_mfa_from_date]
optional , blank allowed

Date after which the user will have to set up MFA for her account. Format must be YYYY-MM-DD. Users are automatically emailed when a date is set and reminded one week before the date.

Validations:

  • Must be a String
users[office365_id]
optional , blank allowed

UID of an Office365 account linked to this user. Can be updated only if the current value is blank.

Validations:

  • Must be a String
users[office365_email]
optional , blank allowed

Office365 email of this user, something like [email protected]

Validations:

  • Must be a String

Returns

Code: 200

Description:

Bulk import result with summary statistics, imported users array, errors array, and ignored users array. Response format: {summary: {message: string, created_count: number, failure_count: number, invited_count: number, ignored_count: number}, users: [user objects], errors: [{error: string, data: object}], ignored: [user objects]}

Param name Description

Code: 422

Description:

Error message in format: {error: error message}

Param name Description

Code: 401

Description:

Unauthorized - invalid or missing OAuth token

Param name Description
>>>

POST /api/v1/users/:id/update
Update existing user. Non-blank string fields cannot be set to blank values - such attempts will be silently ignored and the original value will be retained.

Params

Param name Description
id
required

ID of the user to update

Validations:

  • Must be a String
given_name
optional , blank allowed

Validations:

  • Must be a String
family_name
optional , blank allowed

Validations:

  • Must be a String
non_latin_given_name
optional , blank allowed

Validations:

  • Must be a String
non_latin_family_name
optional , blank allowed

Validations:

  • Must be a String
male
optional , blank allowed

Gender: Wether the user is a male or female

Validations:

  • Must be one of: true, false, true, false.
birthdate
optional , blank allowed

Validations:

  • Must be a String
primary_country
optional , blank allowed

Alpha2 code of the country where the user do most of its Vipassana activity just give address country if you are not sure

Validations:

  • Must be a String
old_student
optional , blank allowed

Have the user already completed a 10day course?

Validations:

  • Must be one of: true, false, true, false.
is_at
optional , blank allowed

Is the user an assistant teacher?

Validations:

  • Must be one of: true, false, true, false.
at_code
optional , blank allowed

Assistant teacher code, for example AD5, YNP, NJ

Validations:

  • Must be a String
is_cct
optional , blank allowed

Is the user an children course teacher?

Validations:

  • Must be one of: true, false, true, false.
student_account_app
optional , blank allowed

Which student app should be used. If not provided, it will be automatically detected from primary_country

Validations:

  • Must be one of: mycourses, do_student_account.
password_required
optional , blank allowed

If the user is required to setup a password (otherwise they might only sign in with external providers such as google or office365)

Validations:

  • Must be one of: true, false, true, false.
require_mfa_from_date
optional , blank allowed

Date after which the user will have to set up MFA for her account. Format must be YYYY-MM-DD. Users are automatically emailed when a date is set and reminded one week before the date.

Validations:

  • Must be a String
office365_id
optional , blank allowed

UID of an Office365 account linked to this user. Can be updated only if the current value is blank.

Validations:

  • Must be a String
office365_email
optional , blank allowed

Office365 email of this user, something like [email protected]

Validations:

  • Must be a String

Returns

Code: 200

Description:

Updated user object in JSON format with the keys: id, email, birthdate, given_name, family_name, non_latin_given_name, non_latin_family_name, primary_country, male, invited_to_url, username, old_student, office365_email, duplicates_ids, student_account_app, is_at, at_code, is_cct, mobile, confirmed, sign_up_complete, session_info, student_account_url, mfa_set_up

Param name Description

Code: 422

Description:

Validation errors or user not found, in format: {error: error message}

Param name Description

Code: 400

Description:

Error message for invalid operations (e.g., trying to update generic oldstudent record), in format: {error: error message}

Param name Description

Code: 401

Description:

Unauthorized - invalid or missing OAuth token

Param name Description
>>>

POST /api/v1/users/invite
Invite by email a user to create an account, or to join an other app if they already have an account

Params

Param name Description
email
optional , blank allowed

Validations:

  • Must be a String
username
optional , blank allowed

Required if the email is shared accross multiple users

Validations:

  • Must be a String
id
optional , blank allowed

VIS ID of an existing user, in case you just want to invite an existing user to a new app

Validations:

  • Must be a String
locale
optional , blank allowed

Locale for invitation and MFA emails (en, fr, de, hi…)

Validations:

  • Must be a String
app_name
optional , blank allowed

Customize APP_NAME in following email. Default to OauthApplication name Hello, you have been invited to APP_NAME, click link below to accept

Validations:

  • Must be a String
invited_to_url
optional , blank allowed

Customize the url to redirect the user afer invitation is accepted. Default to OauthApplication home_page

Validations:

  • Must be a String
try_to_find_existing_user
optional , blank allowed

Will try to find an existing user by the params supplied, instead of creating a new one

Validations:

  • Must be one of: true, false, true, false.
given_name
optional , blank allowed

Validations:

  • Must be a String
family_name
optional , blank allowed

Validations:

  • Must be a String
non_latin_given_name
optional , blank allowed

Validations:

  • Must be a String
non_latin_family_name
optional , blank allowed

Validations:

  • Must be a String
male
optional , blank allowed

Gender: Wether the user is a male or female

Validations:

  • Must be one of: true, false, true, false.
birthdate
optional , blank allowed

Validations:

  • Must be a String
primary_country
optional , blank allowed

Alpha2 code of the country where the user do most of its Vipassana activity just give address country if you are not sure

Validations:

  • Must be a String
old_student
optional , blank allowed

Have the user already completed a 10day course?

Validations:

  • Must be one of: true, false, true, false.
is_at
optional , blank allowed

Is the user an assistant teacher?

Validations:

  • Must be one of: true, false, true, false.
at_code
optional , blank allowed

Assistant teacher code, for example AD5, YNP, NJ

Validations:

  • Must be a String
is_cct
optional , blank allowed

Is the user an children course teacher?

Validations:

  • Must be one of: true, false, true, false.
student_account_app
optional , blank allowed

Which student app should be used. If not provided, it will be automatically detected from primary_country

Validations:

  • Must be one of: mycourses, do_student_account.
password_required
optional , blank allowed

If the user is required to setup a password (otherwise they might only sign in with external providers such as google or office365)

Validations:

  • Must be one of: true, false, true, false.
require_mfa_from_date
optional , blank allowed

Date after which the user will have to set up MFA for her account. Format must be YYYY-MM-DD. Users are automatically emailed when a date is set and reminded one week before the date.

Validations:

  • Must be a String
office365_id
optional , blank allowed

UID of an Office365 account linked to this user. Can be updated only if the current value is blank.

Validations:

  • Must be a String
office365_email
optional , blank allowed

Office365 email of this user, something like [email protected]

Validations:

  • Must be a String

Returns

Code: 200

Description:

Invitation result with success code and user object. Response format: {invite_success_code: 'invited'|'existing_user_invited', user: user_object}

Param name Description

Code: 422

Description:

Validation errors in format: {error: error_message}

Param name Description

Code: 400

Description:

Error message for invalid operations (e.g., trying to invite generic oldstudent record), in format: {error: error_message}

Param name Description

Code: 401

Description:

Unauthorized - invalid or missing OAuth token

Param name Description
>>>

GET /api/v1/users/:id/resend_invite
Resend invitation email

Params

Param name Description
id
required

ID of the user

Validations:

  • Must be a String
locale
optional , blank allowed

Locale for invitation email (en, fr, de, hi…)

Validations:

  • Must be a String

Returns

Code: 200

Description:

User object in JSON format after resending invitation, with the keys: id, email, birthdate, given_name, family_name, non_latin_given_name, non_latin_family_name, primary_country, male, invited_to_url, username, old_student, office365_email, duplicates_ids, student_account_app, is_at, at_code, is_cct, mobile, confirmed, sign_up_complete, session_info, student_account_url, mfa_set_up

Param name Description

Code: 422

Description:

User not found

Param name Description

Code: 400

Description:

Error message for invalid operations (e.g., trying to resend invite to generic oldstudent record), in format: {error: error_message}

Param name Description

Code: 401

Description:

Unauthorized - invalid or missing OAuth token

Param name Description
>>>

DELETE /api/v1/users/:id
Delete user mapping with the calling app. Delete the user entirely if it is not mapped to any other app.

Params

Param name Description
id
required

ID of the user

Validations:

  • Must be a String

Returns

Code: 200

Description:

Success confirmation in format: {success: true}

Param name Description

Code: 400

Description:

Error message for invalid operations (e.g., trying to destroy generic oldstudent record), in format: {error: error_message}

Param name Description

Code: 401

Description:

Unauthorized - invalid or missing OAuth token

Param name Description
>>>

DELETE /api/v1/users/:id/reset_totp
Reset the user's TOTP secret

Params

Param name Description
id
required

ID of the user whose TOTP secret should be cleared

Validations:

  • Must be a String

Returns

Code: 200

Description:

Updated user object in JSON format with the keys: id, email, birthdate, given_name, family_name, non_latin_given_name, non_latin_family_name, primary_country, male, invited_to_url, username, old_student, office365_email, duplicates_ids, student_account_app, is_at, at_code, is_cct, mobile, confirmed, sign_up_complete, session_info, student_account_url, mfa_set_up

Param name Description

Code: 400

Description:

Error message when the TOTP secret cannot be reset, in format: {error: error_message}

Param name Description

Code: 401

Description:

Unauthorized - invalid or missing OAuth token

Param name Description
>>>

GET /api/v1/users/find_by_credentials
Find a user from its login and password

Params

Param name Description
login
required

Email or username

Validations:

  • Must be a String
password
required

Non encrypted password

Validations:

  • Must be a String

Returns

Code: 200

Description:

User object in JSON format when credentials are valid, with the keys: id, email, birthdate, given_name, family_name, non_latin_given_name, non_latin_family_name, primary_country, male, invited_to_url, username, old_student, office365_email, duplicates_ids, student_account_app, is_at, at_code, is_cct, mobile, confirmed, sign_up_complete, session_info, student_account_url, mfa_set_up

Param name Description

Code: 400

Description:

Error message for various authentication failures (not_found, non_uniq_login, unconfirmed, invalid_password), in format: {error: error_code}

Param name Description

Code: 401

Description:

Unauthorized - invalid or missing OAuth token

Param name Description
>>>

POST /api/v1/users/find_or_create_by_provider
Find a user from external provider id

Params

Param name Description
provider
required

Provider name (google, apple, office365)

Validations:

  • Must be a String
uid
required

ID of the user given by provider

Validations:

  • Must be a String
email
optional , blank allowed

Validations:

  • Must be a String
mobile
optional , blank allowed

Validations:

  • Must be a String
origin_id
optional , blank allowed

ID in the previous database

Validations:

  • Must be a String
username
optional , blank allowed

username will be mandatory only if multiple users share same email

Validations:

  • Must be a String
encrypted_password
optional , blank allowed

Encrypted password in the previous database

Validations:

  • Must be a String
custom_pepper
optional , blank allowed

The pepper which have been used to encrypt the password

Validations:

  • Must be a String
google_id
optional , blank allowed

UID of a Google account linked to this user

Validations:

  • Must be a String
apple_id
optional , blank allowed

UID of an Apple account linked to this user

Validations:

  • Must be a String
email_confirmed
optional , blank allowed

Wether the user email have already been confirmed or not

Validations:

  • Must be one of: true, false, true, false.
given_name
optional , blank allowed

Validations:

  • Must be a String
family_name
optional , blank allowed

Validations:

  • Must be a String
non_latin_given_name
optional , blank allowed

Validations:

  • Must be a String
non_latin_family_name
optional , blank allowed

Validations:

  • Must be a String
male
optional , blank allowed

Gender: Wether the user is a male or female

Validations:

  • Must be one of: true, false, true, false.
birthdate
optional , blank allowed

Validations:

  • Must be a String
primary_country
optional , blank allowed

Alpha2 code of the country where the user do most of its Vipassana activity just give address country if you are not sure

Validations:

  • Must be a String
old_student
optional , blank allowed

Have the user already completed a 10day course?

Validations:

  • Must be one of: true, false, true, false.
is_at
optional , blank allowed

Is the user an assistant teacher?

Validations:

  • Must be one of: true, false, true, false.
at_code
optional , blank allowed

Assistant teacher code, for example AD5, YNP, NJ

Validations:

  • Must be a String
is_cct
optional , blank allowed

Is the user an children course teacher?

Validations:

  • Must be one of: true, false, true, false.
student_account_app
optional , blank allowed

Which student app should be used. If not provided, it will be automatically detected from primary_country

Validations:

  • Must be one of: mycourses, do_student_account.
password_required
optional , blank allowed

If the user is required to setup a password (otherwise they might only sign in with external providers such as google or office365)

Validations:

  • Must be one of: true, false, true, false.
require_mfa_from_date
optional , blank allowed

Date after which the user will have to set up MFA for her account. Format must be YYYY-MM-DD. Users are automatically emailed when a date is set and reminded one week before the date.

Validations:

  • Must be a String
office365_id
optional , blank allowed

UID of an Office365 account linked to this user. Can be updated only if the current value is blank.

Validations:

  • Must be a String
office365_email
optional , blank allowed

Office365 email of this user, something like [email protected]

Validations:

  • Must be a String

Returns

Code: 200

Description:

User object in JSON format (existing or newly created), with the keys: id, email, birthdate, given_name, family_name, non_latin_given_name, non_latin_family_name, primary_country, male, invited_to_url, username, old_student, office365_email, duplicates_ids, student_account_app, is_at, at_code, is_cct, mobile, confirmed, sign_up_complete, session_info, student_account_url, mfa_set_up

Param name Description

Code: 422

Description:

Validation errors when creating new user, in format: {error: {field_name: ["error message 1", "error message 2"]}}

Param name Description

Code: 401

Description:

Unauthorized - invalid or missing OAuth token

Param name Description
>>>

POST /api/v1/users/send_password_instructions
Send password reset instructions

Params

Param name Description
login
required

Email or username

Validations:

  • Must be a String
locale
optional , blank allowed

Locale for email (en, fr, de, hi…)

Validations:

  • Must be a String

Returns

Code: 200

Description:

Success confirmation in format: {success: true}

Param name Description

Code: 400

Description:

Error message for various failures (not_found, non_uniq_login, or generic oldstudent), in format: {error: error_message}

Param name Description

Code: 401

Description:

Unauthorized - invalid or missing OAuth token

Param name Description
>>>

POST /api/v1/users/send_confirmation_instructions
Send email confirmation instructions

Params

Param name Description
login
required

Email or username

Validations:

  • Must be a String
locale
optional , blank allowed

Locale for email (en, fr, de, hi…)

Validations:

  • Must be a String

Returns

Code: 200

Description:

Success confirmation in format: {success: true}

Param name Description

Code: 400

Description:

Error message for various failures (not_found, non_uniq_login, or generic oldstudent), in format: {error: error_message}

Param name Description

Code: 401

Description:

Unauthorized - invalid or missing OAuth token

Param name Description