Skip to main content

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​

  • workspaceId is the id of a workspace returned by GET /api/v2/workspaces.
  • surveyCode is the code of a survey returned by GET /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 through items at 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 FOLDER without id) with its sub-folders. Pick the user variables by type: CUSTOM_VAR.
  • Folders have no id: they only group user variables.
  • subtype tells how the user variable is measured; usually SINGLE, MULTIPLE, NUMERIC, REAL or FREQUENCY (the subtypes that can be tabulated). A user variable copied from a survey variable keeps that variable's subtype. Only SINGLE and MULTIPLE user variables list their categories (type: CUSTOM_CAT) in items.
  • Properties without a value are omitted.

Behaviour​

  • All the user variables of the workspace are returned, whatever the survey: surveyCode does not filter them and their validity is not checked. To know which ones can be used with a survey, call POST /api/v2/workspace/{workspaceId}/survey/{surveyCode}/tree/query/custom with validate=true and read status.
  • 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​

StatuserrorCodeWhen
400TREE_ERR_404The workspace does not exist.
401E401The X-API-Key header is missing or empty.
500GEN_ERR_500Unexpected error.

Request​

Responses​

The user variables of the workspace, with their folders and categories nested in items.