Skip to main content

Update a target

PUT 

/api/v2/workspace/:workspaceId/survey/:surveyCode/target/:elementId

Replaces the name and the TGL expression of an existing target.

This is a full replacement: send both label and tgl, even when only one of them changes. The new expression is checked against the variables of surveyCode before anything is saved: if the check fails, the target is left unchanged. The target keeps its id and its place in the workspace folders, so requests that reference it by id use the new definition.

Before you call it​

  • workspaceId: the workspace that contains the target (see Shared workspaces below).
  • elementId: the target id, from GET .../targets (nodes with type: TARGET_VAR) or from the response of POST .../target.
  • surveyCode: the survey used to check the expression, usually the workspace's own surveyCode.
  • Variable and category codes: the id values returned by GET /api/v2/survey/{surveyCode}/variables. The accepted TGL is the same as for POST .../target; see also the TGL guide.

Request body​

FieldRequiredDescription
labelYesNew name of the target. Cannot be empty. Also replaces its title and description.
tglYesNew boolean TGL expression. Cannot be empty.

Unknown fields are ignored. To rename a target without changing its definition, send its current expression, available as filterTgl from POST .../targets/details. Part labels are not included in filterTgl, so a rename sent this way removes them.

Response​

200 OK with the target id, and label and tgl exactly as you sent them.

Behaviour​

  • Idempotent: repeating the same request leaves the target in the same state; only its update date changes.
  • No concurrency control: when two clients update the same target at the same time, the last request processed wins. There is no version check and no 409 Conflict.
  • 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. Changes can take up to one hour to be visible to the other users of a shared workspace.
  • elementId must identify a target: the id of any other workspace element (a table, for example) is rejected with WS_ERR_102.
  • The expression is checked before the target is looked up, so an invalid expression returns a TGL error even when elementId does not exist.

Errors​

errorMessage is meant for people and may be in the user's language. Base your error handling on errorCode.

StatuserrorCodeWhen
400VAL_ERR_001label or tgl is missing or empty, or the body is empty.
400E400The body is not valid JSON.
400AE_ERR_400The body is a JSON array, or a value has the wrong JSON type, such as an object in tgl. The message names the field.
400TGL_ERR_101The expression references a variable or category that does not exist in surveyCode.
400WS_ERR_102No target with this elementId exists in this workspace: unknown id, unknown workspace, or an element that is not a target.
400WS_ERR_403The workspace belongs to another user and is not shared with you.
400TW_ERR_500The X-API-Key value does not identify a TOM user.
401E401The X-API-Key header is missing or empty.
422TGL_INVALIDThe expression cannot be parsed, or uses a variable without a category or a condition.
500GEN_ERR_500Unexpected error.

Request​

Responses​

The target was updated. Returns its id, and the label and tgl you sent.