A builder shares exactly what they choose
The API is built on least privilege. A key reads one organisation, carries only the scopes it was granted, and never crosses into another party’s data. A supplier sees their own catalogue and orders; a platform sees only the schedule and materials a builder shared, never the builder’s costs. Here is precisely what is exposed, what isn’t, and how it’s protected.
What the API exposes
- Your own catalogue: SKUs, pricing, stock, lead times
- Orders placed with you: line items and delivery
- Project name, number, status, stage and type
- Site address, for delivery
- Milestone schedule: dates, status and progress
- Materials lines: description, quantity, unit
What it never exposes
- Another organisation’s catalogue or orders
- A builder’s unit cost, line totals or margin
- Project budget and financials
- Customer records and contact details
- Invoices, payments and documents
- Team members and internal notes
Grant only what the integration needs
A key holds a list of scopes. Request the narrowest set that does the job.
| Scope | What it grants |
|---|---|
projects:read | List projects and read project details, status and site address. |
schedule:read | Read the milestone schedule and dates for a project. |
materials:read | Read the materials list (estimate line items) for a project. No cost or margin data is exposed. |
suppliers:read | Read the supplier tags attached to materials lines. |
leads:read | List and read CRM leads — title, pipeline stage, estimated value, source and notes — with the contacts linked to each lead. No quote line items or customer financial data. |
diary:read | Read the site diary for a project: weather, trades on site, work notes, issues and delays. No photos or device location. |
variations:read | Read the variations on a project with their line items, status and approval dates. Dollar figures (client price, builder cost, line amounts) also need the money scope. |
defects:read | Read the defects logged against a project: title, location, priority, status, assignee and due date. No photos, notification settings or device location. |
contacts:read | List and search the organisation's client contacts: name, company, email, phone and address. Contact data requires this exact scope; the broad read scope does not include it. |
documents:read | List the documents on a project and fetch a short-lived download link for each. No document is served from a stored public URL. |
catalogue:read | For a supplier or manufacturer: read your own product catalogue in Paperless — SKUs, pricing, stock and lead times. |
orders:read | For a supplier: read the orders builders have placed with you, with line items and delivery details. |
webhooks | Register endpoints to receive change events for the resources a key can read: projects, schedule, materials, purchase orders, variations, defects, site diary, documents, notes, leads, contacts, suppliers and catalogue. The full event list is on the developer webhooks page. |
leads:write | Create an enquiry in the customer's CRM and move a lead through the qualification stages. Winning a lead stays in Build Paperless, because that step also creates the client and the project. |
materials:write | Create and update materials lines on a project. Write scopes still require the customer to have granted you the same scope. |
suppliers:write | Attach and change the supplier against a materials line. |
catalogue:write | For a supplier or manufacturer: publish and update your catalogue and pricing. Requires approval. |
orders:write | Write delivery and order status back. Requires partner approval. |
projects:write | Create projects and update project details, status and site address. |
schedule:write | Create and update milestones on a project schedule. |
diary:write | Add site diary entries to a project. |
defects:write | Log defects against a project and update their status. |
contacts:write | Create and update client contacts. Contact data requires this exact scope; the broad write scope does not include it. |
documents:write | Upload documents to a project. |
variations:write | Propose new variations on a project. Proposing also needs the money scope, and nothing is created until someone in your organisation approves it in Paperless. |
purchase_orders:write | Update existing purchase orders. Proposing a new purchase order needs the money scope. |
money | See the dollar figures on variations (client price, builder cost and line amounts) and propose variations and purchase orders. Every proposal waits for someone in your organisation to approve it in Paperless before it is created. |
How keys and data are protected
Keys are hashed at rest
A key is shown once, at creation. We store only a SHA-256 hash and a short prefix. We can’t recover a key, and a database leak can’t reveal one. Keys are revocable in a click and can carry an expiry.
One key, one organisation
Every key is bound to the organisation that created it. There is no cross-organisation path. A project id from another builder returns 404, never data. A materials-ordering platform holds a separate key per builder it serves.
Scoped and rate limited
Keys carry granular scopes, so a key can read the schedule without touching anything else. Each key has a per-hour rate limit, and every response carries X-RateLimit headers so you always know where you stand.
Every request is logged
We record the key, method, path, status and timing of each call. A builder can see how a connected platform is using their data, and revoke access the moment they want to.
Encrypted, hosted in Australia
All traffic is TLS only. Data is stored and served from Australian infrastructure, the same environment that runs the platform.
Found something?
Report a security issue to security@buildpaperless.com.au. We respond to credible reports quickly and won’t pursue good-faith research.
Back to the API reference