MaintainX API Integration Guide
Use this guide to set up an integration between Litmus Edge (LE) and MaintainX. 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.
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:
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.
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.
- 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 ConnectorsManage Connectors 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:
- Click the connector tile. The connector Dashboard appears.
- Click the Topics tab.
- Click the Add a new topic icon. The Data Integration dialog box appears.
- 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 for how the connector resolves the meter ID.
- Enable: Select the toggle to enable the topic.
- Click OK to add the topic.
- 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.
Step 8: Verify data in MaintainX
To verify the readings:
- In MaintainX, open the meter you configured in Step 3.
- 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.
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. |
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.
result = {
body: JSON.stringify({
method: "GET",
path: "/meters/<id>>"
})
};Example: Create a meter with a request body.
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.
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:
// ❌ 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.