Get a workspace
GET/api/v2/workspace/:workspaceId
Returns a workspace with the saved elements you can reuse through the API and the surveys attached to it.
Get workspaceId from GET /api/v2/workspaces.
Element lists
| Property | Contains | Use the element id with |
|---|---|---|
tabulations | Saved tabulations, including trend tables | GET /api/v2/workspace/{workspaceId}/survey/{surveyCode}/tabulation/{elementId}, GET /api/v2/workspace/{workspaceId}/element/{elementId} |
reachTables | Saved Reach tables | GET /api/v2/workspace/{workspaceId}/element/{elementId} |
targets | Saved targets (audiences) | target.id in table, ranking, evaluation and optimization requests; PUT /api/v2/workspace/{workspaceId}/survey/{surveyCode}/target/{elementId} |
userVars | User-defined variables | GET /api/v2/workspace/{workspaceId}/survey/{surveyCode}/user-vars, which returns the ids to use in CUSTOM_VAR axis items |
Saved studies (rankings, evaluations, breakdowns and duplications) are not listed.
Filtering with type
Repeat type once per element type to keep only those lists, for example ?type=TABULATION&type=TARGET. Lists that are not requested are omitted from the response. Without type, all four lists are returned. type does not filter surveys, which is omitted when no survey is attached to the workspace. Comma-separated values are not split. A value that is not an element type returns AE_ERR_401.
Surveys
surveyCode and surveyDescription identify the survey currently active in the workspace; they are empty strings when none is active. surveys lists every survey attached to the workspace, including surveys you can no longer query (for example, no longer contracted), and does not include availableReach. Check them against GET /api/v2/users/surveys before using one.
Surveys are named as in GET /api/v2/users/surveys: description is the name you see (your alias, or the catalog name when there is none) and originalDescription is the catalog name. surveyDescription takes the name of the matching entry in surveys; if the active survey is not among them, it is the name saved with the workspace.
Errors
| Status | errorCode | When |
|---|---|---|
| 400 | WS_ERR_403 | The workspace exists but is neither owned by nor shared with the caller. |
| 400 | AE_ERR_401 | type contains a value that is not an element type. Values are case-sensitive. |
| 400 | TW_ERR_500 | The X-API-Key value does not identify a TOM user. |
| 401 | E401 | The X-API-Key header is missing or empty. |
| 500 | GEN_ERR_500 | Unexpected error. A workspaceId that does not exist is also answered with 500, not 404. |
Request
Responses
- 200
- 400
- 401
- 500
The workspace, its element lists (filtered by type when given) and its attached surveys. surveys is omitted when no survey is attached.
The workspace is neither owned by nor shared with the caller (WS_ERR_403), the X-API-Key value does not identify a TOM user (TW_ERR_500), or type contains a value that is not an element type (AE_ERR_401).
The X-API-Key header is missing or empty.
Unexpected error. A workspaceId that does not exist is also answered with 500 (GEN_ERR_500), not 404.