Skip to main content

Workspaces, targets and reusable elements

A workspace is where TOM keeps what a user saves: tabulations, Reach tables, targets and user variables, together with the surveys attached to it. This guide shows how to find workspaces, create them, read and reuse their elements and manage targets.

1. Find workspaces​

GET /api/v2/workspaces returns every workspace the user can open: the workspaces they own and the workspaces other users have shared with them.

  • Use the id of a workspace as workspaceId in the workspace endpoints.
  • surveyCode and surveyDescription describe the active survey of the workspace (the one selected in the TOM web application). They are empty strings when the workspace has no active survey, for example right after you create it.
  • The list is not paginated.
  • By default the list follows the order the user chose in the workspaces view of the TOM web application; without one, the most recently updated first. Send orderBy (NAME or LAST_UPDATED) and ascending to get another order.
  • ownership tells whether the user owns the workspace (OWN), owns it and shares it (SHARED_BY_ME), or another user shares it with them (SHARED_WITH_ME, with the owner in ownerName). A SHARED_WITH_ME workspace is read only: only its owner can create, edit or delete its elements.
  • lastUpdated is the last update of the workspace itself, not of its elements. It is omitted when the workspace was never updated.
warning

Calling this operation discards your unsaved per-user changes in the workspaces shared with you, including the surveys you added to them with the add-survey operation, and it can reset a TOM web application session that is open at the same time. Do not call it in a loop.

2. Create a workspace and add a survey​

POST /api/v2/workspace creates an empty workspace owned by the user of the key. Only name is required (up to 250 characters); title (250) and description (500) are optional.

{ "name": "Q4 2026 media plan" }
  • Names do not have to be unique, so every successful call creates a new workspace. After a timeout, check GET /api/v2/workspaces before you retry.
  • The new workspace has no surveys and no active survey.

POST /api/v2/workspace/{workspaceId}/source attaches a survey to a workspace so that it appears in its surveys list:

{ "code": "APP_DEMO_2025" }
  • code must be the code of a survey from GET /api/v2/users/surveys. It is not checked against the catalog: an unknown code is accepted with 200 but never appears in the workspace.
  • Adding a survey does not make it the active survey of the workspace.
  • Do not add a code that is already attached: the call is not idempotent and can fail. Check the surveys of the workspace first.
  • In a workspace shared with you, the list of surveys is kept per user: the survey is added to your list only, and after the addition your list may no longer include the surveys the owner attached.

3. Read a workspace​

GET /api/v2/workspace/{workspaceId} returns the workspace, the saved elements you can reuse and the surveys attached to it.

PropertyContainsUse the element id with
tabulationsSaved tabulations, including trend tablesThe saved tabulation and the element operations
reachTablesSaved Reach tablesThe element operation
targetsSaved targets (audiences)target.id in requests, and the update-target operation
userVarsUser variablesThe user variables list, which returns the ids to use in CUSTOM_VAR axes
  • Repeat type once per element type to keep only those lists, for example ?type=TABULATION&type=TARGET. The values are TABULATION, REACH_TABLE, TARGET and USER_VAR, in upper case. Lists that are not requested are omitted; surveys is always returned. Comma-separated values are not split. Any other value is 400 AE_ERR_401, and the message lists the valid ones.
  • Saved studies (rankings, evaluations, breakdowns and duplications) are not listed.
  • surveys lists every survey attached to the workspace, including surveys the user can no longer query, and does not include availableReach. Check them against the survey list before you use one.
  • A workspace that is neither owned by nor shared with the user gives 400 WS_ERR_403. A workspaceId that does not exist gives 500 GEN_ERR_500, not 404.

4. Reuse a saved table​

Saved tabulations and Reach tables come back in two forms:

  • As they are: GET .../survey/{surveyCode}/tabulation/{elementId} calculates the saved tabulation and returns one slice per call. See Building tables.
  • As a request you can edit: GET /api/v2/workspace/{workspaceId}/element/{elementId} returns the element converted to the request format of this API: table for a tabulation or a Reach table, target for a target, and only the metadata for a user variable. Send a tabulation to POST /api/v2/table/{surveyCode}. Send a Reach table unchanged to POST /api/v2/table/{surveyCode}, its /html variant or POST /api/v2/reach/{surveyCode}: it carries its Reach settings.

What to know before you reuse a table as a request:

  • The returned table carries the dimensions, the table type, extraParams (trendCategoriesMode included), the saved target and, when the base was saved applied, the targetBase. A target or a base comes with id when it was saved by id, with filterTgl when there is a saved TGL expression or its saved conditions can be written as one, and with label when there is one. With resolve=TGL, a target or a base saved by id also returns its filterTgl. A target or a base that cannot be returned in one of these forms is listed in notReproducible (see below).
  • A TABULATION or REACH_TABLE carries its effective weeks and weight: when the element has none saved, or the survey no longer has the saved one, they are the first week and the default weighting of the survey, the ones the TOM web application shows. A TREND or REACH_TREND carries them, with selected, in each survey wave of its SOURCES axis.
  • A Reach table (REACH_TABLE, REACH_DUPLICATION or REACH_TREND) carries its targetMedia and diaryFilters when they were saved. Its time configuration is in its TIME_DIARY_EDGE axes, so no Reach setting that changes the figures is left out.
  • A REACH_TREND comes complete: the element type is REACH_TABLE, table.tableType is REACH_TREND, and dimensions carries its SOURCES and DIFFERENCES axes. A SOURCES axis saved as a group of surveys comes expanded, one survey wave per member with its weeks and weighting. The weeks and the weighting of a wave only decide whether the wave is calculated: two waves of the same survey that differ only in them give identical columns.
  • surveyCode in the element is the survey currently active in the workspace, not necessarily the survey the element was saved with, and the table was read with it. Send the request to that surveyCode to get the figures of the element. In a REACH_TREND, the survey of the path acts as the active survey of the comparison, so another survey can give other figures: a survey without Reach is rejected with 400 RC_ERR_100, and a saved target that exists but does not resolve in that survey is left out of every wave with an ERROR diagnostic, while the answer is 200 over the whole population.
  • To build the request, the platform evaluates the saved table: expect the latency of a calculation, once per survey wave in a TREND or REACH_TREND, and an error if the saved definition is no longer valid for the active survey: when the variables of the element do not exist in the survey currently active in the workspace, the answer is 400, TB_ERR_104 when none of them exists there, or VA_ERR_101.
  • Saved studies (rankings, evaluations, breakdowns, duplications) are not supported and return 404.

Parts that cannot be returned as they were saved. notReproducible lists, outside table, what the request cannot carry as it was saved. It is omitted when there is nothing to mark. Each entry has a field and a reason:

fieldreasonWhat happened
target, targetBaseNEGATIONThe whole definition is negated, or it negates a numeric condition. A group or a category negated with NOT is written in filterTgl and is not marked.
target, targetBaseWEIGHTA box or a reference of the definition carries a weight.
target, targetBaseNESTEDThe definition has nested sets or references that cannot be expanded.
target, targetBaseEMPTYThe definition has no conditions.
target, targetBaseOTHERAny other reason, or the platform did not report one.
diaryEdgeGROUPED_ITEMAn item of a CUSTOM_DIARY_EDGE axis grouped several values (for example Monday to Friday), and it was left out of the axis.
diaryEdgeTOTAL_ITEMA CUSTOM_DIARY_EDGE or TIME_DIARY_EDGE axis shows its total item, which a request cannot ask for: sent back, the table has that row or column fewer.
  • A marked target or targetBase comes in table with its label only. Sent back unchanged, it is rejected with 400 AE_ERR_405 and the message names the field: the table is never calculated over the whole population. Define it again, by id or with filterTgl, before you send the table.
  • A base that is not applied is neither returned nor marked.
  • A grouped item is marked once, however many axes had one. The other items of the axis are returned as usual; an axis left without items is left out, and so is a dimension left without axes. Sent back, the table is calculated without the grouped item.

5. Targets​

A target is a named audience defined by a TGL expression, saved in a workspace. See the TGL guide for the syntax.

ToUse
List the targets, in the folder structure of the userGET /api/v2/workspace/{workspaceId}/survey/{surveyCode}/targets
Read the stored expressions and datesPOST .../targets/details with the ids
Create a targetPOST .../target
Replace a targetPUT .../target/{elementId}

List. The response has nodes of two types: TARGET_VAR (a saved target, with id, label and subtype LOGIC) and FOLDER (with label and items; folders have no id). Every target of the workspace is returned, whatever surveyCode you send: targets are not tied to a survey, and one that uses variables missing from a survey fails only when you use it with that survey. The response currently also contains the root folder of the workspace's user variables. If the workspace has no targets, the root Targets folder itself is returned.

Details. Send { "ids": ["..."] }. The response has one entry per id that can be returned, with id, label, filterTgl, creationDate and updatedDate. filterTgl is equivalent to the expression you saved but can be written differently: parentheses are normalised and negations are pushed down. An id that cannot be returned (it does not exist, or belongs to a workspace you cannot access) is left out without an error; if none can be returned, the answer is 200 with []. A missing or empty ids is a 400 VAL_ERR_001.

Create. Send the name and the expression:

{ "label": "Men, age groups 3 and 4", "tgl": "SEX.D1 AND (EDA1.D3 OR EDA1.D4)" }
  • workspaceId must be a workspace you own. surveyCode is the survey used to check the expression, usually the workspace's own survey.
  • The expression is checked before anything is saved: if the check fails, no target is created. An invalid expression returns a TGL error even when the workspace does not exist.
  • The answer is 200 with the new id, the label and the tgl exactly as you sent them.
  • The target is added at the end of the root of the Targets folder: the API cannot place it in a sub-folder.
  • Not idempotent: names do not have to be unique, so every call creates a new target. After a timeout, check the list before you send it again.

Update. PUT .../target/{elementId} is a full replacement: send both label and tgl, even when only one changes. The target keeps its id, so requests that reference it use the new definition.

  • To rename a target without changing its definition, send its current expression, available as filterTgl from the details operation. Part labels are not included in filterTgl, so a rename sent this way removes them.
  • Idempotent: repeating the same request leaves the target in the same state.
  • No concurrency control: when two clients update the same target at the same time, the last request processed wins.
  • Shared workspaces: only the workspace owner changes the target itself. In a workspace that is shared with you, the new expression is saved as your personal version of the target, which the owner and other users do not see, and the name does not change.
  • elementId must identify a target: the id of any other element is rejected with WS_ERR_102.

Targets accept only a subset of TGL: category references, comparisons and ranges on numeric variables, AND, OR and NOT(...). A variable on its own (for example SEX) is rejected, and XOR is saved as OR. See the TGL guide.

6. User variables​

GET /api/v2/workspace/{workspaceId}/survey/{surveyCode}/user-vars returns the user variables saved in a workspace, with their folders and, for categorical user variables, their categories (CUSTOM_CAT). To tabulate one, put its id and subtype in a VARIABLES axis with type: CUSTOM_VAR.

  • 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, query the custom tree with validate=true and read status (see Exploring variables and carriers).
  • Pick the user variables by type: CUSTOM_VAR: the response currently also contains the root folder of the workspace's targets.
  • Folders have no id.

7. Delete workspaces and elements​

Two operations delete data you own. A successful delete answers 204 with no body.

ToUse
Delete a workspace and everything in itDELETE /api/v2/workspace/{workspaceId}
Delete one element of a workspaceDELETE /api/v2/workspace/{workspaceId}/element/{elementId}
curl -X DELETE "https://<host>/api/v2/workspace/<workspaceId>/element/<elementId>" \
-H "X-API-Key: <your-api-key>"
warning

A delete is physical and cannot be undone, exactly as in the TOM web application. There is no trash and no confirmation step.

Delete a workspace. It removes everything the workspace contains: its elements, the folders and the menu, the attached surveys, the settings and the survey groups, together with its shares. The users the workspace was shared with lose access to it without notice.

Delete an element. You can delete tabulations, Reach tables, targets, user variables and saved evaluations. The element also disappears from the menu of the workspace. Folders and the workspace menu, maps and any other type cannot be deleted: the answer is 400 AE_ERR_420, and nothing is deleted.

  • The id of a saved evaluation is the one returned by POST /api/v2/survey/{surveyCode}/evaluation/save/{workspaceId} when you saved it. Saved evaluations are not listed afterwards, so keep that id if you want to delete the evaluation later.
  • Only the owner can delete. In a workspace shared with you (SHARED_WITH_ME), deleting the workspace or any of its elements answers 403 AE_ERR_418. A workspace you own and share (SHARED_BY_ME) can be deleted.
  • Dependencies are not checked. If you delete a target that a saved evaluation or a table uses, the delete succeeds and those elements keep their saved result unchanged.
  • No application module is required: being the owner is enough, including for saved evaluations.
  • A workspace that does not exist, that you cannot see or that is already deleted gives the same 404 AE_ERR_417. An element that does not exist in that workspace, that lives in another workspace or that is already deleted gives 404 AE_ERR_419. Repeating a delete therefore answers 404.
  • The checks run in a fixed order and stop at the first failure: workspace (404), owner (403), element (404), element type (400). For example, an element that does not exist in a workspace shared with you gives 403, not 404.
  • If another client deletes the same resource at the same moment, you get 404 or 204, never a 400 or a 500. In both cases the resource no longer exists.

8. Errors​

Status and errorCodeCause
400 WS_ERR_101The workspace does not exist (add a survey, create a target, save an evaluation).
400 WS_ERR_102The workspace has no target with that elementId, or the element is not a target.
400 WS_ERR_403The workspace is neither owned by nor shared with the user, or, for writes, is not owned by the user.
400 TREE_ERR_404The workspace does not exist (user variables and targets lists).
400 AE_ERR_401A type value of the workspace lists that is not an element type.
400 TGL_ERR_101The expression references a variable or category that does not exist in the survey.
422 TGL_INVALIDThe expression cannot be parsed, or uses a variable without a category or a condition.
400 VAL_ERR_001A required field is missing or empty (name of a workspace, code of a survey, label or tgl of a target), or a text is too long.
400 TB_ERR_104None of the variables of a saved tabulation is in the survey (get an element, saved tabulations).
400 AE_ERR_400The body is a JSON array, or a value has the wrong JSON type, for example an array in name or an object in tgl (create a workspace, add a survey, create or update a target, target details). The message names the field.
404 AE_ERR_404, AE_ERR_406The element, or the target of an element, does not exist.
404 AE_ERR_417The workspace does not exist, is not visible to the user or was already deleted (delete operations).
403 AE_ERR_418The workspace is shared with the user, not owned by them (delete operations).
404 AE_ERR_419The element does not exist in the workspace, or was already deleted (delete an element).
400 AE_ERR_420The type of the element cannot be deleted: a folder, the menu, a map or another type (delete an element).
403 AE_ERR_407The target exists but the user cannot see it.
500 GEN_ERR_500Unexpected error, including a workspaceId that does not exist in the get-workspace operation.

See Errors and troubleshooting.