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. |
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 schedule, materials and order change events. |
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. |
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