Inspections API — Create and Retrieve Field Inspections

Inspections are field records created when a technician inspects a piece of equipment at a site using a checklist template. Each inspection tracks its status through a review workflow and accumulates findings — discrete observations with severity ratings.

The inspections API requires the calso module to be enabled for your tenant. Requests made without the module active will return 403 Forbidden.

Inspection statuses

An inspection moves through the following lifecycle:

Status	Meaning
`draft`	Created, not yet submitted by the technician.
`submitted`	Submitted by the technician for review.
`in_review`	Under review by a coordinator or manager.
`approved`	Inspection approved.
`delivered`	Report delivered to the customer.
`rejected`	Returned to the technician for corrections.

Finding severities

Severity	Meaning
`imminent`	Requires immediate action; equipment should be taken out of service.
`serious`	Significant deficiency requiring prompt repair.
`minor`	Low-risk observation; should be addressed in routine maintenance.

List inspections

GET /api/inspections Returns a paginated list of inspections for the authenticated tenant.

Query parameters

string

Filter by inspection status. One of: draft, submitted, in_review, approved, delivered, rejected.

string

Filter by technician UUID. Returns inspections where the user is the lead technician or a team member.

string

Filter by company (customer) UUID.

string

Full-text search across company name, equipment type name, technician name, and serial number.

integer

default:"1"

1-based page index.

integer

default:"25"

Results per page. Maximum 100.

Response

{
  "data": [
    {
      "inspection": {
        "id": "e1b234cd-0001-4aaa-bbbb-ccccddddeeee",
        "status": "submitted",
        "inspectionDate": "2024-07-15",
        "overallResult": "conditional",
        "notes": "Customer was on-site during inspection.",
        "createdAt": "2024-07-15T08:00:00Z"
      },
      "equipment": {
        "id": "eq-uuid-001",
        "manufacturer": "Genie",
        "model": "S-65",
        "serialNumber": "GS65-001234"
      },
      "equipmentType": {
        "id": "type-uuid-001",
        "name": "Boom Lift",
        "category": "aerial"
      },
      "site": {
        "id": "site-uuid-001",
        "name": "Main Warehouse",
        "address": "123 Industrial Blvd",
        "city": "Austin",
        "state": "TX"
      },
      "customer": {
        "id": "cust-uuid-001",
        "name": "Acme Corp"
      },
      "technician": {
        "id": "user-uuid-001",
        "name": "Jordan Smith"
      },
      "findingCount": 3
    }
  ],
  "total": 47,
  "page": 1,
  "pageSize": 25
}

curl -X GET "https://app.novala.ai/api/inspections?status=submitted" \
  -H "Authorization: Bearer YOUR_API_KEY"

const response = await fetch(
  'https://app.novala.ai/api/inspections?status=submitted',
  { headers: { 'Authorization': `Bearer ${apiKey}` } }
);
const { data, total } = await response.json();

Get an inspection

GET /api/inspections/{id} Retrieves a full inspection record including equipment details, checklist template, findings with photos, and the technician team.

Path parameters

string

required

UUID of the inspection.

Response fields

object

Show Inspection object

string

UUID.

string

Current inspection status.

string

Date of inspection (YYYY-MM-DD).

string | null

One of pass, fail, conditional. Set during review.

array

Checklist item responses recorded by the technician.

string | null

Inspector notes.

string | null

URL of the customer’s signature image.

string | null

Reason for rejection, if status is rejected.

string

ISO 8601 creation timestamp.

string

ISO 8601 last-updated timestamp.

object

Equipment with id, manufacturer, model, serialNumber, ratedCapacity, status, nameplatePhotoUrl, locationLabel.

object

Equipment type with id, name, category, oshaStandard.

object

Site with id, name, address, city, state.

object

Company with id and name.

object

Lead technician with id, name, email.

object

Checklist template with id, name, and sections.

array

Show Finding object

string

UUID of the finding.

string

One of imminent, serious, minor.

string

Description of the deficiency.

string | null

Recommended corrective action.

string | null

Applicable OSHA standard reference.

string

Repair quote status: unquoted, quoted, accepted, declined, completed.

array

Array of photo objects with id, photoUrl, caption, photoType.

array

Array of team members with id, technicianId, role (lead or member), and name.

curl -X GET https://app.novala.ai/api/inspections/e1b234cd-0001-4aaa-bbbb-ccccddddeeee \
  -H "Authorization: Bearer YOUR_API_KEY"

const response = await fetch(
  'https://app.novala.ai/api/inspections/e1b234cd-0001-4aaa-bbbb-ccccddddeeee',
  { headers: { 'Authorization': `Bearer ${apiKey}` } }
);
const { inspection, findings, teamMembers } = await response.json();

Create an inspection

POST /api/inspections Creates a new inspection in draft status. The inspection is assigned to the authenticated user unless a technicianId (or technicianIds) is specified, which requires the Admin or Coordinator role.

Request body

string

required

UUID of the equipment to inspect.

string

required

UUID of the site where the inspection takes place.

string

required

UUID of the checklist template to use. Must belong to your tenant.

string

required

Date of inspection in YYYY-MM-DD format.

string

Pre-inspection notes.

string

UUID of the lead technician. Only honored when the caller has the system_admin or field_coordinator role.

array

Array of technician UUIDs. The first element is the lead; subsequent elements are team members. Takes precedence over technicianId.

Response

Returns 201 Created with the new inspection object (without nested relations). Initial status is always draft.

curl -X POST https://app.novala.ai/api/inspections \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "equipmentId": "eq-uuid-001",
    "siteId": "site-uuid-001",
    "checklistTemplateId": "tmpl-uuid-001",
    "inspectionDate": "2024-08-20",
    "technicianIds": ["user-uuid-001", "user-uuid-002"]
  }'

const response = await fetch('https://app.novala.ai/api/inspections', {
  method: 'POST',
  headers: {
    'Authorization': `Bearer ${apiKey}`,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    equipmentId: 'eq-uuid-001',
    siteId: 'site-uuid-001',
    checklistTemplateId: 'tmpl-uuid-001',
    inspectionDate: '2024-08-20',
    technicianIds: ['user-uuid-001', 'user-uuid-002'],
  }),
});
const inspection = await response.json(); // 201 Created

Overview

Endpoints

Inspections API — Create and Retrieve Field Inspections

Inspection statuses

Finding severities

List inspections

Query parameters

Response

Get an inspection

Path parameters

Response fields

Create an inspection

Request body

Response

​Inspection statuses

​Finding severities

​List inspections

​Query parameters

​Response

​Get an inspection

​Path parameters

​Response fields

​Create an inspection

​Request body

​Response

Inspection statuses

Finding severities

List inspections

Query parameters

Response

Get an inspection

Path parameters

Response fields

Create an inspection

Request body

Response