The tech stack of modern companies is increasingly complex, with data spread across countless tools, platforms, and internal systems. While Databox offers hundreds of native integrations, it's not always possible — or practical — to cover every custom data source or proprietary system. Some organizations also prefer tighter control over how data flows into their reporting environment. The Databox API provides a flexible solution, allowing teams to programmatically send data from any source directly into Databox. As a result, all business-critical metrics can be consolidated in one place, enabling analysts, department leaders, and executives to monitor performance, uncover insights, and make informed decisions from a single, unified source of truth.
The current version of the Databox API is v2, and it is dataset-based: you create a data source, define a dataset with its columns, and then ingest records into it.
Two response conventions apply across every v2 endpoint:
- Every successful response nests its payload under a
datafield. - List responses return an
itemsarray alongsidepagination, wherepageis zero-indexed.
Before authenticating your requests, you must first create an API key in Databox. This key is used to securely authorize all API calls and associate them with your organization.
Follow the steps outlined on the Authentication page in the Databox API documentation to generate your key.
To confirm the key works before you build anything on it, send a GET request to the /v2/auth/validate-key endpoint:
curl -i -X GET \
https://api.databox.com/v2/auth/validate-key \
-H 'x-api-key: YOUR_API_KEY_HERE'A valid key returns 200. A missing or invalid key returns 401.
An API key is tied to the organization that issued it, and requests act on that organization by default. If your organization has accounts, you can run a request against one of them by passing its ID in the x-account-id header. Skip this step if your organization has no accounts.
To list the accounts available to your key, send a GET request to the /v2/accounts endpoint:
curl -i -X GET \
https://api.databox.com/v2/accounts \
-H 'x-api-key: YOUR_API_KEY_HERE'A successful response returns a paginated list of accounts:
{
"requestId": "b0eac937-c25c-47a5-bb7e-552f6b860458",
"status": "success",
"data": {
"items": [
{
"id": 123456,
"name": "ACME, Inc.",
"isSelfManaged": false,
"managedBy": {
"id": 654321,
"name": "Anna Lytics"
}
}
],
"pagination": {
"page": 0,
"pageSize": 25,
"totalItems": 1
}
}
}Pass the account ID as x-account-id on each request you want scoped to that account, including the data source and dataset steps below. The examples that follow omit the header and therefore act on the organization.
A data source serves as a logical container for the datasets you'll send to Databox. You can think of it as the equivalent of an integration or connection within Databox.
Send a POST request to the /v2/data-sources endpoint. Only name is required; timezone accepts an IANA identifier and defaults to Etc/UTC.
curl -i -X POST \
https://api.databox.com/v2/data-sources \
-H 'Content-Type: application/json' \
-H 'x-api-key: YOUR_API_KEY_HERE' \
-d '{
"name": "ERP System",
"timezone": "Etc/UTC"
}'A successful request returns the new data source:
{
"requestId": "b0eac937-c25c-47a5-bb7e-552f6b860458",
"status": "success",
"data": {
"id": 4754489,
"name": "ERP System",
"integrationKey": "DataboxAPI",
"timezone": "Etc/UTC",
"createdAt": "2026-09-18T12:00:00+00:00"
}
}You'll need the data source ID to create a dataset in the next step.
Each dataset represents a table of data within a data source. In v2 you define the dataset's schema up front — every column you intend to send, with its data type — along with an optional primary key used to identify and update unique records.
Each column's dataType must be string, number, or datetime. Display formats such as currency and percentage are applied later, in Databox.
Send a POST request to the /v2/datasets endpoint:
curl -i -X POST \
https://api.databox.com/v2/datasets \
-H 'Content-Type: application/json' \
-H 'x-api-key: YOUR_API_KEY_HERE' \
-d '{
"name": "Transactions",
"dataSourceId": 4754489,
"primaryKey": [
"transaction_id"
],
"schema": [
{ "id": "transaction_id", "dataType": "string" },
{ "id": "transaction_date", "dataType": "datetime" },
{ "id": "product_name", "dataType": "string" },
{ "id": "quantity", "dataType": "number" },
{ "id": "unit_price", "dataType": "number" }
]
}'A successful response returns the dataset's unique identifier:
{
"requestId": "b0eac937-c25c-47a5-bb7e-552f6b860458",
"status": "success",
"data": {
"id": 1234567,
"dataSourceId": 4754489,
"name": "Transactions",
"timezone": "Etc/UTC",
"ingestionSupported": true,
"createdAt": "2026-09-18T12:00:00+00:00"
}
}You'll use the dataset ID to send data to this dataset.
Once the dataset is created, you can begin sending data to it.
Use the /v2/datasets/{id}/data endpoint to ingest records. Each record is keyed by column ID, matching the schema you defined.
curl -i -X POST \
https://api.databox.com/v2/datasets/1234567/data \
-H 'Content-Type: application/json' \
-H 'x-api-key: YOUR_API_KEY_HERE' \
-H 'Idempotency-Key: 3f29b6a2-1c44-4e7a-9b8a-5d6e2f1c9a3d' \
-d '{
"records": [
{
"transaction_id": "T-10024",
"transaction_date": "2026-09-18T09:12:00+00:00",
"product_name": "Standing Desk",
"quantity": 2,
"unit_price": 249
},
{
"transaction_id": "T-10025",
"transaction_date": "2026-09-18T11:40:00+00:00",
"product_name": "Monitor Arm",
"quantity": 1,
"unit_price": 89.5
}
]
}'A successful ingestion returns an ingestion ID you can use to track status:
{
"requestId": "b0eac937-c25c-47a5-bb7e-552f6b860458",
"status": "success",
"data": {
"ingestionId": "8bfba187-84f4-41e2-9dd3-bee4bb884205",
"status": "success",
"message": "Data ingestion request accepted"
}
}To verify how many records were accepted, call:
curl -i -X GET \
https://api.databox.com/v2/datasets/1234567/ingestions/8bfba187-84f4-41e2-9dd3-bee4bb884205 \
-H 'x-api-key: YOUR_API_KEY_HERE'The response reports the ingestion's status, a record-count summary (received, appended, overwritten, and rejected), and any errors encountered, each with the record that caused it.
To review ingestion activity over time, use /v2/datasets/{id}/ingestions for a paginated history and /v2/datasets/{id}/ingestion-statistics for success rates and average durations.
Once your data is successfully ingested, the dataset and its fields become available in Databox for analysis and reporting. You can immediately start building custom metrics, visualizing trends, or combining your API data with metrics from other integrations.
Beyond visualization, Databox offers several tools to help you manage and enrich your datasets directly within the platform:
Add calculated columns — Create new columns derived from existing data using formulas, functions, and operators. This helps you calculate ratios, growth rates, and other custom KPIs without altering your source data.- Merge datasets — Combine multiple datasets into a single, unified dataset to consolidate related information. For example, merging sales and marketing data for cross-department reporting.
- Export a dataset — Download your dataset as a CSV file for backup, further analysis, or sharing with other systems.
Once your dataset is configured, you can:
- Use its fields in the metric builder to create visualizations and KPIs.
- Set goals and forecasts based on your custom data.
- Share Dashboards across teams to keep everyone aligned around the same performance data.
Together, these options turn your API-fed datasets into a flexible, fully managed reporting layer inside Databox — ideal for ongoing performance tracking, analysis, and decision-making.
Sending data is only part of what v2 covers. The same API key also manages the rest of your environment programmatically, including organization details and usage, billing and invoices, accounts, users and profiles, connections, dashboards, integrations, and metrics — including creating a metric from a dataset and reading its values over a date range.
For the full endpoint list, see the API reference and the changelog.
v1 was the first dataset-based version of the Databox API. Its ingestion flow is the same in spirit as the one above, but v2 changes the request and response shapes — payloads are nested under data, lists are paginated with a zero-indexed page, data sources are created with name instead of title, an account is targeted with the x-account-id header instead of an accountId field, and a dataset's schema is declared at creation. If you already send data through v1, follow the migration guide to move to v2.
The Push API (v0) came before either of them and accepted pre-aggregated metric data — already calculated values such as total revenue or number of leads — without datasets or schemas. It was easy to implement but did not support raw data ingestion, record-level updates, or complex data structures. v0 is deprecated: it continues to accept and process incoming data, but new data sources can no longer be created with it and it is no longer maintained. To move off it, see Migrate from Legacy API (v0) or use the in-app migration tool.
FAQ
Can I send real-time updates to Databox?
Yes. You can send data to Databox as frequently as needed, including real-time or event-based updates. However, API rate limits apply — refer to the Rate Limits documentation for details on request thresholds.
Keep in mind that while data is ingested immediately, metric updates in Databox still follow the configured data source sync frequency.
Can I change a dataset's columns after creating it?
Yes. Use the dataset modification endpoints to filter rows, add calculated columns, rename columns, and change their order or visibility. A saved modification is applied in the background, and endpoints that read the dataset's rows, schema, or columns return a 409 with a Retry-After header until it finishes — wait the given number of seconds, then send the same request again.
