List Work Orders

The List Work Orders endpoint allows you to retrieve a paginated list of work orders with powerful filtering and search capabilities.

Endpoint

GET /api/v1/external/workorders/

Full URL: https://app.centroaccess.com/api/v1/external/workorders/

Authentication

Requires API key with view_workorder permission.

Authorization: Api-Key your-api-key-here

Query Parameters

Parameter	Type	Required	Description	Example
status	string	No	Filter by work order status	dispatch, in_progress, completed
priority	string	No	Filter by priority level	low, medium, high, urgent
service_category	string	No	Filter by service category	installation, survey, mdu
assigned_team	UUID	No	Filter by assigned team	550e8400-e29b-41d4-a716-446655440000
service_zone	UUID	No	Filter by service zone	660e8400-e29b-41d4-a716-446655440001
from_date	ISO datetime	No	Work orders created after this date	2025-10-01 or 2025-10-01T10:00:00Z
to_date	ISO datetime	No	Work orders created before this date	2025-10-31 or 2025-10-31T23:59:59Z
page	integer	No	Page number (default: 1)	1, 2, 3
page_size	integer	No	Results per page (default: 50, max: 100)	20, 50, 100

Response Format

Success Response (200 OK)

{
  "count": 150,
  "next": "/api/v1/external/workorders/?page=2&page_size=20",
  "previous": null,
  "results": [
    {
      "id": "550e8400-e29b-41d4-a716-446655440000",
      "title": "Install fiber connection",
      "client_name": "John Doe",
      "client_contact": "+1234567890",
      "status": "dispatch",
      "status_display": "Dispatch",
      "priority": "high",
      "priority_display": "High",
      "service_category": "installation",
      "service_category_display": "Installation",
      "due_date": "2025-12-31",
      "created_at": "2025-10-23T10:00:00Z",
      "updated_at": "2025-10-23T10:00:00Z",
      "service_zone": {
        "id": "660e8400-e29b-41d4-a716-446655440001",
        "name": "Downtown Area"
      },
      "assigned_team": {
        "id": "770e8400-e29b-41d4-a716-446655440002",
        "name": "Installation Team A"
      }
    }
    // ... more work orders
  ]
}

Response Fields

Field	Type	Description
count	integer	Total number of work orders matching filters
next	string/null	URL for next page of results
previous	string/null	URL for previous page of results
results	array	Array of work order objects

Work Order Object Fields

Field	Type	Description
id	UUID	Unique work order identifier
title	string	Work order title
client_name	string	Customer/client name
client_contact	string	Client phone number
status	string	Current status code
status_display	string	Human-readable status
priority	string	Priority level code
priority_display	string	Human-readable priority
service_category	string	Service category code
service_category_display	string	Human-readable category
due_date	string/null	Due date (YYYY-MM-DD)
created_at	string	Creation timestamp (ISO format)
updated_at	string	Last update timestamp (ISO format)
service_zone	object/null	Service zone information
assigned_team	object/null	Assigned team information

Examples

Basic Request

List all work orders (first 50 results):

curl -X GET "https://app.centroaccess.com/api/v1/external/workorders/" \
  -H "Authorization: Api-Key your-api-key-here"

Filter by Status

Get all work orders in "dispatch" status:

curl -X GET "https://app.centroaccess.com/api/v1/external/workorders/?status=dispatch" \
  -H "Authorization: Api-Key your-api-key-here"

Filter by Priority and Service Category

Get high-priority installation work orders:

curl -X GET "https://app.centroaccess.com/api/v1/external/workorders/?priority=high&service_category=installation" \
  -H "Authorization: Api-Key your-api-key-here"

Date Range Filter

Get work orders created in the last 7 days:

curl -X GET "https://app.centroaccess.com/api/v1/external/workorders/?from_date=2025-10-17&to_date=2025-10-24" \
  -H "Authorization: Api-Key your-api-key-here"

Pagination

Get the second page with 20 results per page:

curl -X GET "https://app.centroaccess.com/api/v1/external/workorders/?page=2&page_size=20" \
  -H "Authorization: Api-Key your-api-key-here"

Combined Filters

Complex query with multiple filters:

curl -X GET "https://app.centroaccess.com/api/v1/external/workorders/?status=dispatch&priority=high&service_category=installation&page=1&page_size=10" \
  -H "Authorization: Api-Key your-api-key-here"

Status Values

Work orders can have the following status values:

Status	Description
dispatch	Initial state, waiting to be assigned
assigned	Assigned to a team
resource_enroute	Team is on the way
inspection	Under inspection
submitted	Submitted for review
in_progress	Work is being performed
on_hold	Temporarily paused
pending_review	Waiting for review
review_sales	Sales review required
review_service	Service review required
completed	Work completed successfully
cancelled	Work order cancelled

Priority Values

Priority	Description
low	Low priority
medium	Medium priority (default)
high	High priority
urgent	Urgent priority

Service Categories

Category	Description
survey	Survey work
installation	Installation work
mdu	Multi-dwelling unit work
service_provider	Service provider work
extension	Extension work
transmission	Transmission work
construction	Construction work
review	Review work
support	Support work
relocation	Relocation work
equipment_recovery	Equipment recovery

Error Responses

Invalid Filter Value

Status Code: 400 Bad Request

{
  "error": "Invalid status value",
  "details": "Status 'invalid_status' is not a valid choice."
}

Invalid Date Format

Status Code: 400 Bad Request

{
  "error": "Invalid from_date format. Use ISO format (YYYY-MM-DD or YYYY-MM-DDTHH:MM:SS)"
}

Authentication Required

Status Code: 401 Unauthorized

{
  "detail": "Invalid API key"
}

Insufficient Permissions

Status Code: 403 Forbidden

{
  "error": "Insufficient permissions",
  "required_permission": "workorder.view_workorder"
}

Code Examples

Python

import requests
from datetime import datetime, timedelta

API_KEY = "your-api-key-here"
BASE_URL = "https://app.centroaccess.com/api/v1/external"

headers = {
    "Authorization": f"Api-Key {API_KEY}",
    "Content-Type": "application/json"
}

def list_work_orders(status=None, priority=None, page_size=50):
    """List work orders with optional filtering."""
    params = {"page_size": page_size}
    
    if status:
        params["status"] = status
    if priority:
        params["priority"] = priority
    
    response = requests.get(
        f"{BASE_URL}/workorders/",
        headers=headers,
        params=params
    )
    
    if response.status_code == 200:
        data = response.json()
        print(f"Total work orders: {data['count']}")
        
        for wo in data['results']:
            print(f"- {wo['title']} ({wo['status']}) - {wo['priority']} priority")
        
        return data
    else:
        print(f"Error: {response.status_code} - {response.text}")
        return None

def get_recent_work_orders(days=7):
    """Get work orders created in the last N days."""
    from_date = (datetime.now() - timedelta(days=days)).strftime('%Y-%m-%d')
    
    params = {
        "from_date": from_date,
        "page_size": 100
    }
    
    response = requests.get(
        f"{BASE_URL}/workorders/",
        headers=headers,
        params=params
    )
    
    if response.status_code == 200:
        data = response.json()
        print(f"Work orders created in last {days} days: {data['count']}")
        return data['results']
    else:
        print(f"Error: {response.status_code} - {response.text}")
        return []

# Usage examples
list_work_orders(status="dispatch", priority="high")
recent_orders = get_recent_work_orders(days=3)

JavaScript/Node.js

const axios = require('axios');

const API_KEY = 'your-api-key-here';
const BASE_URL = 'https://app.centroaccess.com/api/v1/external';

const headers = {
  'Authorization': `Api-Key ${API_KEY}`,
  'Content-Type': 'application/json'
};

async function listWorkOrders(filters = {}) {
  try {
    const response = await axios.get(
      `${BASE_URL}/workorders/`,
      {
        headers,
        params: {
          page_size: 50,
          ...filters
        }
      }
    );
    
    console.log(`Total work orders: ${response.data.count}`);
    
    response.data.results.forEach(wo => {
      console.log(`- ${wo.title} (${wo.status}) - ${wo.priority} priority`);
    });
    
    return response.data;
  } catch (error) {
    console.error('Error listing work orders:', error.response?.data || error.message);
    return null;
  }
}

async function getWorkOrdersByTeam(teamId) {
  return await listWorkOrders({
    assigned_team: teamId,
    status: 'assigned'
  });
}

async function getHighPriorityOrders() {
  return await listWorkOrders({
    priority: 'high',
    status: 'dispatch'
  });
}

// Usage examples
listWorkOrders({ status: 'dispatch' });
getHighPriorityOrders();
getWorkOrdersByTeam('550e8400-e29b-41d4-a716-446655440000');

Best Practices

1. Use Pagination

Always use pagination for large datasets:

# Good: Specify page size
curl "https://app.centroaccess.com/api/v1/external/workorders/?page_size=20"

# Avoid: Requesting all results at once
curl "https://app.centroaccess.com/api/v1/external/workorders/?page_size=10000"

2. Filter Results

Use filters to reduce response size and improve performance:

# Good: Filter by status and date range
curl "https://app.centroaccess.com/api/v1/external/workorders/?status=dispatch&from_date=2025-10-01"

# Less efficient: Get all results and filter client-side
curl "https://app.centroaccess.com/api/v1/external/workorders/"

3. Handle Pagination

Process all pages when dealing with large datasets:

def get_all_work_orders():
    all_orders = []
    page = 1
    
    while True:
        response = requests.get(
            f"{BASE_URL}/workorders/",
            headers=headers,
            params={"page": page, "page_size": 100}
        )
        
        if response.status_code != 200:
            break
            
        data = response.json()
        all_orders.extend(data['results'])
        
        if not data['next']:
            break
            
        page += 1
    
    return all_orders

4. Cache Results

Cache results when appropriate to reduce API calls:

import time

class WorkOrderCache:
    def __init__(self, ttl=300):  # 5 minute TTL
        self.cache = {}
        self.ttl = ttl
    
    def get_work_orders(self, filters=None):
        cache_key = str(filters) if filters else "all"
        now = time.time()
        
        if cache_key in self.cache:
            cached_data, timestamp = self.cache[cache_key]
            if now - timestamp < self.ttl:
                return cached_data
        
        # Fetch fresh data
        data = list_work_orders(**(filters or {}))
        self.cache[cache_key] = (data, now)
        return data

Next Steps

• Create Work Order → Learn to create new work orders
• Get Work Order Details → Retrieve detailed work order information
• Authentication → Review API key setup and permissions