---
title: "Data Connection: Ingestion API User Guide"
description: "Learn how to send BESS operating data to the TWAICE platform via the Ingestion API: authentication, endpoints, request format, responses and FAQs."
---

[Skip to content](https://support.twaice.com/knowledge/data-connection-ingestion-api-user-guide#main-content)

![TWAICE Help CenterWordmark (2)](https://support.twaice.com/hs-fs/hubfs/Wordmark%20(2).png?width=138&height=28&name=Wordmark%20(2).png)

Open main navigation

Close main navigation

- [Contact us](mailto:support@twaice.com)

[Contact us](mailto:support@twaice.com)

 How can we help you?

- There are no suggestions because the search field is empty.

1. [Help Center](https://support.twaice.com/knowledge?hsLang=en)
2. [Onboarding Guideline](https://support.twaice.com/knowledge/onboarding-guideline?hsLang=en)
3. [Data Connection Methods](https://support.twaice.com/knowledge/onboarding-guideline?hsLang=en#data-connection-methods)

# Data Connection: Ingestion API User Guide

## Learn how to send BESS measurement data to the TWAICE Ingestion API, including authentication, request format and endpoints.

**On this page**

- [Overview](https://support.twaice.com/knowledge/data-connection-ingestion-api-user-guide#h_e8e9263c53)
- [Authentication](https://support.twaice.com/knowledge/data-connection-ingestion-api-user-guide#h_f04210669b)
- [Request](https://support.twaice.com/knowledge/data-connection-ingestion-api-user-guide#h_9fc0960a25)
- [API Endpoint](https://support.twaice.com/knowledge/data-connection-ingestion-api-user-guide#h_4a88506856)
- [Payload](https://support.twaice.com/knowledge/data-connection-ingestion-api-user-guide#h_5fdb5300c1)
- [Responses](https://support.twaice.com/knowledge/data-connection-ingestion-api-user-guide#h_d8d29512e7)
- [Ingestion](https://support.twaice.com/knowledge/data-connection-ingestion-api-user-guide#h_c18035002d)
- [Authorization](https://support.twaice.com/knowledge/data-connection-ingestion-api-user-guide#h_965f6a5831)
- [Request](https://support.twaice.com/knowledge/data-connection-ingestion-api-user-guide#h_5d32a280c5)
- [API Endpoint](https://support.twaice.com/knowledge/data-connection-ingestion-api-user-guide#h_e8aa5d3a50)
- [Path Parameters](https://support.twaice.com/knowledge/data-connection-ingestion-api-user-guide#h_0d95ba2dc8)
- [Request Body Schema](https://support.twaice.com/knowledge/data-connection-ingestion-api-user-guide#h_e54e8a0da0)
- [Payload](https://support.twaice.com/knowledge/data-connection-ingestion-api-user-guide#h_f8ca8e6fb7)
- [Responses](https://support.twaice.com/knowledge/data-connection-ingestion-api-user-guide#h_0adba03267)
- [Test Environment](https://support.twaice.com/knowledge/data-connection-ingestion-api-user-guide#h_0aacd1f13c)
- [Path Parameters](https://support.twaice.com/knowledge/data-connection-ingestion-api-user-guide#h_6ab9418b4c)
- [Request Body Schema](https://support.twaice.com/knowledge/data-connection-ingestion-api-user-guide#h_89b12c3572)
- [Frequently Asked Questions](https://support.twaice.com/knowledge/data-connection-ingestion-api-user-guide#h_6139fa7d1e)

The TWAICE Ingestion API lets you send BESS operating data (voltage, current, temperature, and related sensor measurements) into the TWAICE platform for analysis.

### **Overview**

- The TWAICE Ingestion API follows [REST](https://restfulapi.net/) architecture principles.
- All requests must use HTTPS.
- Requests and responses are JSON; set the `Content-Type` header to `application/json` on every request.

[![](https://support.twaice.com/hubfs/Knowledge%20Base%20Import/image-4.png)](https://downloads.intercomcdn.eu/i/o/thagvi83/160259478/823bd40e8830263e1ad8bb307d6a/image.png?expires=1792501200&signature=05bcd9ce419490c19d9aa357139617d832ed58f68e967b0595a8111d9bdf4c71&req=0dNvx13zqDAglxv889osp6yzQEy7jOOhKUPZ8EFTvyNdXzNlmyeQOh%2BsLmJS%0AdW4%2F9dTNpO%2FE3fbDDg%3D%3D%0A)

### Authentication

- Authentication is done via [JWT Tokens](https://jwt.io/introduction/). To obtain a token, use the authentication API endpoint with your `email` and `password` as credentials.
- Tokens can only be obtained by registered customers with valid credentials.

    - Your credentials should already have been created for you. If they haven't, contact your TWAICE representative.
- The response returns an `idToken`. Pass it as a bearer token in the `Authorization` header on all subsequent requests:

  ```
  Authorization: Bearer JWT_TOKEN
  ```
- The `idToken` is valid for 1 hour.

**Request**

```
POST /auth/authenticate
```

 

### API Endpoint

| **Data hosted in** | **Endpoint** |
| --- | --- |
| US | https://api.us.twaice.ai/auth/authenticate |
| Australia | https://api.ap.twaice.ai/auth/authenticate |
| All others | https://api.twaice.ai/auth/authenticate |

 

### **Payload**

Payload Body Schema: `application/json`

| **Field** | **Type** |
| --- | --- |
| email (required) | string |
| password (required) | string |

```
{  "email": "johnDoe123@gmail.com",  "password": "d4f089b1e7a6"}
```

 

### Responses

**HTTP 201 Created: Login successful.**

Response Body Schema: `application/json`

| **Field** | **Type** |
| --- | --- |
| idToken | string. JWT Token used for API request authentication & authorization. |

 

**Response Sample:**

```
{  "idToken": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiI1ZGYy"}
```

 

**HTTP 400 Bad Request:** **Validation Error for the request input.**

Response Body Schema: `application/json`

| **Field** | **Type** |
| --- | --- |
| status (required) | string. Enum: "success", "error" |
| data (required) | object |
| message (required) | string. Error message if status is "error". |

 

**Response Sample:**

```
{  "status": "error",  "data": {     "statusCode": 400,     "message": [       "email should not be empty",       "Either email or username should be provided."      ],    "error": "Bad Request"  },  "message": "Bad Request Exception"}
```

 

**HTTP 401 Unauthorized: Invalid login credentials**

Response Body Schema: `application/json`

| **Field** | **Type** |
| --- | --- |
| status (required) | string. Enum: "success", "error" |
| data (required) | object |
| message (required) | string. Error message if status is "error". |

 

**Response Sample:**

```
{  "status": "error",  "data": {     "statusCode": 401,     "message": "Incorrect username or password.",     "error": "Unauthorized"  },  "message": "Incorrect username or password."}
```

 

### Ingestion

Send raw sensor measurements to the TWAICE API.

### Authorization

- **HTTP Authorization Scheme:** `bearer`
- **Bearer format:** `JWT Token`

- `<idToken>` is the value from the authentication request (see How to Authenticate section).

 

```
Authorization: Bearer <idToken>
```

 

### Request

```
POST /ingestion/customers/{customer}/systems/{system}/measurements
```

 

### **API Endpoint**

| **Data hosted in** | **Endpoint** |
| --- | --- |
| US | https://api.us.twaice.ai/ingestion/customers/{customer}/systems/{system}/measurements |
| All others | https://api.twaice.ai/ingestion/customers/{customer}/systems/{system}/measurements |

 

### Path Parameters

`customer` and `system` are provided by TWAICE.

| **Parameter** | **Type** |
| --- | --- |
| customer (required) | string, 1 to 32 characters, ^\[a-z0-9-\]\*$ |
| system (required) | string, 1 to 32 characters, ^\[a-z0-9-\]\*$ |

 

### Request Body Schema

*Array* (\[ 1 .. 1000 \] items): Accepts up to 1000 measurement objects per request *(limit can be modified in need, should be discussed with TWAICE)*

| **Field** | **Type** |
| --- | --- |
| sensor (required) | string, 1 to 200 characters, ^\[^/\]\*$ Customer-provided sensor identifier, unique per system, up to 200 characters. Letters, numbers, and special characters allowed except "forward slashes (/). |
| timestamp (required) | number, range 946684800 to 4102444800. Unix timestamp in seconds, with optional microseconds as a fraction. Must be after 2000-01-01 00:00:00 GMT+0000 and before 2100-01-01 00:00:00 GMT+0000. Example: 1642770062.123456 == 2022-01-21T14:01:02.123456Z (the fraction is 123.456 milliseconds, or 123456 microseconds). |
| value (required) | number. Sensor value at the given timestamp. Accepts integers or float64 (double). |

 

### **Payload**

```
[  {    "sensor": "Sensor XYZ",    "timestamp": 1642770062.123456,    "value": 12.345678  }]
```

 

### Responses

**HTTP 200: Successful Response**

Response Body Schema: `application/json`

| **Field** | **Type** |
| --- | --- |
| numberOfRecordsIngested (required) | integer, \>= 0. Number of measurements ingested by this request. |

 

**Response Sample:**

```
{  "numberOfRecordsIngested": 1}
```

 

**HTTP 404: Not Found**

Returns if there are invalid path parameters.

Response Body Schema: `application/json`

| **Field** | **Type** |
| --- | --- |
| type | string. Default: "about:blank". A URI reference identifying the problem type, scoped to this API. Unlike RFC 7807, it is not required to be dereferenceable or globally unique. |
| title | string. Short summary of the problem type. Written for engineers; not localized. |
| status | integer. 100 to 599. Default 500. The HTTP status code generated by the origin server for this occurrence. |
| detail | string. Human readable explanation of this occurrence. Written for engineers; not localized. |
| timestamp | number. Range 946684800 to 4102444800. Unix timestamp in seconds with optional Microseconds as fraction. The unix timestamp is the number of seconds between a particular date and the Unix Epoch on January 1st, 1970 at UTC. Must be after 2000-01-01 00:00:00 GMT+0000 Must be before 2100-01-01 00:00:00 GMT+0000 Example: 1642770062.123456 == 2022-01-21T14:01:02.123456Z, with the fraction representing 123.456 milliseconds or 123456 microseconds respectively |

 

**Response Sample:**

```
{  "type": "about:blank",  "title": "HTTPException",  "status": 404,  "detail": "Not Found",  "timestamp": 1642770062.123456}
```

 

**HTTP 422: Unprocessable Entity**

Returned when the request contains invalid data.

Response Body Schema: `application/json`

| **Field** | **Type** |
| --- | --- |
| type | string. Default: "about:blank". A URI reference identifying the problem type, scoped to this API. Unlike RFC 7807, it is not required to be dereferenceable or globally unique. |
| title | string. Short summary of the problem type. Written for engineers; not localized. |
| status | integer. 100 to 599. Default 500. The HTTP status code generated by the origin server for this occurrence. |
| detail | string. Human readable explanation of this occurrence. Written for engineers; not localized. |
| instance | string. A URI reference identifying the specific occurrence, for example a fragment or sub-path pointing to the source of the problem. |
| timestamp | number. Range 946684800 to 4102444800. Unix timestamp in seconds with optional Microseconds as fraction. The unix timestamp is the number of seconds between a particular date and the Unix Epoch on January 1st, 1970 at UTC. Must be after 2000-01-01 00:00:00 GMT+0000 Must be before 2100-01-01 00:00:00 GMT+0000 Example: 1642770062.123456 == 2022-01-21T14:01:02.123456Z, with the fraction representing 123.456 milliseconds or 123456 microseconds respectively |
| errors | Array of objects. Detailed information about each subproblem that occurred in the request. |

**Response Sample:**

```
{  "type": "https://docs.twaice.ai/#section/422:-Unprocessable-Entity",  "title": "Unprocessable Entity",  "status": 422,  "detail": "Request contains invalid data, more information about the specific problem could be found in errors field",  "instance": "/system/11223344/sensor/55667788",  "timestamp": 1642770062.123456,  "errors": [    {      "title": "value_error.missing",      "detail": "field required",      "instance": "/body/timestamp"    }  ]}
```

 

**HTTP 500: Internal Server Error**

Returned when an error or failure occurs in the backend service.

### Test Environment

TWAICE provides a sandbox environment for testing your integration without affecting live data.

```
Authorization: Bearer JWT_TOKEN
```

 

### Path Parameters

Identical to the Path Parameters described under Ingestion. `customer` and `system` are provided by TWAICE.

### Request Body Schema

Identical to the Request Body Schema described under Ingestion.

- Sensor IDs must be defined in advance during system configuration. For the sandbox system, any sensor identifier can be used, since sandbox data will not be passed through the full processing pipeline.

**Request Sample**

```
[  {    "sensor": "string 1.1.1-string voltage",    "timestamp": 1642770062.123,    "value": 401.2  },  {    "sensor": "string 1.1.1-string voltage",    "timestamp": 1642770062.123,    "value": 403.1  }]
```

 

### Frequently Asked Questions

Are there any other options for submitting to the API besides a RESTful service?

- No, the API currently supports only the RESTful methods described above.

At what resolution will historical data be required? Is this the same tag list for near real-time data?

- The same tag list applies.
- The time resolution should ideally match as well: 1 point / second if available; otherwise, 1 point / minute.

Is it possible to send large data for initial site onboarding to an S3 bucket rather than the API?

- Yes, this is possible via SFTP or S3 access keys.

Can data be provided at lower time resolutions (e.g. 30 seconds)?

- Resolution between 1 and 60 seconds is accepted. Lower time resolution may affect the accuracy of some KPIs.

How often should data be transmitted? As soon as it's available (near-real-time), or can it be batched? What's the impact of delayed data?

- For the API, it's best to fill the 1000-record maximum batch size. Frequency and rate limits are discussed during onboarding. Delayed data transmission can lead to delayed KPI calculations, notifications, or alerting.

Must data always be delivered in chronological order?

- No. Data is sorted by timestamp on ingestion.

Can we send all data in UTC?

- All timestamps sent, as defined in the ingestion schema, are expected to be Unix timestamps, which are UTC-based by definition.

How would TWAICE like to be notified of failed data transmissions?

- We detect gaps as "missing data". You can resend the data directly, or for longer outages, email [support@twaice.com](mailto:support@twaice.com).

How should a storage system handle resending data that didn't land via the API? How often can we retry, and what's the maximum number of retries TWAICE recommends?

- There is no maximum retry count from our side. If data arrives too late, we may not be able to include it in KPI calculations or alerting.

How would our system play “catch-up” if the TWAICE API becomes unavailable for some reason?

- We inform the customer and fix it as soon as possible.

Does TWAICE have anomaly detection to prune poor-quality data?

- We have threshold-based cleansing rules. These are configured by TWAICE for each storage, but can be tuned based on your needs.

© 2026 TWAICE Technologies GmbH

[twaice.com](https://www.twaice.com)      [Privacy](https://www.twaice.com/legal/data-protection-notice)      [Imprint](https://www.twaice.com/legal/legal-notice)