Bids¶

Available to: Owner, Project Manager, Accounting, Supervisor (read-only)

A bid is the starting point for all work in Hardhat Flow. It captures the full scope, logistics, and financial details of a proposed project before any work begins. Once a bid is approved, a Job is automatically created from it — at which point the bid becomes read-only.

What is a Bid?¶

A bid represents a proposal submitted to a client for a defined scope of work. It tracks everything needed to price and plan the job: location, staffing, materials, permits, inspections, and financial terms.

Bids flow through an approval process. Only an Owner can approve or reject a bid. A Project Manager creates and manages bids on behalf of their assigned projects.

Bid Fields¶

Project Details¶

Field	Description
`client`	The company or individual the work is being performed for. Use + New Client on the New Bid form to create a client inline.
`contact`	The client-side point of contact for this bid. Select from the chosen client's contacts, or use + New Contact to add one inline.
`location`	Physical address or site description for the work.
`pm`	The Project Manager assigned to this bid.
`supervisor`	The field Supervisor responsible for execution.
`scope`	Free-text description of the work to be performed.
`measurements`	Room sizes listed as room name + dimensions (e.g. `Lobby: 20x30 ft`).
`equipment_needed`	Equipment name and quantity only.
`estimated_days`	Estimated number of days to complete the work.
`expected_completion_date`	Estimated calendar date the work will be finished.

Logistics¶

Field	Description
`shift_type`	Whether the work is a `day` or `night` shift.
`escort_name`	Legacy free-text escort name on older jobs. Assign Badge Workers from Settings → Team (or Escorts in the nav), then pick them on each job under Job Operations.
`materials_status`	Current status of materials procurement. One of: `None`, `Needed`, `Ordered`, `Shipped`, `Delivered`.
`permits_needed`	Boolean — whether permits are required for this job.
`inspections_status`	Current inspection status. One of: `None`, `Needed`, `Requested`, `Pass`, `Fail`.
`po_number`	The client's Purchase Order number, required before bid approval in most workflows.

Financials¶

Field	Description
`bid_price`	The total price quoted to the client for the work.
`taxable`	Boolean — whether this bid is subject to sales tax. Tax rate is pulled from CompanySettings.

Flags¶

Field	Description
`priority`	Boolean — marks the bid as high priority. Triggers an SMS notification to PM and Supervisor. Surfaced prominently on the dashboard feed.
`blocked`	Boolean — indicates the bid cannot proceed due to an unresolved issue.
`blocked_reason`	Free-text explanation of why the bid is blocked. Required when `blocked` is set to `true`.

Status Machine¶

Status	Description	Who Can Set
`New Bid`	Default status on creation. Bid is being drafted.	System (on create)
`Bid Awaiting PO`	Bid has been submitted for approval and is awaiting the client's Purchase Order.	Project Manager
`Bid Approved`	Bid has been accepted. A Job is automatically created and the user is redirected to the new Job.	Owner
`Bid Rejected`	Bid was declined. No job is created.	Owner
`Bid Cancelled`	Bid was withdrawn before a decision was made.	Owner

New Bid → Bid Awaiting PO → Bid Approved (creates Job, redirects to Job detail)
                          ↘ Bid Rejected
          Bid Cancelled (from any pre-approved state, Owner only)

Approval Flow (UI)¶

From the Bid detail page:

New Bid status: A Submit for Approval button is shown. Clicking it transitions the bid to Waiting on Approval (Bid Awaiting PO).
Waiting on Approval: PM or Owner can click Edit Bid, revise scope/measurements/equipment, and Save & Resubmit. Owner/Admin also see Approve and Reject.
Edit Bid Proposal opens the document editor to customize the PDF before download.

Editing while waiting on approval

Bids in Waiting on Approval can be edited by the Project Manager or Owner without extra confirmation. Once a bid is Approved and linked to a job, only the Owner can edit (with confirmation), and changes sync to the job.

Approved bids require Owner authorization to edit

After approval, only an Owner can make field edits. Owners will see a confirmation prompt before changes are saved. Confirmed edits are automatically synced to the linked Job.

The Blocked Flag¶

Setting blocked = true on a bid signals that something is preventing progress — a missing permit, unresolved client question, or materials delay.

blocked_reason must be provided when blocking.
Blocked bids are surfaced as alerts in the dashboard feed for the assigned PM and Owner.
Unblocking a bid clears the alert.

The Priority Flag¶

Setting priority = true marks a bid as urgent.

An SMS is sent immediately to the assigned PM and Supervisor.
Priority bids appear at the top of the dashboard alert panel.
The flag can be toggled by the PM or Owner at any time before approval.

PDF Generation¶

A printable bid proposal PDF can be generated at any time.

Available to Owner, PM, and Accounting roles.
The PDF uses a standardized proposal layout so every client-facing bid has the same structure.
Header includes your company name and address.
Proposal section includes:
BID PROPOSAL title and the date generated
contact name and client name lines
intro text describing the proposed work
job location
numbered scope lines from the bid scope
a final supervision line with your company name
TOTAL from the bid price
Bid Prepared By with the name, email, and phone for the user who generated the PDF
The PDF reflects the bid's current values at the moment it is generated and is not stored as a separate record.

Use PDF export when sharing bid details with clients or for record-keeping outside the system.

Edit Permissions by Status¶

Bid Status	Who Can Edit
`New Bid`	Owner, Project Manager (any role with bid access)
`Bid Awaiting PO`	Owner / Platform Admin only — confirmation required
`Bid Approved`	Owner / Platform Admin only — confirmation required, job is synced
`Bid Rejected`	No one — terminal state, locked
`Bid Cancelled`	No one — terminal state, locked

Owner Confirmation Flow¶

When an Owner attempts to edit a bid in Awaiting PO or Approved status, the API returns HTTP 409 with:

{
  "requires_confirmation": true,
  "has_job": true,
  "warning": "This bid has progressed beyond New status. Changes will also update the linked job. Send the request again with X-Confirm-Override: true to proceed."
}

The client must re-send the request with the X-Confirm-Override: true header to apply the changes.

Job Sync on Confirmed Edit¶

When an Owner confirms an edit on an Approved bid that has a linked Job, the following fields are automatically synced from the bid to the job:

project_manager, supervisor, escort, escort_name, po_number, permits_list, priority, materials_status, inspections_status, completion_date (from expected_completion_date)

Staff assignments for PM and Supervisor are also updated on the Job to match the bid.

Role Access¶

Action	Owner	PM	Accounting	Supervisor	Badge Worker
Create bid	Yes	Yes	No	No	No
Edit bid (`new_bid`)	Yes	Yes	No	No	No
Edit bid (progressed, with confirm)	Yes	No	No	No	No
View bid	Yes	Yes	Yes	Yes (assigned)	No
Submit for PO	Yes	Yes	No	No	No
Approve bid	Yes	No	No	No	No
Reject bid	Yes	No	No	No	No
Cancel bid	Yes	No	No	No	No
Set priority flag	Yes	Yes	No	No	No
Set blocked flag	Yes	Yes	No	No	No
Generate PDF	Yes	Yes	Yes	No	No

Supervisors can view bids they are assigned to, but cannot edit any bid fields.