---
title: "POST /jobs"
method: POST
path: "/jobs"
tags: ["Jobs"]
---

# POST /jobs

`POST /jobs`

Creates a new job. Supports two modes depending on whether `isDraft` is set:

**Non-draft job** (default, `isDraft` omitted or `false`):
All of `jobType`, `title`, `description`, `customerId`, and `siteId` are required. The job is created in an active state and assigned a job number immediately.

**Draft job** (`isDraft: true`):
Only `jobType` and `title` are required. `description`, `customerId`, and `siteId` are optional and can be filled in later via `PUT /jobs/:jobId`. A draft job does not receive a job number until it is finalised via `PUT /jobs/:jobId/finalise`.

**Job types** (`jobType`): `Quote`, `Estimate`, `Charge Up`

**Typical draft workflow:**
  1. `POST /jobs` with `isDraft: true` — create the draft

  2. `PUT /jobs/:jobId` — update fields (customer, site, description, etc.)
  
  3. `PUT /jobs/:jobId/finalise` — convert the draft to an active job

**Variation job** (`parentJobId` set): provide `parentJobId` to instead create a variation of an existing job:
- requires `jobType`
- inherits customer, site, contacts and budget from the parent
- `title`, `description` and `customerReference` are optional overrides
- always created finalised (non-draft)

## Request body

- object
  - `isDraft` boolean
  - `jobType` 'Quote' | 'Estimate' | 'Charge Up', required
  - `title` string
  - `description` string
  - `customerId` number
  - `customerReference` string
  - `siteId` number
  - `parentJobId` number — When provided, creates a variation of the job with this id as its parent. Only `jobType` is required; `title`, `description` and `customerReference` are optional and inherited from the parent when omitted.

## Response `201`

Resource created successfully

- JobResponse
  - `result` string, required
  - `data` Job, required
    - `id` number, required
    - `jobNo` string, nullable, required
    - `jobNumber` string, nullable, required
    - `description` string, nullable, required
    - `longDescription` string, nullable, required
    - `createdAt` string, date-time, required
    - `lastModified` string, date-time, nullable, required
    - `jobType` string, required
    - `status` string, required
    - `assignedGroups` string[], required — Default group assigned to a job for easy tracking. This gets assigned automatically by default on new job phases.
    - `customer` JobCustomer, required
      - `id` number, required
      - `customerFullName` string, nullable, required
    - `siteAddress` JobSiteAddress, required
      - `id` number, required
      - `name` string, nullable, required
      - `firstName` string, nullable, required
      - `lastName` string, nullable, required
      - `address1` string, nullable, required
      - `address2` string, nullable, required
      - `addressSuburb` string, nullable, required
      - `addressCity` string, nullable, required
      - `addressRegion` string, nullable, required
      - `addressCountry` string, nullable, required
      - `addressPostcode` string, nullable, required
    - `mainContact` object, nullable, required
      - `id` number, required
      - `firstName` string, nullable, required
      - `lastName` string, nullable, required
      - `contactItems` ContactItem[], nullable, required
        - `id` number, required
        - `contactType` 'email' | 'phone' | 'mobile' | 'other' | 'fax' | 'website', required — The type of this contact item. It can be one of the following: email, phone, mobile, other, fax, website
        - `contactValue` string, required — The value of this contact item.
    - `activeQuote` object, nullable, required
      - `id` number, required
      - `versionNumber` number, required
      - `guid` string, nullable, required
      - `title` string, nullable, required
      - `description` string, nullable, required
      - `quoteDate` string, date-time, nullable, required
      - `isSent` boolean, required
      - `isAccepted` boolean, required
      - `isSuperseded` boolean, required
      - `isLocked` boolean, required
      - `voidedAt` string, date-time, nullable, required
      - `declinedAt` string, date-time, nullable, required
      - `createdAt` string, date-time, required
      - `lastModified` string, date-time, required
      - `publishedAt` string, date-time, nullable, required
      - `dueDate` string, date-time, nullable, required
      - `dueDays` string, nullable, required
      - `isDraft` boolean, required
      - `total` number, nullable
    - `onHold` boolean, required
    - `archived` boolean, required
    - `customerReference` string, nullable, required
    - `parentJobId` number, nullable, required — The id of the parent job when this job is a variant, otherwise null.
    - `jobVariants` number[], nullable, required — The ids of the variant (child) jobs when this job is a parent job, otherwise null.
    - `links` Links[], required
      - `href` string, required
      - `rel` string, required
      - `type` 'GET' | 'POST' | 'PUT' | 'PATCH', required

## Other responses

- `4XX` — Client Request Errors
- `5XX` — Server Errors

---

[API](https://skmtc.dev/fergus/apis/fergus-api.md) · [All operations](https://skmtc.dev/fergus/apis/fergus-api/llms.txt) · [OpenAPI document](https://skmtc-service-production.skmtc.workers.dev/v1/apis/fergus/fergus-api/revisions/b4f232a22363/schema)