Jobs

Creates a job (estimate or draft) for a customer, optionally with material, labor and custom-charge lines.

Same code path as the MVC "Create job" page. Requires an Idempotency-Key header. Line totals are computed on the server from the lines you send. The job number is generated when omitted. Initial status: Estimated, or Draft when isDraft is true, unless statusId / statusKey names one of the organization's statuses. publishImmediately: true is the "Create & Publish" button: the job is created as a Draft and published in the same call under the rules of POST /api/v1/jobs/{id}/finalize; when it cannot be published yet it is still created as a Draft and the response's warning says why (never a 4xx for an unpublishable-but-created job). The write is attributed to the user who created the key.

post/api/v1/jobs

Request

  • Base URL: https://app.flexonthejob.com
  • URL: https://app.flexonthejob.com/api/v1/jobs
  • Auth: HTTP bearer

Request body

customerIdinteger required

Customer the job is for (must belong to the key's organization).

customerAddressIdinteger nullable

Optional site address id; must belong to customerId.

jobNumberstring nullable

Optional job number. Omit to have one generated; a duplicate is suffixed to stay unique.

jobTypestring

Free-text job type, e.g. Installation (default), Repair, Service.

descriptionstring nullable

Short description of the work, shown in lists. ≤ 500 characters. Example: Replace water heater.

notesstring nullable

Free-form internal notes (not shown to the customer). No length limit.

isDraftboolean

Save as a draft (status Draft) instead of an estimate. Ignored when statusId / statusKey is given.

publishImmediatelyboolean

Create and publish in one call — the "Create & Publish" button. The job starts as a Draft and is then published exactly as POST /api/v1/jobs/{id}/finalize would (needs at least one charge and a unit price on every material line), landing on Estimated, or Scheduled when scheduledDate is given. When it cannot be published yet the job is still created as a Draft (201) and warning on the response says why. Takes precedence over isDraft; 400 when statusId / statusKey names a non-Draft status. Default false.

statusIdinteger nullable

Initial status definition id (one of the org's statuses). Mutually exclusive with statusKey.

statusKeystring nullable

Initial status by name — a status definition name (case-insensitive) or a system status key such as Draft, Estimated, Scheduled. Mutually exclusive with statusId.

scheduledDatestring date-time nullable

Scheduled start as the organization's local wall clock, yyyy-MM-ddTHH:mm:ss with no UTC offset (the date-time format here is a local time, not RFC 3339 with zone); a trailing Z is converted to local time. Example: 2026-09-08T08:30:00.

estimateChecklistTemplateIdinteger nullable

Optional id of one of the organization's estimate pre-inspection checklist templates; its sections and items are copied onto the job.

Response

The created job (same shape as GET /api/v1/jobs/{id}, plus warning when a requested publish did not happen); Location points at it.

idinteger

Numeric id used in /api/v1/jobs/{id}. Unique within this organization. Example: 1042.

syncIdstring uuid

Stable cross-device identifier (GUID) — also the pagination cursor value. Example: 3f2504e0-4f89-11d3-9a0c-0305e82c3301.

jobNumberstring

Human-readable job number shown to staff and customers. Example: J-2026-0042.

jobTypestring nullable

Free-text job category configured by the organization. Example: Installation, Repair.

statusstring

Workflow status name. One of Draft, InspectionInProgress, Estimated, AwaitingOptionSelection, Scheduled, InProgress, Completed, Invoiced, Paid, Cancelled, Outstanding.

statusNamestring

Display label of the status as the organization has customised it (falls back to status). Example: On Site.

paymentStatusstring nullable

Payment state, independent of workflow status: Unpaid, Partial, Paid, Overpaid or Refunded.

customerIdinteger

Id of the customer the job is for (see /api/v1/customers/{id}).

customerNamestring

Customer display name at read time. Example: Acme Property Management.

descriptionstring nullable

Short description of the work. May be null for drafts.

createdAtstring date-time

When the job was created, ISO-8601 UTC. Example: 2026-09-01T14:03:22Z.

updatedAtstring date-time

Last modification time, ISO-8601 UTC (creation time when never modified). Use with the updatedSince filter to poll for changes.

scheduledDatestring date-time nullable

Scheduled start as the organization's local wall-clock time with no UTC offset (the date-time format here is a local time, not RFC 3339 with zone), e.g. 2026-09-08T08:30:00. Null when unscheduled.

scheduledDurationMinutesinteger nullable

Planned duration in minutes (default 120 when scheduled without an explicit duration). Null when unscheduled.

startDatestring date-time nullable

When work actually started, ISO-8601 UTC. Null until the job is in progress.

completedDatestring date-time nullable

When work was completed, ISO-8601 UTC. Null until completed.

totalPricenumber double

Customer price before tax, after the job-level discount, in the organization's currency (decimal, e.g. 1250.00).

notesstring nullable

Internal notes typed on the job itself (not the timeline). Null when empty.

materialPricenumber double

Sum of material lines before job-level discount and tax (decimal currency, e.g. 800.00).

laborPricenumber double

Sum of labor lines before job-level discount and tax (decimal currency).

customChargesTotalnumber double

Sum of custom charges before job-level discount and tax (decimal currency).

discountPercentnumber double nullable

Job-level discount as a percentage of every line (0–100), or null when a fixed amount / no discount applies.

discountAmountnumber double nullable

Job-level fixed discount amount (decimal currency), or null when a percentage / no discount applies.

taxRatenumber double

Tax rate locked in at creation, as a percentage (e.g. 8.25).

downPaymentAmountnumber double nullable

Money collected before invoicing (decimal currency), or null when none.

warningstring nullable

Set only on the POST /api/v1/jobs response when publishImmediately was requested but the job could not be published yet (it was created as a Draft), e.g. Not published yet: Cannot finalize estimate. All material items must have a unit price.. Always null on GET.

Changes

No recorded changes to this operation across all 1 revision of this API.