# Send data to Databox via API 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. ## Send data to Databox via API The current version of the Databox API is **v2**, and it is [dataset](/understanding-datasets)**-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 **`data`** field. - List responses return an **`items`** array alongside **`pagination`**, where `page` is zero-indexed. ### Before you begin 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](https://developers.databox.com/docs/api/authentication) 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 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`. ### Target a specific account An API key is tied to the organization that issued it, and requests act on that organization by default. If your organization has [accounts](/databox-glossary), 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 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: ```json { "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. Response examples in this article show only the fields used in the steps that follow. See the [API reference](https://developers.databox.com/docs/api/overview) for the complete schemas. ### Create a data source 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 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: ```json { "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. To view all supported time zones, send a `GET` request to `/v2/organization/timezones`. Use one of the returned IANA identifiers in the `timezone` field when creating your data source. ### Create a dataset 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 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: ```json { "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. You can create multiple datasets under a single data source if you need to organize data by entity or domain (e.g., *Customers*, *Orders*, *Campaigns*). ### Send data to a 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 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: ```json { "requestId": "b0eac937-c25c-47a5-bb7e-552f6b860458", "status": "success", "data": { "ingestionId": "8bfba187-84f4-41e2-9dd3-bee4bb884205", "status": "success", "message": "Data ingestion request accepted" } } ``` The optional **`Idempotency-Key`** header makes a request safe to retry after a timeout or dropped connection. Supply a client-generated unique value, such as a UUID. If the same key is sent again within 24 hours, the API returns the original response instead of ingesting the records a second time. The header is also supported when creating accounts, data sources, datasets, and metrics, and when duplicating or purging a dataset. ### Check the ingestion result To verify how many records were accepted, call: ```curl 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. ## What happens next 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: - ![lock](/assets/lock.2fb1bbc208afcc03d15a0a45f22bdf7f830322016e038e5721965851130807af.419bb737.svg) [Add calculated columns](/add-a-calculated-column-to-a-dataset) — 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. - ![lock](/assets/lock.2fb1bbc208afcc03d15a0a45f22bdf7f830322016e038e5721965851130807af.419bb737.svg) [Merge datasets](/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. - ![lock](/assets/lock.2fb1bbc208afcc03d15a0a45f22bdf7f830322016e038e5721965851130807af.419bb737.svg) [Export a dataset](/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. ## Beyond data ingestion 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](https://developers.databox.com/docs/api/overview) and the [changelog](https://developers.databox.com/docs/api/changelog). ## Earlier API versions **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](https://developers.databox.com/docs/api/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)](/migrate-from-legacy-api-v0-to-databox-api-v1) or use the in-app [migration tool](/migrate-legacy-metrics-with-the-migration-tool). 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](https://developers.databox.com/docs/api/rate-limits) 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](/change-the-data-sync-frequency). 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. Ask Genie Get instant answers or help with your data using the in-app AI assistant. Talk to an expert For customers: Get help with your setup, strategy, or making the most of Databox. Book a demo New to Databox? See how it works and get guidance on getting started. Send an email Reach out to support for help with your account, data, or technical issues.