User APIs

The User API endpoints allow you to programmatically manage ThoughtSpot users.

Supported operations

POST /tspublic/v1/user/
Creates a user account.

POST /tspublic/v1/user/activate
Activates a user account.

PUT /tspublic/v1/user/{userid}
Modifies a user account.

PUT /tspublic/v1/user/email
Add or modifies the email address of a user.

GET /tspublic/v1/user/
Gets details of the users in a ThoughtSpot system.

DELETE /tspublic/v1/user/{userid}
Deletes a user account.

GET /tspublic/v1/user/list
Gets all users, groups, and their inter-dependencies.

POST /tspublic/v1/user/updatepreference
Modifies a user profile.

POST /tspublic/v1/user/transfer/ownership
Transfers the ownership of objects from one user to another.

POST /tspublic/v1/user/updatepassword
Changes the password of a user account.

POST /tspublic/v1/user/resetpassword
Resets the password of a user account.

POST /tspublic/v1/user/session/invalidate
Invalidates a user session.

POST /tspublic/v1/user/inactivate
Deactivates a user account.

POST /tspublic/v1/user/sync
Synchronizes user details and attributes from an external database with the user data in the ThoughtSpot system.

POST /tspublic/v1/user/{userid}/groups
Assigns a user to the specified user groups.

GET /tspublic/v1/user/{userid}/groups
Gets details of the user groups associated with a specific user.

PUT /tspublic/v1/user/{userid}/groups
Updates the user group data for a specific user.

DELETE /tspublic/v1/user/{userid}/groups
Removes a user from the specified user groups.

Create a user

To programmatically create a user account in the ThoughtSpot system, send a POST request to /tspublic/v1/user/ API endpoint.

  • To create a user, you require admin user privileges.

  • By default, all users in the ThoughtSpot system are added to the All group.

Resource URL

POST /tspublic/v1/user/

Request parameters

Form parameter Description

name

String. Name of the user. The username string must be unique.

password

String.Password for the user account.

displayname

String. A unique display name string for the user, usually their first and last name.

properties
Optional

String. A JSON map of user properties fetched from external systems such as LDAP. If you are using Active Directory to authenticate users, and your LDAP configuration requires users to be created manually, you can upload the user properties as a JSON file.

groups
Optional

Array of strings. A JSON array of the GUIDs of groups to which you want to assign the user. The user privileges are determined by the group to which you assign the user. For example, if you assign the user to a group that has the ADMINISTRATION privilege, the user will have admin privileges.

usertype
Optional

String. Type of user. The default value is LOCAL_USER, which indicates that the user is created locally in the ThoughtSpot system.

tenantid
Optional

String. GUID of the tenant for which the user is being created.

visibility
Optional

String. Visibility of the user. The visibility attribute is set to DEFAULT when creating a user. The DEFAULT attribute makes a user visible to other users and user groups, and thus allows them to share objects.

Example request

cURL
curl -X POST \
--header 'Content-Type: application/x-www-form-urlencoded' \
--header 'Accept: application/json' \
--header 'X-Requested-By: ThoughtSpot' \
-d 'name=TS%20User&password=testy1%4022&displayname=TS%20User&usertype=LOCAL_USER&visibility=DEFAULT' \
'https://<ThoughtSpot-host>/callosum/v1/tspublic/v1/user/'
Request URL
https://<ThoughtSpot-host>/callosum/v1/tspublic/v1/user/

Example response

If the user is successfully created in ThoughtSpot, the API returns the user GUID along with the following JSON response:

{
  "userContent": {
    "userPreferences": {
      "notifyOnShare": true,
      "showWalkMe": true,
      "analystOnboardingComplete": false
    },
    "userProperties": {},
    "userActivityProto": {
      "first_login": -1,
      "welcome_email_sent": false
    }
  },
  "state": "ACTIVE",
  "assignedGroups": [
    "b25ee394-9d13-49e3-9385-cd97f5b253b4"
  ],
  "inheritedGroups": [
    "b25ee394-9d13-49e3-9385-cd97f5b253b4"
  ],
  "privileges": [],
  "type": "LOCAL_USER",
  "parenttype": "USER",
  "visibility": "DEFAULT",
  "tenantId": "982d6da9-9cd1-479e-b9a6-35aa05f9282a",
  "displayName": "TS User",
  "header": {
    "id": "79c4cb2a-18cd-44a7-a077-6de65d1b468e",
    "indexVersion": 0,
    "generationNum": 0,
    "name": "TS User",
    "author": "59481331-ee53-42be-a548-bd87be6ddd4a",
    "created": 1624796017810,
    "modified": 1624796017810,
    "modifiedBy": "59481331-ee53-42be-a548-bd87be6ddd4a",
    "owner": "79c4cb2a-18cd-44a7-a077-6de65d1b468e",
    "tags": [],
    "isExternal": false,
    "isDeprecated": false
  },
  "complete": true,
  "incompleteDetail": [],
  "isSuperUser": false,
  "isSystemPrincipal": false
}

Response codes

HTTP status code Description

200

Successful operation

403

Unauthorized request

500

Incorrect password format

Update user details

To modify the attributes of a ThoughtSpot user account, send a PUT request to the /tspublic/v1/user/{userid} endpoint.

This API allows the following modifications to a user profile:

  • User name modifications

  • Password reset

  • Group assignment

  • User visibility for sharing objects

  • User preferences such as viewing onboarding experience, subscribing to or unsubscribing from email notifications, and so on.

To add or modify the email address of a user, use the /tspublic/v1/user/email API endpoint.

Resource URL

PUT /tspublic/v1/user/{userid}

Request parameters

Form parameter Description

userid

String. GUID of the user.

content

String. A JSON map of strings with the user profile attributes.

password
Optional

String. Password string for the user account. Use this attribute to change the password of the user account.

Example request

cURL
curl -X PUT \
--header 'Content-Type: application/x-www-form-urlencoded' \
--header 'Accept: application/json' \
--header 'X-Requested-By: ThoughtSpot' \
-d 'userid=4391d676-2dd8-4248-b6db-d973811f0122' \
-d 'content={"displayName": "Guest", "header": {"id": "4391d676-2dd8-4248-b6db-d973811f0122", "name": "guest1234", "displayName": "Guest", "owner": "4391d676-2dd8-4248-b6db-d973811f0122"}}' \
'https://<ThoughtSpot-host>/callosum/v1/tspublic/v1/user/{userid}' \
-b 'JSESSIONID=0e97a2a6-7e9a-496a-b48b-2d66ec8b1e15'
Request URL
https://<ThoughtSpot-host>/callosum/v1/tspublic/v1/user/{userid}

JSON file example for updating user profile

{
   "userContent":{
      "userPreferences":{
         "notifyOnShare":false,
         "showWalkMe":true,
         "analystOnboardingComplete":false
      },
      "userProperties":{

      },
      "userActivityProto":{
         "first_login":-1,
         "welcome_email_sent":false
      }
   },
   "state":"ACTIVE",
   "assignedGroups":[
      "d0326b56-ef23-4c8a-8327-a30e99bcc72b",
      "b25ee394-9d13-49e3-9385-cd97f5b253b4"
   ],
   "inheritedGroups":[
      "b25ee394-9d13-49e3-9385-cd97f5b253b4"
   ],
   "privileges":[

   ],
   "type":"LOCAL_USER",
   "parenttype":"USER",
   "visibility":"DEFAULT",
   "tenantId":"982d6da9-9cd1-479e-b9a6-35aa05f9282a",
   "displayName":"TS User2",
   "header":{
      "id":"d1f4f2c8-c5bb-4f20-a81d-1f24af0b3286",
      "indexVersion":0,
      "generationNum":0,
      "name":"TS User2",
      "author":"59481331-ee53-42be-a548-bd87be6ddd4a",
      "created":1624846987754,
      "modified":1624846987754,
      "modifiedBy":"59481331-ee53-42be-a548-bd87be6ddd4a",
      "owner":"d1f4f2c8-c5bb-4f20-a81d-1f24af0b3286",
      "tags":[

      ],
      "isExternal":false,
      "isDeprecated":false
   },
   "complete":true,
   "incompleteDetail":[

   ],
   "isSuperUser":false,
   "isSystemPrincipal":false
}

Example response

On successful update of the user profile, the API returns the following response code:

Response Code
204

Response codes

HTTP status code Description

204

Successful operation

403

Unauthorized request

500

Invalid content format

Add or modify the email address of a user

To add or modify the email address of a user, send a PUT request to the /tspublic/v1/user/email API endpoint.

Resource URL

PUT /tspublic/v1/user/email

Request parameters

Form parameter Description

userid

String. GUID of the user.

emailid

String. Email address of the user.

Example request

cURL
curl -X PUT \
--header 'Content-Type: application/x-www-form-urlencoded' \
--header 'Accept: application/json' \
--header 'X-Requested-By: ThoughtSpot' \
-d 'userid=a8aeda00-dc3c-4485-b8d1-fd6ac701a819&emailid=user123%40thoughtspot.com' 'https://<ThoughtSpot-host>/callosum/v1/tspublic/v1/user/email'
Request URL
https://<ThoughtSpot-host>/callosum/v1/tspublic/v1/user/email

Example response

If the email address is added successfully, the API returns the following response code:

Response Code
204

Response codes

HTTP status code Description

204

Successful operation

400

Invalid user ID

500

Invalid email format

Get user details

To get the details of a specific user account or all users in the ThoughtSpot system, send a GET request to /tspublic/v1/user/ API endpoint.

If you want to get a list of object headers associated with a user or user group, you can use the GET /tspublic/v1/metadata/listobjectheaders endpoint.

Resource URL

GET /tspublic/v1/user/

Request parameters

Query parameter Description

userid
Optional

String. The GUID of the user account to query.

name
Optional

String. Username of the user that you want to query.

You can use either userid or name to query data for a specific user. If using both, make sure the values you specify for these attributes point to the same user account. If neither of these parameters is defined, the API returns metadata for all users in the ThoughtSpot system.

Example request

cURL
curl -X GET \
--header 'Accept: application/json' \
--header 'X-Requested-By: ThoughtSpot' \
'https://<ThoughtSpot-host>/callosum/v1/tspublic/v1/user/?userid=b995e481-d0a7-4820-b1e8-54051ede77a2'
Request URL
https://<ThoughtSpot-host>/callosum/v1/tspublic/v1/user/?userid=b995e481-d0a7-4820-b1e8-54051ede77a2

Example response

{
  "userContent": {
    "userPreferences": {
      "notifyOnShare": true,
      "showWalkMe": true,
      "analystOnboardingComplete": false
    },
    "userProperties": {},
    "userActivityProto": {
      "first_login": -1,
      "welcome_email_sent": false
    }
  },
  "state": "ACTIVE",
  "assignedGroups": [
    "b25ee394-9d13-49e3-9385-cd97f5b253b4"
  ],
  "inheritedGroups": [
    "b25ee394-9d13-49e3-9385-cd97f5b253b4"
  ],
  "privileges": [
    "AUTHORING"
  ],
  "type": "LOCAL_USER",
  "parenttype": "USER",
  "visibility": "DEFAULT",
  "tenantId": "982d6da9-9cd1-479e-b9a6-35aa05f9282a",
  "displayName": "kailash",
  "header": {
    "id": "b995e481-d0a7-4820-b1e8-54051ede77a2",
    "indexVersion": 2602,
    "generationNum": 2602,
    "name": "kailash",
    "displayName": "kailash",
    "author": "59481331-ee53-42be-a548-bd87be6ddd4a",
    "created": 1623728042624,
    "modified": 1623728042624,
    "modifiedBy": "59481331-ee53-42be-a548-bd87be6ddd4a",
    "owner": "b995e481-d0a7-4820-b1e8-54051ede77a2",
    "isDeleted": false,
    "isHidden": false,
    "tags": [],
    "type": "LOCAL_USER",
    "isExternal": false,
    "isDeprecated": false
  },
  "complete": true,
  "incompleteDetail": [],
  "isSuperUser": false,
  "isSystemPrincipal": false
}

If no userid or name attribute is specified, the API returns a response with the details of all users in the ThoughtSpot system.

Response codes

HTTP status code Description

200

Successful retrieval of user details

400

Invalid username string

500

Invalid user ID

#deactivate-user] == Deactivate a user account

To deactivate a user account, send a POST request to the /tspublic/v1/user/inactivate API endpoint.

Resource URL

POST /tspublic/v1/user/inactivate

Request parameters

Form parameter Description

username

String. Username of the user account to deactivate.

url

String. The URL of the cluster on which the user account is currently active.

Example request

cURL
curl -X POST \
--header 'Content-Type: application/x-www-form-urlencoded' \
--header 'Accept: text/plain' --header 'X-Requested-By: ThoughtSpot' \
-d 'username=usr1&url=https%3A%2F%2F<ThoughtSpot-host>.cloud%2F' \
'https://<ThoughtSpot-host>/callosum/v1/tspublic/v1/user/inactivate'
Request URL
https://<ThoughtSpot-host>/callosum/v1/tspublic/v1/user/inactivate

Example response

If the user deactivation operation is successful, the API returns the following response:

https://<ThoughtSpot-host>/#/activate?id=5fe00a84-e7eb-4a8b-b58d-ec205de9c645&token=JHNoaXJvMSRTSEEtMjU2JDUwMDAwMCR1WUlOQ0VLbGtWMXZyMWtXUGdKSG9nPT0kTjY3Znd2STA1bURMMXNVMDMzVUkvK2tybllaZUUwUktTUWNEUEJZNWQwbz0

Note the user ID and auth token string. You will need this information to re-activate a user account.

Response codes

HTTP status code Description

200

Successful operation

403

Unauthorized request

500

Invalid username

Activate a user account

To activate a user account that is currently inactive, send a POST request to the /tspublic/v1/user/activate API endpoint.

When a user account is deactivated using the /tspublic/v1/user/inactivate endpoint, the API returns a response with the user ID and auth token string. This auth token string and the user ID are required for reactivating a user session.

https:/<ThoughtSpot-Host>/#/activate?id=<user-guid>&token=<auth_token_string>

Resource URL

POST /tspublic/v1/user/activate

Request parameters

Form parameter Description

userid

String. The GUID of the user account to activate.

auth_token

String. The authentication token to reactivate the user account.

password

String. The password string for the user account.

properties

Array of Strings. A JSON map of the user properties to update the user account.

Example request

cURL
curl -X POST \
--header 'Content-Type: application/x-www-form-urlencoded' \
--header 'Accept: application/json'  \
--header 'X-Requested-By: ThoughtSpot'  \
-d 'userid=996969b6-0a4c-4e3d-9f38-a976fe821790&auth_token=JHNoaXJvMSRTSEEtMjU2JDUwMDAwMCRKWE9MWU4yalVHYUdZaXdHS0dsbWFRPT0kUDRvODVkS1dsRHMyNWd0Njg5K0ZDZVl5R2h1MFBTKzBlQk1pRGNyaW9CQT0&password=fooFoo123!&properties=%5B%7B%22mail%22%3A%22test_user1%40thoughtspot.com%22%7D%5D' 'https://<ThoughtSpot-host>/callosum/v1/tspublic/v1/user/activate'
Request URL
https://<ThoughtSpot-host>/callosum/v1/tspublic/v1/user/activate

Example response

If the user account activation is successful, the API returns the following response:

Response Code
204

Response codes

HTTP status code Description

204

Successful operation

403

Unauthorized request

500

Invalid user ID

Invalidate a user session

After a password of a user account is reset, you may want to invalidate a user session and force the user to re-login with the new password. To invalidate a user session, you can send a POST request to the /tspublic/v1/user/session/invalidate endpoint.

  • Use this API with caution as it may invalidate active user sessions and force users to re-login.

  • Make sure you specify the usernames or user IDs. If you pass null values in the API call, all user sessions on your cluster become invalid and users are forced to re-login.

Resource URL

POST /tspublic/v1/user/session/invalidate

Request parameters

Form parameter Description

username

Array of strings. A JSON array of usernames of the users whose sessions you want to revoke. This attribute is Optional if the userid attribute is defined.

userid

Array of strings. A JSON array of the GUIDs of the user account. This attribute is Optional if the username attribute is defined.

Example request

cURL
curl -X POST \
--header 'Content-Type: application/x-www-form-urlencoded' \
--header 'Accept: application/json' \
--header 'X-Requested-By: ThoughtSpot' \
-d 'username=%5B%22tsadmin%22%5D'  \
'https://<ThoughtSpot-host>/callosum/v1/tspublic/v1/user/session/invalidate'
Request URL
https://<ThoughtSpot-host>/callosum/v1/tspublic/v1/user/session/invalidate

Example response

If the user deactivation operation is successful, the API returns the following response:

Response Code
204

Response codes

HTTP status code Description

204

Successful operation

403

Unauthorized request

500

Invalid username or userID

Delete a user account

To remove a user from the ThoughtSpot system, send a DELETE request to the /tspublic/v1/user/{userid} API endpoint.

Resource URL

DELETE /tspublic/v1/user/{userid}

Request parameters

Path Parameter Description

userid

String. GUID of the user account to delete.

Example request

cURL
curl -X DELETE \
--header 'Accept: application/json' \
--header 'X-Requested-By: ThoughtSpot' \
'https://<ThoughtSpot-host>/callosum/v1/tspublic/v1/user/ee74b737-da39-4667-95ad-cc06c81ab13d'
Request URL
https://<ThoughtSpot-host>/callosum/v1/tspublic/v1/user/ee74b737-da39-4667-95ad-cc06c81ab13d

Example response

On successful removal of the user account, the API returns the following response:

Response Code
204

Response codes

HTTP status code Description

204

Successful operation

403

Unauthorized request

500

Invalid user ID

Get a list of users and groups

To get a list of users and groups available in the ThoughtSpot system and view details of their inter-dependencies, use the /tspublic/v1/user/list API endpoint.

Resource URL

GET /tspublic/v1/user/list

Example request

cURL
curl -X GET \
--header 'Accept: application/json' \
'https://<ThoughtSpot-host>/callosum/v1/tspublic/v1/user/list'
Request URL
https://<ThoughtSpot-host>/callosum/v1/tspublic/v1/user/list

Example response

[
  {
    "name": "Administrator",
    "displayName": "Administration Group",
    "created": 1354006445722,
    "modified": 1354006445722,
    "principalTypeEnum": "LOCAL_GROUP",
    "groupNames": [],
    "visibility": "DEFAULT",
    "activate": false
  },
  {
    "name": "All",
    "displayName": "All Group",
    "created": 1354006445722,
    "modified": 1354006445722,
    "principalTypeEnum": "LOCAL_GROUP",
    "groupNames": [],
    "visibility": "DEFAULT",
    "activate": false
  },
  {
    "name": "System",
    "displayName": "System Management Group",
    "created": 1354006445722,
    "modified": 1354006445722,
    "principalTypeEnum": "LOCAL_GROUP",
    "groupNames": [],
    "visibility": "DEFAULT",
    "activate": false
  },
  {
    "name": "su",
    "displayName": "Administrator Super-User",
    "created": 1354006445722,
    "modified": 1354006445722,
    "mail": "",
    "principalTypeEnum": "LOCAL_USER",
    "groupNames": [
      "Administrator",
      "All",
      "System"
    ],
    "visibility": "DEFAULT",
    "activate": false
  },
  {
    "name": "system",
    "displayName": "System User",
    "created": 1354006445722,
    "modified": 1354006445722,
    "mail": "",
    "principalTypeEnum": "LOCAL_USER",
    "groupNames": [
      "All",
      "System"
    ],
    "visibility": "DEFAULT",
    "activate": false
  },
  {
    "name": "aptest",
    "displayName": "APtest",
    "created": 1634265580100,
    "modified": 1634269380481,
    "mail": "user15@thoughtspot.com",
    "principalTypeEnum": "LOCAL_USER",
    "groupNames": [
      "Administrator",
      "All"
    ],
    "visibility": "DEFAULT",
    "activate": false
  }
]

Object properties

A typical principal object contains the following properties:

  • name

    Name of the principal. This field, in conjunction with whether the object is a user or group, is used to identify a user or group. The name of the principal must be unique.

  • displayName

    Display name of the principal.

  • description

    Description of the principal.

  • mail

    The email address of the user. This field is populated only for the user objects. It is ignored if the object type is a group.

  • principalTypeEnum

    Type of the user created in the ThoughtSpot system. Valid values are:

    • LOCAL_USER for users that are created and authenticated locally in the ThoughtSpot system.

    • LOCAL_GROUP for groups that are saved in the local database of the ThoughtSpot system.

  • password

    The password of the user. This field is populated only for the user object. It is ignored in the case of groups.

    Password is only required:

    • if the user is of LOCAL_USER type

    • when the user is created for the first time. In subsequent updates, the user password is not modified even if it changes in the source system.

  • groupNames

    Name of the groups to which a principal belongs. For example, Administrator, All, and so on. Users can belong to multiple groups.

  • visibility

    If the user is visible to the other ThoughtSpot users or user groups who might want to share objects.

  • activate

Indicates if the user or user group needs to be activated. If the user or user group is already active, the activate property is set to false.

Response codes

HTTP status code Description

200

Successful operation.

Change password

To change the password of a ThoughtSpot user account, use the /tspublic/v1/user/updatepassword API endpoint.

Resource URL

POST /tspublic/v1/user/updatepassword

Request parameters

Form parameter Description

name

String. Name of the user account.

currentpassword

String. The password of the currently logged-in user. Note that only users with admin privileges can change the password of a user account.

password

String. A new password for the user specified in the name attribute.

Example request

cURL
curl -X POST \
--header 'Content-Type: application/x-www-form-urlencoded' \
--header 'Accept: application/json' \
--header 'X-Requested-By: ThoughtSpot' \
-d 'name=guest&currentpassword=test&password=User1234!' \
'https://<ThoughtSpot-host>/callosum/v1/tspublic/v1/user/updatepassword'
Request URL
https://<ThoughtSpot-host>/callosum/v1/tspublic/v1/user/updatepassword

Example response

If the operation is successful, the API returns the following response:

Response Code
204

Response codes

HTTP status code Description

204

Password update is successful.

Reset password

To reset the password of a ThoughtSpot user account, send a POST request to the /tspublic/v1/user/resetpassword API endpoint.

Resource URL

POST /tspublic/v1/user/resetpassword

Request parameters

Form parameter Description

userid

String. The GUID of the user account.

auth_token

String. The authentication token obtained for your user session.

password

String. A new password string for the user account.

Example request

cURL
curl -X POST \
--header 'Content-Type: application/x-www-form-urlencoded' \
--header 'Accept: application/json' \
--header 'X-Requested-By: ThoughtSpot' \
-d 'userid=59481331-ee53-42be-a548-bd87be6ddd4a&auth_token=JHNoaXJvMSRTSEEtMjU2JDUwMDAwMCRPMFA2S0ZlNm51Qlo4NFBlZUppdzZ3PT0kMnJKaSswSHN6Yy96ZGxqdXUwd1dXZkovNVlHUW40d3FLMVdBT3hYVVgxaz0&password=foobarA@123'
'https://<ThoughtSpot-host>/callosum/v1/tspublic/v1/user/resetpassword'
Request URL
https://<ThoughtSpot-host>/callosum/v1/tspublic/v1/user/resetpassword

Example response

If the operation is successful, the API returns the following response:

Response Code
204

Response codes

HTTP status code Description

204

Password reset is successful

401

Unauthorized request

500

Invalid parameter

Update a user profile

To update the profile settings of a ThoughtSpot user programmatically, you can use the /tspublic/v1/user/updatepreference API.

The /tspublic/v1/user/updatepreference API allows you to modify the following attributes of a ThoughtSpot user profile:

  • Email address

    The email address of the user.

  • Language preference

    The system locale setting. The locale setting determines the language of the ThoughtSpot UI, date, number, and currency format.

  • Notification setting

    User preference for receiving email notifications when another ThoughtSpot user shares answers or pinboards.

  • Settings for revisiting the onboarding experience

    The user preference for revisiting the onboarding experience.

    ThoughtSpot provides an interactive guided walkthrough to onboard new users. The onboarding experience leads users through a set of actions to help users get started and accomplish their tasks quickly. The users can turn off the Onboarding experience and access it again when they need assistance with the ThoughtSpot UI.

The /tspublic/v1/user/updatepreference API does not support modifying the profile picture of a user, the password of a user account, and the Answer experience preference settings in a user profile.

Resource URL

POST /tspublic/v1/user/updatepreference

Request parameters

Form parameter Description

userid
Optional

String. The GUID of the user.

username
Optional

String. Username of the user.

preferences

String. The JSON map of user preferences. In the JSON map, you can define the attributes to set the following preferences for a user:

  • change the display language of the ThoughtSpot UI

  • receive email notifications when another user shares an answer or pinboard

  • enable the onboarding experience

preferencesProto
Optional

String. A 64-bit encoded string for setting user preferences in a secure manner. For example, CgoKCAgBEAEYASAB.

If your browser or OS locale is set to a ThoughtSpot supported locale, ThoughtSpot automatically defaults to that locale. If your browser locale is not supported in ThoughtSpot, ThoughtSpot sets en-US (US English) as your default locale.

Example request

cURL
curl -X POST \
--header 'Content-Type: application/x-www-form-urlencoded' \
--header 'Accept: application/json' \
--header 'X-Requested-By: ThoughtSpot' \
-d 'userid=59481331-ee53-42be-a548-bd87be6ddd4a&preferences={"showWalkMe":true,"notifyOnShare":true,"analystOnboardingComplete":false,"preferredLocale":"en-IN"}' \
'https://<ThoughtSpot-host>/callosum/v1/tspublic/v1/user/updatepreference''
Request URL
https://<ThoughtSpot-host>/callosum/v1/tspublic/v1/user/updatepreference
Example JSON String

This example shows the following preference settings that you can pass as a JSON string.

{
   "showWalkMe":true,
   "notifyOnShare":true,
   "analystOnboardingComplete":false,
   "preferredLocale":"en-CA"
}
  • showWalkMe Boolean

    Enables or disables the guided onboarding walkthrough. When set to true, the user can revisit the onboarding experience.

  • notifyOnShare Boolean

    Sets a notification preference for receiving emails when another user shares answers or pinboards.

  • analystOnboardingComplete Boolean

    Indicates if the user is onboarded.

  • preferredLocale String

    Sets the ThoughtSpot locale for the specified user account. For example, to allow a user to view the ThoughtSpot UI in Deutsche, you can set the preferredLocale parameter to de-DE.

    The allowed values are:

    Locale Language

    da-DK

    Dansk

    de-DE

    Deutsche

    en-AU

    English (Australia)

    en-CA

    English (Canada)

    en-IN

    English (India)

    en-GB

    English (United Kingdom)

    en-US

    English (United States)

    es-US

    Español (Latinoamérica)

    es-ES

    Español (España)

    fr-CA

    Français (Canada)

    fr-FR

    Français (France)

    it-IT

    Italiano

    nl-NL

    Nederland

    nb-NO

    Norsk

    pt-BR

    Português (Brasil)

    pt-PT

    Português (Portugal)

    fi-FI

    Suomi

    sv-SE

    Svenska

    zh-CN

    中文(简体)

    ja-JP

    日本語

Response codes

HTTP status code Description

204

Successful update of a user profile

400

Invalid user ID

Transfer ownership

When a user is removed from the ThoughtSpot application, you may want to transfer objects from the deleted user account to another account. If you are an admin user, you can programmatically transfer the ownership of one or several objects from one ThoughtSpot user account to another, use the /tspublic/v1/user/transfer/ownership API endpoint.

Resource URL

POST /tspublic/v1/user/transfer/ownership

Request parameters

Query parameter Description

fromUserName

String. Username to transfer from.

toUserName

String. Username to transfer to.

objectid

String. A JSON array of ThoughtSpot object IDs.

Example request

cURL
curl -X POST \
--header 'Content-Type: application/json' \
--header 'Accept: application/json' \
--header 'X-Requested-By: ThoughtSpot' \
 'https://<ThoughtSpot-host>/callosum/v1/tspublic/v1/user/transfer/ownership?fromUserName=guest&toUserName=guest1'
Request URL
https://<ThoughtSpot-host>/callosum/v1/tspublic/v1/user/transfer/ownership?fromUserName=guest&toUserName=guest1

Example response

If the operation is successful, the API returns the following response:

Response Code
204

Response codes

HTTP status code Description

204

The ownership of objects is successfully transferred.

400

Invalid fromName or toName, or no user in the ThoughtSpot that matches the specified username.

Synchronize principals

To programmatically synchronize user accounts and user groups with ThoughtSpot, use the /tspublic/v1/user/sync API. The payload takes principals containing all users and groups present in the external database. A successful API call returns the object that represents the changes made in the ThoughtSpot system.

During this operation:

  • Objects (users or groups) present in ThoughtSpot, but not present in the external list are deleted in ThoughtSpot.

  • Objects present in ThoughtSpot and the external list are updated such that the object attributes in ThoughtSpot match those present in the list.

    This includes group membership.

  • Objects not present in ThoughtSpot, but present in the external list are created in ThoughtSpot.

Resource URL

POST /tspublic/v1/user/sync

Request parameters

This API uses multipart/form-data content-type.

Make sure you use a JSON file encoded as application/json or text/json for the principals attribute. The other arguments use standard form-encoding. Each is sent as its own part of the multi-part request.

Form parameter Description

principals

String. Specify a list of principal objects in the JSON file format. The JSON file can contain all users and groups present in the external database.

applyChanges

Boolean. Specify whether to sync the users and groups to the system and apply the difference evaluated. By default, this attribute is set to false.

removeDeleted

Boolean. Specify whether to remove the deleted users and user groups. By default, this attribute is set to true. If you do not want to remove deleted users or user groups, make sure to set removeDeleted to false.

password

String. The password of the admin user.

Example request

cURL
curl -X POST \
--header 'X-Requested-By : ThoughtSpot' \
--header 'Cookie : JSESSIONID=0f534ede-f096-44d0-966a-f02be91dcb68; clientId=5ea75049-cbc9-4443-b083-2d148059c235; userGUID=a0d4311a-d123-48e5-806b-8bdc35e3e835' \
--header 'Accept: application/json' \
-F 'applyChanges=false' \
-F 'removeDeleted=false' \
-F 'principals=@principals.json;type=application/json' \
https://<ThoughtSpot-host>/callosum/v1/tspublic/v1/user/sync
Request URL
https://<ThoughtSpot-host>/callosum/v1/tspublic/v1/user/sync

JSON request

The principals.json file contains the JSON request to be sent for synchronizing users. Make sure the JSON file is encoded as application/json in the API request.

Use the example format for the JSON requests:

[
  { "name": "Customer Success",
    "displayName": "Customer Success",
    "description": "CS",
    "created": 1568926267025,
    "modified": 1568926982242,
    "principalTypeEnum": "LOCAL_GROUP",
    "groupNames": [],
    "visibility": "DEFAULT" },

  { "name": "All",
    "displayName": "All Group",
    "created": 1354006445722,
    "modified": 1354006445722,
    "principalTypeEnum": "LOCAL_GROUP",
    "groupNames": [],
    "visibility": "DEFAULT" },

  { "name": "Marketing",
    "displayName": "Marketing",
    "description": "Marketing Group",
    "created": 1587573582931,
    "modified": 1587573583003,
    "principalTypeEnum": "LOCAL_GROUP",
    "groupNames": [],
    "visibility": "DEFAULT" },

  { "name": "test1",
    "displayName": "test one",
    "description": "",
    "created": 1587573554475,
    "modified": 1587573589986,
    "mail": "test1@test.com",
    "principalTypeEnum": "LOCAL_USER",
    "groupNames": [ "All", "Customer Success", "Marketing" ],
    "visibility": "DEFAULT" },

  { "name": "test2",
    "displayName": "test two",
    "created": 1587573621279,
    "modified": 1587573621674,
    "mail": "test2@test.com",
    "principalTypeEnum": "LOCAL_USER",
    "groupNames": [ "Administrator", "All" ],
    "visibility": "DEFAULT" }
]

The above example covers user objects (with emails), group objects, and their relationships.

  • You can leave the created and modified dates blank for new users.

  • You can specify if the principal is a user or user group in the principalTypeEnum keyword.

  • In the example JSON request, the test1 user belongs to two groups, Customer Success and Marketing, and the test2 user belongs to the group Administrator.

  • All is a default group to which every user belongs; you may omit it from the input.

  • Set visibility to NON_SHARABLE if you do not want users to share ThoughtSpot objects with other users in this group.

Response codes

HTTP status code Description

200

The user sync operation is successful.

500

Invalid request

Assign a user to groups

To assign a user to groups that exist in the Thoughtspot system, send a POST request to the /tspublic/v1/user/{userid}/groups API endpoint.

Resource URL

POST /tspublic/v1/user/{userid}/groups

Request parameters

Parameter Parameter Type Description

userid

path

String. The GUID of the user that you want to assign to the specified groups.

groupids

query

String. A JSON array of the GUIDs of the user groups to which you want to add the user.

Example request

cURL
curl -X POST \
--header 'Content-Type: application/json' \
--header 'Accept: application/json' \
--header 'X-Requested-By: ThoughtSpot' 'https://<ThoughtSpot-host>/callosum/v1/tspublic/v1/user/a8aeda00-dc3c-4485-b8d1-fd6ac701a819/groups?groupids=%5B%2246fc2125-d424-40bd-9513-23cd5e2e92c3%22%2C%222e3f697a-e38d-4d50-b5c5-e2514e85d90e%22%5D'
Request URL
https://<ThoughtSpot-host>/callosum/v1/tspublic/v1/user/a8aeda00-dc3c-4485-b8d1-fd6ac701a819/groups?groupids=%5B%2246fc2125-d424-40bd-9513-23cd5e2e92c3%22%2C%222e3f697a-e38d-4d50-b5c5-e2514e85d90e%22%5D

Example response

If the user group assignment is successful, the API returns the following response:

Response Code
204

Response codes

HTTP status code Description

204

Successful operation

400

Invalid parameter

Get user group details for a specific user

To get a list of user groups associated with a user, send a GET request to the /tspublic/v1/user/{userid}/groups API endpoint.

Resource URL

GET /tspublic/v1/user/{userid}/groups

Request parameters

Path parameter Description

Example request

cURL
curl -X GET \
--header 'Accept: application/json' \
--header 'X-Requested-By: ThoughtSpot' \ 'https://<ThoughtSpot-host>/callosum/v1/tspublic/v1/user/a8aeda00-dc3c-4485-b8d1-fd6ac701a819/groups'
Request URL
https://<ThoughtSpot-host>/callosum/v1/tspublic/v1/user/a8aeda00-dc3c-4485-b8d1-fd6ac701a819/groups

Example response

If the GET operation is successful, the API returns the following response:

[
  {
    "userGroupContent": {},
    "groupIdx": 2,
    "metadataVersion": -1,
    "assignedPinboards": [],
    "assignedGroups": [],
    "inheritedGroups": [],
    "privileges": [],
    "type": "LOCAL_GROUP",
    "parenttype": "GROUP",
    "visibility": "DEFAULT",
    "tenantId": "982d6da9-9cd1-479e-b9a6-35aa05f9282a",
    "displayName": "Test Group3",
    "header": {
      "id": "2364bf7c-7eec-4839-ac4b-e0cbb27aec37",
      "indexVersion": 95,
      "generationNum": 95,
      "name": "TestGroup3",
      "displayName": "Test Group3",
      "author": "59481331-ee53-42be-a548-bd87be6ddd4a",
      "created": 1634527727318,
      "modified": 1634527727318,
      "modifiedBy": "59481331-ee53-42be-a548-bd87be6ddd4a",
      "owner": "2364bf7c-7eec-4839-ac4b-e0cbb27aec37",
      "isDeleted": false,
      "isHidden": false,
      "tags": [],
      "type": "LOCAL_GROUP",
      "isExternal": false,
      "isDeprecated": false
    },
    "complete": true,
    "incompleteDetail": [],
    "isSystemPrincipal": false
  },
  {
    "userGroupContent": {},
    "groupIdx": 2,
    "metadataVersion": -1,
    "assignedPinboards": [],
    "assignedGroups": [],
    "inheritedGroups": [],
    "privileges": [],
    "type": "LOCAL_GROUP",
    "parenttype": "GROUP",
    "visibility": "DEFAULT",
    "tenantId": "982d6da9-9cd1-479e-b9a6-35aa05f9282a",
    "displayName": "Test Group2",
    "header": {
      "id": "2e3f697a-e38d-4d50-b5c5-e2514e85d90e",
      "indexVersion": 94,
      "generationNum": 94,
      "name": "TestGroup2",
      "displayName": "Test Group2",
      "author": "59481331-ee53-42be-a548-bd87be6ddd4a",
      "created": 1634527708775,
      "modified": 1634527708775,
      "modifiedBy": "59481331-ee53-42be-a548-bd87be6ddd4a",
      "owner": "2e3f697a-e38d-4d50-b5c5-e2514e85d90e",
      "isDeleted": false,
      "isHidden": false,
      "tags": [],
      "type": "LOCAL_GROUP",
      "isExternal": false,
      "isDeprecated": false
    },
    "complete": true,
    "incompleteDetail": [],
    "isSystemPrincipal": false
  }
]

Response codes

HTTP status code Description

200

Successful operation

400

Invalid parameter

Update group association for a user

To update the user group data for a specific user, send a PUT request to the /tspublic/v1/user/{userid}/groups API endpoint.

Resource URL

PUT /tspublic/v1/user/{userid}/groups

Request parameters

Parameter Parameter Type Description

userid

path

String. The GUID of the user that you want to modify.

groupids

query

String. A JSON array of the GUIDs of the user groups that you want to add or modify for the specified user.

Example request

cURL
curl -X PUT \
--header 'Content-Type: application/json' \
--header 'Accept: application/json'  \
--header 'X-Requested-By: ThoughtSpot' \
'https://<ThoughtSpot-host>/callosum/v1/tspublic/v1/user/a8aeda00-dc3c-4485-b8d1-fd6ac701a819/groups?groupids=%5B%222e3f697a-e38d-4d50-b5c5-e2514e85d90e%22%2C%222364bf7c-7eec-4839-ac4b-e0cbb27aec37%22%2C%2246fc2125-d424-40bd-9513-23cd5e2e92c3%22%5D'
Request URL
https://<ThoughtSpot-host>/callosum/v1/tspublic/v1/user/a8aeda00-dc3c-4485-b8d1-fd6ac701a819/groups?groupids=%5B%222e3f697a-e38d-4d50-b5c5-e2514e85d90e%22%2C%222364bf7c-7eec-4839-ac4b-e0cbb27aec37%22%2C%2246fc2125-d424-40bd-9513-23cd5e2e92c3%22%5D

Example response

If the user group update operation is successful, the API returns the following response:

Response Code
204

Response codes

HTTP status code Description

204

Successful operation

400

Invalid parameter

Remove a user from user groups

To remove the existing group assignments for a user, send a DELETE request to the /tspublic/v1/user/{userid}/groups API endpoint.

Resource URL

DELETE /tspublic/v1/user/{userid}/groups

Request parameters

Parameter Parameter Type Description

userid

path

String. The GUID of the user from which you want to delete the user group association.

groupids

query

String. A JSON array of the GUIDs of the user groups from which you want to remove the specified user object.

Example request

cURL
curl -X DELETE \
--header 'Accept: application/json' \
--header 'X-Requested-By: ThoughtSpot' \ 'https://<ThoughtSpot-host>/callosum/v1/tspublic/v1/user/a8aeda00-dc3c-4485-b8d1-fd6ac701a819/groups?groupids=%5B%222e3f697a-e38d-4d50-b5c5-e2514e85d90e%22%2C%222364bf7c-7eec-4839-ac4b-e0cbb27aec37%22%5D'
Request URL
https://<ThoughtSpot-host>/callosum/v1/tspublic/v1/user/a8aeda00-dc3c-4485-b8d1-fd6ac701a819/groups?groupids=%5B%222e3f697a-e38d-4d50-b5c5-e2514e85d90e%22%2C%222364bf7c-7eec-4839-ac4b-e0cbb27aec37%22%5D

Example response

If the user is removed from specified user groups, the API returns the following response:

Response Code
204

Response codes

HTTP status code Description

204

Successful operation

400

Invalid parameter