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, fromGET /api/v2/workspacesorPOST /api/v2/workspace. You cannot create targets in a workspace that is only shared with you.surveyCode: the survey used to check the expression, fromGET /api/v2/users/surveys. This is usually the workspace's ownsurveyCode.- Variable and category codes: the
idvalues returned byGET /api/v2/survey/{surveyCode}/variables, writtenVARIABLE.CATEGORY(for exampleSEX.D1). Codes are not case-sensitive.
Request body
| Field | Required | Description |
|---|---|---|
label | Yes | Name 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. |
tgl | Yes | Boolean 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 exampleEDA1.D3. - Comparisons on numeric variables:
=,<>(also!=and/=),<,<,>,>=followed by a number, for exampleAGE >= 18. - Integer ranges on numeric variables:
AGE IN 18..34andAGE NOT IN 18..34. AND,OR, parentheses andNOT(...).ANDis evaluated beforeOR; 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 .../targetswhether 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 returnedid.
Errors
errorMessage is meant for people and may be in the user's language. Base your error handling on errorCode.
| Status | errorCode | When |
|---|---|---|
| 400 | VAL_ERR_001 | label or tgl is missing or empty, or the body is empty. |
| 400 | E400 | The body is not valid JSON. |
| 400 | AE_ERR_400 | The body is a JSON array, or a value has the wrong JSON type, such as an object in tgl. The message names the field. |
| 400 | TGL_ERR_101 | The expression references a variable or category that does not exist in surveyCode. |
| 400 | WS_ERR_101 | No workspace exists with this workspaceId. |
| 400 | WS_ERR_403 | The workspace belongs to another user. |
| 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. |
| 422 | TGL_INVALID | The expression cannot be parsed, or uses a variable without a category or a condition (for example SEX). |
| 500 | GEN_ERR_500 | Unexpected error. |
Request
Responses
- 200
- 400
- 401
- 422
- 500
The target was created. Returns its id, label and the tgl you sent.
The request cannot be processed. TGL_ERR_101: the expression references a variable or category that does not exist in surveyCode. WS_ERR_101: no workspace exists with this workspaceId. WS_ERR_403: the workspace belongs to another user. E400: the body is not valid JSON. AE_ERR_400: the body is a JSON array, or a value has the wrong JSON type. TW_ERR_500: the X-API-Key value does not identify a TOM user. VAL_ERR_001: label or tgl is missing or empty, or the body is empty.
The X-API-Key header is missing or empty.
The TGL expression cannot be used: it does not parse, or it uses a variable without a category or condition. An unknown variable or category returns 400 TGL_ERR_101 instead.
Unexpected error.