TOM External API
The TOM External API gives programmatic access to TOM, ODEC's media-planning platform. Use it to find the audience surveys contracted for your user, explore their variables and carriers, manage workspaces and the elements saved in them (tabulations, targets, user variables), and run the platform's calculations: tables, carrier rankings, media plan evaluations, Reach tables, response curves and asynchronous media plan optimizations.
This reference documents version 2 (/api/v2). Version 1 (/api/v1) is frozen: it receives no new features and is documented separately. To move from v1, read the Migration guide.
Getting started
- Authenticate. Send your API key in the
X-API-Keyheader of every request. - Pick a survey.
GET /api/v2/users/surveyslists the surveys your key can use. A survey is also called a source. Itscodeis thesurveyCodepath parameter of every survey-scoped endpoint. URL-encode path parameters. - Explore the survey.
GET /api/v2/survey/{surveyCode}/variablesandGET /api/v2/survey/{surveyCode}/carriersreturn its variables and carriers.POST /api/v2/survey/{surveyCode}/tree/querybrowses them level by level.GET /api/v2/statistics?tableType=...lists the statistics each kind of table can show. - Calculate.
POST /api/v2/table/{surveyCode}calculates a table from a definition in the request body. Rankings, evaluations, Reach tables, response curves and optimizations have their own endpoints. - Reuse saved work.
GET /api/v2/workspaceslists the workspaces of the user behind the key. A workspace'sidis theworkspaceIdof the workspace endpoints.
Authentication and access
Send X-API-Key: <your key> with every request. The key identifies one TOM user, and every call runs with that user's permissions:
- Only the surveys contracted for that user can be used.
- Calculations need the matching application module in the user's profile: Tabulation for tables, Study for rankings, evaluations, response curves, optimizations and the study table types, and Reach for Reach tables.
A request without the header, or with an empty one, is rejected with 401 (E401). A module that is not enabled for the user gives 403 (AE_ERR_408). On the variables, carriers and tree endpoints, a survey you cannot use gives 403 (AE_ERR_415); other endpoints currently return the platform's code, for example 401 SO_ERR_203 for a survey outside your profile or 400 SO_ERR_201 for a survey that is disabled or being loaded. A key that does not identify a TOM user is rejected too, but the status and code currently depend on the endpoint; see Errors.
Keep the key on your server. Never put it in a URL, in browser or mobile code, or in logs.
Versioning and compatibility
- Breaking changes ship as a new major version under a new base path.
- Within v2 we may add endpoints, optional request fields, response fields and enum values. Ignore response fields you do not know, and handle unknown enum values gracefully.
- Deprecated fields and endpoints are announced in the Release notes before they are removed.
Conventions
- Format. Requests and responses are JSON (UTF-8). Send
Content-Type: application/jsononPOSTandPUT. The only exception isPOST /api/v2/table/{surveyCode}/html, which returnstext/html. - Strict and lenient bodies. The table model of
POST /api/v2/table/{surveyCode},.../htmlandPOST /api/v2/reach/{surveyCode}rejects unknown fields at the request, dimension and axis level, in theweightof the table, and in the survey waves of aSOURCESaxis and theirweight, with400(AE_ERR_411). The body ofPOST /api/v2/survey/{surveyCode}/optimizationsis strict throughout: an unknown field in the request, intarget, intargetBase, in a candidate carrier or in an objective returns400(AE_ERR_400). Nested objects of the table model (variables, categories, statistics, carriers, targets) and the other request bodies currently ignore unknown fields, so a misspelled field is silently dropped: check your field names. - Identifiers. Every identifier is an opaque string: survey codes, workspace and element ids, tree node ids,
sliceIdandjobId. Do not build or parse them. - Dates. ISO 8601 date-time with a UTC offset, for example
2026-05-27T10:00:00.000+00:00or2026-05-27T10:00:00Z. Use a full ISO 8601 parser. - Labels and numbers. Labels come in the language of the user behind the key; codes and enum values do not change. Calculated values are unrounded numbers unless you ask for formatted cells.
- Compression. JSON and HTML responses are gzip-compressed when the request sends
Accept-Encoding: gzip. Error bodies (application/problem+json) are not compressed. - Size. Request bodies can be up to 10 MB.
- Partial results. The survey tree query (
POST /api/v2/survey/{surveyCode}/tree/query) answers206 Partial Contentwhen the result is longer than 3,000 nodes; narrow the query to get the rest. The workspace custom tree query always returns the whole result. - Asynchronous jobs. Submitting an optimization returns
202and ajobId. Poll the job's status, waiting at leastretryAfterSecondsbetween polls, then fetch the result.
Errors
Every error returns a JSON object (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" }
errorCodeis the machine-readable code. Branch on it together with the HTTP status and the endpoint.errorMessageis for people. It can change and can be translated into the user's language: never parse it.- Code families:
E<status>codes are generic HTTP errors (E400malformed JSON,E401missing key,E404unknown route; an invalid value of an enumerated query parameter is400AE_ERR_401).AE_ERR_*codes come from this API; the number afterAE_ERR_is not an HTTP status. Codes with any other prefix (WS_ERR_*,RC_ERR_*,TR_ERR_*,TGL_INVALID,JOB_*, ...) are passed through from the platform, usually with HTTP400. Unexpected failures return500(GEN_ERR_500). - Any operation can also answer
405(E405) to a method its path does not have,406(E406) when theAcceptheader leaves out the media type of its response, and415(E415) when theContent-Typeof a body is notapplication/json; these are not listed per operation. - Some
AE_ERR_*codes mean different things on different endpoint families, so read a code together with the endpoint that returned it. - A body value of the wrong JSON type, such as a number where an array goes or a string where a boolean goes, returns
400(AE_ERR_400) on every v2 operation. The message names the field by its path, for exampledimensions[1].axis[0].sources[0].selected, and the type it takes.
Limits
- Optimization. A user can run one optimization at a time, including optimizations open in the TOM web application; a job that starts while another one of the same user is active ends
FAILED. Each user can have up to 50 queued background jobs; beyond that a submission gets429(JOB_USER_LIMIT_REACHED). A run stops after one hour of execution, and results are kept for 30 days. - Synchronous calculations. A calculation that takes longer than about two minutes is aborted with
500. Reduce the request and try again.
Authentication
- API Key: X-API-Key
Your TOM API key, sent in the X-API-Key header of every request. The key identifies a TOM user: each call runs with that user's contracted surveys and enabled modules (Tabulation, Study, Reach). Requests without the header are rejected with 401 (E401). Keep the key secret and on the server side.
Security Scheme Type: | apiKey |
|---|---|
Header parameter name: | X-API-Key |