Data source Type Apps: Build your data connector

Sofia Fernandes

15 April 2026 13:33

Overview

A Data source Type App allows you to build your own data connector inside the platform.

With this type of app, you can:

Define a new data source type
Provide a custom setup experience
Create and manage data sources
Send readings into the platform

This is the recommended approach to:

Integrate an external system
Build a reusable connector
Productise a public integration

If you just looking to send data via API to an already existing datasource and/or without any custom interface, you can just follow the insertion API instruction.

Before you start

You must:

Have created an app (see: Development API: Create and manage your app)
Have backend infrastructure (API server)
Be able to expose public HTTPS endpoints
PRO tip: ask support for an app skeleton that will help you advance faster

What is a Data source Type App?

A Data source Type App is an app that:

Defines a data source type
Allows users to create data sources through your UI
Sends data into those data sources

How it works (end-to-end)

1. App is installed

The app is installed in an account
Your backend receives a permanent token
You use this token to call API v3

(for more details see: Development API: Create and manage your app)

2. Data source type becomes available

After installation:

Go to Settings
Open Data sources
Click Register new data source
Your data source type appears in the list under the external data sources section

3. User creates a data source

When the user selects your data source type, the platform loads your UI:

GET /datasources/new

4. Your app handles setup

Your UI should:

Ask for configuration (credentials, IDs, etc.)
Validate input
Send data to your backend

Custom interface to create and edit each datasource type

5. Your backend creates the data source

You must call API v3:

POST https://api.dexcell.com/v3/datasources

Example:

curl --location 'https://api.dexcell.com/v3/datasources' \
  --header 'x-dexcell-token: <TOKEN>' \
  --header 'Content-Type: application/json' \
  --data '{
    "name": "My Datasource",
    "key": "unique-key-123",
    "timezone": "Europe/Madrid",
    "type": "VIRTUAL",
    "status": "CONNECTED"
  }'

👉 Full reference: https://developers.dexma.com/#75913267-89ad-422f-bce2-fbf606353196

6. Store data source data locally

Your backend must store:

data source id
data source key
data source configuration
mapping to your external system

7. Retrieve insertion token

After creating the data source:

GET https://api.dexcell.com/v3/datasources/{id}/token

This returns the token required to send readings.

👉 Full reference: https://developers.dexma.com/#18c8716c-e3fe-4d09-82a9-ebd4c17096cb

8. Send readings (Insertion API)

This is the core data flow.

POST https://insert.dexma.com/readings?source_key=<DATASOURCE_KEY>

Headers:

x-dexcell-source-token: <DATASOURCE_TOKEN>
Content-Type: application/json

Example request

curl -X POST "https://insert.dexma.com/readings?source_key=<KEY>" \
  -H "x-dexcell-source-token: <TOKEN>" \
  -H "Content-Type: application/json" \
  -d '[
    {
      "did": "device-1",
      "sqn": 1,
      "ts": "2026-01-01T00:00:00+01:00",
      "values": [
        { "p": 402, "v": 1250.0 }
      ]
    }
  ]'

How insertion works

to define "p" see Introduction to Parameters and parameter id & operation & resolution list
Requests are asynchronous
HTTP 200 OK means accepted, not fully processed
Data appears later in the platform

👉 Full reference: Using the insertion API to introduce data in a gateway

9. Editing a data source

When a user opens a data source:

GET /datasources/{id}

Your app should:

Load current configuration
Allow edits
Send updates to backend

Backend call:

PUT https://api.dexcell.com/v3/datasources/{id}

10. Deleting a data source

When a data source is deleted:

DELETE /datasources/{id}

Your backend must:

Remove internal mappings
Optionally call API v3:

DELETE https://api.dexcell.com/v3/datasources/{id}

Return:

HTTP 2xx

If you return an error, deletion is cancelled.

API responsibilities

	API v3	Insertion API
Used for	Create/update/delete data source Obtain data source token Retrieve context data Retrieve readings	Sending readings
Documentation	https://developers.dexma.com	Using the insertion API to introduce data in a gateway
Authentication	x-dexcell-token	datasource-token

Critical architectural rule

Do not call API v3 before every insertion.

Instead:

Store data source state locally
Keep it updated when changes occur
Use insertion API directly

Why this matters

If you don’t follow this:

You may hit API limits
Performance will degrade
Integration may fail at scale

Payload and performance guidelines

Recommended: ~1,000 readings per request
Maximum: ~5,000 readings
Max concurrency: ~8 requests
Use batching when possible

Common issues

Insert error

wrong data source token
wrong data source key
invalid parameter combo (base parameter + resolution + parameter)
wrong timestamp format

Insert succeeds but no data

Data is insert with OK, but not visualised in the data source

Data can not be be seen inside the data source in delete readings or last readings. Can be due to:

invalid timestamp for the parameter combo: time interval data must be inserted at the begging of the period and considering the chosen resolution.
invalid parameter parameter combo (base parameter + resolution + parameter)
device being rejected

Data is inserted with OK, but not visualised in analytics

Data can be seen inside the data source in delete readings or last readings, but not in analytics. Check that:

the device and parameter and accepted
the device is assigned to a location
your are visualising data in the correct device, parameter, resolution, operation and time period

UI best practices