> ## Documentation Index
> Fetch the complete documentation index at: https://docs.kodelabs.com/llms.txt
> Use this file to discover all available pages before exploring further.

# MaintainX

> Connect MaintainX to KODE OS for assets, current meter readings, and work orders

> Connect MaintainX to KODE OS for asset, meter, and work order data

## Overview

Use this integration to collect MaintainX assets, current meter readings, and work orders. KODE OS represents assets as devices, asset meters as points, and maintenance records as work orders.

| Property            | Value       |
| ------------------- | ----------- |
| **System Type**     | Work Orders |
| **Communication**   | REST        |
| **Collection**      | Pull        |
| **Collection Mode** | SNAPSHOT    |

## Supported capabilities

* Discover devices and points
* Collect current meter readings
* Collect work orders

## Prerequisites

* A MaintainX account with access to API keys
* A MaintainX API key
* Access to the required organization and location
* KODE OS access to `Data Sources`

## Generate an API key

1. Open [MaintainX API Keys](https://app.getmaintainx.com/settings/integrations/apiKeys).
2. Generate an API key for the integration.
3. Copy the key and store it securely.

## Configure the connector in KODE OS

1. Open `Data Sources` for your building.
2. Select `API Catalog`, then search for `MaintainX API`.
3. Select `+ Add Datasource`.
4. Complete the connector fields.

| Field               | Required | Type     | Description                                                    |
| ------------------- | -------- | -------- | -------------------------------------------------------------- |
| **Name**            | Yes      | text     | Name that identifies this connection in KODE OS                |
| **Area**            | No       | dropdown | Area associated with the connection                            |
| **URL**             | Yes      | text     | MaintainX API base URL, such as `https://api.getmaintainx.com` |
| **API Key**         | Yes      | password | Static Bearer token generated in MaintainX                     |
| **Organization ID** | Yes      | dropdown | MaintainX organization to collect                              |
| **Location ID**     | Yes      | dropdown | Location within the selected organization                      |
| **Notes**           | No       | text     | Additional connection details                                  |

Multi-organization tokens require an organization header. KODE OS uses the organization selected on the connector.

## Discover devices and points

After you save the connector, select `Discover`. Review the returned assets and meter points, then save the records you want in KODE OS.

MaintainX meters without an associated asset are not available for discovery. One asset can contain multiple meter points.

For more details, see the [Discovery guide](/products/integrations/capabilities/discovery).

## Devices and points

Each MaintainX asset becomes a KODE OS device. The connector creates one point for each associated meter.

| Point               | Description                       | Unit                                   | Writable | Collection |
| ------------------- | --------------------------------- | -------------------------------------- | -------- | ---------- |
| `lastReading.value` | Most recent numeric meter reading | Unit configured on the MaintainX meter | No       | Polling    |

The MaintainX REST API provides the current reading only. It does not provide meter-reading history.

## What data you get

### Assets

Asset records include the name, location, manufacturer, model, status, external ID, parent, and description.

### Work orders

| KODE field      | MaintainX field             |
| --------------- | --------------------------- |
| **id**          | `id`                        |
| **woNumber**    | `sequentialId`              |
| **title**       | `title`                     |
| **description** | `description`               |
| **status**      | `status`                    |
| **priority**    | `priority`                  |
| **category**    | `type`                      |
| **asset**       | `asset.id` and `asset.name` |
| **location**    | `locationId`                |
| **assignedTo**  | `assignees.id`              |
| **dueDate**     | `dueDate`                   |
| **startedAt**   | `startDate`                 |
| **completedAt** | `completedAt`               |
| **createdAt**   | `createdAt`                 |
| **updatedAt**   | `updatedAt`                 |

Supported statuses include `OPEN`, `IN_PROGRESS`, `ON_HOLD`, `DONE`, `CANCELED`, and `SKIPPED`. Supported priorities include `NONE`, `LOW`, `MEDIUM`, and `HIGH`.

### Polling schedule

* **Current meter readings** — Approximately every 10 minutes

KODE OS stores a new meter value only when the reading date changes.

## Use cases

Once connected, you can:

* Monitor MaintainX asset status and current meter values
* Review work orders across locations
* Analyze maintenance status, priority, assignees, and due dates in KODE OS

## Troubleshooting

<AccordionGroup>
  <Accordion title="Authentication or connection error">
    Verify the API key is active. For a multi-organization token, confirm the connector uses the correct organization.
  </Accordion>

  <Accordion title="A meter is missing from discovery">
    Confirm the meter is associated with a MaintainX asset. Meters without an asset cannot become points on a KODE OS device.
  </Accordion>

  <Accordion title="Meter history is unavailable">
    MaintainX exposes only `lastReading` through this REST integration. KODE OS begins building history from the current values collected after connection.
  </Accordion>
</AccordionGroup>