Jobs

Adds a material line to a job (the app's "Add material" button).

Requires ManageJobs and an Idempotency-Key header. Same rules as the web app: a cancelled job is read-only, parent / sell-by-unit / add-on items are added through the app instead, and a matching plain planned line is merged rather than duplicated. The line price is resolved by the pricing engine (tiers) unless you send a unitPrice that differs from the base price, which is kept as a manual override. In counter-sales mode stock is consumed immediately. The write is attributed to the user who created the key.

post/api/v1/jobs/{id}/items

Request

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

Path parameters

idinteger required

Job id from GET /api/v1/jobs.

Request body

itemTemplateIdinteger

Item template id from GET /api/v1/items; must belong to your organization. Parent, sell-by-unit and add-on items are added through the app instead.

quantityinteger

Whole units, 1–10000. Default 1.

unitCostnumber double nullable

Cost per unit to the organization, in its currency, ≥ 0. Omit to use the template's base cost. Example: 12.50.

unitPricenumber double nullable

Price per unit charged to the customer, ≥ 0. Omit to let pricing resolve the tier/base price; a value that differs from the base price is kept as a manual override. Example: 19.99.

notesstring nullable

Line note, ≤ 500 characters.

Response

The updated job (same shape as GET /api/v1/jobs/{id}).

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.