Skip to main content

Create a target

POST 

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

Creates a target in a workspace from a name and a TGL expression, and returns the identifier of the new target.

The expression is checked against the variables of surveyCode before anything is saved: if the check fails, no target is created. The target is saved in the workspace, not in the survey, and can be reused by id with any survey that contains the variables it references.

Before you call it​

  • workspaceId: a workspace you own, from GET /api/v2/workspaces or POST /api/v2/workspace. You cannot create targets in a workspace that is only shared with you.
  • surveyCode: the survey used to check the expression, from GET /api/v2/users/surveys. This is usually the workspace's own surveyCode.
  • Variable and category codes: the id values returned by GET /api/v2/survey/{surveyCode}/variables, written VARIABLE.CATEGORY (for example SEX.D1). Codes are not case-sensitive.

Request body​

FieldRequiredDescription
labelYesName of the target in the workspace. Cannot be empty. Also used as the target's title and description. Names do not have to be unique.
tglYesBoolean TGL expression that defines the audience. Cannot be empty.

workspaceId and surveyCode go in the path, not in the body. Unknown fields in the body are ignored.

TGL accepted in targets​

Targets accept a subset of the language described in the TGL guide:

  • Category references: VARIABLE.CATEGORY, for example EDA1.D3.
  • Comparisons on numeric variables: =, <> (also != and /=), <, <, >, >= followed by a number, for example AGE >= 18.
  • Integer ranges on numeric variables: AGE IN 18..34 and AGE NOT IN 18..34.
  • AND, OR, parentheses and NOT(...). AND is evaluated before OR; use parentheses when you mix them.
  • Optional weights and labels, as described in the TGL guide.

A variable on its own, without a category or a condition (for example SEX), is rejected. Comparisons and ranges work on numeric variables only. Do not use functions, arithmetic, text comparisons, text category references, TRUE/FALSE or XOR in targets: they are not supported, and some of them are not rejected but saved with a different meaning (XOR is saved as OR). A leading name ('Adults': ...) is ignored: the target's name always comes from label.

Response​

200 OK with the new target's id, its label, and tgl exactly as you sent it. To read the expression as stored, and the creation date, send the id to POST /api/v2/workspace/{workspaceId}/survey/{surveyCode}/targets/details.

Behaviour​

  • The target is added at the end of the root of the workspace's 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, even when the request is repeated. If a call times out, check with GET .../targets whether the target was created before you send it again.
  • The expression is checked before the workspace: an invalid expression returns a TGL error even when the workspace does not exist.
  • To change the target later, use PUT .../target/{elementId} with the returned id.

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_101No workspace exists with this workspaceId.
400WS_ERR_403The workspace belongs to another user.
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 (for example SEX).
500GEN_ERR_500Unexpected error.

Request​

Responses​

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