Skip to main content

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, from GET /api/v2/workspaces or POST /api/v2/workspace. Workspaces shared with the user cannot be written to.
  • Everything the evaluation needs: surveyCode, carriers with insertions per 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 to EVALUATION.
  • target (optional): with target.id the element stores a reference to the saved target (its id and label), which may live in any workspace visible to the user; with target.filterTgl the expression itself is stored. With both, filterTgl is used; a target with neither is rejected.
  • targetBase (optional): the element stores the population base, applied, as it is sent: the id or the expression.
  • price of 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.id does 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 workspaceId is 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 with GET /api/v2/workspace/{workspaceId}/element/{elementId}; open it in the TOM web application.
  • The id of the response is the one to use to delete the evaluation later with DELETE /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.

StatuserrorCodeWhen
400AE_ERR_405target or targetBase has neither a non-blank id nor a non-blank filterTgl.
400AE_ERR_400carriers is missing, null or empty (an empty or null body included), or a value has the wrong JSON type.
400AE_ERR_400A price is negative, or is sent on a folder; the message names the carrier.
400AE_ERR_412An item of carriers or statistics is null or has no id; the message gives its position.
400EV_ERR_104No carrier has a positive number of insertions.
400EV_ERR_103A carrier has a negative number of insertions.
400SP_ERR_101A carrier id does not exist in the survey.
400TG_ERR_113targetBase.id does not identify a saved target.
400TGL_ERR_101A filterTgl of target or targetBase uses a variable or category that the survey does not have.
400ST_ERR_122The survey cannot be used for media planning, for example a consumption-diary (Reach) survey.
400WS_ERR_101The workspace does not exist.
400WS_ERR_403The user does not own the workspace.
400VAL_ERR_001title is longer than 100 characters.
400E400The body is not valid JSON.
400SO_ERR_201, SO_ERR_202The survey is disabled, being loaded, or deleted.
401E401The X-API-Key header is missing or empty.
401SO_ERR_203The survey is not in your profile or does not exist.
403AE_ERR_408The user does not have the Study module.
403AE_ERR_407target.id exists but is not visible to the user.
404AE_ERR_406target.id does not exist in any workspace visible to the user.
422TGL_INVALIDA filterTgl of target or targetBase cannot be used: it does not parse, or it uses a variable without a category or a condition.
500GEN_ERR_500Unexpected 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​

The evaluation was saved as a new study element of the workspace. The response describes that element, not the calculated figures.