--- title: MaintainX API Integration Guide slug: litmusedge/maintainx-api-integration-guide docTags: createdAt: 2026-09-04T20:48:36.855Z --- Use this guide to set up an integration between Litmus Edge (LE) and [MaintainX](https://api.getmaintainx.com/v1/docs). After you set up the integration, you can publish tag values from LE directly into MaintainX as meter readings, so equipment usage recorded at the edge drives maintenance triggers in MaintainX without manual entry. :::hint{type="info"} **Note:** This connector publishes data from LE to MaintainX. It does not subscribe to MaintainX data. For any other MaintainX API call, use the **IT Hub** processor in Analytics, which accepts a dynamic method, path, and request body. ::: ## Before you begin Complete Steps 1 to 3 in MaintainX before you configure the connector in LE. For reference, see the following MaintainX resources: - [MaintainX API reference](https://api.getmaintainx.com/v1/docs) - [Authentication](https://api.getmaintainx.com/v1/docs#tag/Authentication) - [Meter Readings](https://api.getmaintainx.com/v1/docs#tag/Meter-Readings) ## Step 1: Create an API key in MaintainX In MaintainX, go to **Settings** > **Integrations** > **API Keys** and create a key. Record the token. You enter it as the **Bearer Token** when you configure the connector. :::hint{type="info"} **Caution:** Store the token securely. ::: ## Step 2: Note your organization ID If your token is scoped to more than one MaintainX organization, record the organization ID. You enter it as the **Organization ID** when you configure the connector, and LE sends it as an `x-organization-id` header. If your token covers a single organization, skip this step. ## Step 3: Create the meter for the readings Every reading LE publishes belongs to a MaintainX meter, identified by a numeric meter ID. Create the meter in MaintainX before you configure the outbound topic, and record its ID. ## Step 4: Set up the outbound connection Configure LE to publish meter readings to MaintainX. ## Step 5: Add the MaintainX API connector Follow the steps in @adda and select **MaintainX** as the provider type and **MaintainX API** as the provider name. Configure the following parameters. For every field, including the retry, timeout, and persistent storage options, see [MaintainX API](docId\:Y0q94FTGq7yRSaSd3g1PS). - **Name**: Enter a name for the connector. - **MaintainX Base URL**: Keep the default `https://api.getmaintainx.com/v1` unless you are connecting to a sandbox or staging environment. - **Bearer Token**: Enter the token you created in Step 1. - **Organization ID**: Enter the organization ID from Step 2. Leave it empty for a single-organization token. - **Response Topic**: Enter a local topic to receive the MaintainX response for each reading. Leave it empty if you do not need the responses. - **Response Mode**: Select `body_only` for the correlation ID, status code, and body, or `full_metadata` to also receive headers, latency, and any error. ## Step 6: Enable the connector In the connector tile, click the toggle to enable the connector. If the connector shows a *Failed* status, see [Manage Connectors](docId\:tQoP7QtquSQqDq9yhbJ34) and review the error messages. An invalid base URL, an invalid token, or an incorrect organization ID each produce a distinct error in the logs. ## Step 7: Add an outbound topic Add one or more outbound topics to define which LE data the connector publishes to MaintainX. Each topic maps one LE topic to one MaintainX meter. **To add an outbound topic:** 1. Click the connector tile. The connector *Dashboard* appears. 2. Click the **Topics** tab. 3. Click the **Add a new topic** icon. The *Data Integration* dialog box appears. 4. Configure the following parameters: - **Data Direction**: Select **Local to Remote - Outbound**. - **Local Data Topic**: Select the DeviceHub tag topic you want to publish. - **Remote Data Topic**: Enter the meter ID from Step 3, such as `53`. If you leave it empty, the connector reads `metadata.meterId` from each payload instead. See [MaintainX API](docId\:Y0q94FTGq7yRSaSd3g1PS) for how the connector resolves the meter ID. - **Enable**: Select the toggle to enable the topic. 5. Click **OK** to add the topic. 6. On the connector tile, confirm that the connector shows a **CONNECTED** status and the topic shows an **Enabled** status. The payload on the local topic must contain a `value` and a `timestamp`. A DeviceHub tag payload contains both. If the payload contains `success: false`, the connector drops the message rather than creating a reading from a failed read. For the full contract, see [MaintainX API](docId\:Y0q94FTGq7yRSaSd3g1PS). ## Step 8: Verify data in MaintainX **To verify the readings:** 1. In MaintainX, open the meter you configured in Step 3. 2. Confirm that new readings appear with values from your LE tag. If no readings appear, check the following: - The connector tile shows **CONNECTED** and the topic shows **Enabled**. - The local topic is publishing. A tag with a 30-second polling interval produces a reading every 30 seconds. - The connector logs show no drops. A dropped message logs an error naming the reason, such as `payload.success is false — DeviceHub reading marked as failed; dropping`. - The drop count on the connector dashboard is not increasing. A rising drop count with no readings in MaintainX usually means the meter ID is missing or is not an integer. ## Step 9: Make dynamic API calls with IT Hub Beyond the outbound meter-reading subscription, the MaintainX connector supports any MaintainX API call, with any method and subpath, through the **IT Hub** processor in Analytics. Use it to drive calls dynamically from an upstream **JavaScript** processor. :::hint{type="info"} **Note:** Pass the request spec as a JSON string in the IT Hub `body` field. ::: The following fields go inside the stringified `body`: | Field | Type | Description | | --------- | --------------- | ------------------------------------------------------------------------------------- | | `method` | string | HTTP method: `GET`, `POST`, `PUT`, `PATCH`, or `DELETE`. | | `path` | string | Subpath appended to **MaintainX Base URL**, for example `/meters/778324`. | | `query` | object | URL query parameters, appended as `?key=value`. Keys and values must both be strings. | | `headers` | object | Extra request headers. Keys and values must both be strings. | | `body` | object or array | HTTP request body, for `POST`, `PUT`, and `PATCH`. | :::hint{type="info"} **Note:** The connector applies the bearer token from its own configuration, so you do not add an Authorization header to the spec. ::: Example: Get meter information with no request body. ```javascript result = { body: JSON.stringify({ method: "GET", path: "/meters/>" }) }; ``` Example: Create a meter with a request body. ```javascript result = { body: JSON.stringify({ method: "POST", path: "/meters", body: { name: "Boiler Temp", description: "Monitors boiler temperature", measurementType: "AUTOMATED_SENSOR", unit: "Celsius" } }) }; ``` Example: Use `query` and `headers` to list meters, filtered and paginated. ```javascript result = { body: JSON.stringify({ method: "GET", path: "/meters", query: { // Appended to the URL → /meters?limit=50&status=ACTIVE limit: "50", status: "ACTIVE" }, headers: { // Extra request headers (do NOT set Authorization — see note above) "x-organization-id": "litmus-edge" } }) }; ``` Note the following about `query` and `headers`: - Quote every number, such as `limit: "50"` rather than `limit: 50`. - The connector URL-encodes `query` values and appends them as `?key=value&key=value`. - The connector merges the spec's `headers` with any headers configured on the IT Hub processor. On a key collision, the spec's `headers` win. Common mistakes that return `400`: ```javascript // ❌ Spec passed as top-level object (no `body`, not stringified) result = { method: "GET", path: "/meters/778324" }; // ❌ `body` present but a raw object, not a JSON string result = { body: { method: "GET", path: "/meters/778324" } }; ``` Both cause the connector to receive an empty payload and fall back to its default `POST /meterreadings`, which returns `{"errors":[{"error":"must be array"}]}` with status `400`. The following settings decide whether the call reaches MaintainX and whether you see the result: - **MaintainX Base URL** must include the API version, `https://api.getmaintainx.com/v1`. The connector appends `path` to it. - Set a **Response Topic** on the IT Hub processor, and match it to the topic you are watching. Without it, the server response goes nowhere you can see. The REST API v2 (Gen 2) connector accepts the same spec shape: `method`, `path`, `query`, `headers`, and `body`. ## Related topics - [MaintainX API](docId\:Y0q94FTGq7yRSaSd3g1PS) - [Add a Connector](docId:4YVfCEP7GYScJHMKYFCuM) - [Manage Connectors](docId\:tQoP7QtquSQqDq9yhbJ34)