Changelog - BuildPass API

Recent updates

July 24, 2026 - Defects read API

The new read-only Defects API exposes builder defects to approved integrators.

GET /builders/<builderId>/defects - List active defects with project, location, assignee, attachment, status, priority, and pagination data
GET /builders/<builderId>/defects/<defectId> - Get one defect by ID

Both endpoints require the read:defects scope. Defect IDs use the defect_ prefix, project location IDs use the loc_ prefix, and assignees use the public USER, COMPANY, or TAG union with resource-specific ID prefixes.

July 24, 2026 - Idempotent photo gallery sync removal

DELETE /builders/<builderId>/photo-gallery/bulk-upsert now locates an external photo page by its stable source metadata, even after the caller changes projects. Repeating a removal after the synced folder is already absent now returns a successful deleted response with empty deleted IDs instead of failing. Re-syncing an existing external photo page to a new project now removes all active prior-project copies before creating the replacement, preventing duplicate photos across projects. Destination folder creation is deferred until cleanup succeeds and is committed with the first photo, so failed or interrupted attempts do not leave empty folders behind.

July 23, 2026 - Direct attachment uploads

The new POST /builders/<builderId>/attachments/presign endpoint creates a short-lived, builder-scoped S3 upload URL for images up to 40 MiB. Uploading directly to the returned URL avoids the Vercel Function request-body limit on the existing multipart attachment endpoints. The returned attachment reference can be used with photo create and bulk-upsert requests.

July 23, 2026 - Photos list pagination

The photos list endpoint is now paginated, consistent with every other list endpoint.

GET /builders/<builderId>/photos - Now paginated with offset/limit
- Behavior change: responses now default to limit=25; previously the entire photo set was returned. Integrators reading full galleries should page with offset until meta.totalCount is reached
- limit and offset are validated like every other list endpoint: limit above 25 or malformed values now return a 400 instead of being silently ignored
- Responses now include the meta pagination object

July 23, 2026 - Access to builder-company SWMS and UI photo sources

External API consumers can now opt into records that are represented separately in the BuildPass UI.

GET /subcontractors
- Pass includeBuilderCompany=true to include the builder’s internal company subcontractor record
- The default remains false, so existing integrations continue to receive third-party subcontractors only
- Responses now include isBuilder so the internal company record can be identified
- Archived subcontractors are excluded and results have deterministic ordering
GET /subcontractors/<id>
- Pass includeBuilderCompany=true to retrieve the internal company record returned by the opt-in list
GET /subcontractors/<id>/swms and GET /subcontractors/<id>/swms/<swmsDocId>
- SWMS documents can now be read for the builder-company subcontractor returned by the opt-in company list
GET /builders/<builderId>/photos and GET /builders/<builderId>/photos/<photoId>
- Pass repeatable source parameters to read photos shown in other UI areas, for example source=GALLERY&source=DEFECT
- Supported sources are GALLERY, SITE_DIARY, PRE_START, CHECKLIST, ITP, PLATFORM_ACTION, and DEFECT
- The default remains GALLERY; photo write and folder endpoints remain gallery-only
SWMS, prequalification, and insurance list responses now report the requested offset and limit with calculated pagination totals.

June 11, 2026 - Photos API

We’ve added endpoints for integrators to work with BuildPass photo galleries, folders, and uploaded attachment references.

Attachments

POST /builders/<builderId>/attachments/upload - Upload one attachment for later resource creation
- Requires an authenticated builder request, with no resource-specific scope required
- Requires type=attachment so BuildPass can route the file to the correct storage family
- Returns { key, regionId, type } plus a short-lived signed imageUrl
POST /builders/<builderId>/attachments/bulk-upload - Upload multiple attachments for later resource creation or upsert
- Requires an authenticated builder request, with no resource-specific scope required
- Requires type=attachment, or per-file type:0=attachment fields, so BuildPass can route each file to the correct storage family
- For example, returned attachment references can be used as photos[].imageAttachment

Photos

GET /builders/<builderId>/photos - List gallery photos for a builder
- Filter by project and folder
- Returns photo metadata and a short-lived signed imageUrl
POST /builders/<builderId>/photos - Create a photo attachment
- Accepts an uploaded imageAttachment reference from the attachment upload endpoint
- Supports approved HTTPS imageUrl imports for enabled hosts
- Stores the image in BuildPass attachment storage
GET /builders/<builderId>/photos/<photoId> - Get a photo by id
PATCH /builders/<builderId>/photos/<photoId> - Update photo metadata or move a photo between folders
DELETE /builders/<builderId>/photos/<photoId> - Archive a photo

Photo Folders

GET /builders/<builderId>/photo-folders - List photo folders for a builder
POST /builders/<builderId>/photo-folders - Create a photo folder for a project
GET /builders/<builderId>/photo-folders/<folderId> - Get a photo folder by id
PATCH /builders/<builderId>/photo-folders/<folderId> - Update a folder name or parent folder
DELETE /builders/<builderId>/photo-folders/<folderId> - Delete an empty photo folder

Photo Gallery Sync

POST /builders/<builderId>/photo-gallery/bulk-upsert - Bulk upsert external photo pages into a BuildPass photo folder
- Accepts a returned folder id for repeated sends and skips existing photos
- Uses externalSourceId metadata for idempotency
- Returns created, skipped, and failed photo details
- Supports deleting photos created for an external source with DELETE /builders/<builderId>/photo-gallery/bulk-upsert

Photo and folder endpoints use the read:photos and write:photos scopes. Attachment upload endpoints require authentication but do not require a resource-specific scope.

June 8, 2026 - Meetings API

We’ve added endpoints for integrators to work with BuildPass meetings.

Meetings

GET /builders/<builderId>/meetings - List meetings for a builder
- Filter by project, status, start date, and end date
- Supports pagination with offset/limit
- Returns meeting title, type, project, schedule, status, agenda, notes, and update metadata
POST /builders/<builderId>/meetings - Create a draft meeting for a builder
- Supports ad hoc meetings from external capture products
- Optionally links the meeting to a specific project
PATCH /builders/<builderId>/meetings/<meetingId> - Update a meeting title
- Allows external capture products to keep generated meeting names in sync with BuildPass
POST /builders/<builderId>/meetings/<meetingId>/start - Mark a meeting as running
POST /builders/<builderId>/meetings/<meetingId>/end - Mark a meeting as completed

Meeting Notes

GET /builders/<builderId>/meetings/<meetingId>/notes - List notes synced to a meeting
POST /builders/<builderId>/meetings/<meetingId>/notes - Create or update a meeting note from an external source
- Notes are upserted by externalSourceId
- Template-backed meetings store synced notes in the meeting template response
- Meetings without a template response store synced notes in the meeting notes field

These endpoints use the read:meetings and write:meetings scopes.

April 7, 2026 - Signed profile and builder asset URLs

OAuth identity responses now expose signed image URLs for BuildPass profile and company branding data:

GET /me now returns profilePictureUrl
GET /me memberships now return builderLogoUrl
GET /builders and GET /builders/{id} now return logoUrl

These fields are intended for integrations that want to mirror BuildPass profile photos or builder logos inside their own applications.

January 7, 2026 - Complete OAuth 2.0 Authorization Server

We’ve implemented a full-featured OAuth 2.0 Authorization Server, enabling BuildPass to act as an identity provider for third-party integrations. This comprehensive implementation supports multiple grant types, client types, and security best practices.

OAuth 2.0 Endpoints

BuildPass now provides a complete suite of OAuth 2.0 endpoints:

POST /oauth/token - Token endpoint for all grant types
- Client Credentials Grant (server-to-server)
- Authorization Code Grant (user authorization)
- Refresh Token Grant (token renewal)
GET /oauth/authorize - Authorization endpoint for user consent
- Interactive consent screen for builders
- State parameter for CSRF protection
- Support for pre-selecting builders
- Secure session management
POST /oauth/revoke - Token revocation endpoint (RFC 7009)
- Revoke access tokens or refresh tokens
- Immediate token invalidation
- Compliant with OAuth 2.0 security standards

Grant Types Supported

1. Client Credentials Grant (RFC 6749 Section 4.4)

Server-to-server authentication without user involvement
Ideal for backend services and automated integrations
Scoped access to builder data based on pre-configured connections

2. Authorization Code Grant with PKCE (RFC 7636)

User authorization flow with proof key for code exchange
Support for web apps, mobile apps, and SPAs
10-minute authorization code lifetime
Single-use codes with automatic revocation on reuse
Refresh token rotation for enhanced security

3. Refresh Token Grant (RFC 6749 Section 6)

Obtain new access tokens without re-authorization
30-day refresh token lifetime
Automatic token rotation on use

Client Types

Confidential Clients

Backend services and servers that can securely store a client_secret
Required to authenticate with both client_id and client_secret
Support for all grant types
HTTP Basic Authentication or request body credentials

Public Clients

Mobile apps, SPAs, and desktop applications
Authenticate with only client_id (no secret required or allowed)
Must use PKCE with Authorization Code flow
Enhanced security through cryptographic proof

Security Features

PKCE (Proof Key for Code Exchange) - RFC 7636

Mandatory for all Authorization Code flows
Supports SHA256 (S256) and plain (PLAIN) challenge methods
Prevents authorization code interception attacks
Generates cryptographically secure code verifiers

Authorization Code Reuse Protection

Single-use authorization codes
Automatic revocation of all refresh tokens if code is reused
Protects against replay attacks

Refresh Token Rotation

New refresh token issued on every use
Old refresh token automatically revoked
Prevents token theft and replay attacks

Token Security

JWT access tokens with HMAC-SHA256 signing
1-hour access token lifetime
30-day refresh token lifetime
Unique token IDs (jti claim) for tracking
Cache-Control: no-store headers on token responses

State Parameter Validation

Required state parameter for CSRF protection
Validated on callback to prevent cross-site attacks

Redirect URI Validation

Strict matching of registered redirect URIs
Prevents token theft through malicious redirects

Token Structure

Access Tokens (JWT)

{
  "sub": "integrator_id",
  "client_id": "client_id",
  "builder_id": "builder_id", // For Authorization Code flow
  "iss": "https://api.buildpass.global",
  "aud": "https://api.buildpass.global",
  "scope": "read:builders read:subcontractors",
  "jti": "unique_token_id",
  "iat": 1234567890,
  "exp": 1234571490 // 1 hour from iat
}

Token Response Format

{
  "access_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
  "token_type": "Bearer",
  "expires_in": 3600,
  "scope": "read:builders read:subcontractors",
  "refresh_token": "550e8400-e29b-41d4-a716-446655440000"
}

Available Scopes

Granular permission system for controlling API access:

read:builders - Access builder information
read:subcontractors - Access subcontractor data
read:projects - Access project information
read:insurances - Access insurance certificates
read:prequalifications - Access prequalification documents
read:contacts - Access contact information
read:swms - Access SWMS documents
read:timesheets - Access timesheet data
read:inductions - Access induction records

Scopes are validated against:

Client’s allowed scopes (configured per integration)
Audience-specific scope requirements
Builder connections (for Authorization Code flow)

Authorization Request

GET /oauth/authorize?
  response_type=code&
  client_id=YOUR_CLIENT_ID&
  redirect_uri=https://yourapp.com/callback&
  scope=read:builders+read:subcontractors&
  state=RANDOM_STATE&
  code_challenge=BASE64_CHALLENGE&
  code_challenge_method=S256

User Experience

User redirected to BuildPass consent screen
Displays requested permissions and integrator information
User reviews and approves/denies access
Redirect to application with authorization code or error
Application exchanges code for tokens

Builder Selection

Automatic selection for users with single builder access
Builder selection screen for users with multiple builders
Optional builder_id parameter to pre-select builder

RFC Compliance

BuildPass OAuth 2.0 implementation is fully compliant with:

✅ RFC 6749 - OAuth 2.0 Authorization Framework
- Client Credentials Grant (Section 4.4)
- Authorization Code Grant (Section 4.1)
- Refresh Token Grant (Section 6)
- Error response format (Section 5.2)
✅ RFC 7636 - Proof Key for Code Exchange (PKCE)
- Required for all Authorization Code flows
- SHA256 challenge method support
✅ RFC 7009 - Token Revocation
- Standardized revocation endpoint
- Success response regardless of token validity
✅ RFC 6750 - Bearer Token Usage
- Authorization header format
- Cache control headers

Audit Logging

Comprehensive audit trail for all OAuth operations:

Token requests (all grant types)
Authorization requests and approvals/denials
Token revocations
Failed authentication attempts
Includes client ID, IP address, timestamps, and outcomes

Error Handling

Standard OAuth 2.0 error responses: Authorization Errors (redirect to client):

access_denied - User denied authorization
invalid_scope - Requested scopes not allowed
server_error - Internal server error

Token Endpoint Errors (JSON response):

invalid_request - Missing or malformed parameters
invalid_client - Invalid client credentials
invalid_grant - Invalid/expired authorization code or refresh token
unsupported_grant_type - Grant type not supported

All errors include descriptive error_description for debugging.

CORS Support

Full CORS support for browser-based applications:

Preflight request handling (OPTIONS)
Configurable allowed origins
Credential support for secure cookie handling
Headers: Access-Control-Allow-Origin, Access-Control-Allow-Methods, Access-Control-Allow-Headers

Migration

No action required for existing integrations:

All existing clients default to Confidential type
Existing Client Credentials flow continues unchanged
Existing authentication patterns remain fully supported

New capabilities available:

Request Authorization Code flow access for user-facing integrations
Request Public client type for mobile/SPA applications
Contact BuildPass support to enable new features

Documentation

Complete documentation available:

Authentication Overview - Client types and Client Credentials flow
OAuth 2.0 Authorization Code Flow - User authorization guide
Example code for multiple languages and platforms
Security best practices for credential storage
Platform-specific integration guides

November 19, 2025 - Multi-Region Database Support

We’ve added multi-region database routing to support clients in both Australia and the United States.

What’s New

Region-based Routing: Route API requests to your client’s regional tenant using the X-BuildPass-Region-Id header
Supported Regions:
- au1 - Australia (Sydney) - Default
- us1 - United States (Ohio)

Usage

Include the region header in your API requests to connect to your client’s tenant:

curl -X GET "https://api.buildpass.global/builders" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "X-BuildPass-Api-Version: v1" \
  -H "X-BuildPass-Region-Id: us1"

Each client’s BuildPass account is hosted in one region. Store the region identifier alongside their OAuth credentials in your integration.

Migration

No migration is required for existing Australian clients:

Australian clients: Continue without the header (defaults to au1) or explicitly add X-BuildPass-Region-Id: au1
United States clients: Add X-BuildPass-Region-Id: us1 to all requests for these clients

Best Practices

Store each client’s region identifier with their credentials
Use the same region for token generation and all API requests for a client
When onboarding new clients, confirm their region with BuildPass

For detailed documentation, see Multi-Region Support.

November 11, 2025 - New Inductions API endpoints

We’ve added new endpoints to help you integrate with BuildPass induction data:

Inductions API

New endpoints for accessing induction records:

GET /subcontractors/<id>/inductions - Get all inductions for workers associated with a subcontractor
- Filter by project ID, status, and type
- Supports pagination with offset/limit
- Returns induction details including type, status, worker, subcontractor
GET /builders/<builderId>/projects/<projectId>/inductions - Get all inductions for a project
- Filter by status
- Supports pagination with offset/limit
- Returns induction details including type, status, and worker information
GET /builders/<builderId>/projects/<projectId>/inductions/<identifierOrId> - Get a specific induction
- Supports lookup by project-specific identifier (e.g. 5) or induction ID (e.g. ind_abc123)
- Automatically returns latest version when version history exists
- Returns full induction details with worker, subcontractor, project, and responses

These endpoints require the read:inductions scope and follow the same authentication patterns as other API endpoints.

January 15, 2025 - Subcontractor endpoints improvements

Enhanced performance and reliability for subcontractor status data:

GET /subcontractors - List subcontractors
- Subcontractor statuses are now properly filtered based on the projectId query parameter when provided
- Fixed an issue that caused duplicate statuses to appear in responses
GET /subcontractors/<id> - Get subcontractor
- Added support for the projectId query parameter to retrieve project-specific status information

June 25, 2025 - OAuth 2.0 authentication enhancements

We’ve enhanced our authentication system to more effectively comply with the OAuth 2.0 standards:

New features

HTTP Basic Authentication: You can now authenticate using HTTP Basic Authentication in addition to the existing request body method
- Pass client credentials via the Authorization: Basic <credentials> header
- Credentials should be Base64-encoded in the format client_id:client_secret
- Request body credentials take precedence when both methods are used

Changes

Standardized Token Expiration: The expires field has been renamed to expires_in. The value of this field has not changed.
Enhanced Security: Improved request validation and error handling.

Migration guide

You must ensure your code properly handles the expires_in field. This can be used to determine when a new token is necessary. The expires field will be maintained until the 25th of September, 2025.

May 26th, 2025 - New API endpoints

Timesheets API

We’ve added comprehensive timesheet management endpoints to help you integrate with BuildPass timesheet data:

GET /timesheets - Retrieve all timesheets for a builder with filtering options
- Filter by project, status, and date range
- Supports pagination with offset/limit
- Returns timesheet details including hours, notes, time types, and cost codes
GET /timesheets/<timesheetId> - Get a specific timesheet by ID
- Includes associated profile and project information
- Full timesheet details with approval status
GET /timesheets/time-types - Get configured time types for a builder
- Returns available time categories (e.g., “Regular Hours”, “Overtime”, “Annual Leave”)
GET /timesheets/cost-codes - Get configured cost codes for a builder
- Returns project cost codes for timesheet categorization

SWMS (Safe Work Method Statements) API

New endpoints for accessing SWMS documents:

GET /subcontractors/<id>/swms - Get all SWMS documents for a subcontractor
- Filter by project ID and review status
- Supports pagination
- Returns document metadata and review status
GET /subcontractors/<id>/swms/<swmsDocId> - Get a specific SWMS document
- Includes document URL for download
- Shows current review status and approval state

These endpoints require appropriate scopes (read:timesheets and read:swms) and follow the same authentication patterns as other API endpoints.

Need help?

If you have questions about these changes or need assistance with migration, please contact our support team.

​Recent updates

​July 24, 2026 - Defects read API

​July 24, 2026 - Idempotent photo gallery sync removal

​July 23, 2026 - Direct attachment uploads

​July 23, 2026 - Photos list pagination

​July 23, 2026 - Access to builder-company SWMS and UI photo sources

​June 11, 2026 - Photos API

​Attachments

​Photos

​Photo Folders

​Photo Gallery Sync

​June 8, 2026 - Meetings API

​Meetings

​Meeting Notes

​April 7, 2026 - Signed profile and builder asset URLs

​January 7, 2026 - Complete OAuth 2.0 Authorization Server

​OAuth 2.0 Endpoints

​Grant Types Supported

​Client Types

​Security Features

​Token Structure

​Available Scopes

​User Consent Flow

​RFC Compliance

​Audit Logging

​Error Handling

​CORS Support

​Migration

​Documentation

​November 19, 2025 - Multi-Region Database Support

​What’s New

​Usage

​Migration

​Best Practices

​November 11, 2025 - New Inductions API endpoints

​Inductions API

​January 15, 2025 - Subcontractor endpoints improvements

​June 25, 2025 - OAuth 2.0 authentication enhancements

​New features

​Changes

​Migration guide

​May 26th, 2025 - New API endpoints

​Timesheets API

​SWMS (Safe Work Method Statements) API

​Need help?

Recent updates

July 24, 2026 - Defects read API

July 24, 2026 - Idempotent photo gallery sync removal

July 23, 2026 - Direct attachment uploads

July 23, 2026 - Photos list pagination

July 23, 2026 - Access to builder-company SWMS and UI photo sources

June 11, 2026 - Photos API

Attachments

Photos

Photo Folders

Photo Gallery Sync

June 8, 2026 - Meetings API

Meetings

Meeting Notes

April 7, 2026 - Signed profile and builder asset URLs

January 7, 2026 - Complete OAuth 2.0 Authorization Server

OAuth 2.0 Endpoints

Grant Types Supported

Client Types

Security Features

Token Structure

Available Scopes

User Consent Flow

RFC Compliance

Audit Logging

Error Handling

CORS Support

Migration

Documentation

November 19, 2025 - Multi-Region Database Support

What’s New

Usage

Migration

Best Practices

November 11, 2025 - New Inductions API endpoints

Inductions API

January 15, 2025 - Subcontractor endpoints improvements

June 25, 2025 - OAuth 2.0 authentication enhancements

New features

Changes

Migration guide

May 26th, 2025 - New API endpoints

Timesheets API

SWMS (Safe Work Method Statements) API

Need help?