Set up a custom integration

Availability

  Users, Editors, and Admins

  All accounts

  Feature exclusive to select subscription plans

Databox provides integrations for many popular tools, but you may need to work with data from a source that isn’t supported out of the box. With Custom Integration, a configurable connector, you can connect to any external REST API and pull data into a Databox dataset. This gives you the flexibility to bring in custom or internal data, centralize everything in one place, and build metrics tailored to your reporting needs. Once the data is in a dataset, you can create metrics, build Databoards, and track performance just like with any other data source.

Set up a custom integration

Setting up a Custom Integration involves creating a connection, defining how data is requested from your API, transforming the response into a dataset, and choosing how often the data should sync. Follow the steps below to turn raw API responses into structured data you can use in Databox.

Step 1: Create a connection

A connection stores your API base URL and authentication details. You can reuse one connection across multiple datasets.

1. Go to Data Manager > Available Integrations.
2. Find Custom Integration and click Connect.
3. In the dialog, enter the required details:

• • Connection name — Enter a label to identify the connection.
  • Description — Add optional notes about the connection.
  • Base API URL — Enter the root domain of the API (for example, https://api.company.com).
  • Authentication method — Select one of the following:
    • Basic — Use a username and password. Credentials are sent as a standard HTTP Basic Auth header.
    • Token — Use an API key or bearer token. Typically sent in the Authorization header or as a custom header.
    • OAuth2 — Use OAuth 2.0 credentials. You will be prompted to authorize access through the provider.
    • No authentication — Use this for public APIs that do not require credentials.

1. • (Optional) Test endpoint — Enter a sample endpoint to verify that the connection and credentials work.

2. Click Connect.

Step 2: Build the API request

After creating the connection, the dataset setup wizard opens. The first step is to define how Databox should request data from your API.

1. Select the HTTP method (for example, GET or POST).
2. Enter the endpoint path (for example, /v1/data).

3. Use the configuration tabs to refine your request:

   • Variables —  Shows available variables for dynamic requests, such as dates or pagination. Insert them in the endpoint or any request tab.
   • Query params — Add key-value pairs to the request URL.
   • Headers — Add custom HTTP headers required by the API.
   • Body — Define the request body for POST or PUT requests.
   • Pagination — Configure how multiple pages of results are retrieved.
   • Settings — Adjust additional request options. 
4. Click Send to test the request. 

A successful request returns a response preview in the right panel. If the request fails, you will see an error message and status code (such as 401, 403, or 500). This usually indicates an issue with the endpoint, headers, parameters, or authentication settings.

Once the request returns the expected data, click Continue.

Step 3: Transform the data

In this step, you define how the API response is converted into a dataset.

You can choose between two modes:

Simple mode

1. Select fields from the JSON response.
2. Review the preview table on the right. 

Advanced mode (JSONata)

1. Edit or write a JSONata expression to extract and structure your data.
2. Click Run transformation to preview the result. 

The result must return an object or an array of objects, which becomes your dataset.

Click Continue when the output matches your expectations.

Step 4: Set the update frequency

Choose how often Databox should sync data from the API and click Finish to create the dataset.

Frequently Asked Questions

Can I connect to APIs that return XML or CSV?

No. The Custom Integration connector currently supports only APIs that return JSON responses.

Can I control API rate limits?

No. The Custom Integration connector does not currently include built-in controls for managing API rate limits.

API rate limits define how many requests you can send to an API within a given time period. If you exceed these limits, the API may return errors (such as a 429 status code) and stop responding temporarily.

To avoid hitting rate limits, you should adjust your request configuration and sync frequency. For example, reduce how often data syncs or limit the number of pages retrieved during pagination.

Does the dataset accumulate data over time?

No. The dataset does not accumulate or store historical data across syncs. Each sync replaces the existing data with the latest response from the API.

To retain historical data, your API must return it as part of the response. For example, include a date range in your request or use endpoints that provide historical records.

How are errors handled in a Custom Integration?

Error handling is currently limited. If a request fails, you will see an error message and status code in the request preview. It is not possible to detect or handle specific errors at this time.

Still need help?

Visit our community, send us an email, or start a chat in Databox.