Jobs API

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

Job object

Every job returned by the API contains these fields:

List jobs

GET /api/v1/jobs

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

Query parameters

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-25T04:00:00-05:00",
      "scheduled_end": "2026-02-25T06:00:00-05:00",
      "actual_start": null,
      "actual_end": null,
      "created_at": "2026-02-24T09:30:00-05:00",
      "updated_at": "2026-02-24T09:30:00-05:00"
    }
  ],
  "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-25T04:00:00-05:00",
    "scheduled_end": "2026-02-25T06:00:00-05:00",
    "actual_start": null,
    "actual_end": null,
    "created_at": "2026-02-24T09:30:00-05:00",
    "updated_at": "2026-02-24T09:30:00-05:00"
  },
  "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

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-25T04:00:00-05:00",
    "scheduled_end": "2026-02-25T06:00:00-05:00",
    "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-24T09:30:00-05:00"
  },
  "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]
  }'

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, and a status change made through the API has the same effects as one made in the app: the customer gets the same emails (cancellation, rescheduling, completion, and the on-the-way and arrival emails where your plan includes them), your team gets the same alerts, completion records the job's measured duration and SLA result, and the change is written to the audit log. The API key acts as your company, so these records name no individual user.

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"}'

Completing a job

Setting job_status to Completed needs a final_comment: a short note on the work done, which appears on the invoice. It can be up to 500 characters (characters such as & and < count as more than one). The job is only completed when all three checks pass, in this order:

1. Final comment. Missing or empty returns 400 final_comment_required; too long returns 400 comment_too_long.
2. Required forms. If a form the job needs is not submitted yet, you get 409 job_forms_incomplete. The missing list names each form (response_id, form_name) and the keys of its unanswered items (missing_items). Submit the forms in the app, then retry. The API cannot skip this check.
3. Required custom fields. If a field marked required to complete the job is empty, you get 422 custom_fields_required. The missing list names each field (field_key, field_name). Fill them in with PUT and custom_fields, then retry.

A refused completion changes nothing: the job keeps its status.

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": "Completed", "final_comment": "Replaced the capacitor and tested the unit."}'

{
  "success": false,
  "error": "custom_fields_required",
  "message": "Fill in the required fields before completing this job.",
  "missing": [
    {"field_key": "gate_code", "field_name": "Gate code"}
  ]
}

Putting a job on hold

Setting job_status to On-Hold needs a reason, the same one your team picks in the app. Send hold_reason_key and, if you like, a hold_reason_note of up to 500 characters.

The built-in reasons are:

Your company can rename or hide reasons and add its own in Company Settings; a hidden reason is refused.

Listing your company's hold reasons

GET /api/v1/jobs?sub=hold-reasons returns the reasons your company offers right now, in the order your team sees them in the app: the built-in reasons (under your company's names), your own reasons, then other. Hidden reasons are left out. It needs the jobs:read scope.

curl "https://fsmnavigator.com/api/v1/jobs?sub=hold-reasons" \
  -H "X-API-Key: YOUR_API_KEY"

{
  "data": [
    { "hold_reason_key": "waiting_on_parts", "hold_reason_label": "Waiting on parts", "requires_note": false },
    { "hold_reason_key": "custom_3f9a1c2b7d", "hold_reason_label": "Permit pending", "requires_note": false },
    { "hold_reason_key": "other", "hold_reason_label": "Other", "requires_note": true }
  ],
  "request_id": "8f2c41d09a7e4b6c9d3e5f1a2b7c6d40e9f1"
}

Any other sub value, or sub together with id, returns 400 invalid_sub.

A refused hold changes nothing. Once the job is on hold, GET /api/v1/jobs?id={id} returns the reason in hold_reason_key, hold_reason_label and hold_reason_note. Sending On-Hold for a job that is already on hold changes nothing, including its reason.

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": "On-Hold", "hold_reason_key": "waiting_on_parts", "hold_reason_note": "Compressor on back order"}'

Example response

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

Custom fields

Job custom fields are the extra fields your company adds to jobs, such as a gate code or a PO number. Every job you read returns them in custom_fields. To write them, send a custom_fields object on create or update, keyed by each field's key.

If any value is refused (a key that is not one of your fields, a value of the wrong type, or a required field left out when creating), the whole request is refused with 400 custom_field_invalid and nothing is written. The errors object names each field key and what is wrong with it:

{
  "success": false,
  "error": "custom_field_invalid",
  "message": "Some custom fields need attention.",
  "errors": {
    "po_number": "PO number is required."
  }
}

SLA deadlines

Every job carries an SLA deadline in due_at — the date and time the work is measured against. It is what puts a job in the right place on the dispatch board, what drives the reminders your team gets as the date approaches, and what decides whether the job counts as on time when it is finished. A job with no deadline would sit outside all three, so the API does not let one exist.

On create, due_at is optional. Send one and it is stored exactly as you sent it. Leave it out and we work one out for you, in this order:

1. The customer's own response time (default_sla_hours on the customer record), reached through the location the job is at.
2. Your company's default response time, from Settings → Company Settings.
3. 24 hours.

Those hours count on every day your company is open, all day, and skip the days it is closed (the days marked closed in your business hours — Saturday and Sunday if you have never changed them — and any closed dates on your booking page). If every day is marked closed, every day counts. A due_at you send is stored as sent.

On update, you can move the deadline but not remove it. See the note under Update a job.

Explicit nulls

Create and update answer an explicit "due_at": null differently, and the difference is deliberate — they are being asked different questions.

On create there is no deadline yet, so an empty value can only mean pick one for me — there is nothing there to remove. On update there already is one, so the same empty value reads as take it away, and a job with no deadline is the one thing the API will not leave behind.

This catches out integrations that build a request body by filling every field they know about and setting the rest to null. That style creates jobs without complaint and then starts returning 400 the first time it updates one. The fix is to leave due_at out of the update body rather than sending it empty — an omitted field is never changed.

A due_at that is present but is not a valid ISO 8601 datetime is a different error on both endpoints: 400 Bad Request with invalid_date_format.

Valid statuses

Jobs can have one of nine statuses:

Status transitions

Assets on jobs

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

Link assets on creation

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

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-25T09:30:00-05:00"
      }
    ]
  }
}

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": []}'

A PUT that changes the linked assets counts as a job update, even when no other field changes. The job's version goes up by one, and your job.updated webhook subscribers are notified. If the list you send matches the job's current links, nothing is written and version stays the same. You can include expected_version here too: if the job changed since you read it, you get 409 conflict and nothing is written.

Error responses

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

Related guides

• Endpoints overview — all available endpoints
• Authentication — API key setup
• Customers API — manage customer records
• Rate limits — request throttling
• Jobs overview — managing jobs from the web dashboard
• Assets API — manage asset records