Bid Desk: reading bids and bills of materials

An app such as an ERP connector or a PLM or CAD sync can read a tenant's bids and its assemblies' bills of materials through app API 2027-01. It reads the same rows a person with the same rights would see, minus anything confidential to a bid's members and minus every cost, margin and money field.

Bid Desk is an add-on. On a tenant without it, every Bid Desk query refuses an app with the same message a person gets: Bid Desk is an add-on. Contact Growmax to add it. Bills of materials also need the add-on's engineered-products feature.

Scopes

Ask for these in your manifest's scopes. The consent screen shows each one's sentence.

Scope	Consent sentence	What it lets the app call
`read_bids`	Read bids open to the whole organization, and the hand-over package of a won bid, without costs or margins.	`bid`, `bidHandoverPackage`
`read_assemblies`	Read assemblies' bills of materials and where each part is used.	`bomVersion`
`write_assemblies`	Create and edit draft bills of materials. Releasing a bill of materials stays with a person.	everything `read_assemblies` allows; the write commands come in a later API package

A bid's customerName also needs read_customers, because it comes from the customer record.

Queries

query OneBid {
  bid(id: "…") {
    id
    bidNumber
    title
    status
    stage
    visibility
    currency
    customerId
    ownerUserId
    closedAt
    updatedAt
  }
}

query HandedOver {
  bidHandoverPackage(bidId: "…") {
    bidNumber
    outcome
    quoteId
    quoteNumber
    salesOrderId
    packageHash
    lines { nodePath productId variantId sku description quantity unit leadTimeDays }
    milestones { label pct trigger }
  }
}

query OneBillOfMaterials {
  bomVersion(id: "…") {
    id
    assemblyProductId
    versionNo
    status
    releasedAt
    lines { componentProductId componentName kind quantity scrapPercent findNumber uomId }
  }
}

Quantities and percentages are exact decimal strings. bidHandoverPackage answers only after the bid has been handed over.

The lists bids, bomVersions and bomWhereUsed are not on 2027-01 yet. They join once they take the sync arguments every app list has (updatedAfter, cursor, includeDeleted).

Which bids an app sees

An installation acting for the whole organization sees bids open to the whole organization. A confidential bid (visible to its members only) answers Bid not found, the same as a bid that does not exist.
A token bound to one sales rep sees the bids that rep may see, confidential ones included.
No scope grants "view all bids", so no app reads every confidential bid.

Never sent to an app

The bid's estimated value, every unit cost, cost-sheet references and every other field whose name reads as money. Money fields will arrive as { amount, currencyCode } in a later version.
The owner's name and the status reason (staff details). The owner's id is sent.
A bid's due date and a milestone's due days are closed on this version too, because their names read as money to the field review; they open once each is reviewed.

Never available to an app

An app never creates, edits, archives or changes the status of a bid, never edits or releases a proposal, never hands a bid over, never releases a bill of materials, never approves, never changes Bid Desk settings and never invites a guest. None of these operations is on the app API, and the permissions behind them are closed to every app.

Coming next

Bill-of-materials writes for write_assemblies, and Bid Desk webhook topics.

Scopes​

Queries​

Which bids an app sees​

Never sent to an app​

Never available to an app​

Coming next​