Create a new user

curl --request POST \
  --url https://myorg.tribalhabits.com/papi/users \
  --header 'Authorization: <api-key>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "user_name": "12345",
  "first_name": "Bilbo",
  "last_name": "Baggins",
  "email": "bilbo@myorg.com",
  "manager_email": "manager@company.com",
  "manager_2_email": "manager2@company.com",
  "mentor_email": "mentor@company.com",
  "lms_learner_id": "456",
  "lms_reference": "Testlms",
  "type": "Client",
  "role_1": "Instructor",
  "X-Country": "Australia",
  "X-State": "Queensland",
  "X-Preferred Name": "Jack",
  "groups": "Bundaberg;Brisbane",
  "goals": "Goal1;Goal2"
}
'

import requests

url = "https://myorg.tribalhabits.com/papi/users"

payload = {
    "user_name": "12345",
    "first_name": "Bilbo",
    "last_name": "Baggins",
    "email": "bilbo@myorg.com",
    "manager_email": "manager@company.com",
    "manager_2_email": "manager2@company.com",
    "mentor_email": "mentor@company.com",
    "lms_learner_id": "456",
    "lms_reference": "Testlms",
    "type": "Client",
    "role_1": "Instructor",
    "X-Country": "Australia",
    "X-State": "Queensland",
    "X-Preferred Name": "Jack",
    "groups": "Bundaberg;Brisbane",
    "goals": "Goal1;Goal2"
}
headers = {
    "Authorization": "<api-key>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

const options = {
  method: 'POST',
  headers: {Authorization: '<api-key>', 'Content-Type': 'application/json'},
  body: JSON.stringify({
    user_name: '12345',
    first_name: 'Bilbo',
    last_name: 'Baggins',
    email: 'bilbo@myorg.com',
    manager_email: 'manager@company.com',
    manager_2_email: 'manager2@company.com',
    mentor_email: 'mentor@company.com',
    lms_learner_id: '456',
    lms_reference: 'Testlms',
    type: 'Client',
    role_1: 'Instructor',
    'X-Country': 'Australia',
    'X-State': 'Queensland',
    'X-Preferred Name': 'Jack',
    groups: 'Bundaberg;Brisbane',
    goals: 'Goal1;Goal2'
  })
};

fetch('https://myorg.tribalhabits.com/papi/users', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://myorg.tribalhabits.com/papi/users",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_POSTFIELDS => json_encode([
    'user_name' => '12345',
    'first_name' => 'Bilbo',
    'last_name' => 'Baggins',
    'email' => 'bilbo@myorg.com',
    'manager_email' => 'manager@company.com',
    'manager_2_email' => 'manager2@company.com',
    'mentor_email' => 'mentor@company.com',
    'lms_learner_id' => '456',
    'lms_reference' => 'Testlms',
    'type' => 'Client',
    'role_1' => 'Instructor',
    'X-Country' => 'Australia',
    'X-State' => 'Queensland',
    'X-Preferred Name' => 'Jack',
    'groups' => 'Bundaberg;Brisbane',
    'goals' => 'Goal1;Goal2'
  ]),
  CURLOPT_HTTPHEADER => [
    "Authorization: <api-key>",
    "Content-Type: application/json"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

using RestSharp;


var options = new RestClientOptions("https://myorg.tribalhabits.com/papi/users");
var client = new RestClient(options);
var request = new RestRequest("");
request.AddHeader("Authorization", "<api-key>");
request.AddJsonBody("{\n  \"user_name\": \"12345\",\n  \"first_name\": \"Bilbo\",\n  \"last_name\": \"Baggins\",\n  \"email\": \"bilbo@myorg.com\",\n  \"manager_email\": \"manager@company.com\",\n  \"manager_2_email\": \"manager2@company.com\",\n  \"mentor_email\": \"mentor@company.com\",\n  \"lms_learner_id\": \"456\",\n  \"lms_reference\": \"Testlms\",\n  \"type\": \"Client\",\n  \"role_1\": \"Instructor\",\n  \"X-Country\": \"Australia\",\n  \"X-State\": \"Queensland\",\n  \"X-Preferred Name\": \"Jack\",\n  \"groups\": \"Bundaberg;Brisbane\",\n  \"goals\": \"Goal1;Goal2\"\n}", false);
var response = await client.PostAsync(request);

Console.WriteLine("{0}", response.Content);

require 'uri'
require 'net/http'

url = URI("https://myorg.tribalhabits.com/papi/users")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)
request["Authorization"] = '<api-key>'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"user_name\": \"12345\",\n  \"first_name\": \"Bilbo\",\n  \"last_name\": \"Baggins\",\n  \"email\": \"bilbo@myorg.com\",\n  \"manager_email\": \"manager@company.com\",\n  \"manager_2_email\": \"manager2@company.com\",\n  \"mentor_email\": \"mentor@company.com\",\n  \"lms_learner_id\": \"456\",\n  \"lms_reference\": \"Testlms\",\n  \"type\": \"Client\",\n  \"role_1\": \"Instructor\",\n  \"X-Country\": \"Australia\",\n  \"X-State\": \"Queensland\",\n  \"X-Preferred Name\": \"Jack\",\n  \"groups\": \"Bundaberg;Brisbane\",\n  \"goals\": \"Goal1;Goal2\"\n}"

response = http.request(request)
puts response.read_body

{
  "user_name": "12345",
  "first_name": "Bilbo",
  "last_name": "Baggins",
  "email": "bilbo@myorg.com",
  "manager_email": "manager@company.com",
  "manager_2_email": "manager2@company.com",
  "manager_3_email": null,
  "manager_4_email": null,
  "manager_5_email": null,
  "mentor_email": "mentor@company.com",
  "lms_learner_id": "456",
  "lms_reference": "Testlms",
  "org_admin": false,
  "creator": false,
  "team_leader": false,
  "created_at": "2019-04-01T15:46:31.586+11:00",
  "updated_at": "2021-06-15T09:25:25.756+10:00",
  "current_sign_in_at": "2022-06-15T09:25:25.756+10:00",
  "admin_type": null,
  "deactivate_scheduled_date": "2022-06-15T00:00:00.000+10:00",
  "reactivate_scheduled_date": null,
  "language": "en",
  "created_by": "API",
  "timezone": "Australia/Sydney",
  "user_notifications_enabled": true,
  "team_leader_report_frequency": "every_thursday",
  "learner_report_frequency": null,
  "assessor_report_frequency": "every_wednesday",
  "default_landing_page": "Default",
  "org_admin_access": "none",
  "login": "internal",
  "type": "Client",
  "active": true,
  "X-Country": "Australia",
  "X-State": "Queensland",
  "X-Preferred Name": "Jack",
  "platform_champion": false,
  "role_1": "Instructor",
  "role_2": null,
  "role_3": null,
  "role_4": null,
  "role_5": null,
  "groups": "Brisbane;Bundaberg",
  "goals": "Goal1;Goal2"
}

"Bad request: Illegal value 'maybe' for 'active'"

{
  "user_name": "12345",
  "email": "not-an-email",
  "params": {
    "user_name": "12345",
    "email": "not-an-email"
  },
  "reason": "Email is invalid",
  "errors": [
    "Email is invalid"
  ]
}

{
  "error": "Rate limit exceeded. Please slow down.",
  "retry_after_seconds": 23
}

Users

Create a new user

This endpoint creates a new person. If the user_name or email is already used by another user, or a field is invalid, 422 is returned with details of the problem.

Boolean fields accept true, 1 or "yes", and false, 0 or "no". Values are case-insensitive and can also be sent as strings, eg "true". Any other value returns 400.

The fields org_admin and admin_type cannot be set through the API. If supplied they are ignored. Administrator access must be granted in the Tribal Habits web interface.

Enrolment codes (enrolment_code_N) are not processed by this endpoint. To enrol users, use Batch create or update or Create or update topic or pathway enrolments.

POST

https://myorg.tribalhabits.com/papi

users

Create a new user

curl --request POST \
  --url https://myorg.tribalhabits.com/papi/users \
  --header 'Authorization: <api-key>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "user_name": "12345",
  "first_name": "Bilbo",
  "last_name": "Baggins",
  "email": "bilbo@myorg.com",
  "manager_email": "manager@company.com",
  "manager_2_email": "manager2@company.com",
  "mentor_email": "mentor@company.com",
  "lms_learner_id": "456",
  "lms_reference": "Testlms",
  "type": "Client",
  "role_1": "Instructor",
  "X-Country": "Australia",
  "X-State": "Queensland",
  "X-Preferred Name": "Jack",
  "groups": "Bundaberg;Brisbane",
  "goals": "Goal1;Goal2"
}
'

import requests

url = "https://myorg.tribalhabits.com/papi/users"

payload = {
    "user_name": "12345",
    "first_name": "Bilbo",
    "last_name": "Baggins",
    "email": "bilbo@myorg.com",
    "manager_email": "manager@company.com",
    "manager_2_email": "manager2@company.com",
    "mentor_email": "mentor@company.com",
    "lms_learner_id": "456",
    "lms_reference": "Testlms",
    "type": "Client",
    "role_1": "Instructor",
    "X-Country": "Australia",
    "X-State": "Queensland",
    "X-Preferred Name": "Jack",
    "groups": "Bundaberg;Brisbane",
    "goals": "Goal1;Goal2"
}
headers = {
    "Authorization": "<api-key>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

const options = {
  method: 'POST',
  headers: {Authorization: '<api-key>', 'Content-Type': 'application/json'},
  body: JSON.stringify({
    user_name: '12345',
    first_name: 'Bilbo',
    last_name: 'Baggins',
    email: 'bilbo@myorg.com',
    manager_email: 'manager@company.com',
    manager_2_email: 'manager2@company.com',
    mentor_email: 'mentor@company.com',
    lms_learner_id: '456',
    lms_reference: 'Testlms',
    type: 'Client',
    role_1: 'Instructor',
    'X-Country': 'Australia',
    'X-State': 'Queensland',
    'X-Preferred Name': 'Jack',
    groups: 'Bundaberg;Brisbane',
    goals: 'Goal1;Goal2'
  })
};

fetch('https://myorg.tribalhabits.com/papi/users', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://myorg.tribalhabits.com/papi/users",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_POSTFIELDS => json_encode([
    'user_name' => '12345',
    'first_name' => 'Bilbo',
    'last_name' => 'Baggins',
    'email' => 'bilbo@myorg.com',
    'manager_email' => 'manager@company.com',
    'manager_2_email' => 'manager2@company.com',
    'mentor_email' => 'mentor@company.com',
    'lms_learner_id' => '456',
    'lms_reference' => 'Testlms',
    'type' => 'Client',
    'role_1' => 'Instructor',
    'X-Country' => 'Australia',
    'X-State' => 'Queensland',
    'X-Preferred Name' => 'Jack',
    'groups' => 'Bundaberg;Brisbane',
    'goals' => 'Goal1;Goal2'
  ]),
  CURLOPT_HTTPHEADER => [
    "Authorization: <api-key>",
    "Content-Type: application/json"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

using RestSharp;


var options = new RestClientOptions("https://myorg.tribalhabits.com/papi/users");
var client = new RestClient(options);
var request = new RestRequest("");
request.AddHeader("Authorization", "<api-key>");
request.AddJsonBody("{\n  \"user_name\": \"12345\",\n  \"first_name\": \"Bilbo\",\n  \"last_name\": \"Baggins\",\n  \"email\": \"bilbo@myorg.com\",\n  \"manager_email\": \"manager@company.com\",\n  \"manager_2_email\": \"manager2@company.com\",\n  \"mentor_email\": \"mentor@company.com\",\n  \"lms_learner_id\": \"456\",\n  \"lms_reference\": \"Testlms\",\n  \"type\": \"Client\",\n  \"role_1\": \"Instructor\",\n  \"X-Country\": \"Australia\",\n  \"X-State\": \"Queensland\",\n  \"X-Preferred Name\": \"Jack\",\n  \"groups\": \"Bundaberg;Brisbane\",\n  \"goals\": \"Goal1;Goal2\"\n}", false);
var response = await client.PostAsync(request);

Console.WriteLine("{0}", response.Content);

require 'uri'
require 'net/http'

url = URI("https://myorg.tribalhabits.com/papi/users")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)
request["Authorization"] = '<api-key>'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"user_name\": \"12345\",\n  \"first_name\": \"Bilbo\",\n  \"last_name\": \"Baggins\",\n  \"email\": \"bilbo@myorg.com\",\n  \"manager_email\": \"manager@company.com\",\n  \"manager_2_email\": \"manager2@company.com\",\n  \"mentor_email\": \"mentor@company.com\",\n  \"lms_learner_id\": \"456\",\n  \"lms_reference\": \"Testlms\",\n  \"type\": \"Client\",\n  \"role_1\": \"Instructor\",\n  \"X-Country\": \"Australia\",\n  \"X-State\": \"Queensland\",\n  \"X-Preferred Name\": \"Jack\",\n  \"groups\": \"Bundaberg;Brisbane\",\n  \"goals\": \"Goal1;Goal2\"\n}"

response = http.request(request)
puts response.read_body

{
  "user_name": "12345",
  "first_name": "Bilbo",
  "last_name": "Baggins",
  "email": "bilbo@myorg.com",
  "manager_email": "manager@company.com",
  "manager_2_email": "manager2@company.com",
  "manager_3_email": null,
  "manager_4_email": null,
  "manager_5_email": null,
  "mentor_email": "mentor@company.com",
  "lms_learner_id": "456",
  "lms_reference": "Testlms",
  "org_admin": false,
  "creator": false,
  "team_leader": false,
  "created_at": "2019-04-01T15:46:31.586+11:00",
  "updated_at": "2021-06-15T09:25:25.756+10:00",
  "current_sign_in_at": "2022-06-15T09:25:25.756+10:00",
  "admin_type": null,
  "deactivate_scheduled_date": "2022-06-15T00:00:00.000+10:00",
  "reactivate_scheduled_date": null,
  "language": "en",
  "created_by": "API",
  "timezone": "Australia/Sydney",
  "user_notifications_enabled": true,
  "team_leader_report_frequency": "every_thursday",
  "learner_report_frequency": null,
  "assessor_report_frequency": "every_wednesday",
  "default_landing_page": "Default",
  "org_admin_access": "none",
  "login": "internal",
  "type": "Client",
  "active": true,
  "X-Country": "Australia",
  "X-State": "Queensland",
  "X-Preferred Name": "Jack",
  "platform_champion": false,
  "role_1": "Instructor",
  "role_2": null,
  "role_3": null,
  "role_4": null,
  "role_5": null,
  "groups": "Brisbane;Bundaberg",
  "goals": "Goal1;Goal2"
}

"Bad request: Illegal value 'maybe' for 'active'"

{
  "user_name": "12345",
  "email": "not-an-email",
  "params": {
    "user_name": "12345",
    "email": "not-an-email"
  },
  "reason": "Email is invalid",
  "errors": [
    "Email is invalid"
  ]
}

{
  "error": "Rate limit exceeded. Please slow down.",
  "retry_after_seconds": 23
}

Authorizations

Authorization

string

header

required

Your organisation's API key, sent as Authorization: my_api_key. The key can also be passed as an api_key query parameter. See Authentication.

Body

application/json

user_name

string

required

Unique identifier for the new user. Stored in lower case

first_name

string

required

User's first name - used for display purposes

last_name

string

required

User's last name - used for display purposes

string

required

User's email address (must be unique within your organisation) - used for email notifications

type

string

Type of user. One of Client, Contractor, Customer, Director, Employee, Lead, Member, Parent, Partner, Practitioner, Prospect, Staff, Student, Subscriber, Supporter, Volunteer, Worker. Case-insensitive. Defaults to Staff

manager_email

string

Email address of the user's manager - used for email notifications and team reporting

manager_2_email

string

Email address of the user's 2nd manager - used for email notifications and team reporting

manager_3_email

string

Email address of the user's 3rd manager - used for email notifications and team reporting

manager_4_email

string

Email address of the user's 4th manager - used for email notifications and team reporting

manager_5_email

string

Email address of the user's 5th manager - used for email notifications and team reporting

mentor_email

string

Email address of the user's mentor - used for email notifications

language

string

One of en, fj, fr, de, hi-IN, id, it, ja, ko, mi, ms, ne, pa-IN, pt, sm, zh-Hans, es, tl, ta, te, th, to, zh-Hant-HK, vi. Case-insensitive. Unrecognised values are ignored

timezone

string

User's time zone, eg Australia/Sydney. Defaults to your organisation's time zone

lms_learner_id

string

User's id in company LMS - used for matching users in Tribal Habits. The combination of lms_reference and lms_learner_id must be unique

lms_reference

string

Company LMS name - used for matching users in Tribal Habits

internal (Tribal Habits login) or external (single sign-on)

Available options:

internal,

external

active

boolean

Specify false to create the user account but disable login

creator

boolean

Specify true to allow this user to create topics

user_notifications_enabled

boolean

User will receive email notifications

User must change their password at next login

manager_email_report_1st_month

boolean

Send the manager email report on the 1st of the month

manager_email_report_15th_month

boolean

Send the manager email report on the 15th of the month

password

string

8 to 72 characters, with at least one number, one upper case and one lower case character

deactivate_scheduled_date

string

A future date this account will be deactivated. Formats: 'yyyy-mm-dd', 'dd/mm/yyyy' or 'dd/mm/yy'

reactivate_scheduled_date

string

A future date this account will be reactivated. Same formats as deactivate_scheduled_date

team_leader_report_frequency

string

Frequency of team leader report emails, if the user is a team leader. One of every_half, every_quarter, once_a_month, twice_a_month, every_monday, every_tuesday, every_wednesday, every_thursday, every_friday, every_weekday, every_day. none or an empty value clears it. Any other value returns 400

learner_report_frequency

string

Frequency of learner report emails. Same values as team_leader_report_frequency

assessor_report_frequency

string

Frequency of assessor report emails, if the user is an assessor or creator. Same values as team_leader_report_frequency

default_landing_page

string

One of Assess, Create, Admin, Dashboard - Overview, Dashboard - Calendar, Training - Enrolments, Profile. Case-insensitive. Unrecognised values are ignored

role_1

string

Name of the role assigned to the user in position 1. The role must already exist, otherwise 400 is returned. An empty value removes the role in that position

role_2

string

Name of the role assigned to the user in position 2. The role must already exist, otherwise 400 is returned. An empty value removes the role in that position

role_3

string

Name of the role assigned to the user in position 3. The role must already exist, otherwise 400 is returned. An empty value removes the role in that position

role_4

string

Name of the role assigned to the user in position 4. The role must already exist, otherwise 400 is returned. An empty value removes the role in that position

role_5

string

Name of the role assigned to the user in position 5. The role must already exist, otherwise 400 is returned. An empty value removes the role in that position

groups

Group names separated with a semicolon, eg "groups": "Brisbane;Bundaberg", or an array of group names, eg "groups": ["Brisbane", "Bundaberg"]. Groups must already exist, otherwise 400 is returned. Replaces all of the user's current groups; an empty value removes the user from all groups

goals

Goal names separated with a semicolon, eg "goals": "Goal1;Goal2", or an array of goal names, eg "goals": ["Goal1", "Goal2"]. Replaces all of the user's current goals. Goals must already exist, otherwise 400 is returned. An empty value removes all goals

X-[Custom]

any

Custom field. Replace [Custom] with the custom field name. See Custom fields

send_invitation

boolean

Specify true to send an invitation email to the user

Response

The user was created

The user object returned by the user endpoints. Custom fields are included as X- fields, see Custom fields.

user_name

string

Unique identifier of the user. Always stored and returned in lower case

first_name

string

User's first name

last_name

string

User's last name

string

User's email address

manager_email

string | null

Email address of the user's manager. null if not set

manager_2_email

string | null

Email address of the user's 2nd manager. null if not set

manager_3_email

string | null

Email address of the user's 3rd manager. null if not set

manager_4_email

string | null

Email address of the user's 4th manager. null if not set

manager_5_email

string | null

Email address of the user's 5th manager. null if not set

mentor_email

string

Email address of the user's mentor

lms_learner_id

string

User's identifier in your company LMS

lms_reference

string

User's LMS name in your company LMS

org_admin

boolean

true if the user is an administrator

creator

boolean

true if the user can create topics

team_leader

boolean

true if the user is the manager of at least one other user (derived from other users' manager emails)

created_at

string<date-time>

Timestamp

updated_at

string<date-time>

Timestamp

Timestamp. null if the user has never signed in

admin_type

integer | null

Administrator type as a number: 0 = super, 1 = standard, 2 = knowledge, 3 = reporting, 4 = instructor, 5 = restricted, 6 = observer, 7 = people, 8 = library. null if not an administrator

deactivate_scheduled_date

string<date-time> | null

Timestamp of the date on which the account is scheduled to be deactivated, or null

reactivate_scheduled_date

string<date-time> | null

Timestamp of the date on which the account is scheduled to be reactivated, or null

language

string

Language code, eg en

created_by

string

How the user was created, eg API

timezone

string

User's time zone, eg Australia/Sydney

user_notifications_enabled

boolean

true if the user receives email notifications

team_leader_report_frequency

string | null

Team leader report email frequency. See Update a specific user for values

learner_report_frequency

string | null

Learner report email frequency. See Update a specific user for values

assessor_report_frequency

string | null

Assessor report email frequency. See Update a specific user for values

default_landing_page

string

Page shown after login, or Default

org_admin_access

string

Name of the administrator type (see admin_type), or none

internal or external

Available options:

internal,

external

type

string

Type of user, eg Staff, Client

active

boolean

false if the account has been deactivated

X-[Custom]

any

Custom fields. See Custom fields

platform_champion

boolean

true if the user is a platform champion for your organisation

role_1

string | null

Name of the role in position 1, or null

role_2

string | null

Name of the role in position 2, or null

role_3

string | null

Name of the role in position 3, or null

role_4

string | null

Name of the role in position 4, or null

role_5

string | null

Name of the role in position 5, or null

groups

string

Group names, sorted and separated by semicolons

goals

string

Goal names, sorted and separated by semicolons

Getting started

Users

Topics

Pathways

Enrolments

Certificates

External Knowledge

Webhooks

Create a new user

Authorizations

Body

Response