User API

The User APIs allow you to programmatically create, update, and administer ThoughtSpot users.

Supported operations🔗

API endpoint Available from

API endpoint	Available from
`POST /tspublic/v1/user/` Creates a user account.	ThoughtSpot Cloud ts7.jun.cl ThoughtSpot Software 7.1.1
`POST /tspublic/v1/user/activate` Activates a user account.	ThoughtSpot Cloud ts7.sep.cl ThoughtSpot Software 7.2.1
`PUT /tspublic/v1/user/{userid}` Modifies a user account.	ThoughtSpot Cloud ts7.aug.cl ThoughtSpot Software 7.1.1
`PUT /tspublic/v1/user/email` Modifies the email address of a user.	ThoughtSpot Cloud ts7.oct.cl ThoughtSpot Software 7.2.1
`POST /tspublic/v1/user/addtoorg` Adds one or several users to the specified Org.	ThoughtSpot Cloud 8.10.0.cl ThoughtSpot Software Not available
`GET /tspublic/v1/user/` Gets details of the users in a ThoughtSpot system.	ThoughtSpot Cloud ts7.oct.cl ThoughtSpot Software 7.1.1
`DELETE /tspublic/v1/user/{userid}` Deletes a user account.	ThoughtSpot Cloud ts7.oct.cl ThoughtSpot Software 7.1.1
`GET /tspublic/v1/user/list` Gets all users, groups, and their inter-dependencies.	ThoughtSpot Cloud ts7.april.cl ThoughtSpot Software 6.0.x
`POST /tspublic/v1/user/updatepreference` Modifies a user profile.	ThoughtSpot Cloud ts7.jun.cl ThoughtSpot Software 7.1.1
`POST /tspublic/v1/user/transfer/ownership` Transfers the ownership of objects from one user to another.	ThoughtSpot Cloud ts7.april.cl ThoughtSpot Software 6.0.x
`POST /tspublic/v1/user/updatepassword` Changes the password of a user account.	ThoughtSpot Cloud ts7.april.cl ThoughtSpot Software 6.0.x
`POST /tspublic/v1/user/resetpassword` Resets the password of a user account.	ThoughtSpot Cloud ts7.sep.cl ThoughtSpot Software 7.2.1
`POST /tspublic/v1/user/session/invalidate` Invalidates a user session.	ThoughtSpot Cloud ts7.sep.cl ThoughtSpot Software 7.2.1
`POST /tspublic/v1/user/inactivate` Deactivates a user account.	ThoughtSpot Cloud ts7.sep.cl ThoughtSpot Software 7.2.1
`POST /tspublic/v1/user/sync` Synchronizes user and group properties from an external database with the user data on ThoughtSpot.	ThoughtSpot Cloud ts7.april.cl ThoughtSpot Software 6.0.x
`POST /tspublic/v1/user/{userid}/groups` Assigns a user to the specified user groups.	ThoughtSpot Cloud ts7.oct.cl ThoughtSpot Software 7.2.1
`GET /tspublic/v1/user/{userid}/groups` Gets details of the user groups associated with a specific user.	ThoughtSpot Cloud ts7.oct.cl ThoughtSpot Software 7.2.1
`PUT /tspublic/v1/user/{userid}/groups` Updates the user group data for a specific user.	ThoughtSpot Cloud ts7.oct.cl ThoughtSpot Software 7.2.1
`DELETE /tspublic/v1/user/{userid}/groups` Removes a user from the specified user groups.	ThoughtSpot Cloud ts7.oct.cl ThoughtSpot Software 7.2.1

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

ThoughtSpot Cloud ts7.jun.cl
ThoughtSpot Software 7.1.1

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

ThoughtSpot Cloud ts7.sep.cl
ThoughtSpot Software 7.2.1

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

ThoughtSpot Cloud ts7.aug.cl
ThoughtSpot Software 7.1.1

PUT /tspublic/v1/user/email
Modifies the email address of a user.

ThoughtSpot Cloud ts7.oct.cl
ThoughtSpot Software 7.2.1

POST /tspublic/v1/user/addtoorg
Adds one or several users to the specified Org.

ThoughtSpot Cloud 8.10.0.cl
ThoughtSpot Software Not available

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

ThoughtSpot Cloud ts7.oct.cl
ThoughtSpot Software 7.1.1

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

ThoughtSpot Cloud ts7.oct.cl
ThoughtSpot Software 7.1.1

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

ThoughtSpot Cloud ts7.april.cl
ThoughtSpot Software 6.0.x

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

ThoughtSpot Cloud ts7.jun.cl
ThoughtSpot Software 7.1.1

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

ThoughtSpot Cloud ts7.april.cl
ThoughtSpot Software 6.0.x

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

ThoughtSpot Cloud ts7.april.cl
ThoughtSpot Software 6.0.x

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

ThoughtSpot Cloud ts7.sep.cl
ThoughtSpot Software 7.2.1

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

ThoughtSpot Cloud ts7.sep.cl
ThoughtSpot Software 7.2.1

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

ThoughtSpot Cloud ts7.sep.cl
ThoughtSpot Software 7.2.1

POST /tspublic/v1/user/sync
Synchronizes user and group properties from an external database with the user data on ThoughtSpot.

ThoughtSpot Cloud ts7.april.cl
ThoughtSpot Software 6.0.x

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

ThoughtSpot Cloud ts7.oct.cl
ThoughtSpot Software 7.2.1

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

ThoughtSpot Cloud ts7.oct.cl
ThoughtSpot Software 7.2.1

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

ThoughtSpot Cloud ts7.oct.cl
ThoughtSpot Software 7.2.1

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

ThoughtSpot Cloud ts7.oct.cl
ThoughtSpot Software 7.2.1

Required permissions🔗

You must have administrator access to create, edit, and delete a user, assign users to groups, transfer objects from one user to another, and invalidate, deactivate or activate a user session.

If you have a multi-tenant instance with Orgs feature enabled, the cluster admin can create a user and associate the user to an orgid. For more information about Orgs, see Multi-tenancy with Orgs.

Create a user🔗

To programmatically create a user account in the ThoughtSpot system, send a POST request to /tspublic/v1/user/ API endpoint. Using this API, you can create a user and assign a user to a group.

Note	To create a user, you require admin user privileges. All users created in the ThoughtSpot system are added to ALL.

Resource URL🔗

POST /tspublic/v1/user/

Request parameters🔗

Parameter Type Description

name

Form parameter

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

password

Form parameter

String. Password for the user account.

displayname

Form parameter

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

properties Optional

Form parameter

String. A JSON map of user properties fetched from external systems such as LDAP. User property such as email address can be added in the JSON format.
"properties": { "mail": "[email protected]", }

groups Optional

Form parameter

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

Form parameter

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

LDAP_USER
SAML_USER
OIDC_USER
REMOTE_USER
LOCAL_USER

Note	If you call this API when importing user properties from an external server, such as Active Directory or IdP, the `usertype` property is automatically assigned to the users. For example, a user from an LDAP server is added as `LDAP_USER` in ThoughtSpot.

tenantid Optional

Form parameter

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

visibility Optional

Form parameter

String. Visibility of the user. The visibility attribute is set to DEFAULT when creating a user. The DEFAULT attribute sets the user visibility to shareable, which allows other users and groups to share objects with the user. To set user’s visibility to non-shareable, specify NON_SHARABLE.

orgids
Optional

Form parameter

Integer. A JSON array of org IDs to which you want to add the user. If orgids is not defined, ThoughtSpot assigns the user to an Org based on the administrator’s session. For example, if the administrator sends the API request from the Org 0 context, the user is added to Org 0.

triggeredbyadmin

Form parameter

Boolean. Indicates if the API request is initiated by a ThoughtSpot administrator or an external application. The default value is false.
When set to true, the displayNameLastUpdatedBy property is set to ADMIN in the API response, Else, displayNameLastUpdatedBy is set to AUTO.

orgScope Optional

Query parameter

String. The Org scope. Applicable to ThoughtSpot instances with Orgs feature enabled. When set to ALL, the administrator is authorized to perform cross-Org operations. By default, ThoughtSpot allows administrators to create a user in the Org context from which they make an API request. If you want to add the user to a different Org or multiple Orgs, set the Org scope to ALL and specify the Org ID(s) in the orgids attribute.

sendEmail

Query parameter

Boolean. When set to true, an email with the activation link is sent to the user’s email address.

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/?sendEmail=true'

Request URL

https://{ThoughtSpot-Host}/callosum/v1/tspublic/v1/user/?sendEmail=true

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": {
      "mail": "[email protected]",
      "displayNameLastUpdatedBy": "ADMIN"
    },
    "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": "userA2023",
  "header": {
    "id": "f31cc613-5f03-4df6-bc4a-309ab6160c0c",
    "indexVersion": 0,
    "generationNum": 0,
    "name": "userA2023",
    "displayName": "userA2023",
    "author": "59481331-ee53-42be-a548-bd87be6ddd4a",
    "created": 1698063672659,
    "modified": 1698063672659,
    "modifiedBy": "59481331-ee53-42be-a548-bd87be6ddd4a",
    "owner": "f31cc613-5f03-4df6-bc4a-309ab6160c0c",
    "isDeleted": false,
    "isHidden": false,
    "orgIds": [
      0
    ],
    "tags": [],
    "type": "LOCAL_USER",
    "aiAnswerGenerationDisabled": false,
    "isExternal": false,
    "isDeprecated": false,
    "isSharedViaConnection": false
  },
  "complete": true,
  "incompleteDetail": [],
  "isSuperUser": false,
  "isSystemPrincipal": false
}

Response codes🔗

HTTP status code	Description
200	Successful operation
400	Invalid parameter values Unauthorized user addition to an org
409	Username is not unique
403	Unauthorized request
500	Incorrect password format

HTTP status code

Description

200

Successful operation

400

Invalid parameter values
Unauthorized user addition to an org

409

Username is not unique

403

Unauthorized request

500

Incorrect password format

Update user details🔗

To modify an existing user account, send a PUT request to the /tspublic/v1/user/{userid} endpoint.

This API you to modify the following properties of a user object:

Username modifications
Password reset
Group assignment
User visibility for sharing objects
User’s email address
User preferences, such as viewing onboarding experience, subscribing to or unsubscribing from email notifications, and so on.

Note	You can also use the `/tspublic/v1/user/email` API endpoint to add or modify the email address of a user

Resource URL🔗

PUT /tspublic/v1/user/{userid}

Request parameters🔗

Parameter Type Description

Parameter	Type	Description
`userid`	Form parameter	String. GUID of the user.
`content`	Form parameter	String. A JSON map of strings with the user profile attributes.
`password` Optional	Form parameter	String. Password string for the user account. Use this attribute to change the password of the user account.
`triggeredbyadmin`	Form parameter	Boolean. Indicates if the user update API request is initiated by the ThoughtSpot administrator or an external application. By default, the `triggeredbyadmin` flag is set to `false`. The default value is `false`. When set to `true`, ThoughtSpot updates the `displayNameLastUpdatedBy` property to `ADMIN`. Else, the `displayNameLastUpdatedBy` property is set to `AUTO` for the specified user object.
`orgScope` Optional	Query parameter	String. The Org scope. If you are making this API request for a user that belongs to a different Org than the one you are currently logged in to, specify `ALL` to authorize the cross-Org operation.

userid

Form parameter

String. GUID of the user.

content

Form parameter

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

password Optional

Form parameter

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

triggeredbyadmin

Form parameter

Boolean. Indicates if the user update API request is initiated by the ThoughtSpot administrator or an external application. By default, the triggeredbyadmin flag is set to false. The default value is false.

When set to true, ThoughtSpot updates the displayNameLastUpdatedBy property to ADMIN. Else, the displayNameLastUpdatedBy property is set to AUTO for the specified user object.

orgScope Optional

Query parameter

String. The Org scope. If you are making this API request for a user that belongs to a different Org than the one you are currently logged in to, specify ALL to authorize the cross-Org operation.

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=6deb3976-e7c9-4f6a-94cc-90d790ee828d&content= {
   "userContent":{
      "userPreferences":{
         "notifyOnShare":false
      },
      "userProperties": {
         "mail": "[email protected]",
      },
      "userActivityProto":{
         "welcome_email_sent":true
      }
   },
   "state":"ACTIVE",
   "assignedGroups":[
      "f67ea2a4-efe7-4881-9ec4-32e1cb2605f3",
      "6085cc9f-087a-4075-9b33-11578538cec8"
   ],
   "inheritedGroups":[
      "bed1da2ea-e9b0-4d3e-8156-02dd331577d5"
   ],
   "privileges":[
      "A3ANALYSIS",
      "DATADOWNLOADING",
      "SHAREWITHALL",
      "USERDATAUPLOADING",
      "DATAMANAGEMENT",
      "ADMINISTRATION",
   ],
   "displayName":"UserA",
}&triggeredbyadmin=true' \
'https://{ThoughtSpot-Host}/callosum/v1/tspublic/v1/user/{userid}'

Request URL

https://{ThoughtSpot-Host}/callosum/v1/tspublic/v1/user/{userid}

JSON file example for updating user profile🔗

{
   "userContent":{
      "userPreferences":{
         "notifyOnShare":false,
      },
      "userActivityProto":{
         "welcome_email_sent":true
      }
   },
   "state":"ACTIVE",
   "assignedGroups":[
      "f67ea2a4-efe7-4881-9ec4-32e1cb2605f3",
      "6085cc9f-087a-4075-9b33-11578538cec8"
   ],
   "inheritedGroups":[
      "bed1da2ea-e9b0-4d3e-8156-02dd331577d5"
   ],
   "privileges":[
      "A3ANALYSIS",
      "DATADOWNLOADING",
      "SHAREWITHALL",
      "USERDATAUPLOADING",
      "DATAMANAGEMENT",
      "ADMINISTRATION",
   ],
   "displayName":"UserA",
   "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":[

Request URL

https://{ThoughtSpot-Host}/callosum/v1/tspublic/v1/user/{userid}

JSON file example for updating user profile🔗

The following example shows the JSON map content to send in the API request:

{
    "userContent": {
        "userPreferences": {
            "notifyOnShare": true,
            "showWalkMe": true,
            "analystOnboardingComplete": false
        },
        "userProperties": {
            "mail": "[email protected]",
            "displayNameLastUpdatedBy": "ADMIN"
        },
        "userActivityProto": {
            "first_login": -1,
            "welcome_email_sent": false
        }
    },
    "state": "ACTIVE",
    "assignedGroups": [
        "b25ee394-9d13-49e3-9385-cd97f5b253b4"
        "f67ea2a4-efe7-4881-9ec4-32e1cb2605f3",
        "6085cc9f-087a-4075-9b33-11578538cec8"
    ],
    "inheritedGroups": [
        "b25ee394-9d13-49e3-9385-cd97f5b253b4"
    ],
    "privileges": [],
    "type": "LOCAL_USER",
    "parenttype": "USER",
    "visibility": "DEFAULT",
    "tenantId": "982d6da9-9cd1-479e-b9a6-35aa05f9282a",
    "displayName": "TestDisplayName",
    "header": {
        "id": "d99556d5-9a32-4dea-bf40-b8955dcd186a",
        "indexVersion": 0,
        "generationNum": 0,
        "name": "Test",
        "displayName": "TestDisplayName",
        "author": "59481331-ee53-42be-a548-bd87be6ddd4a",
        "created": 1697793220573,
        "modified": 1697793220573,
        "modifiedBy": "59481331-ee53-42be-a548-bd87be6ddd4a",
        "owner": "d99556d5-9a32-4dea-bf40-b8955dcd186a",
        "isDeleted": false,
        "isHidden": false,
        "orgIds": [
            0
        ],
        "tags": [],
        "type": "LOCAL_USER",
        "aiAnswerGenerationDisabled": false,
        "aiAnswerState": "NOT_SET",
        "isExternal": false,
        "isDeprecated": false,
        "isSharedViaConnection": false,
        "isVerified": 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

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

Form parameter	Description
`userid`	String. GUID of the user.
`emailid`	String. Email address of the user.

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

HTTP status code

Description

204

Successful operation

400

Invalid user ID

500

Invalid email format

Add users to an Org🔗

To add one or several users to an org, send a POST request to the POST /tspublic/v1/user/addtoorg API endpoint.

Resource URL🔗

POST /tspublic/v1/user/addtoorg

Request parameters🔗

Parameter Type Description

Parameter	Type	Description
`userids`	Form parameter	String. A JSON array of user GUIDs to add to the specified org.
`orgid`	Form parameter	Integer. ID of the Org object to which you want to assign the users. By default, the user is added to the Org context from which the API request is sent. To add the user to another Org, specify the Org ID and set `orgScope` to `ALL`.
`orgScope`	Query parameter	String. The Org scope. For cross-Org operations, set this attribute to `ALL`.

userids

Form parameter

String. A JSON array of user GUIDs to add to the specified org.

orgid

Form parameter

Integer. ID of the Org object to which you want to assign the users. By default, the user is added to the Org context from which the API request is sent. To add the user to another Org, specify the Org ID and set orgScope to ALL.

orgScope

Query parameter

String. The Org scope. For cross-Org operations, set this attribute to ALL.

Example request🔗

cURL

curl -X POST \
--header 'Content-Type: application/x-www-form-urlencoded' \
--header 'Accept: application/json' \
-d 'userids=%5B4391d676-2dd8-4248-b6db-d973811f0122%2C37539499-624a-4d3d-8f88-e9be5653c114%5D&orgid=3' \
'http://{ThoughtSpot-Host}/callosum/v1/tspublic/v1/user/addtoorg?orgScope=ALL'

Request URL

https://{ThoughtSpot-Host}/callosum/v1/tspublic/v1/user/addtoorg?orgScope=ALL

Example response🔗

If the request is successful, the API returns the 204 response code:

Response Code
204

Response codes🔗

HTTP status code	Description
204	Successful operation
400	Invalid parameter
403	Unauthorized request

HTTP status code

Description

204

Successful operation

400

Invalid parameter

403

Unauthorized request

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.

Note	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` API.

Resource URL🔗

GET /tspublic/v1/user/

Request parameters🔗

Query parameter Description

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.

userid
Optional

String. The GUID of the user account to query.

name
Optional

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

Note	You can use either `userid` or `name` to query data for a specific user. If using both, make sure the values for these parameters 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": {
        "displayNameLastUpdatedBy": "ADMIN",
        "persona": "BUSINESS_USER"
        "mail": "[email protected]",
        "companyName": "",
        "activatedAtMs": 1649842964294
     },
    "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
}

Note	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

HTTP status code

Description

200

Successful retrieval of user details

400

Invalid username string

500

Invalid user ID

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

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.

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 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 via POST /tspublic/v1/user/activate API call.

Response codes🔗

HTTP status code	Description
200	Successful operation
403	Unauthorized request
500	Invalid username

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.

Important

When a user account is deactivated using the /tspublic/v1/user/inactivate endpoint, the API returns a response with the user ID and token string. Use this ID and the token string along with user properties in the base64 encoded format in the API request to re-activate the user account.

Resource URL🔗

POST /tspublic/v1/user/activate

Request parameters🔗

Form parameter Description

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`	String. User property string on the Base64 Encoded format. For example, if the user’s email address is `[email protected]`, specify `VXNlckFAdGhvdWdoc3BvdC5jb20=` in the request body.

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

String. User property string on the Base64 Encoded format. For example, if the user’s email address is [email protected], specify VXNlckFAdGhvdWdoc3BvdC5jb20= in the request body.

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=VXNlckFAdGhvdWdoc3BvdC5jb20='
'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

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.

Warning

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

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.

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

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🔗

Parameter Type Description

Parameter	Type	Description
`userid`	Path	String. GUID of the user account to delete.
`orgid`	Query	Integer. The org ID to which the user is associated. This parameter is required only if your ThoughtSpot instance has Orgs. If you are trying to delete a user that belongs only to the Org specified in the API request, the user is deleted from the Org and ThoughtSpot system. If the user belongs to multiple Orgs and you specify only one Org ID, the user is removed only from the specified Org and not from the ThoughtSpot system. To remove the user from all Orgs and the ThoughtSpot system, set the `orgScope` to `ALL`.
`orgScope`	Query	String. The Org scope. Specify `ALL` to set the Org scope to all Orgs.

userid

Path

String. GUID of the user account to delete.

orgid

Query

Integer. The org ID to which the user is associated. This parameter is required only if your ThoughtSpot instance has Orgs.
If you are trying to delete a user that belongs only to the Org specified in the API request, the user is deleted from the Org and ThoughtSpot system.
If the user belongs to multiple Orgs and you specify only one Org ID, the user is removed only from the specified Org and not from the ThoughtSpot system.
To remove the user from all Orgs and the ThoughtSpot system, set the orgScope to ALL.

orgScope

Query

String. The Org scope. Specify ALL to set the Org scope to all Orgs.

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

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": "[email protected]",
    "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. For example:
- 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
- SAML_USER for SSO users authenticated by a SAML IdP
- OIDC_USER for SSO users authenticated by an OpenID provider via OIDC protocol
- LDAP_GROUP for groups synchronized from an LDAP server
- LOCAL_GROUP for groups that are created locally on ThoughtSpot.
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 Code	Description
200	Successful operation

HTTP Code

Description

200

Successful operation

Change password🔗

To change the password of a ThoughtSpot user account, send a POST request to the /tspublic/v1/user/updatepassword endpoint.

Resource URL🔗

POST /tspublic/v1/user/updatepassword

Request parameters🔗

Form parameter Description

Form parameter	Description
`name`	String. Name of the user account.
`currentpassword`	String. The password of the currently logged-in user.
`password`	String. A new password for the user specified in the `name` attribute.

name

String. Name of the user account.

currentpassword

String. The password of the currently logged-in user.

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=foobarfoobar' \
'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.

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

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.

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

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, send a PUT request to the /tspublic/v1/user/updatepreference endpoint.

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 Liveboards.
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.

Note	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

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 Liveboard enable the onboarding experience
`preferencesProto` Optional	String. A 64-bit encoded string to set user preferences in a secure manner. For example, `CgoKCAgBEAEYASAB`.

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 Liveboard
enable the onboarding experience

preferencesProto Optional

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

Note	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 Liveboards.
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

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`	日本語

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

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 the account. Administrators can programmatically transfer the ownership of one or several objects from one ThoughtSpot user to another via the /tspublic/v1/user/transfer/ownership API endpoint.

Resource URL🔗

POST /tspublic/v1/user/transfer/ownership

Request parameters🔗

Query parameter Description

Query parameter	Description
`fromUserName`	String. Username to transfer from.
`toUserName`	String. Username to transfer to.
`objectsID` Optional	Array of strings. A JSON array of ThoughtSpot object IDs. Example with multiple object IDs: `[7589cbdb-eb50-4d8c-89e7-08e8f4573a5d,84481cda-f92e-4ba5-a1ef-366eb61017f5,5f9bc462-eca8-4b12-b8da-36474664eada]` Example with a single object ID: `[7589cbdb-eb50-4d8c-89e7-08e8f4573a5d]` If you do not specify the object IDs, all the objects owned by the user specified in `fromUserName` will be transferred to the user specified in `toUserName`.

fromUserName

String. Username to transfer from.

toUserName

String. Username to transfer to.

objectsID
Optional

Array of strings. A JSON array of ThoughtSpot object IDs.

Example with multiple object IDs:
[7589cbdb-eb50-4d8c-89e7-08e8f4573a5d,84481cda-f92e-4ba5-a1ef-366eb61017f5,5f9bc462-eca8-4b12-b8da-36474664eada]
Example with a single object ID:
[7589cbdb-eb50-4d8c-89e7-08e8f4573a5d]

If you do not specify the object IDs, all the objects owned by the user specified in fromUserName will be transferred to the user specified in toUserName.

Example request🔗

cURL

curl -X POST
--header 'Content-Type: application/json' /
--header 'Accept: application/json' /
'https://{ThoughtSpot-Host}/callosum/v1/tspublic/v1/user/transfer/ownership?fromUserName=User3&toUserName=tsadmin&objectsID=%5B%228e7d27c5-d4e8-494e-8c13-196a9961ffa1%22%2C%220c68a0a1-930b-4ba0-b7a0-59ea49b09848%22%5D'

Request URL

https://{ThoughtSpot-Host}/callosum/v1/tspublic/v1/user/transfer/ownership?fromUserName=testUser3&toUserName=tsadmin&objectsID=%5B%228e7d27c5-d4e8-494e-8c13-196a9961ffa1%22%2C%220c68a0a1-930b-4ba0-b7a0-59ea49b09848%22%5D

Example response🔗

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

Response Code
204

Response codes🔗

HTTP Code Description

HTTP 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.

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 the multipart/form-data content-type.

Note	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

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. Assign a password for new users added during the sync operation. By default, all new users will have the same password.
`orgScope` Optional	Query parameter

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. Assign a password for new users added during the sync operation. By default, all new users will have the same password.

orgScope
Optional

Query parameter

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 '[email protected];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": "[email protected]",
    "principalTypeEnum": "LOCAL_USER",
    "groupNames": [ "All", "Customer Success", "Marketing" ],
    "visibility": "DEFAULT" },

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

Important

The preceding 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

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

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.

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

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

Path parameter	Description
`userid`	String. The GUID of the user that you want to query.

userid

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

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

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

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.

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

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

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.

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