> ## Documentation Index > Fetch the complete documentation index at: https://api-docs.tribalhabits.com/llms.txt > Use this file to discover all available pages before exploring further. # Update a specific user > This endpoint updates a specific user. Only fields that are supplied will be updated. To clear an optional field, send an empty string, eg `"manager_email": ""`. Returns `404` if the user does not exist. `user_name` in the URL is the unique identifier of the person to update (case-insensitive). 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](/api-reference/users/batch-create-or-update) or [Create or update topic or pathway enrolments](/api-reference/enrolments/create-or-update-topic-or-pathway-enrolments). ## OpenAPI ````yaml /openapi.yaml put /users/{user_name} openapi: 3.1.0 info: title: Tribal Habits Public API version: '1' description: > The Tribal Habits Public API V1. Use it to manage your Tribal Habits user accounts (list, show, create and update) and other entities. Replace `myorg` in the server URL with your organisation's subdomain. See [Vanity URL](/vanity-url) if you use your own domain. servers: - url: https://myorg.tribalhabits.com/papi security: - ApiKeyHeader: [] tags: - name: Users description: Users - name: Topics description: Topics - name: Pathways description: Pathways - name: Enrolments description: Topic and Pathway Enrolments - name: Certificates description: >- Certificate generation and retrieval for completed topic and pathway enrolments. - name: External Knowledge description: Knowledge obtained from a source external of Tribal Habits. - name: Webhooks description: >- Webhooks triggered from certain actions in code that will call URLs assigned by you. paths: /users/{user_name}: parameters: - name: user_name in: path required: true schema: type: string example: '12345' put: tags: - Users summary: Update a specific user description: > This endpoint updates a specific user. Only fields that are supplied will be updated. To clear an optional field, send an empty string, eg `"manager_email": ""`. Returns `404` if the user does not exist. `user_name` in the URL is the unique identifier of the person to update (case-insensitive). 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](/api-reference/users/batch-create-or-update) or [Create or update topic or pathway enrolments](/api-reference/enrolments/create-or-update-topic-or-pathway-enrolments). operationId: updateUser requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/UserUpdate' example: active: false groups: - Brisbane - Bundaberg responses: '200': description: The updated user content: application/json: schema: $ref: '#/components/schemas/User' examples: example: $ref: '#/components/examples/UserInactive' '400': $ref: '#/components/responses/BadRequest' '401': $ref: '#/components/responses/Unauthorized' '404': $ref: '#/components/responses/NotFound' '406': $ref: '#/components/responses/NotAcceptable' '422': $ref: '#/components/responses/UserUnprocessable' '429': $ref: '#/components/responses/TooManyRequests' components: schemas: UserUpdate: type: object properties: user_name: type: string description: A new unique identifier for the user. Stored in lower case first_name: type: string description: User's first name - used for display purposes last_name: type: string description: User's last name - used for display purposes email: type: string description: >- User's email address (must be unique within your organisation) - used for email notifications type: type: string description: >- Type of user. One of `Client`, `Contractor`, `Customer`, `Director`, `Employee`, `Lead`, `Member`, `Parent`, `Partner`, `Practitioner`, `Prospect`, `Staff`, `Student`, `Subscriber`, `Supporter`, `Volunteer`, `Worker`. Case-insensitive. manager_email: type: string description: >- Email address of the user's manager - used for email notifications and team reporting manager_2_email: type: string description: >- Email address of the user's 2nd manager - used for email notifications and team reporting manager_3_email: type: string description: >- Email address of the user's 3rd manager - used for email notifications and team reporting manager_4_email: type: string description: >- Email address of the user's 4th manager - used for email notifications and team reporting manager_5_email: type: string description: >- Email address of the user's 5th manager - used for email notifications and team reporting mentor_email: type: string description: Email address of the user's mentor - used for email notifications language: type: string description: >- 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: type: string description: User's time zone, eg `Australia/Sydney` lms_learner_id: type: string description: >- 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: type: string description: Company LMS name - used for matching users in Tribal Habits login: type: string enum: - internal - external description: '`internal` (Tribal Habits login) or `external` (single sign-on)' active: type: boolean description: >- Specify `false` to deactivate the account, or `true` to reactivate it creator: type: boolean description: Specify `true` to allow this user to create topics user_notifications_enabled: type: boolean description: User will receive email notifications force_pwd_reset_next_login: type: boolean description: User must change their password at next login manager_email_report_1st_month: type: boolean description: Send the manager email report on the 1st of the month manager_email_report_15th_month: type: boolean description: Send the manager email report on the 15th of the month password: type: string description: >- 8 to 72 characters, with at least one number, one upper case and one lower case character deactivate_scheduled_date: type: string description: >- A future date this account will be deactivated. Formats: 'yyyy-mm-dd', 'dd/mm/yyyy' or 'dd/mm/yy' reactivate_scheduled_date: type: string description: >- A future date this account will be reactivated. Same formats as `deactivate_scheduled_date` team_leader_report_frequency: type: string description: >- 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: type: string description: >- Frequency of learner report emails. Same values as `team_leader_report_frequency` assessor_report_frequency: type: string description: >- Frequency of assessor report emails, if the user is an assessor or creator. Same values as `team_leader_report_frequency` default_landing_page: type: string description: >- One of `Assess`, `Create`, `Admin`, `Dashboard - Overview`, `Dashboard - Calendar`, `Training - Enrolments`, `Profile`. Case-insensitive. Returns `400` if the user does not have access to that page (eg `Admin` for a non-administrator). Unrecognised values are ignored role_1: type: string description: >- 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: type: string description: >- 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: type: string description: >- 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: type: string description: >- 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: type: string description: >- 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: description: >- 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 oneOf: - title: Semicolon-separated type: string - title: Array type: array items: type: string goals: description: >- 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 oneOf: - title: Semicolon-separated type: string - title: Array type: array items: type: string X-[Custom]: description: >- Custom field. Replace `[Custom]` with the custom field name. See [Custom fields](/custom-fields) send_invitation: type: boolean description: Specify `true` to send an invitation email to the user patternProperties: ^X-: description: Custom field. See [Custom fields](/custom-fields) User: type: object description: >- The user object returned by the user endpoints. Custom fields are included as `X-` fields, see [Custom fields](/custom-fields). properties: user_name: type: string description: >- Unique identifier of the user. Always stored and returned in lower case first_name: type: string description: User's first name last_name: type: string description: User's last name email: type: string description: User's email address manager_email: type: - string - 'null' description: Email address of the user's manager. `null` if not set manager_2_email: type: - string - 'null' description: Email address of the user's 2nd manager. `null` if not set manager_3_email: type: - string - 'null' description: Email address of the user's 3rd manager. `null` if not set manager_4_email: type: - string - 'null' description: Email address of the user's 4th manager. `null` if not set manager_5_email: type: - string - 'null' description: Email address of the user's 5th manager. `null` if not set mentor_email: type: string description: Email address of the user's mentor lms_learner_id: type: string description: User's identifier in your company LMS lms_reference: type: string description: User's LMS name in your company LMS org_admin: type: boolean description: '`true` if the user is an administrator' creator: type: boolean description: '`true` if the user can create topics' team_leader: type: boolean description: >- `true` if the user is the manager of at least one other user (derived from other users' manager emails) created_at: type: string format: date-time description: Timestamp updated_at: type: string format: date-time description: Timestamp current_sign_in_at: type: - string - 'null' format: date-time description: Timestamp. `null` if the user has never signed in admin_type: type: - integer - 'null' description: >- 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: type: - string - 'null' format: date-time description: >- Timestamp of the date on which the account is scheduled to be deactivated, or `null` reactivate_scheduled_date: type: - string - 'null' format: date-time description: >- Timestamp of the date on which the account is scheduled to be reactivated, or `null` language: type: string description: Language code, eg `en` created_by: type: string description: How the user was created, eg `API` timezone: type: string description: User's time zone, eg `Australia/Sydney` user_notifications_enabled: type: boolean description: '`true` if the user receives email notifications' team_leader_report_frequency: type: - string - 'null' description: >- Team leader report email frequency. See [Update a specific user](/api-reference/users/update-a-specific-user) for values learner_report_frequency: type: - string - 'null' description: >- Learner report email frequency. See [Update a specific user](/api-reference/users/update-a-specific-user) for values assessor_report_frequency: type: - string - 'null' description: >- Assessor report email frequency. See [Update a specific user](/api-reference/users/update-a-specific-user) for values default_landing_page: type: string description: Page shown after login, or `Default` org_admin_access: type: string description: Name of the administrator type (see `admin_type`), or `none` login: type: string enum: - internal - external description: '`internal` or `external`' type: type: string description: Type of user, eg `Staff`, `Client` active: type: boolean description: '`false` if the account has been deactivated' X-[Custom]: description: Custom fields. See [Custom fields](/custom-fields) platform_champion: type: boolean description: '`true` if the user is a platform champion for your organisation' role_1: type: - string - 'null' description: Name of the role in position 1, or `null` role_2: type: - string - 'null' description: Name of the role in position 2, or `null` role_3: type: - string - 'null' description: Name of the role in position 3, or `null` role_4: type: - string - 'null' description: Name of the role in position 4, or `null` role_5: type: - string - 'null' description: Name of the role in position 5, or `null` groups: type: string description: Group names, sorted and separated by semicolons goals: type: string description: Goal names, sorted and separated by semicolons patternProperties: ^X-: description: Custom field. See [Custom fields](/custom-fields) UserValidationError: type: object properties: user_name: type: string email: type: string params: type: object description: The parameters sent in the request reason: type: string description: Description of the problem errors: type: array items: type: string examples: UserInactive: summary: A deactivated user value: 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: false 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 responses: BadRequest: description: >- Bad Request - The request is missing a required parameter or has an invalid value. See the response body for more details content: application/json: schema: type: string example: 'Bad request: Illegal value ''maybe'' for ''active''' Unauthorized: description: >- Unauthorized - The request does not include the API key, the API key is incorrect, or API access is not enabled on your plan. NotFound: description: Not Found - The specified resource or endpoint could not be found content: application/json: schema: type: string example: not found NotAcceptable: description: >- Not Acceptable - A `POST` or `PUT` request had a `Content-Type` header other than `application/json` UserUnprocessable: description: >- Unprocessable entity - The user you are creating or updating is not valid (e.g. not an email address). See the response body for more details content: application/json: schema: $ref: '#/components/schemas/UserValidationError' example: user_name: '12345' email: not-an-email params: user_name: '12345' email: not-an-email reason: Email is invalid errors: - Email is invalid TooManyRequests: description: >- Too Many Requests - You have exceeded the rate limit. See [Rate limits](/rate-limits) headers: Retry-After: description: Number of seconds until the rate limit window resets schema: type: integer content: application/json: schema: type: object properties: error: type: string retry_after_seconds: type: integer example: error: Rate limit exceeded. Please slow down. retry_after_seconds: 23 securitySchemes: ApiKeyHeader: type: apiKey in: header name: Authorization description: > 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](/authentication). ```` This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.