Skip to main content

Migration Guide: /api/v1 to /api/v2

info

Audience: consumers of the TOM External API.

Document status: this guide describes version 2.3 of the API reference. Where a point depends on a date that has not been announced yet, it says so.

1. Introduction​

The TOM External API is published in two versions:

  • /api/v2 — the current version. It receives all new capabilities and is the version every integration should target.
  • /api/v1 — the previous version. It is frozen and deprecated.

Version 2 was introduced because the response of the table-calculation endpoint changed shape in a way that is not backward compatible (see section 4). Rather than breaking existing integrations, the whole API surface was re-published under the /api/v2 prefix. The v2 contract is self-contained: once you migrate, you never need to call a v1 endpoint again.

This guide explains, endpoint by endpoint, what changes, what does not, and how to adapt your client code safely.


2. Coexistence and support policy​

Aspect/api/v1 (frozen)/api/v2 (current)
StatusDeprecated. No behavioral changes, no new capabilities.Actively maintained; receives all new features.
Table calculation responsematrix — a single matrix objectmatrixList — a list of matrices
Table types on POST /tableTABULATION onlyTABULATION, TREND, BREAKDOWN_CARRIERS, DUPLICATIONS, REACH_TABLE, REACH_DUPLICATION
HTML table renderingNot availableAvailable (POST /table/{surveyCode}/html)
Reach calculationsNot availableAvailable
SupportMaintained temporarily during the migration windowFull support

Important guidelines:

  • Do not mix versions. Use v1 or v2 consistently within one integration. Do not combine v1 and v2 calls in the same workflow.
  • Migrate as a block, not endpoint by endpoint: switch the base prefix, adapt the parsing of the table-calculation and stored-tabulation responses, and validate the whole flow in a test environment.
  • Migration deadline: /api/v1 is deprecated and is maintained only during the migration window. The end-of-support date will be communicated in advance; migrate as soon as possible.

3. Authentication (unchanged)​

Both versions use the same authentication mechanism: every request must include your API key in the X-API-Key HTTP header. No change is required in this area when migrating.


4. The breaking change: table response​

The response of the table-calculation endpoint changes shape:

POST /api/v1/table/{surveyCode} → POST /api/v2/table/{surveyCode}

The stored-tabulation endpoint changes in the same way (see section 5.1).

4.1. Before (v1): a single matrix object​

{
"tableType": "TABULATION",
"dimensions": [ /* the axes of the request, echoed back */ ],
"matrix": {
"rowCount": 2,
"columnCount": 2,
"table": [ [123456.0, 12.3], [98765.0, 9.8] ],
"items": []
}
}

Limitation of v1: when a calculation produces several planes (for example, a table with more than one selected item in the PLANES dimension), v1 collapses all resulting matrices into a single one — only the last one is returned and the remaining information is lost.

4.2. After (v2): a matrixList array​

In v2 the response carries a matrixList field: a list of matrices, one per plane combination. Each matrix is self-identified by its items field, which states the plane combination (statistic, plane variable category, etc.) that the matrix contains.

{
"tableType": "TABULATION",
"dimensions": [ /* the axes of the request, echoed back */ ],
"matrixList": [
{
"items": [
{ "axis": "3", "variable": { "id": "wTotal", "label": "Weighted total" } }
],
"rowCount": 2,
"columnCount": 2,
"table": [ [123456.0, 12.3], [98765.0, 9.8] ]
},
{
"items": [
{ "axis": "3", "variable": { "id": "ColPercentWeighted", "label": "Column %" } }
],
"rowCount": 2,
"columnCount": 2,
"table": [ [55.6, 44.4], [50.2, 49.8] ]
}
]
}

Each entry of items names the plane axis (axis is the axis id) and the item of that axis (variable) that the matrix belongs to.

4.3. How to consume matrixList correctly​

  1. Identify each matrix by its items field, never by its position in the list. The items array states the exact plane combination the matrix belongs to.
  2. Each matrix remains a dense, positional two-dimensional array: table[row][column], with its own rowCount and columnCount.
  3. The mapping from row/column indexes to concrete elements is derived, as in v1, from the axes echoed back in the dimensions field of the response.

Adaptation outline:

# v1
matrix = response.matrix
render(matrix.table, response.dimensions)

# v2
for matrix in response.matrixList:
plane = matrix.items # identifies the plane/statistic of this matrix
render(matrix.table, response.dimensions, context = plane)

4.4. Multiple planes (new in v2)​

In v2, the PLANES dimension accepts more than one selected item. When several plane items are selected, the response contains one matrix per selected plane combination, each identified by its items. In every dimension other than PLANES, each axis must keep exactly one selected item.


5. Endpoints whose response shape does NOT change​

For the following operations the response keeps the same shape as v1: the path prefix changes and the names of carriers and enumerated values follow the v2 vocabulary (section 7.6):

  • POST /api/v2/survey/{surveyCode}/ranking — still returns a single matrix.
  • POST /api/v2/survey/{surveyCode}/evaluation — still returns a single matrix.
  • All catalog, workspace, target, variable and carrier endpoints — the same request contracts and the same structure under the new prefix, except for the names and values of section 7.6 (for example, type: CARRIER and audienceModel in the carriers list).

5.1. Stored tabulation retrieval DOES change​

GET /api/v2/workspace/{workspaceId}/survey/{surveyCode}/tabulation/{elementId} now returns the same typed model as the calculation endpoint:

  • matrix → matrixList, exactly as described in section 4.
  • Axes are the polymorphic v2 axes (section 7.5), not the flat v1 shape.

The slice-based navigation model is unchanged: one call per slice through sliceId, with combinations, indexCombination, selfTableLink, nextTableLink and previousTableLink. The operation reference explains how to read them.

The v1 endpoint keeps the flat, single-matrix shape untouched.

In short: matrixList appears in the responses of the table calculation, the Reach calculation (section 7.3, which shares the same response model) and the stored tabulation.


6. Endpoint migration reference​

v1 endpointv2 endpointChanges besides the prefix
GET /api/v1/statisticsGET /api/v2/statisticsOptional tableType filter accepts: TABULATION, RANKING, EVALUATION, BREAKDOWN_CARRIERS, TREND, DUPLICATIONS. An invalid value returns 400 AE_ERR_401 (v1: 404).
GET /api/v1/users/surveysGET /api/v2/users/surveysValues: description is the name the user sees for the survey, which can be the user's own alias (v1: always the catalog name). Additive: each survey now carries the boolean flag availableReach and originalDescription, the catalog name.
GET /api/v1/workspacesGET /api/v2/workspacesDefault order: the one the user chose in the TOM web application (v1: own workspaces by name, then shared ones). Optional orderBy and ascending parameters. Additive: lastUpdated, ownership and ownerName on each workspace.
POST /api/v1/workspacePOST /api/v2/workspaceNone.
GET /api/v1/workspace/{workspaceId}GET /api/v2/workspace/{workspaceId}Values: surveyDescription and the description of each item of surveys are the name the user sees for the survey, which can be the user's own alias (v1 never returns the alias: description is the catalog name). Additive: originalDescription, the catalog name, on each item of surveys.
POST /api/v1/workspace/{workId}/sourcePOST /api/v2/workspace/{workspaceId}/sourceNone. Only the name of the path variable differs; the URL shape is the same.
GET .../survey/{surveyCode}/variablessame path under /api/v2None.
GET .../survey/{surveyCode}/carrierssame path under /api/v2Values: type CARRIER (v1: SUPPORT) and audienceModel instead of subtype on carriers (section 7.6).
GET .../tabulation/{elementId}same path under /api/v2Breaking: response matrix → matrixList and polymorphic axes (sections 5.1 and 7.5); axes of carriers use CARRIERS and carriers (section 7.6). Slice navigation unchanged. Additive: a TARGET_VAR calculated from a TGL expression includes filterTgl in the axes (v1 never returns it).
GET .../tabulation/{elementId}/combinationssame path under /api/v2None.
GET .../targets / POST .../target / PUT .../target/{elementId} / POST .../targets/detailssame paths under /api/v2None.
GET .../user-varssame path under /api/v2None.
POST /api/v1/table/{surveyCode}POST /api/v2/table/{surveyCode}Breaking: response matrix → matrixList (section 4). Additive: new accepted tableType values (section 7.1); in responses, a TARGET_VAR calculated from a TGL expression includes filterTgl (v1 never returns it). Values: axes of carriers use CARRIERS and carriers (section 7.6). Stricter: the request body is validated strictly (section 8.1), and VARIABLES axis variables that v1 accepted may be rejected with 400 AE_ERR_412/AE_ERR_416 (section 8).
POST .../survey/{surveyCode}/rankingsame path under /api/v2Single matrix preserved. Values: the rows are a CARRIERS axis with carriers (v1: SUPPORTS and supports), and type of each row uses the names of section 7.6.
POST .../survey/{surveyCode}/evaluationsame path under /api/v2Single matrix preserved. Values: type of each row of the MEDIA axis uses the names of section 7.6.
POST .../survey/{surveyCode}/evaluation/save/{workspaceId}same path under /api/v2None.
(not available in v1)POST /api/v2/table/{surveyCode}/htmlNew: HTML rendering of a table (section 7.2).
(not available in v1)GET /api/v2/survey/{surveyCode}/reach-capabilitiesNew: Reach discovery (section 7.3).
(not available in v1)POST /api/v2/reach/{surveyCode}New: Reach calculation (section 7.3).
(not available in v1)POST /api/v2/survey/{surveyCode}/tree/queryNew: the variables or carriers tree, queried level by level.
(not available in v1)POST /api/v2/workspace/{workspaceId}/survey/{surveyCode}/tree/query/customNew: the custom tree of a workspace (user variables and targets), queried level by level.
(not available in v1)GET /api/v2/workspace/{workspaceId}/element/{elementId}New: a saved element returned as a request you can edit and send again.
(not available in v1)DELETE /api/v2/workspace/{workspaceId}New: delete a workspace you own, with everything it contains.
(not available in v1)DELETE /api/v2/workspace/{workspaceId}/element/{elementId}New: delete a tabulation, Reach table, target, user variable or saved evaluation of a workspace you own.
(not available in v1)POST /api/v2/survey/{surveyCode}/response-curveNew: response curve of a media plan.
(not available in v1)POST /api/v2/survey/{surveyCode}/optimizations, GET /api/v2/optimizations/{jobId} and GET /api/v2/optimizations/{jobId}/resultNew: asynchronous media plan optimization.

7. New capabilities in v2​

7.1. Additional table types on POST /table​

POST /api/v2/table/{surveyCode} is the universal calculation entry point. The tableType field of the request body accepts:

tableTypeDescriptionResponse shape
TABULATION (default when omitted)Multivariate cross-tabulationmatrixList, one matrix per plane combination
TRENDEvolution of the crossing over timematrixList
BREAKDOWN_CARRIERSAudience breakdown by carriermatrixList
DUPLICATIONSDuplication analysis between carriersmatrixList
REACH_TABLEReach (coverage) calculationmatrixList (see section 7.3)
REACH_DUPLICATIONReach duplication calculationmatrixList (see section 7.3)

Each table type requires an application module in the user's profile: Tabulation for TABULATION, Study for TREND, BREAKDOWN_CARRIERS and DUPLICATIONS, and Reach for the Reach types. A user without the module gets 403 AE_ERR_408.

Ranking and evaluation calculations are not consolidated into /table: keep using their dedicated endpoints (POST .../ranking, POST .../evaluation).

7.2. HTML rendering: POST /api/v2/table/{surveyCode}/html​

Returns the rendered HTML representation of a table:

  • The request body is identical to the JSON endpoint (POST /api/v2/table/{surveyCode}).
  • The success response is a non-empty text/html document.
  • Error responses are returned as application/problem+json, never as HTML, with the same status codes as the JSON endpoint.

7.3. Reach​

Version 2 introduces Reach (coverage and duplication) calculations. The recommended flow is: check availability, discover capabilities, then calculate.

7.3.1. Availability: the availableReach flag​

In GET /api/v2/users/surveys, each survey carries a boolean availableReach flag. Only surveys with availableReach: true support Reach requests; a Reach request on any other survey is rejected with HTTP 400 and business error code RC_ERR_100.

7.3.2. Discovery: GET /api/v2/survey/{surveyCode}/reach-capabilities​

Returns the statistics available per mode (REACH_TABLE / REACH_DUPLICATION), the diary edges, and the time configuration of the survey. The catalog is dynamic: query it as part of your flow and do not cache it as a fixed list.

7.3.3. Calculation entry points​

Two entry points calculate Reach tables. Both return the same response model, but they are not equivalent:

  • POST /api/v2/table/{surveyCode} with tableType set to REACH_TABLE or REACH_DUPLICATION.
  • POST /api/v2/reach/{surveyCode} — the same request, plus the optional Reach-specific fields targetMedia (the media that count as 100% in share statistics) and diaryFilters (filters on the diary edges). Only this endpoint accepts those fields: POST /api/v2/table/{surveyCode} rejects them with 400 AE_ERR_411. Both endpoints accept targetBase (the population base: the reference universe of the percentages), which is applied to the calculation: with neither a non-blank id nor a non-blank filterTgl it is rejected with 400 AE_ERR_405. base is a deprecated alias of targetBase accepted only by this endpoint. On this endpoint tableType is required and must be REACH_TABLE or REACH_DUPLICATION; without it, or with any other value, the request returns 400 AE_ERR_401.

7.3.4. Response layout​

The placement of the statistics axis in your request determines the shape of the response, in both entry points:

  • Statistics in the COLUMNS dimension → matrixList contains one matrix of carriers × statistics.
  • Statistics in the PLANES dimension (all of them selected) → matrixList contains one matrix per statistic, each identified by its items field.

7.4. Optional axis identifiers in calculation requests​

In the request body of the calculation endpoints, the id field of each axis (dimensions[].axis[].id) is optional. When omitted, the API assigns a unique sequential identifier automatically, guaranteed not to collide with any identifier you did provide. Axis identifiers you supply explicitly are always preserved.

7.5. Split axes​

A split axis is a VARIABLES axis whose categories are laid out along the opposite dimension. It is expressed as two linked axes:

  • the VARIABLES axis carries "split": true (the field is omitted when false);
  • a CATEGORIES axis in the opposite dimension carries parentId (the id of the split axis) and the ordered categories list.
{ "axisType": "VARIABLES", "id": "1", "label": "Axis 1", "split": true, "variables": [ ... ] }

{ "axisType": "CATEGORIES", "id": "2", "label": "* Axis 1", "parentId": "1",
"categories": [ { "type": "TOTAL" }, { "type": "BASE" },
{ "type": "SPLIT", "label": "Male" }, { "type": "SPLIT", "label": "Female" } ] }

type accepts SPLIT, BASE and TOTAL; label is only meaningful for SPLIT, and hidden is omitted when false. During calculation, SPLIT categories are matched by label against the categories of the parent axis variables.

Both axes are emitted by the stored-tabulation detail and accepted by the calculation endpoint, so a tabulation can be read and re-sent unchanged.

categories is required: the server does not derive it. If you change the variables of a split axis after reading it, recompute the category labels before sending the request.

A CATEGORIES axis whose parentId is missing from the request, or points to an axis that is not a VARIABLES axis with "split": true, is rejected with AE_ERR_414.

7.6. Public vocabulary: carriers and enumerated values​

v2 calls a media vehicle a carrier. v1 used the word support and, in some places, the names that the platform uses internally. In v2 responses these names change:

Wherev1v2
axisType of an axis of carriers (ranking, table, Reach)SUPPORTSCARRIERS
Property of that axissupportscarriers
type of a carrier in a table, Reach, ranking or evaluation responseSUPPORT, SUPPORT_JOINT, TOTAL_MEDIA_SUPPORT, TOTAL_SUPPORTCARRIER, CARRIER_JOINT, TOTAL_MEDIA, TOTAL
type of a leaf of the carriers listSUPPORTCARRIER
Audience model of a carrier in the carriers listsubtype (DEFAULT, COMSCORE, POISSON, ...)audienceModel (STANDARD, DIGITAL_MEASUREMENT, POISSON, ...); carriers have no subtype
tableType in responsesBREAKDOWN_SUPPORTSBREAKDOWN_CARRIERS
Id and label of the total of all mediaTOTAL_MEDIA_SUPPORTTOTAL_MEDIA

Adapt the parts of your client that read these values. The id of the axis of a ranking (AXIS_SUPPORTS) does not change: it is an opaque identifier, so read the kind of axis from axisType.

Responses never return the v1 names. The API reference lists the values of each enumerated field with their meaning.

Deprecated names​

Requests keep accepting the previous names (SUPPORTS, supports, SUPPORT, BREAKDOWN_SUPPORTS and a few others) as deprecated aliases, so a request that still uses the v1 names keeps working. The population base and the inline target follow the same rule: base is a deprecated name of targetBase (Reach and optimization), and tgl is a deprecated name of filterTgl in the target and targetBase of an optimization. The reference names them only in the sections about deprecated names. Use the current names: the full table is in Limits and conventions.


8. Error handling​

Both versions report errors as application/problem+json:

{
"status": "Bad Request",
"statusCode": 400,
"errorCode": "AE_ERR_412",
"errorMessage": "Axis '1' in dimension 'ROWS' is invalid: variables[0] (id 'SEX'): field 'subtype' is required for VAR"
}
  • status is the reason phrase of the HTTP status and statusCode is the HTTP status as a number.
  • errorCode is the machine-readable code. Branch on it together with the HTTP status.
  • errorMessage is for people: it can change and can be translated into the user's language.

The statuses to handle are 400 (invalid request, including business errors from the platform such as RC_ERR_100 for Reach on an incompatible survey or WS_ERR_101 for a workspace that does not exist), 401 (missing API key, or a survey outside the user's profile on the calculation endpoints: E401 and SO_ERR_203), 403 (a module that is not enabled, AE_ERR_408; a survey you cannot use on the variables, carriers and tree endpoints, AE_ERR_415), 404 (resource not found), and 500 (unexpected error). The page Errors and troubleshooting lists the codes and explains how to react to each one.

An invalid value of an enumerated field, in a body or in the tableType and type query parameters, returns 400 AE_ERR_401, and the message lists the valid values.

In v2, a VARIABLES axis variable that cannot be converted is rejected with 400: AE_ERR_412 when a required subtype, id or filterTgl is missing and AE_ERR_416 for an unsupported combination. Both messages locate the axis, dimension, variable (its id, or its position), field and offending value (if any). As in v1, the subtype declared for a CUSTOM_VAR is used as is: send the one the variable actually has.

8.1. Stricter request validation​

In v2 the body of POST /table, POST /table/html and POST /reach is validated strictly:

  • Every axis needs an axisType, and only the fields of that axis type are accepted.
  • An unknown field at the request, dimension or axis level (and in weight, in split categories, and in the survey waves of a SOURCES axis and their weight) is rejected with 400 AE_ERR_411. Unknown fields inside variables, categories, statistics, target and targetBase are ignored, so a misspelled field there is silently dropped: check your field names.
  • MEDIA and MEDIA_PLANS axes appear in responses only and are rejected in requests (AE_ERR_410).

Clients that sent v1 axes with extra or empty fields must remove them.

The body of POST /api/v2/survey/{surveyCode}/optimizations is strict as well: an unknown field in the request, in target, in targetBase, in a candidate carrier or in an objective is rejected with 400 AE_ERR_400, and the message names the field and the object that contains it.


9. Migration checklist​

  • Change the base prefix of every call from /api/v1 to /api/v2.
  • Adapt the parsing of the POST /table response: matrix (single object) → matrixList (array). Match each matrix by its items field, never by position.
  • Adapt the parsing of the stored-tabulation response: matrixList and polymorphic axes (section 5.1).
  • Confirm that your ranking and evaluation flows require no parsing changes (their response shapes are unchanged; see section 5).
  • Remove extra or empty fields from the axes of your table requests (section 8.1).
  • Read carriers with the v2 vocabulary: CARRIERS axes with carriers, type CARRIER, audienceModel and TOTAL_MEDIA (section 7.6), and send the current names in requests.
  • Do not mix v1 and v2 endpoints within the same workflow.
  • (Reach) Read the availableReach flag from the survey list before requesting Reach capabilities or calculations.
  • (Reach) Query reach-capabilities dynamically; do not cache the statistics catalog.
  • (Reach) Choose your calculation entry point: /api/v2/table, or /api/v2/reach if you need targetBase, targetMedia or diaryFilters. Always send tableType on /api/v2/reach, and send the population base as targetBase (not base).
  • (Optimization) Send the audience in target and the population base in targetBase, each with id or filterTgl (not tgl), and remove any field that the request does not define.
  • Verify your error handling against the application/problem+json format, including RC_ERR_100, 401 and 403.
  • Validate the complete integration in a test environment before you switch your production traffic to v2.

If you have any questions regarding this migration, please contact your TOM platform representative.