Skip to main content

ResponseCurveRequest

Body of the response-curve calculation: the carriers, the optional target and targetBase and the curve configuration. title and statistics are accepted, as in the evaluation, but they do not change the curve.

carriers object[]required

Carriers to calculate, with ids from GET /api/v2/survey/{surveyCode}/carriers. In an evaluation or a response curve, each position of the insertions array of a carrier is a plan. Required and non-empty.

Possible values: >= 1

  • Array [
  • idstring

    Identifier of the carrier or folder, as returned by the carriers listing.

    labelstring

    Display label. Optional: the result labels each row in the language of the user.

    typeRankingCarrierType (string)

    Kind of carrier. CARRIER (the default when omitted) is one carrier. Any other value, FOLDER included, is read as a folder: every carrier of that folder of the carriers tree, and its insertions are ignored. A joint of carriers is not supported by these operations: it is read as a folder. Values are case-sensitive.

    Enum ValueDescription
    CARRIEROne carrier (a media vehicle). It is the default when type is omitted and the only kind that reads insertions.
    FOLDEREvery carrier of a folder of the carriers tree, kept as a grouping row. Its insertions are ignored.

    Possible values: [CARRIER, FOLDER]

    pathstring

    Folder path of the carrier in the carriers tree. Optional. Responses do not return it.

    insertionsinteger<int32>[]

    Insertions of the carrier, one value per plan: position 0 is plan 1, position 1 is plan 2, and so on. A ranking adds one plan column per position; an evaluation and a response curve measure the plans. In a response curve it is required and non-empty, otherwise 400 AE_ERR_400. Ignored for a folder.

    pricenumber<double>

    Net price of one insertion of the carrier, in the currency of the survey. Optional. It replaces the price configured for this carrier, as the price of an optimization candidate does, and every cost statistic is calculated with it: the list price ones (PRICE, CPM_CONT, CGRP...) and the discounted ones (DISCOUNT_PRICE, DISCOUNT_CPM_CONT...). One price per carrier: it applies to every plan. 0 is a cost of zero (in an optimization it counts as no price). Without it, the configured price is used. A negative price, or a price on a folder, is rejected with 400 AE_ERR_400. A response curve accepts it, but its figures do not change: the curve returns no cost statistic.

    Possible values: >= 0

  • ]
  • statistics object[]

    Statistics to calculate, by id, from GET /api/v2/statistics?tableType=RANKING or tableType=EVALUATION. Only id is read. An id that does not apply returns 400 AE_ERR_402; one the survey does not provide, 400 AE_ERR_403. Required by the ranking: without it, or with an empty list, the ranking returns 400 T_ERR_104. Optional in the evaluation, its save and the response curve: when omitted, the evaluation uses the statistics configured for evaluations in the user's TOM settings.

  • Array [
  • idstring

    Identifier of the statistic, as returned by GET /api/v2/statistics. Send it in a STATISTICS axis.

    labelstring

    Display label, in the language of the user.

    descriptionstring

    Explanation of what the statistic measures, in the language of the user.

    selectedboolean

    Not returned by GET /api/v2/statistics. In table requests and responses it marks the selected statistic of an axis; in a PLANES axis several can be selected (one matrix each), in any other axis at most one.

  • ]
  • titlestring

    Name of the element created by POST /api/v2/survey/{surveyCode}/evaluation/save/{workspaceId}; the other operations ignore it. Up to 100 characters; EVALUATION when omitted.

    Possible values: <= 100 characters

    hierarchyboolean

    When true, the folders of the carriers are kept as grouping rows above their carriers. Default false.

    Default value: false
    target object

    Audience the calculation is restricted to: id (a saved target visible to the user) or filterTgl (an inline TGL expression); with both, filterTgl wins, and other fields are ignored. An object with neither returns 400 AE_ERR_405; an unknown id, 404 AE_ERR_406; a target that is not visible, 403 AE_ERR_407. Omit it to use the whole population.

    idstring

    Identifier of the saved target, as returned by GET /api/v2/workspace/{workspaceId}/survey/{surveyCode}/targets.

    labelstring

    Display name of the target. Ignored when the target is sent in a request.

    filterTglstring

    TGL expression that defines the audience. In responses it is omitted when the target has no definition that can be expressed in TGL. In requests, send it to define the audience inline.

    creationDatestring<date-time>

    Creation date and time of the target, ISO 8601 with a UTC offset. Omitted when not available. Ignored in requests.

    updatedDatestring<date-time>

    Date and time of the last update of the target, ISO 8601 with a UTC offset. Omitted when not available. Ignored in requests.

    workspaceIdstring

    Id of the workspace that owns the target. Returned only when the target is looked up across workspaces; omitted otherwise. Ignored in requests.

    targetBase object

    Population base: fixes the reference universe of the percentages. It is identified by id (a saved target) or by filterTgl (an inline TGL expression); with both, filterTgl wins, and an object with neither returns 400 AE_ERR_405. A saved target id is not checked beforehand: if it cannot be resolved, the calculation fails. The evaluation save keeps the base in the saved element. Omit it to calculate over the whole population.

    idstring

    Identifier of the saved target, as returned by GET /api/v2/workspace/{workspaceId}/survey/{surveyCode}/targets.

    labelstring

    Display name of the target. Ignored when the target is sent in a request.

    filterTglstring

    TGL expression that defines the audience. In responses it is omitted when the target has no definition that can be expressed in TGL. In requests, send it to define the audience inline.

    creationDatestring<date-time>

    Creation date and time of the target, ISO 8601 with a UTC offset. Omitted when not available. Ignored in requests.

    updatedDatestring<date-time>

    Date and time of the last update of the target, ISO 8601 with a UTC offset. Omitted when not available. Ignored in requests.

    workspaceIdstring

    Id of the workspace that owns the target. Returned only when the target is looked up across workspaces; omitted otherwise. Ignored in requests.

    memorizationCoefficientinteger<int32>

    Memorization coefficient, as a percentage in integer form (12 means 12%): the chance of remembering a single contact, compounding over successive ones. From 0 to 100: any other value, or a decimal, returns 400 AE_ERR_400. Mutually exclusive with weightings: sending both returns 400 AE_ERR_400. Absent means the unweighted curve.

    weightingsinteger<int32>[]

    One weighting per contact range, as a percentage, in integers. The last value carries over to the remaining ranges, the open one included. At most one more than intervals (more returns 400 AE_ERR_400). Mutually exclusive with memorizationCoefficient. Absent means none.

    intervalsinteger<int32>[]

    Contact intervals of the curve: positive integers in ascending order, each one the top of a range, so [1,2,3,15] gives 1, 2, 3, 4-15 and >15. A value that is not positive, out of order or repeated returns 400 AE_ERR_400. Absent means 1 to 19.

    planLabelsstring[]

    Names for the plans, matched by position with insertions. More names than plans returns 400 AE_ERR_400. They do not affect the calculation.

    includeTotalPlanboolean

    Whether to return the total plan, every plan taken together, in the total field of the response. Default false.

    ResponseCurveRequest
    {
    "carriers": [
    {
    "id": "string",
    "label": "string",
    "type": "CARRIER",
    "path": "string",
    "insertions": [
    0
    ],
    "price": 0
    }
    ],
    "statistics": "Unknown Type: array,null",
    "title": "string",
    "hierarchy": false,
    "target": {
    "id": "string",
    "label": "string",
    "filterTgl": "string",
    "creationDate": "2024-07-29T15:51:28.071Z",
    "updatedDate": "2024-07-29T15:51:28.071Z",
    "workspaceId": "string"
    },
    "targetBase": {
    "id": "string",
    "label": "string",
    "filterTgl": "string",
    "creationDate": "2024-07-29T15:51:28.071Z",
    "updatedDate": "2024-07-29T15:51:28.071Z",
    "workspaceId": "string"
    },
    "memorizationCoefficient": 0,
    "weightings": [
    0
    ],
    "intervals": [
    0
    ],
    "planLabels": [
    "string"
    ],
    "includeTotalPlan": true
    }