MaintainX Hello World

Overview

Create your first work order using the MaintainX REST API - the core building block of CMMS operations.

Prerequisites

Completed maintainx-install-auth setup
Valid API credentials configured
Development environment ready

Instructions

Step 1: List Existing Work Orders (Read)

First, verify your connection by listing existing work orders:

# Using curl
curl -X GET "https://api.getmaintainx.com/v1/workorders?limit=5" \
  -H "Authorization: Bearer $MAINTAINX_API_KEY" \
  -H "Content-Type: application/json"

Expected response:

{
  "workOrders": [
    {
      "id": "wo_123456",
      "title": "Weekly Equipment Inspection",
      "status": "OPEN",
      "priority": "MEDIUM",
      "createdAt": "2025-01-15T10:30:00Z"
    }
  ],
  "nextCursor": "eyJpZCI6MTIzNDU2fQ=="
}

Step 2: Create Your First Work Order

// hello-maintainx.ts
import { MaintainXClient } from './maintainx/client';

async function createFirstWorkOrder() {
  const client = new MaintainXClient();

  // Create a simple work order
  const workOrder = await client.createWorkOrder({
    title: 'Hello World - Test Work Order',
    description: 'This is my first work order created via the API!',
    priority: 'LOW',
  });

  console.log('Work order created successfully!');
  console.log('ID:', workOrder.data.id);
  console.log('Title:', workOrder.data.title);
  console.log('Status:', workOrder.data.status);

  return workOrder.data;
}

createFirstWorkOrder().catch(console.error);

Step 3: Create Work Order with Asset Assignment

// create-maintenance-task.ts
import { MaintainXClient } from './maintainx/client';

async function createMaintenanceTask() {
  const client = new MaintainXClient();

  // First, get an asset to assign
  const assetsResponse = await client.getAssets({ limit: 1 });
  const asset = assetsResponse.data.assets[0];

  // Get a location
  const locationsResponse = await client.getLocations({ limit: 1 });
  const location = locationsResponse.data.locations[0];

  // Create work order with full context
  const workOrder = await client.createWorkOrder({
    title: 'Quarterly HVAC Filter Replacement',
    description: `
      Maintenance Task:
      1. Turn off HVAC unit
      2. Remove old filter
      3. Install new filter (size: 20x25x1)
      4. Turn on unit and verify operation
      5. Log meter reading
    `,
    priority: 'MEDIUM',
    assetId: asset?.id,
    locationId: location?.id,
    dueDate: new Date(Date.now() + 7 * 24 * 60 * 60 * 1000).toISOString(), // 7 days from now
  });

  console.log('Maintenance task created:');
  console.log(JSON.stringify(workOrder.data, null, 2));

  return workOrder.data;
}

createMaintenanceTask().catch(console.error);

Step 4: Full CRUD Example

// crud-example.ts
import { MaintainXClient } from './maintainx/client';

async function workOrderCrudExample() {
  const client = new MaintainXClient();

  // CREATE
  console.log('Creating work order...');
  const created = await client.createWorkOrder({
    title: 'API Test - CRUD Demo',
    description: 'Testing full lifecycle',
    priority: 'LOW',
  });
  console.log('Created:', created.data.id);

  // READ
  console.log('\nReading work order...');
  const read = await client.getWorkOrder(created.data.id);
  console.log('Read:', read.data.title);

  // LIST with filtering
  console.log('\nListing open work orders...');
  const list = await client.getWorkOrders({
    status: 'OPEN',
    limit: 10
  });
  console.log('Found', list.data.workOrders.length, 'open work orders');

  // Note: Update and Delete operations depend on your plan tier
  // and may require additional endpoints

  return { created: created.data, read: read.data, list: list.data };
}

workOrderCrudExample().catch(console.error);

Python Example

# hello_maintainx.py
from maintainx_client import MaintainXClient
from datetime import datetime, timedelta

def main():
    client = MaintainXClient()

    # List existing work orders
    print("Fetching existing work orders...")
    work_orders = client.get_work_orders(limit=5)
    print(f"Found {len(work_orders.get('workOrders', []))} work orders")

    # Create new work order
    print("\nCreating new work order...")
    new_wo = client.create_work_order({
        "title": "Hello World - Python API Test",
        "description": "Created via Python MaintainX client",
        "priority": "LOW",
        "dueDate": (datetime.now() + timedelta(days=7)).isoformat() + "Z"
    })

    print(f"Created work order: {new_wo['id']}")
    print(f"Title: {new_wo['title']}")
    print(f"Status: {new_wo['status']}")

if __name__ == "__main__":
    main()

Output

Working code file with MaintainX client usage
Successfully created work order in your MaintainX account
Console output showing:

Work order created successfully!
ID: wo_789012
Title: Hello World - Test Work Order
Status: OPEN

Error Handling

| Error | Cause | Solution | |-------|-------|----------| | 400 Bad Request | Missing required fields | Include at least title field | | 401 Unauthorized | Invalid API key | Check MAINTAINX_API_KEY environment variable | | 403 Forbidden | Plan limitations | Verify API access on your subscription | | 422 Unprocessable | Invalid field values | Check enum values (priority, status) |

Common Field Values

Work Order Priority

NONE - No priority set
LOW - Low priority
MEDIUM - Medium priority
HIGH - High priority

Work Order Status

OPEN - New, not started
IN_PROGRESS - Work underway
ON_HOLD - Paused/waiting
DONE - Completed

Resources

Next Steps

Proceed to maintainx-local-dev-loop for development workflow setup.