Save a media plan evaluation to a workspace
POST/api/v2/survey/:surveyCode/evaluation/save/:workspaceId
Calculates a media plan evaluation and saves the result as a new study element in a workspace, so that it can be opened later in the TOM web application.
The calculation is exactly the one of POST /api/v2/survey/{surveyCode}/evaluation. The response describes the created element, not the calculated figures; call the evaluation operation when you need the numbers.
Before you call it
workspaceId: a workspace owned by the user of the API key, fromGET /api/v2/workspacesorPOST /api/v2/workspace. Workspaces shared with the user cannot be written to.- Everything the evaluation needs:
surveyCode, carriers withinsertionsper plan, statistic ids and, optionally, a target and a population base. - The user needs the Study module.
Request
The same body as POST /api/v2/survey/{surveyCode}/evaluation, plus:
title(optional): name of the new element, also used as its title and description. Up to 100 characters. Defaults toEVALUATION.target(optional): withtarget.idthe element stores a reference to the saved target (its id and label), which may live in any workspace visible to the user; withtarget.filterTglthe expression itself is stored. With both,filterTglis used; atargetwith neither is rejected.targetBase(optional): the element stores the population base, applied, as it is sent: theidor the expression.priceof each carrier (optional): the element keeps it as the price of that carrier, so the saved plan opens with it.
The element is saved with surveyCode as its survey.
Deprecated names
Earlier versions used other names for carriers. The type values SUPPORT (for CARRIER) and FAMILY (for FOLDER) are still accepted in requests. Use the current names.
Behaviour
- Not idempotent: every successful call creates a new element, even with an identical body. Do not retry blindly after a timeout.
- If
target.iddoes not exist (404,AE_ERR_406) or is not visible to the user (403,AE_ERR_407), the request is rejected and no element is saved. - Unlike
POST /api/v2/survey/{surveyCode}/evaluation, the statistic ids are not validated: an id that does not apply is ignored without an error. - The evaluation is calculated before the workspace is checked, so an invalid
workspaceIdis reported after the calculation. - The element is a study element. It is not listed by
GET /api/v2/workspace/{workspaceId}and cannot be read back withGET /api/v2/workspace/{workspaceId}/element/{elementId}; open it in the TOM web application. - The
idof the response is the one to use to delete the evaluation later withDELETE /api/v2/workspace/{workspaceId}/element/{elementId}. Keep it: the evaluation is not listed anywhere else.
Response
200 with the created element: id, name, title, description, enabled and its creation and last update dates.
Errors
errorMessage is meant for people and may be in the user's language. Base your error handling on errorCode.
| Status | errorCode | When |
|---|---|---|
| 400 | AE_ERR_405 | target or targetBase has neither a non-blank id nor a non-blank filterTgl. |
| 400 | AE_ERR_400 | carriers is missing, null or empty (an empty or null body included), or a value has the wrong JSON type. |
| 400 | AE_ERR_400 | A price is negative, or is sent on a folder; the message names the carrier. |
| 400 | AE_ERR_412 | An item of carriers or statistics is null or has no id; the message gives its position. |
| 400 | EV_ERR_104 | No carrier has a positive number of insertions. |
| 400 | EV_ERR_103 | A carrier has a negative number of insertions. |
| 400 | SP_ERR_101 | A carrier id does not exist in the survey. |
| 400 | TG_ERR_113 | targetBase.id does not identify a saved target. |
| 400 | TGL_ERR_101 | A filterTgl of target or targetBase uses a variable or category that the survey does not have. |
| 400 | ST_ERR_122 | The survey cannot be used for media planning, for example a consumption-diary (Reach) survey. |
| 400 | WS_ERR_101 | The workspace does not exist. |
| 400 | WS_ERR_403 | The user does not own the workspace. |
| 400 | VAL_ERR_001 | title is longer than 100 characters. |
| 400 | E400 | The body is not valid JSON. |
| 400 | SO_ERR_201, SO_ERR_202 | The survey is disabled, being loaded, or deleted. |
| 401 | E401 | The X-API-Key header is missing or empty. |
| 401 | SO_ERR_203 | The survey is not in your profile or does not exist. |
| 403 | AE_ERR_408 | The user does not have the Study module. |
| 403 | AE_ERR_407 | target.id exists but is not visible to the user. |
| 404 | AE_ERR_406 | target.id does not exist in any workspace visible to the user. |
| 422 | TGL_INVALID | A filterTgl of target or targetBase cannot be used: it does not parse, or it uses a variable without a category or a condition. |
| 500 | GEN_ERR_500 | Unexpected error. If the failure happens after the calculation, the element may or may not have been created: check in the TOM web application before retrying. |
Errors raised by the workspace service and the calculation engine keep their own errorCode, and their errorMessage can be translated: rely on errorCode.
Request
Responses
- 200
- 400
- 401
- 403
- 404
- 422
- 500
The evaluation was saved as a new study element of the workspace. The response describes that element, not the calculated figures.
The request cannot be processed. AE_ERR_400: carriers is missing or empty, or a price is negative or sent on a folder. AE_ERR_412: an item of carriers or statistics is null or has no id. AE_ERR_405: target or targetBase has neither id nor filterTgl. EV_ERR_104: no carrier has a positive number of insertions. EV_ERR_103: a carrier has a negative number of insertions. SP_ERR_101: a carrier id does not exist in the survey. TG_ERR_113: targetBase.id does not identify a saved target. TGL_ERR_101: a filterTgl uses a variable or category that the survey does not have. ST_ERR_122: the survey cannot be used for media planning, for example a consumption-diary (Reach) survey. WS_ERR_101: the workspace does not exist. WS_ERR_403: the user does not own the workspace. SO_ERR_201, SO_ERR_202: the survey is disabled, being loaded or deleted. E400: the body is not valid JSON. VAL_ERR_001: title is longer than 100 characters.
The X-API-Key header is missing or empty (E401), or the survey is not in the user's profile or does not exist (SO_ERR_203).
The application module this operation needs is not enabled for the user (AE_ERR_408), or the target id exists but is not visible to the user (AE_ERR_407).
target.id does not exist in any workspace visible to the user (AE_ERR_406).
A TGL expression of the request cannot be used (TGL_INVALID): 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. If the failure happens after the calculation, the element may or may not have been created: check in the TOM web application before retrying.