Getting started
This guide takes you from an API key to your first calculated table. You will list the surveys your key can use, discover the variables and statistics of a survey, calculate a cross-tabulation and read the result.
1. What you need
- An API key. It identifies one TOM user: every call runs with that user's contracted surveys and enabled modules.
- The base URL of the API you are working against.
- A survey your user can use.
- An HTTP client. The examples use curl, Python (
requests) and JavaScript (fetch, Node.js 18 or later).
Ask your TOM platform representative for the key and the base URL. Keep both out of your source code: the examples read them from environment variables.
export TOM_API_BASE_URL="https://your-api-host.example"
export TOM_API_KEY="your-api-key"
The key gives access to your data. Keep it on your server. Never put it in a URL, in browser or mobile code, or in logs.
2. Authenticate
Send the key in the X-API-Key header of every request. Also send:
Content-Type: application/jsononPOSTandPUTrequests.Accept-Encoding: gzip, so that large JSON responses (such as the variables tree) arrive compressed. curl needs--compressed; the Python and JavaScript clients do it for you.
A request without the X-API-Key header is rejected with 401 and the error code E401.
3. List your surveys
A survey (also called a source) is an audience study loaded in TOM. GET /api/v2/users/surveys returns the surveys your key can use.
- curl
- Python
- JavaScript
curl --compressed \
-H "X-API-Key: $TOM_API_KEY" \
"$TOM_API_BASE_URL/api/v2/users/surveys"
import os
import requests
BASE_URL = os.environ["TOM_API_BASE_URL"]
HEADERS = {"X-API-Key": os.environ["TOM_API_KEY"]}
response = requests.get(f"{BASE_URL}/api/v2/users/surveys", headers=HEADERS, timeout=130)
response.raise_for_status()
for survey in response.json():
print(survey["code"], survey["description"])
const baseUrl = process.env.TOM_API_BASE_URL;
const headers = { "X-API-Key": process.env.TOM_API_KEY };
const response = await fetch(`${baseUrl}/api/v2/users/surveys`, { headers });
if (!response.ok) throw new Error(`${response.status} ${await response.text()}`);
for (const survey of await response.json()) {
console.log(survey.code, survey.description);
}
The response is a list:
[
{
"code": "APP_DEMO_2025",
"description": "Demo application survey 2025",
"creationDate": "2025-01-15T09:12:44.120+00:00",
"updatedDate": "2025-06-02T07:30:00.000+00:00",
"availableReach": false
}
]
The code of a survey is the surveyCode that every survey-scoped endpoint takes in its path. The rest of this guide uses APP_DEMO_2025; replace it with a code from your own list. availableReach tells whether the survey supports Reach tables (see the Reach guide).
4. Discover the variables
GET /api/v2/survey/{surveyCode}/variables returns the complete variables tree of the survey: folders, the variables they contain and the categories of each variable.
curl --compressed \
-H "X-API-Key: $TOM_API_KEY" \
"$TOM_API_BASE_URL/api/v2/survey/APP_DEMO_2025/variables"
[
{
"id": "DEMOGRAPHICS",
"label": "Demographics",
"type": "FOLDER",
"items": [
{
"id": "SEX",
"label": "Sex",
"type": "VAR",
"subtype": "SINGLE",
"items": [
{ "id": "D1", "label": "Male", "type": "CATEGORY" },
{ "id": "D2", "label": "Female", "type": "CATEGORY" }
]
}
]
}
]
Here the id of a variable (SEX) and of a category (D1) are the codes the rest of the API uses. The tree is complete and can be large: cache it on your side instead of downloading it before every table. To browse it level by level, or to search it by label, use POST /api/v2/survey/{surveyCode}/tree/query instead (see Exploring variables and carriers).
The tree query returns nodes with two identifiers. The id of a node is opaque, belongs to that tree only and can change when the survey is reloaded. Use the code of the node in tables, targets and TGL expressions.
Remember also the subtype of each variable you plan to use: a table axis needs it (SINGLE in this example).
5. Discover the statistics
A statistic is a measure that a table shows in its cells. GET /api/v2/statistics lists the statistics available for a kind of table (tableType, TABULATION by default).
curl --compressed \
-H "X-API-Key: $TOM_API_KEY" \
"$TOM_API_BASE_URL/api/v2/statistics"
[
{ "id": "wTotal", "label": "Weighted total", "description": "Number of people (weighted and projected to the universe) who meet the conditions of the cell." },
{ "id": "ColPercentWeighted", "label": "Column %", "description": "Weighted percentage of the cell over the total of its column." },
{ "id": "Sample", "label": "Sample", "description": "Number of survey respondents who meet the conditions of the cell, without weighting." }
]
Labels and descriptions come in the language of the user behind the key; the id does not change. The catalog depends on the kind of table, not on the survey. Your list can differ from this one: it follows the statistics the user has enabled in TOM.
6. Calculate your first table
POST /api/v2/table/{surveyCode} calculates a table from the definition you send. This body crosses SEX (rows) with EDA1, an age-group variable (columns), and calculates the weighted total:
{
"dimensions": [
{
"id": "ROWS",
"axis": [
{
"axisType": "VARIABLES",
"variables": [{ "id": "SEX", "type": "VAR", "subtype": "SINGLE" }]
}
]
},
{
"id": "COLUMNS",
"axis": [
{
"axisType": "VARIABLES",
"variables": [{ "id": "EDA1", "type": "VAR", "subtype": "SINGLE" }]
}
]
},
{ "id": "PLANES", "axis": [{ "axisType": "STATISTICS", "statistics": [{ "id": "wTotal" }] }] }
]
}
A table has up to three dimensions: ROWS, COLUMNS and PLANES. Each dimension holds typed axes, and axisType selects the kind of axis. Here the rows and columns hold VARIABLES axes, and the planes hold the STATISTICS axis that every table needs. Use the variable codes and subtype that you found in your own survey.
Save the body as table.json and send it:
- curl
- Python
- JavaScript
curl --compressed -X POST \
-H "X-API-Key: $TOM_API_KEY" \
-H "Content-Type: application/json" \
-d @table.json \
"$TOM_API_BASE_URL/api/v2/table/APP_DEMO_2025"
import json
import os
import requests
BASE_URL = os.environ["TOM_API_BASE_URL"]
HEADERS = {"X-API-Key": os.environ["TOM_API_KEY"]}
with open("table.json") as file:
body = json.load(file)
response = requests.post(
f"{BASE_URL}/api/v2/table/APP_DEMO_2025",
headers=HEADERS,
json=body,
timeout=130, # a calculation can take up to about two minutes
)
response.raise_for_status()
table = response.json()
import { readFile } from "node:fs/promises";
const baseUrl = process.env.TOM_API_BASE_URL;
const body = await readFile("table.json", "utf8");
const response = await fetch(`${baseUrl}/api/v2/table/APP_DEMO_2025`, {
method: "POST",
headers: {
"X-API-Key": process.env.TOM_API_KEY,
"Content-Type": "application/json",
},
body,
signal: AbortSignal.timeout(130_000), // a calculation can take up to about two minutes
});
if (!response.ok) throw new Error(`${response.status} ${await response.text()}`);
const table = await response.json();
7. Read the result
The response repeats the structure you asked for in dimensions, with the labels and the categories that were resolved, and adds matrixList with the calculated values. This is the response, with the COLUMNS and PLANES dimensions shortened:
{
"dimensions": [
{
"id": "ROWS",
"axis": [
{
"id": "1",
"axisType": "VARIABLES",
"variables": [
{
"id": "SEX",
"label": "Sex",
"type": "VAR",
"subtype": "SINGLE",
"categories": [
{ "id": "D1", "label": "Male", "type": "CATEGORY" },
{ "id": "D2", "label": "Female", "type": "CATEGORY" }
]
}
]
}
]
},
{ "id": "COLUMNS", "axis": [ ... ] },
{ "id": "PLANES", "axis": [ ... ] }
],
"matrixList": [
{
"items": [
{ "axis": "3", "variable": { "id": "wTotal", "label": "Weighted total", "type": "VARIABLES", "selected": true } }
],
"rowCount": 2,
"columnCount": 8,
"table": [
[2944.91, 2445.12, 5010.43, 5906.75, 7180.52, 6080.76, 4269.15, 3535.56],
[2761.02, 2300.62, 4846.63, 5918.49, 7132.19, 6361.85, 4822.72, 5206.1]
]
}
]
}
The figures are illustrative.
matrixList[i].table[r][c]is the value for the r-th item ofROWSand the c-th item ofCOLUMNS, in the order in which those items appear indimensions. Heretable[0][1]isSEX.D1(Male) byEDA1.D2(20 to 24).- A table can return several matrices, for example when you select two statistics in
PLANES. Identify each matrix by itsitems, never by its position in the list. - By default, cells are numbers.
dataType,localeanddecimalsin the request change how cells are returned (see Building tables).
To print each cell with its labels:
rows = table["dimensions"][0]["axis"][0]["variables"][0]["categories"]
columns = table["dimensions"][1]["axis"][0]["variables"][0]["categories"]
matrix = table["matrixList"][0]["table"]
for r, row in enumerate(rows):
for c, column in enumerate(columns):
print(row["label"], column["label"], matrix[r][c])
8. If the first call fails
Every error returns a JSON body with status, statusCode, errorCode and errorMessage. Branch on errorCode together with the HTTP status; the message is for people and can be translated.
| Status | errorCode | Cause | What to do |
|---|---|---|---|
401 | E401 | The X-API-Key header is missing. | Send the header on every request. |
401 | SO_ERR_203 | On a calculation, the survey is not in your profile or does not exist. | Use a code from GET /api/v2/users/surveys. |
403 | AE_ERR_415 | On the variables, carriers and tree endpoints, the survey is not available to you: not contracted, disabled, being loaded or non-existent. | Use a code from your survey list, or try later. |
403 | AE_ERR_408 | The application module that the operation needs is not enabled for your user. | A TABULATION table needs the Tabulation module. Ask your TOM platform representative. |
400 | AE_ERR_412 or AE_ERR_416 | A variable of a VARIABLES axis misses subtype, id or filterTgl, or uses an unsupported combination. | Read errorMessage: it names the axis, the variable and the field. |
400 | E400 | The body is not valid JSON. | Check the JSON and the Content-Type header. |
400 | SO_ERR_201 | The survey is disabled or being loaded. | Try again later. |
The Errors and troubleshooting page lists every code.
9. Next steps
- Authentication and access: modules, survey access and what to do when a key stops working.
- Core concepts: the vocabulary of the API.
- Building tables: axes, variables, statistics, planes and recipes.
- Limits and conventions: sizes, timeouts, formats and idempotency.
- TGL guide: define audiences with expressions such as
SEX.D1 AND EDA1.D3.