The Users endpoints allow listing, creation and modification of users.
Part of Web API v3 for user management. You need a token with the v3:users:read or v3:users:write scope, see Authenticating with the Web API v3.
Listing users
List users using the /api/v3/public/users/ GET endpoint.
The list is paginated. Use limit (default 100, maximum 1000) and offset to page through it. Each response contains count, next and results; next is empty on the last page.
To find specific users, filter on email, employee_id or saml_username, for example /api/v3/public/users/?employee_id=12345. You can also filter on date ranges with contract_start_date__gt, contract_start_date__lt, first_login__gt, first_login__lt, registered_at__gt and registered_at__lt.
See the rate limits in Web API v3 for user management before you build a sync that lists all users.
User fields
Field | Description |
| Users are uniquely identified by their uuid, and all other endpoints in API v3 that refer to users do so through this identifier. Read-only. |
| The email address of a user. Should be unique if they log in with a username and password. |
| Used to refer to a user on the platform. |
| Can be used in automations to automatically make content available in an onboarding programme, or automatically suspend users when their contracts end. See 02 An introduction to automations. |
| A customer-specific (unique) identifier, which can be used to disambiguate users. |
| The language for a user in ISO 639-1 format. Only languages currently enabled on the platform are valid options. Please contact support if you need to know which languages are currently enabled. |
| The date-time when the user first logged in. Read-only. |
| The date-time when the user used their RegistrationToken to set up their password. Stays |
| Controls whether the user can log in. A suspended user does not count toward the licenses, but is not able to log in either. See deleting and suspending users below. |
| A pending user has not logged in yet. Pending users receive activity and journey assignments like other users, so they see their content at first login. They do not receive notifications, are not added to smart groups, get no programme access and do not count in an automation's user count until they log in. The field is set to |
| The username used with a saml2 SSO. |
| The username used with a JWT integration. |
| The username used with an OpenID integration. |
đ§ Be careful
It is not possible to set is_pending to true. Instead, you may want to suspend a user.
Creating users
With a POST request to /api/v3/public/users/ you can add new users.
If you require users to log in with email and password on our platform, and optionally send a registration email through the platform, a separate call to our activation token endpoint needs to be made. See Activation tokens and invitation emails.
Modifying users
With a PUT or PATCH request to /api/v3/public/users/<uuid>/ you can modify existing users.
The PUT requires all writable fields to be included, while the PATCH only updates provided fields.
Changing a user's email address. Update the email field with a PATCH request. The user keeps the same uuid, and with it their progress, certificates and group memberships. Do not create a new user when an email address changes: a new user starts without any progress.
Deleting and suspending users
A suspended user can not log in to the platform.
It is not possible to delete a user directly. Instead, the user should be suspended by setting is_suspended to true.
A suspended user is removed from the platform after the suspend period set for your platform. On many platforms this is between 6 and 18 months, and your TinQwise contact can tell you the value for yours. The user's data is only anonymised if they are not on any other TinQwise platform.
đ Good to know
The suspend period before deletion can be customised per platform. Email service@tinqwise.com if you want a different period for your platform.
Unsuspending users
If a user is suspended and you want to reactivate them, then the user should be unsuspended by setting is_suspended to false. This is only possible within the suspend period, before the user is permanently deleted from the platform.
It is not necessary to send a new activation token to the user after unsuspending them. The user can log in with their old password, or with SSO.
đ Good to know
Users will receive an automatic "welcome back" email after they are unsuspended. This behaviour can be configured through the Unsuspend Email feature.