Migration Guide: /api/v1 to /api/v2
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) |
|---|---|---|
| Status | Deprecated. No behavioral changes, no new capabilities. | Actively maintained; receives all new features. |
| Table calculation response | matrix — a single matrix object | matrixList — a list of matrices |
Table types on POST /table | TABULATION only | TABULATION, TREND, BREAKDOWN_CARRIERS, DUPLICATIONS, REACH_TABLE, REACH_DUPLICATION |
| HTML table rendering | Not available | Available (POST /table/{surveyCode}/html) |
| Reach calculations | Not available | Available |
| Support | Maintained temporarily during the migration window | Full 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/v1is 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
- Identify each matrix by its
itemsfield, never by its position in the list. Theitemsarray states the exact plane combination the matrix belongs to. - Each matrix remains a dense, positional two-dimensional array:
table[row][column], with its ownrowCountandcolumnCount. - The mapping from row/column indexes to concrete elements is derived, as in v1, from the axes
echoed back in the
dimensionsfield 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 singlematrix.POST /api/v2/survey/{surveyCode}/evaluation— still returns a singlematrix.- 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: CARRIERandaudienceModelin 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 endpoint | v2 endpoint | Changes besides the prefix |
|---|---|---|
GET /api/v1/statistics | GET /api/v2/statistics | Optional tableType filter accepts: TABULATION, RANKING, EVALUATION, BREAKDOWN_CARRIERS, TREND, DUPLICATIONS. An invalid value returns 400 AE_ERR_401 (v1: 404). |
GET /api/v1/users/surveys | GET /api/v2/users/surveys | Values: 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/workspaces | GET /api/v2/workspaces | Default 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/workspace | POST /api/v2/workspace | None. |
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}/source | POST /api/v2/workspace/{workspaceId}/source | None. Only the name of the path variable differs; the URL shape is the same. |
GET .../survey/{surveyCode}/variables | same path under /api/v2 | None. |
GET .../survey/{surveyCode}/carriers | same path under /api/v2 | Values: type CARRIER (v1: SUPPORT) and audienceModel instead of subtype on carriers (section 7.6). |
GET .../tabulation/{elementId} | same path under /api/v2 | Breaking: 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}/combinations | same path under /api/v2 | None. |
GET .../targets / POST .../target / PUT .../target/{elementId} / POST .../targets/details | same paths under /api/v2 | None. |
GET .../user-vars | same path under /api/v2 | None. |
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}/ranking | same path under /api/v2 | Single 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}/evaluation | same path under /api/v2 | Single 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/v2 | None. |
| (not available in v1) | POST /api/v2/table/{surveyCode}/html | New: HTML rendering of a table (section 7.2). |
| (not available in v1) | GET /api/v2/survey/{surveyCode}/reach-capabilities | New: 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/query | New: the variables or carriers tree, queried level by level. |
| (not available in v1) | POST /api/v2/workspace/{workspaceId}/survey/{surveyCode}/tree/query/custom | New: 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-curve | New: 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}/result | New: 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:
tableType | Description | Response shape |
|---|---|---|
TABULATION (default when omitted) | Multivariate cross-tabulation | matrixList, one matrix per plane combination |
TREND | Evolution of the crossing over time | matrixList |
BREAKDOWN_CARRIERS | Audience breakdown by carrier | matrixList |
DUPLICATIONS | Duplication analysis between carriers | matrixList |
REACH_TABLE | Reach (coverage) calculation | matrixList (see section 7.3) |
REACH_DUPLICATION | Reach duplication calculation | matrixList (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/htmldocument. - 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}withtableTypeset toREACH_TABLEorREACH_DUPLICATION.POST /api/v2/reach/{surveyCode}— the same request, plus the optional Reach-specific fieldstargetMedia(the media that count as 100% in share statistics) anddiaryFilters(filters on the diary edges). Only this endpoint accepts those fields:POST /api/v2/table/{surveyCode}rejects them with400AE_ERR_411. Both endpoints accepttargetBase(the population base: the reference universe of the percentages), which is applied to the calculation: with neither a non-blankidnor a non-blankfilterTglit is rejected with400AE_ERR_405.baseis a deprecated alias oftargetBaseaccepted only by this endpoint. On this endpointtableTypeis required and must beREACH_TABLEorREACH_DUPLICATION; without it, or with any other value, the request returns400AE_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 →
matrixListcontains one matrix of carriers × statistics. - Statistics in the PLANES dimension (all of them selected) →
matrixListcontains one matrix per statistic, each identified by itsitemsfield.
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
VARIABLESaxis carries"split": true(the field is omitted when false); - a
CATEGORIESaxis in the opposite dimension carriesparentId(the id of the split axis) and the orderedcategorieslist.
{ "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:
| Where | v1 | v2 |
|---|---|---|
axisType of an axis of carriers (ranking, table, Reach) | SUPPORTS | CARRIERS |
| Property of that axis | supports | carriers |
type of a carrier in a table, Reach, ranking or evaluation response | SUPPORT, SUPPORT_JOINT, TOTAL_MEDIA_SUPPORT, TOTAL_SUPPORT | CARRIER, CARRIER_JOINT, TOTAL_MEDIA, TOTAL |
type of a leaf of the carriers list | SUPPORT | CARRIER |
| Audience model of a carrier in the carriers list | subtype (DEFAULT, COMSCORE, POISSON, ...) | audienceModel (STANDARD, DIGITAL_MEASUREMENT, POISSON, ...); carriers have no subtype |
tableType in responses | BREAKDOWN_SUPPORTS | BREAKDOWN_CARRIERS |
| Id and label of the total of all media | TOTAL_MEDIA_SUPPORT | TOTAL_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"
}
statusis the reason phrase of the HTTP status andstatusCodeis the HTTP status as a number.errorCodeis the machine-readable code. Branch on it together with the HTTP status.errorMessageis 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 aSOURCESaxis and theirweight) is rejected with400AE_ERR_411. Unknown fields inside variables, categories, statistics,targetandtargetBaseare ignored, so a misspelled field there is silently dropped: check your field names. MEDIAandMEDIA_PLANSaxes 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/v1to/api/v2. - Adapt the parsing of the
POST /tableresponse:matrix(single object) →matrixList(array). Match each matrix by itsitemsfield, never by position. - Adapt the parsing of the stored-tabulation response:
matrixListand 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:
CARRIERSaxes withcarriers,typeCARRIER,audienceModelandTOTAL_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
availableReachflag from the survey list before requesting Reach capabilities or calculations. - (Reach) Query
reach-capabilitiesdynamically; do not cache the statistics catalog. - (Reach) Choose your calculation entry point:
/api/v2/table, or/api/v2/reachif you needtargetBase,targetMediaordiaryFilters. Always sendtableTypeon/api/v2/reach, and send the population base astargetBase(notbase). - (Optimization) Send the audience in
targetand the population base intargetBase, each withidorfilterTgl(nottgl), and remove any field that the request does not define. - Verify your error handling against the
application/problem+jsonformat, includingRC_ERR_100,401and403. - 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.