List the user variables of a workspace
GET/api/v2/workspace/:workspaceId/survey/:surveyCode/user-vars
Returns all the user variables saved in a workspace, with the folders that organise them and, for categorical user variables, their categories.
A user variable is a variable that a user builds in the TOM web application from the survey variables (for example, a recode of age into three groups, or a combination of several answers) and saves in a workspace. You can tabulate it like a survey variable: put its id and subtype in a VARIABLES axis of POST /api/v2/table/{surveyCode} with type: CUSTOM_VAR.
Before you call it
workspaceIdis theidof a workspace returned byGET /api/v2/workspaces.surveyCodeis thecodeof a survey returned byGET /api/v2/users/surveys.
Response
- An array with the content of the workspace's user-variables folder: sub-folders (
type: FOLDER) and user variables (type: CUSTOM_VAR), nested throughitemsat any depth. The folder itself is not returned, except when the workspace has no user variables: then the user-variables folder itself is returned instead of an empty array. - The array currently also contains the root folder of the workspace's targets (a
FOLDERwithoutid) with its sub-folders. Pick the user variables bytype: CUSTOM_VAR. - Folders have no
id: they only group user variables. subtypetells how the user variable is measured; usuallySINGLE,MULTIPLE,NUMERIC,REALorFREQUENCY(the subtypes that can be tabulated). A user variable copied from a survey variable keeps that variable's subtype. OnlySINGLEandMULTIPLEuser variables list their categories (type: CUSTOM_CAT) initems.- Properties without a value are omitted.
Behaviour
- All the user variables of the workspace are returned, whatever the survey:
surveyCodedoes not filter them and their validity is not checked. To know which ones can be used with a survey, callPOST /api/v2/workspace/{workspaceId}/survey/{surveyCode}/tree/query/customwithvalidate=trueand readstatus. - A user variable whose definition cannot be read is left out of the response.
- Targets saved in the same workspace are listed by
GET /api/v2/workspace/{workspaceId}/survey/{surveyCode}/targets.
Errors
| Status | errorCode | When |
|---|---|---|
| 400 | TREE_ERR_404 | The workspace does not exist. |
| 401 | E401 | The X-API-Key header is missing or empty. |
| 500 | GEN_ERR_500 | Unexpected error. |
Request
Responses
- 200
- 400
- 401
- 500
The user variables of the workspace, with their folders and categories nested in items.
The workspace does not exist (TREE_ERR_404).
The X-API-Key header is missing or empty.
Unexpected error.