{"templateId":"markdown","sharedDataIds":{"sidebar":"sidebar-sidebars.yaml"},"props":{"metadata":{"markdoc":{"tagList":["availability","callout","faq","faq-item","partial"]},"type":"markdown","userRole":"Admins","accountType":"All accounts","plan":"Exclusive to select subscription plans"},"seo":{"title":"Send data to Databox via API","description":"Learn how to send custom data to Databox via the Databox API to build metrics and dashboards from any data source.","siteUrl":"https://help.databox.com","llmstxt":{"title":"Databox Knowledge Base","description":"Databox is a business analytics platform that consolidates data in one place, enabling real-time performance tracking and insights by mixing and matching data from various sources for a comprehensive view.","details":{"content":"This knowledge base covers everything from account setup and integrations to building Databoards, creating custom metrics, and using AI-powered features."},"sections":[{"title":"General","includeFiles":["docs/general/*.md","docs/general/visualization-types/*.md","docs/general/templates/*.md"],"excludeFiles":[]},{"title":"AI","includeFiles":["docs/ai/*.md"],"excludeFiles":[]},{"title":"Account Management","includeFiles":["docs/account-management/**/*.md"],"excludeFiles":[]},{"title":"Databoards","includeFiles":["docs/databoards/**/*.md"],"excludeFiles":[]},{"title":"Data Management","includeFiles":["docs/data-management/**/*.md"],"excludeFiles":[]},{"title":"Metrics","includeFiles":["docs/metrics/**/*.md"],"excludeFiles":[]},{"title":"Forecasts","includeFiles":["docs/forecasts/*.md"],"excludeFiles":[]},{"title":"Goals","includeFiles":["docs/goals/*.md"],"excludeFiles":[]},{"title":"Reports","includeFiles":["docs/reports/*.md"],"excludeFiles":[]},{"title":"Notifications","includeFiles":["docs/notifications/*.md"],"excludeFiles":[]},{"title":"Pricing and Billing","includeFiles":["docs/pricing-and-billing/*.md"],"excludeFiles":[]},{"title":"Mobile","includeFiles":["docs/mobile/*.md"],"excludeFiles":[]},{"title":"Support","includeFiles":["docs/support/*.md"],"excludeFiles":[]},{"title":"Integrations","includeFiles":["docs/integrations/**/*.md"],"excludeFiles":[]}],"hide":false,"excludeFiles":[]}},"dynamicMarkdocComponents":[],"compilationErrors":[],"ast":{"$$mdtype":"Tag","name":"article","attributes":{},"children":[{"$$mdtype":"Tag","name":"Heading","attributes":{"level":1,"id":"send-data-to-databox-via-api","__idx":0},"children":["Send data to Databox via API"]},{"$$mdtype":"Tag","name":"Availability","attributes":{"users":"admins","accounts":"all","plans":"exclusive"},"children":[]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["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 ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["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."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"send-data-to-databox-via-api-1","__idx":1},"children":["Send data to Databox via API"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["The Databox API (v1) is ",{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"/understanding-datasets"},"children":["dataset"]},{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["-based"]},", meaning you create containers for data and then ingest records into them."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"before-you-begin","__idx":2},"children":["Before you begin"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Before authenticating your requests, you must first ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["create an API key"]}," in Databox. This key is used to securely authorize all API calls and associate them with your account."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Follow the steps outlined on the ",{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"https://developers.databox.com/docs/api/authentication"},"children":["Authentication page"]}," in the Databox API documentation to generate your key."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"list-available-accounts","__idx":3},"children":["List available accounts"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["After generating your API key, the next step is to ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["list the Databox accounts"]}," you have access to. You'll need the ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["account ID"]}," to create a new data source in the next step."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["To retrieve your accounts, send a ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["GET"]}," request to the ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["/v1/accounts"]}," endpoint:"]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"curl","header":{"controls":{"copy":{}}},"source":"curl -i -X GET \\  \n  https://api.databox.com/v1/accounts \\  \n  -H 'x-api-key: YOUR_API_KEY_HERE'\n","lang":"curl"},"children":[]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["A successful response returns a list of accounts associated with your API key:"]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"json","header":{"controls":{"copy":{}}},"source":"{  \n  \"requestId\": \"b0eac937-c25c-47a5-bb7e-552f6b860458\",  \n  \"status\": \"success\",  \n  \"accounts\": [  \n    {  \n      \"id\": 123456,  \n      \"name\": \"Acme Corp\",  \n      \"accountType\": \"organization\"  \n    }  \n  ]  \n}\n","lang":"json"},"children":[]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Use the appropriate ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["account ID"]}," from this list when creating a data source to ensure the dataset is added to the correct Databox account."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"create-a-data-source","__idx":4},"children":["Create a data source"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Once you have your account ID, the next step is to 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 your Databox account."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Send a ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["POST"]}," request to the ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["/v1/data-sources"]}," endpoint:"]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"curl","header":{"controls":{"copy":{}}},"source":"curl -i -X POST \\  \n  https://api.databox.com/v1/data-sources \\  \n  -H 'Content-Type: application/json' \\  \n  -H 'x-api-key: YOUR_API_KEY_HERE' \\  \n  -d '{  \n    \"accountId\": 123456,  \n    \"title\": \"ERP System\",  \n    \"timezone\": \"UTC\"  \n  }'\n","lang":"curl"},"children":[]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["A successful request returns the ID of your new data source:"]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"json","header":{"controls":{"copy":{}}},"source":"{  \n  \"requestId\": \"b0eac937-c25c-47a5-bb7e-552f6b860458\",  \n  \"status\": \"processing\",  \n  \"id\": 4754489,  \n  \"title\": \"ERP System\",  \n  \"created\": \"2025-10-01T12:00:00.000000Z\",  \n  \"timezone\": \"UTC\",  \n  \"key\": \"ingestion\"  \n}\n","lang":"json"},"children":[]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["You'll need the ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["data source ID"]}," to create a dataset in the next step."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":[{"$$mdtype":"Tag","name":"Callout","attributes":{"type":"note"},"children":["To view all supported time zones, send a ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["GET"]}," request to ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["/v1/timezones"]},". Use one of these values in the ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["timezone"]}," field when creating your data source."]}]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"create-a-dataset","__idx":5},"children":["Create a dataset"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Each dataset represents a table of data within a data source. Define the dataset structure, including ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["primary keys"]}," (used to identify and update unique records)."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Send a ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["POST"]}," request to the ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["/v1/datasets"]}," endpoint:"]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"curl","header":{"controls":{"copy":{}}},"source":"curl -i -X POST \\  \n  https://api.databox.com/v1/datasets \\  \n  -H 'Content-Type: application/json' \\  \n  -H 'x-api-key: YOUR_API_KEY_HERE' \\  \n  -d '{  \n    \"title\": \"Transactions\",  \n    \"dataSourceId\": 4754489,  \n    \"primaryKeys\": [  \n      \"invoice_id\"  \n    ]  \n  }'\n","lang":"curl"},"children":[]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["A successful response returns the dataset's unique identifier:"]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"json","header":{"controls":{"copy":{}}},"source":"{  \n  \"requestId\": \"b0eac937-c25c-47a5-bb7e-552f6b860458\",  \n  \"status\": \"success\",  \n  \"id\": \"4e1219d8-7fa8-44b7-96c6-a8f2a9cfb0bf\",  \n  \"title\": \"Transactions\",  \n  \"created\": \"2025-10-01T12:00:00.000000Z\"  \n}\n","lang":"json"},"children":[]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["You'll use the ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["dataset ID"]}," to send data to this dataset."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":[{"$$mdtype":"Tag","name":"Callout","attributes":{"type":"tip"},"children":["You can create multiple datasets under a single data source if you need to organize data by entity or domain (e.g., ",{"$$mdtype":"Tag","name":"em","attributes":{},"children":["Customers"]},", ",{"$$mdtype":"Tag","name":"em","attributes":{},"children":["Orders"]},", ",{"$$mdtype":"Tag","name":"em","attributes":{},"children":["Campaigns"]},")."]}]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"send-data-to-a-dataset","__idx":6},"children":["Send data to a dataset"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Once the dataset is created, you can begin sending data to it."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Use the ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["/v1/datasets/{datasetId}/data"]}," endpoint to ingest records."]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"curl","header":{"controls":{"copy":{}}},"source":"curl -i -X POST \\  \n  https://api.databox.com/v1/datasets/4e1219d8-7fa8-44b7-96c6-a8f2a9cfb0bf/data \\  \n  -H 'Content-Type: application/json' \\  \n  -H 'x-api-key: YOUR_API_KEY_HERE' \\  \n  -d '{  \n    \"records\": [  \n      {  \n        \"transactionId\": \"9826\",  \n        \"occurredAt\": \"2025-10-01T12:00:00.000000Z\",  \n        \"amount\": 42.5,  \n        \"tags\": [  \n          \"promo\",  \n          \"returning\"  \n        ]  \n      },  \n      {  \n        \"transactionId\": \"9827\",  \n        \"occurredAt\": \"2025-10-02T10:45:00.000Z\",  \n        \"amount\": 87.9,  \n        \"tags\": [  \n          \"new\",  \n          \"discount\"  \n        ]  \n      }  \n    ]  \n  }'\n","lang":"curl"},"children":[]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["A successful ingestion returns an ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["ingestion ID"]}," you can use to track status:"]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"json","header":{"controls":{"copy":{}}},"source":"{  \n  \"requestId\": \"b0eac937-c25c-47a5-bb7e-552f6b860458\",  \n  \"status\": \"success\",  \n  \"ingestionId\": \"8bfba187-84f4-41e2-9dd3-bee4bb884205\",  \n  \"message\": \"Data ingestion request accepted\"  \n}\n","lang":"json"},"children":[]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["To verify the ingestion result, call:"]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"curl","header":{"controls":{"copy":{}}},"source":"curl -i -X GET \\  \n  https://api.databox.com/v1/datasets/4e1219d8-7fa8-44b7-96c6-a8f2a9cfb0bf/ingestions/8bfba187-84f4-41e2-9dd3-bee4bb884205 \\  \n  -H 'x-api-key: YOUR_API_KEY_HERE'\n","lang":"curl"},"children":[]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"what-happens-next","__idx":7},"children":["What happens next"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Once your data is successfully ingested, the dataset and its fields become available in Databox for analysis and reporting. You can immediately start building ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["custom metrics"]},", visualizing trends, or combining your API data with metrics from other integrations."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Beyond visualization, Databox offers several tools to help you manage and enrich your datasets directly within the platform:"]},{"$$mdtype":"Tag","name":"ul","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"img","attributes":{"src":"/assets/lock.2fb1bbc208afcc03d15a0a45f22bdf7f830322016e038e5721965851130807af.419bb737.svg","alt":"lock"},"children":[]}," ",{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"/add-a-calculated-column-to-a-dataset"},"children":["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."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"img","attributes":{"src":"/assets/lock.2fb1bbc208afcc03d15a0a45f22bdf7f830322016e038e5721965851130807af.419bb737.svg","alt":"lock"},"children":[]}," ",{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"/merge-datasets"},"children":["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."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"img","attributes":{"src":"/assets/lock.2fb1bbc208afcc03d15a0a45f22bdf7f830322016e038e5721965851130807af.419bb737.svg","alt":"lock"},"children":[]}," ",{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"/export-a-dataset"},"children":["Export a dataset"]}," — Download your dataset as a CSV file for backup, further analysis, or sharing with other systems."]}]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Once your dataset is configured, you can:"]},{"$$mdtype":"Tag","name":"ul","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Use its fields in the ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["metric builde"]},"r to create visualizations and KPIs."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Set ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["goals"]}," and ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["forecasts"]}," based on your custom data."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Share ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Databoards"]}," across teams to keep everyone aligned around the same performance data."]}]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["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."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"about-the-legacy-push-api-v0","__idx":8},"children":["About the legacy Push API (v0)"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Before the introduction of the dataset-based API (v1), Databox provided a simpler ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Push API (v0)"]}," for sending ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["pre-aggregated metric data"]},". It was designed for quick submissions, allowing users to push already calculated values — such as total revenue or number of leads — directly into Databox without the need to define datasets or schemas."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["While v0 was easy to implement and suited basic reporting needs, it offered limited flexibility. It did not support raw data ingestion, record-level updates, or complex data structures — capabilities that are fully supported in ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["v1"]},"."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["The ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Push API (v0)"]}," is now ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["deprecated"]},". Although it continues to accept and process incoming data, new data sources can no longer be created using this version, and it is no longer maintained or updated."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["The modern ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["v1 API"]}," introduces a robust, dataset-based framework that supports structured data ingestion, validation, and integration with Databox's datasets feature. It is the recommended option for all new and future implementations."]},{"$$mdtype":"Tag","name":"Faq","attributes":{},"children":[{"$$mdtype":"Tag","name":"FaqItem","attributes":{"question":"Can I send real-time updates to Databox?"},"children":[{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Yes. You can send data to Databox as frequently as needed, including real-time or event-based updates. However, API ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["rate limits"]}," apply — refer to the ",{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"https://developers.databox.com/docs/api/rate-limits"},"children":["Rate Limits documentation"]}," for details on request thresholds."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Keep in mind that while data is ingested immediately, ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["metric updates"]}," in Databox still follow the configured ",{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"/change-the-data-sync-frequency"},"children":["data source sync frequency"]},"."]}]}]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":[" "]},{"$$mdtype":"Tag","name":"Cards","attributes":{"columns":4,"cardMinWidth":160},"children":[{"$$mdtype":"Tag","name":"FooterCard","attributes":{"title":"Ask Genie","icon":"genie","to":"https://app.databox.com/genie","variant":"elevated"},"children":[{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Get instant answers or help with your data using the in-app AI assistant."]}]},{"$$mdtype":"Tag","name":"FooterCard","attributes":{"title":"Talk to an expert","icon":"assistance","to":"https://meetings.hubspot.com/databox-meeting/account-management","variant":"elevated"},"children":[{"$$mdtype":"Tag","name":"p","attributes":{},"children":["For customers: Get help with your setup, strategy, or making the most of Databox."]}]},{"$$mdtype":"Tag","name":"FooterCard","attributes":{"title":"Book a demo","icon":"eye-open","to":"https://meetings.hubspot.com/databox-meeting/ref-knowledge-base","variant":"elevated"},"children":[{"$$mdtype":"Tag","name":"p","attributes":{},"children":["New to Databox? See how it works and get guidance on getting started."]}]},{"$$mdtype":"Tag","name":"FooterCard","attributes":{"title":"Send an email","icon":"help","to":"mailto:help@databox.com","variant":"elevated"},"children":[{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Reach out to support for help with your account, data, or technical issues."]}]}]}]},"headings":[{"value":"Send data to Databox via API","id":"send-data-to-databox-via-api","depth":1},{"value":"Send data to Databox via API","id":"send-data-to-databox-via-api-1","depth":2},{"value":"Before you begin","id":"before-you-begin","depth":3},{"value":"List available accounts","id":"list-available-accounts","depth":3},{"value":"Create a data source","id":"create-a-data-source","depth":3},{"value":"Create a dataset","id":"create-a-dataset","depth":3},{"value":"Send data to a dataset","id":"send-data-to-a-dataset","depth":3},{"value":"What happens next","id":"what-happens-next","depth":2},{"value":"About the legacy Push API (v0)","id":"about-the-legacy-push-api-v0","depth":2}],"frontmatter":{"slug":"send-data-to-databox-via-api","seo":{"title":"Send data to Databox via API","description":"Learn how to send custom data to Databox via the Databox API to build metrics and dashboards from any data source."},"keywords":{"includes":["Databox API","send data to Databox via API","Databox API data ingestion","push custom data to Databox","how to use Databox API","Databox Push API custom metrics","ingest data into Databox programmatically"]},"metadata":{"userRole":"Admins","accountType":"All accounts","plan":"Exclusive to select subscription plans"}},"lastModified":"2026-05-27T11:00:17.000Z","pagePropGetterError":{"message":"","name":""}},"slug":"/send-data-to-databox-via-api","userData":{"isAuthenticated":false,"teams":["anonymous"]},"isPublic":true}