Skip to content

Jobs API

Enterprise feature

The REST API is available on Enterprise plans. Compare plans to find the right fit for your team.

The Jobs API lets you create, retrieve, update, and manage field service jobs programmatically. Use it to sync jobs with external systems, automate workflows, or build custom dashboards.

Endpoints summary

Method Path Scope Description
GET /api/v1/jobs jobs:read List jobs
GET /api/v1/jobs?id={id} jobs:read Get a single job
POST /api/v1/jobs jobs:write Create a job
PUT /api/v1/jobs?id={id} jobs:write Update a job
PATCH /api/v1/jobs?id={id} jobs:write Update job status

Job object

Every job returned by the API contains these fields:

Field Type Description
job_id integer Unique job identifier
job_title string Short description of the work
job_description string Detailed notes for the technician
job_status string Current status (see Valid statuses)
job_priority string Low, Medium, High, or Urgent
assigned_technician_id integer ID of the assigned technician, or null
assigned_technician_name string Full name of the assigned technician, or null
customer_location_id integer ID of the service location
customer_location_name string Name of the service location
customer_id integer ID of the customer
customer_name string Name of the customer
scheduled_start string Scheduled start time (ISO 8601), or null
scheduled_end string Scheduled end time (ISO 8601), or null
actual_start string Actual start time, or null
actual_end string Actual end time, or null
created_at string When the job was created (ISO 8601)
updated_at string When the job was last updated (ISO 8601)
assets array Linked assets (Enterprise only). See Assets on jobs

List jobs

GET /api/v1/jobs

Returns a paginated list of jobs. Use query parameters to filter results.

Query parameters

Parameter Type Description
status string Filter by status (see Valid statuses)
priority string Filter by priority: Low, Medium, High, Urgent
assigned_technician_id integer Filter by assigned technician
customer_location_id integer Filter by customer location
created_after string Jobs created on or after this date (ISO 8601 format)
created_before string Jobs created on or before this date (ISO 8601 format)
page integer Page number (default: 1)
per_page integer Results per page (default: 50, max: 100)

Example request

curl -X GET "https://fsmnavigator.com/api/v1/jobs?status=Pending&priority=High" \
  -H "X-API-Key: YOUR_API_KEY"

Example response

{
  "data": [
    {
      "job_id": 123,
      "job_title": "AC unit repair",
      "job_description": "Customer reports AC not cooling in main office",
      "job_status": "Pending",
      "job_priority": "High",
      "assigned_technician_id": null,
      "assigned_technician_name": null,
      "customer_location_id": 87,
      "customer_location_name": "Main Office",
      "customer_id": 201,
      "customer_name": "Acme Corporation",
      "scheduled_start": "2026-02-25T09:00:00Z",
      "scheduled_end": "2026-02-25T11:00:00Z",
      "actual_start": null,
      "actual_end": null,
      "created_at": "2026-02-24T14:30:00Z",
      "updated_at": "2026-02-24T14:30:00Z"
    }
  ],
  "pagination": {
    "page": 1,
    "per_page": 50,
    "total": 1,
    "total_pages": 1
  },
  "request_id": "a1b2c3d4e5f6"
}

Get a single job

GET /api/v1/jobs?id={id}

Retrieves full details for one job.

Example request

curl -X GET "https://fsmnavigator.com/api/v1/jobs?id=123" \
  -H "X-API-Key: YOUR_API_KEY"

Example response

{
  "data": {
    "job_id": 123,
    "job_title": "AC unit repair",
    "job_description": "Customer reports AC not cooling in main office",
    "job_status": "Pending",
    "job_priority": "High",
    "assigned_technician_id": 45,
    "assigned_technician_name": "John Smith",
    "customer_location_id": 87,
    "customer_location_name": "Main Office",
    "customer_id": 201,
    "customer_name": "Acme Corporation",
    "scheduled_start": "2026-02-25T09:00:00Z",
    "scheduled_end": "2026-02-25T11:00:00Z",
    "actual_start": null,
    "actual_end": null,
    "created_at": "2026-02-24T14:30:00Z",
    "updated_at": "2026-02-24T14:30:00Z"
  },
  "request_id": "a1b2c3d4e5f6"
}

Create a job

POST /api/v1/jobs

Creates a new job and returns the created record. Returns 201 Created on success.

Request body

Field Type Required Description
job_title string Yes Short description of the work
job_description string No Detailed notes for the technician
job_priority string No Low, Medium (default), High, or Urgent
customer_location_id integer Yes ID of the customer location
assigned_technician_id integer No Assign to a specific technician
scheduled_start string No Scheduled start time (ISO 8601)
scheduled_end string No Scheduled end time (ISO 8601)
asset_ids array of integers No IDs of assets to link (Enterprise only)
asset_relationship_type string No Relationship type: serviced (default), installed, replaced, inspected, maintenance, or meter_threshold

Example request

curl -X POST "https://fsmnavigator.com/api/v1/jobs" \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "job_title": "AC unit repair",
    "job_description": "Customer reports AC not cooling in main office",
    "job_priority": "High",
    "customer_location_id": 87,
    "assigned_technician_id": 45,
    "scheduled_start": "2026-02-25T09:00:00Z",
    "scheduled_end": "2026-02-25T11:00:00Z",
    "asset_ids": [42, 67]
  }'

Example response

{
  "success": true,
  "message": "Job created successfully",
  "data": {
    "job_id": 123,
    "job_title": "AC unit repair",
    "job_status": "Pending",
    "created_at": "2026-02-24T14:30:00Z"
  },
  "request_id": "a1b2c3d4e5f6"
}

Update a job

PUT /api/v1/jobs?id={id}

Updates one or more fields on an existing job.

Example request

curl -X PUT "https://fsmnavigator.com/api/v1/jobs?id=123" \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "job_priority": "Urgent",
    "job_description": "Customer reports no cooling — escalated to urgent",
    "asset_ids": [42, 67, 103]
  }'

Syncing asset links

Passing asset_ids on a PUT replaces all current asset links. Pass "asset_ids": [] to remove every link.

Example response

{
  "success": true,
  "message": "Job updated successfully",
  "data": {
    "job_id": 123,
    "job_title": "AC unit repair",
    "job_status": "Pending"
  },
  "request_id": "a1b2c3d4e5f6"
}

Update job status

PATCH /api/v1/jobs?id={id}

Changes only the status of a job. The API enforces valid status transitions.

Example request

curl -X PATCH "https://fsmnavigator.com/api/v1/jobs?id=123" \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"job_status": "Assigned"}'

Example response

{
  "success": true,
  "message": "Job status updated to Assigned",
  "data": {
    "job_id": 123,
    "job_status": "Assigned",
    "previous_status": "Pending"
  },
  "request_id": "a1b2c3d4e5f6"
}

Valid statuses

Jobs can have one of nine statuses:

Status Description
Pending Job created, awaiting assignment
Assigned Technician assigned, not yet started
In Progress Technician actively working on the job
On Hold Job temporarily paused
Completed Work finished by the technician
Invoiced Invoice generated for the completed work
Paid Customer payment received
Closed Job fully closed out (terminal)
Cancelled Job cancelled before completion (terminal)

Status transitions

From Allowed transitions
Pending Assigned, Cancelled
Assigned In Progress, Pending, Cancelled, On Hold
In Progress Completed, Assigned, On Hold, Cancelled
On Hold In Progress, Assigned, Cancelled
Completed Invoiced
Invoiced Paid
Paid Closed
Cancelled (terminal — no further transitions)
Closed (terminal — no further transitions)

Invalid transitions return an error

If you attempt an invalid transition (e.g., Pending → Completed), the API returns 400 Bad Request with a descriptive error message.

Assets on jobs

Enterprise feature

Asset linking requires the Asset Management module on Enterprise plans.

When creating or updating a job, you can link it to one or more assets. Linked assets appear in the detail response.

Include asset_ids in the POST body:

curl -X POST "https://fsmnavigator.com/api/v1/jobs" \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "job_title": "Replace compressor on Unit #7",
    "customer_location_id": 87,
    "asset_ids": [42, 67],
    "asset_relationship_type": "serviced"
  }'

Relationship types

Type Description
serviced General service or repair (default)
installed New asset installation
replaced Asset being replaced
inspected Routine inspection
maintenance Scheduled maintenance
meter_threshold Triggered by meter reading threshold

Assets in job response

When retrieving a single job, linked assets appear in the assets array:

{
  "data": {
    "job_id": 123,
    "job_title": "Replace compressor on Unit #7",
    "assets": [
      {
        "asset_id": 42,
        "asset_tag": "HVAC-007",
        "asset_name": "Rooftop AC Unit #7",
        "asset_status": "In Maintenance",
        "relationship_type": "serviced",
        "relationship_notes": null,
        "linked_at": "2026-02-25T14:30:00Z"
      }
    ]
  }
}

Update linked assets

Use PUT to sync the asset list. This replaces all current links:

curl -X PUT "https://fsmnavigator.com/api/v1/jobs?id=123" \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"asset_ids": [42, 67, 103]}'

Pass an empty array to remove all links:

curl -X PUT "https://fsmnavigator.com/api/v1/jobs?id=123" \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"asset_ids": []}'

Asset validation

Each asset ID is verified against your company's asset inventory. Invalid or deleted asset IDs are silently skipped.

Error responses

See Error codes for the full reference. Common job-specific errors:

HTTP code Error Description
400 validation_failed Missing required fields or invalid values
404 not_found Job ID does not exist
400 invalid_status_transition The requested status change is not allowed