Introduction

The Performance Hub Partner API enables external partner platforms to seamlessly integrate with Performance Hub's core modules. The API supports computer vision, analytics, member access logging, and facility insights.

Request Format

The API accepts JSON-encoded request bodies and returns JSON-encoded responses.

Rate Limiting

To ensure fair usage and system stability, Partner API accounts start with default limits:

• 5 requests per second per endpoint
• Recommended: 1000 items maximum per batch request for optimal performance
• 10MB maximum payload size

Rate limits are adjustable and can be configured on a case-by-case basis by your Performance Hub partner account manager. If your integration needs higher throughput for launch, migrations, reporting backfills, or high-volume facilities, raise this during onboarding or before the planned change window.

Authentication

Access to the Partner API requires authentication using API secret keys. Generate and manage your keys through the Partner Console.

API keys serve as your credentials for accessing partner resources. Each key has restricted access to specific organisation data and can be deactivated instantly when needed.

Handle your API keys with care—they provide full access to your account! Never expose these keys in public repositories, client-side applications, or anywhere they could be compromised.

Authenticate requests using HTTP Basic Auth by passing your API key as the username. Leave the password empty.

The API only accepts secure HTTPS connections. Plain HTTP requests are rejected, as are any requests missing proper authentication credentials.

Going-Live Checklist

Use this checklist before enabling a partner integration for production facilities.

Partner Console setup

• Your partner profile is complete.
• Your logo URL, website, category, and description are accurate.
• Your data linking method is configured: Direct Link or Linking Identifier.
• Facility linking has been tested with at least one real facility.
• The right key type is being used:
  • Dryrun for non-destructive write testing.
  • Read-only for safe data consumption.
  • Live only when you are ready to affect production data.

Authentication and key management

• Secret keys are stored server-side only.
• Keys are not embedded in client-side applications, mobile apps, public repositories, or support tickets.
• Key rotation and revocation have been tested.
• Your team knows which key is used by each environment.

Data validation

• Required fields are present for every endpoint you call.
• Facility identifiers match your configured linking method.
• IDs from your system are stable and do not change between syncs.
• Large imports are split into batches under the documented limits.
• Failed batch items can be identified and resent.

Endpoint testing

Before launch, test every endpoint your integration depends on:

• Organisations and facilities can be read.
• Members can be saved and updated.
• Membership plans, access zones, and access hours sync correctly.
• Check-ins are accepted and can be correlated back to your system.
• Report snapshots use the expected reporting period and metrics.
• Door/Gate Controller flows are tested on real hardware where applicable.

Access control readiness

For access control integrations:

• Your system makes the access decision before calling Performance Hub.
• The integration handles device_offline, maintenance_mode_active, and unlock_confirmation_timeout.
• Operators understand that a timeout means the unlock was not confirmed.
• Your logs store the returned event_id and command_id.
• You have a manual fallback process for facility staff.

Error handling and retries

• 400, 401, 403, 404, 409, and 422 responses are surfaced to operators or support teams rather than retried blindly.
• 429, 500, 502, 503, and 504 responses use bounded retry logic with backoff.
• Repeated failures create an alert in your system.
• The integration never drops failed records silently.

Observability

• Your logs include endpoint, timestamp, facility identifier, source record ID, request outcome, and response body.
• Your support team can search by member ID, facility ID, check-in ID, or unlock event ID.
• You have a way to replay or reconcile failed syncs.

Production launch

• Performance Hub has confirmed your production access.
• At least one production facility has enabled your integration.
• Your production key is active.
• Your operational and technical contacts are current.
• Your support process is documented for customers.

After these checks are complete, your configured integration will appear in the Performance Hub partner directory inside the core Performance Hub platform.

Best Practices

Use these patterns to keep partner integrations predictable, observable, and safe for facilities.

Identify facilities consistently

Choose the linking method configured for your partner account and use it consistently:

• Direct Link - use the Performance Hub facility_id returned by the facilities endpoint.
• Linking Identifier - use your own location identifier, such as a branch ID, location code, or store number.

Do not send both identifiers in the same request. Performance Hub resolves requests using the linking method configured for your partner account.

See Partner Linking Methods for setup guidance.

Batch writes carefully

The Partner API accepts JSON request bodies and is designed for batch-oriented sync workflows where documented. Keep batches bounded and retryable.

Default guidance:

• Use up to 1000 items per batch request for optimal performance.
• Keep payloads under 10MB.
• Stay within 5 requests per second per endpoint.

Rate limits are adjustable and can be configured on a case-by-case basis by your Performance Hub partner account manager. If you expect high-volume imports, launch traffic, or reporting backfills, agree the required throughput before the change window.

If you need to sync a large dataset, split it into deterministic chunks and log each chunk ID on your side. This makes failed retries easier to reason about.

Retry safely

Use exponential backoff for transient failures such as 429, 500, 502, 503, and 504.

Avoid tight retry loops. A good starting point is:

1. Retry after 1 second.
2. Retry after 2 seconds.
3. Retry after 4 seconds.
4. Stop and alert if the operation still fails.

For validation failures such as 400 or 422, fix the request before retrying.

Use idempotency where supported

The Door/Gate Controller unlock endpoint supports an optional idempotency_key. Reusing the same key for the same partner, facility, and door returns the existing result when one is available.

Use a stable key for the action being performed, for example a check-in ID or access event ID from your system.

Do not assume every write endpoint supports idempotency unless it is documented for that endpoint.

Keep source data clean

Send stable, normalized values wherever possible:

• Use consistent member, plan, facility, and check-in IDs from your source system.
• Use ISO 8601 timestamps for dates and times.
• Send phone numbers in international format where available.
• Send currencies using the fields documented for each endpoint.
• Avoid overloading free-text fields with data that belongs in structured fields.

Design for incremental and full syncs

Most partner integrations need both:

• Incremental syncs for day-to-day changes.
• Full reconciliation syncs to correct missed events, historical imports, or data drift.

Your integration should be able to resend the current state for a member, membership plan, or report snapshot without depending on a previous request having succeeded.

Treat access control as safety-critical

For Door/Gate Controller unlocks:

• Your system must decide whether the person is allowed to enter before calling Performance Hub.
• Performance Hub returns 200 only after the on-site controller confirms the relay physically unlocked.
• Most confirmations complete in 3-5 seconds.
• A timeout is an explicit failed unlock, not a background success.
• Retry only according to your own access and safety rules.

Always log the event_id and command_id returned by the unlock endpoint.

Monitor your integration

Use the Partner Console request logs during development and launch. In production, also maintain your own logs with:

• Request timestamp.
• Endpoint.
• Source record ID.
• Facility identifier.
• HTTP status code.
• Performance Hub response body or error message.

These fields make support and reconciliation much faster when a customer asks what happened.

Organisations

Represents the top-level business entity that operates one or more facilities integrated with the Performance Hub platform.

The Organisation object

Attributes

• org_id string required

  Unique identifier for the organisation.

• name string required

  Organisation name.

List all organisations

Returns a list of organisations accessible to your partner account.

Returns

Returns a JSON object with a data property containing an array of Organisation objects.

Facilities

Represents a physical location, branch, club, gym, or studio where members can access services.

The Facility object

Attributes

• facility_id string required

  Unique identifier for the facility.

• org_id string required

  Unique identifier for the parent organisation.

• name string required

  Facility name.

• brand string optional

  Brand name used by the facility.

• website_url string optional

  Facility website URL.

• place_data object optional

  Location data from Google Places API containing country, formatted address, Google Place ID, province, and city.

• social_links object optional

  Social media links for the facility.

• timezone string optional

  IANA timezone identifier (e.g., "Australia/Sydney", "America/New_York").

List all facilities

Returns a list of facilities accessible to your partner account.

Returns

Returns a JSON object with a data property containing an array of Facility objects.

Membership Plans

Defines a purchasable offering from an organisation or facility, including services, entitlements, schedule, and pricing.

The Membership Plan object

Attributes

• membership_plan_id string required

  Unique identifier for the membership plan.

• facility_id string either/orProvide the facility identifier type configured for your integration: use facility_id for direct-link integrations, or linking_identifier for linking-identifier integrations. Do not send both; the API uses the identifier type configured for your partner account and ignores the other one. Learn more

  Unique identifier of the facility from Performance Hub.

• linking_identifier string either/orProvide the facility identifier type configured for your integration: use facility_id for direct-link integrations, or linking_identifier for linking-identifier integrations. Do not send both; the API uses the identifier type configured for your partner account and ignores the other one. Learn more

  Unique identifier value for each location that the partner uses (e.g., "Branch ID", "Location Code", "Store Number"). Learn more

• name string required

  Human-readable plan name (e.g., "Unlimited Monthly", "10 Class Pack").

• billing_cycle string optional

  Billing frequency. One of weekly, fortnightly, monthly, annually, or one_time.

• price integer optional

  Base cost in smallest currency unit (cents for USD/AUD).

• currency string optional

  ISO 4217 currency code (e.g., "AUD", "USD").

• description string optional

  Optional marketing or internal description.

• active_members integer optional

  Number of active members using this membership plan

• is_recurring boolean optional

  Whether the plan auto-renews.

• is_trial boolean optional

  Whether this is a trial offering.

• visible_to_public boolean optional

  Whether the plan is available for self-service purchase.

• duration_days integer optional

  Number of days the membership plan is valid for.

• access_zones array optional

  Array of access zones included in the membership plan. Each zone can define its own access hours. See Access Zones for details.

• class_limit integer optional

  Maximum number of classes allowed (null for unlimited).

Access Zones

Access zones define specific areas within a facility where a membership plan grants access. Each zone can have its own access hours, allowing different time restrictions per area.

Structure

Each access zone includes:

• name string required

  The name of the zone (e.g., "Main Gym Floor", "Group Fitness Studio").

• description string optional

  Description of what's included in that zone.

• access_hours object optional

  Access hours specific to this zone. See Access Hours for the time range format.

Access Hours

Access hours specify when members can access a specific zone during each day of the week. Access hours are defined per access zone, allowing different time restrictions for different areas of a facility.

Save a membership plan

Creates or updates membership plan records. The API determines whether to create or update based on the membership_plan_id.

Parameters

• membership_plans array required

  Array of Membership Plan objects to save. Recommended maximum: 1000 items per request for optimal performance. The API automatically batches items for processing. Each item must include either facility_id (required if not using linking_identifier) or linking_identifier (required if not using facility_id).

Returns

Returns a simple message confirming the sync operation.

Members

Represents an individual customer of a facility. Can be a lead, prospect, recurring customer, expired member, or blocked user.

The Member object

Attributes

• member_id string required

  Unique identifier for the member.

• facility_id string either/orProvide the facility identifier type configured for your integration: use facility_id for direct-link integrations, or linking_identifier for linking-identifier integrations. Do not send both; the API uses the identifier type configured for your partner account and ignores the other one. Learn more

  Unique identifier of the facility from Performance Hub.

• linking_identifier string either/orProvide the facility identifier type configured for your integration: use facility_id for direct-link integrations, or linking_identifier for linking-identifier integrations. Do not send both; the API uses the identifier type configured for your partner account and ignores the other one. Learn more

  Unique identifier value for each location that the partner uses (e.g., "Branch ID", "Location Code", "Store Number"). Learn more

• first_name string required

  Member's first name.

• last_name string required

  Member's last name.

• email string optional

  Email address.

• mobile_phone string optional

  Mobile phone number in E.123 format (e.g., "+1 415 555 2671").

• address object optional

  Physical address object with the following properties:

  • address_line_1 (string) - Primary street address
  • address_line_2 (string, optional) - Secondary address line
  • city (string) - City name
  • state (string) - State/province code
  • postal_code (string) - Postal/ZIP code
  • country (string) - ISO 3166-1 alpha-2 country code (e.g., "AU", "US")
  • country_name (string, optional) - Full country name

• date_of_birth string optional

  Birth date in YYYY-MM-DD format.

• gender string optional

  One of male, female, non_binary, prefer_not_to_say, or unknown.

• type string optional

  Member type (e.g. staff, member, prospect).

• tags array optional

  Quick helper strings or texts to categorise and identify specific members (e.g. ["vip", "personal-training", "student"]).

• membership_status string optional

  Current membership status (e.g., active, expired, on_hold).

• membership_plans array optional

  Array of membership plans associated with the member.

• profile_picture string optional

  Base64-encoded profile picture (optional).

• created string optional

  ISO 8601 timestamp when the member was created.

• updated string optional

  ISO 8601 timestamp when the member was last updated.

Save a member

Creates or updates member records. The API determines whether to create or update based on the member_id.

Parameters

• members array required

  Array of Member objects to save. Recommended maximum: 1000 items per request for optimal performance. The API automatically batches items for processing. Each item must include either facility_id (required if not using linking_identifier) or linking_identifier (required if not using facility_id).

Returns

Returns a simple message confirming the sync operation.

Check-Ins

Represents a record of a person being present at a facility, class, or activity. Used for tracking attendance, usage analytics, and improving visual detection accuracy.

The Check-In object

Attributes

• check_in_id string optional

  Unique identifier for the check-in. Optional - auto-generated from member_id and timestamp pair if not provided.

• member_id string required

  Unique identifier of the member.

• facility_id string either/orProvide the facility identifier type configured for your integration: use facility_id for direct-link integrations, or linking_identifier for linking-identifier integrations. Do not send both; the API uses the identifier type configured for your partner account and ignores the other one. Learn more

  Unique identifier of the facility from Performance Hub.

• linking_identifier string either/orProvide the facility identifier type configured for your integration: use facility_id for direct-link integrations, or linking_identifier for linking-identifier integrations. Do not send both; the API uses the identifier type configured for your partner account and ignores the other one. Learn more

  Unique identifier value for each location that the partner uses (e.g., "Branch ID", "Location Code", "Store Number"). Learn more

• check_in_type string optional

  Type of visit. One of member, class, staff, guest, or trial.

• source string optional

  How the check-in was captured. Common values include manual, tag, rfid, kiosk, app. Additional values like door_reader or booking may also be used.

• class_id string optional

  Optional. If tied to a class booking or attendance.

• timestamp string required

  ISO 8601 format timestamp of when the check-in occurred.

Save check-ins

Creates check-in records. The API automatically deduplicates based on member, facility, and timestamp.

Parameters

• check_ins array required

  Array of Check-In objects to save. Recommended maximum: 1000 items per request for optimal performance. The API automatically batches items for processing. Each item must include either facility_id (required if not using linking_identifier) or linking_identifier (required if not using facility_id).

Returns

Returns a simple message confirming the sync operation.

Access Control

The Partner API can trigger Performance Hub Door/Gate Controller hardware for facilities where your integration is enabled.

Use this API when your member management system has already decided that a person is allowed to enter. Performance Hub does not evaluate membership status, access hours, door-zone rules, fraud checks, or suspension logic. Your system remains the authority for those decisions.

The unlock request is synchronous. Performance Hub sends the command to the on-site controller over MQTT and returns 200 only after the device confirms that the relay physically unlocked. Most confirmations should complete in 3-5 seconds. If no confirmation is received within the timeout window, the API returns an explicit failure.

The Door/Gate Controller object

Attributes

• door_id string required

  Unique identifier for the Door/Gate Controller. Store this in your system after discovery and use it when calling the unlock endpoint.

• facility_id string required

  Performance Hub facility ID.

• linking_identifier string optional

  Partner facility identifier when your integration uses linking identifiers. Learn more

• name string required

  Human-readable device name configured in Performance Hub.

• zone string optional

  Door zone or location, such as Entrance.

• status string required

  online or offline.

• relay_state string optional

  Latest known relay state, such as locked or unlocked.

• maintenance_mode string required

  Current maintenance mode. One of off, force-open, or force-closed.

• hold_time_seconds integer required

  Default unlock hold time configured for the door.

• last_seen string optional

  ISO timestamp for the latest device metadata update.

List Door/Gate Controllers

Returns Door/Gate Controllers available to your integration.

If neither facility_id nor linking_identifier is provided, the API returns Door/Gate Controllers across all facilities linked to your partner account.

Parameters

• facility_id string optional either/orProvide the facility identifier type configured for your integration: use facility_id for direct-link integrations, or linking_identifier for linking-identifier integrations. Do not send both; the API uses the identifier type configured for your partner account and ignores the other one. Learn more

  Performance Hub facility ID. Use this for direct-link integrations.

• linking_identifier string optional either/orProvide the facility identifier type configured for your integration: use facility_id for direct-link integrations, or linking_identifier for linking-identifier integrations. Do not send both; the API uses the identifier type configured for your partner account and ignores the other one. Learn more

  Your own facility/location identifier. Use this when your integration is configured for linking identifiers.

Returns

Returns an array of Door/Gate Controller objects.

Get Door/Gate Controller status

Retrieves the latest known state and basic configuration for a single Door/Gate Controller.

Provide a facility identifier so Performance Hub can verify that the door belongs to a facility your integration can access.

Parameters

• door_id string required

  Door/Gate Controller ID returned by the list endpoint.

• facility_id string either/orProvide the facility identifier type configured for your integration: use facility_id for direct-link integrations, or linking_identifier for linking-identifier integrations. Do not send both; the API uses the identifier type configured for your partner account and ignores the other one. Learn more

  Performance Hub facility ID. Required for direct-link integrations.

• linking_identifier string either/orProvide the facility identifier type configured for your integration: use facility_id for direct-link integrations, or linking_identifier for linking-identifier integrations. Do not send both; the API uses the identifier type configured for your partner account and ignores the other one. Learn more

  Partner facility identifier. Required for linking-identifier integrations.

Returns

Returns a Door/Gate Controller object.

Unlock a Door/Gate Controller

Sends an unlock command to the Door/Gate Controller and waits for the physical relay to confirm it has unlocked.

Your system must decide whether the person is authorised before calling this endpoint. Performance Hub only verifies the partner key, facility access, door ownership, and device state.

Parameters

• door_id string required

  Door/Gate Controller ID returned by the list endpoint.

• facility_id string either/orProvide the facility identifier type configured for your integration: use facility_id for direct-link integrations, or linking_identifier for linking-identifier integrations. Do not send both; the API uses the identifier type configured for your partner account and ignores the other one. Learn more

  Performance Hub facility ID. Required for direct-link integrations.

• linking_identifier string either/orProvide the facility identifier type configured for your integration: use facility_id for direct-link integrations, or linking_identifier for linking-identifier integrations. Do not send both; the API uses the identifier type configured for your partner account and ignores the other one. Learn more

  Partner facility identifier. Required for linking-identifier integrations.

• member_id string required

  Partner member ID. This is used for audit logging and later data linking.

• first_name string required

  First name of the person opening the door.

• last_name string required

  Last name of the person opening the door.

• full_name string optional

  Optional. If omitted, Performance Hub combines first_name and last_name.

• check_in_id string optional

  Optional check-in ID from your system for correlation.

• idempotency_key string optional

  Optional replay-protection key. Reusing the same key for the same partner, facility, and door returns the existing result when available.

Returns

Returns 200 only when the device confirms the relay physically unlocked. The door uses the hold time configured in Performance Hub Device Management; partners cannot override relay timing per request. Most confirmations should complete in 3-5 seconds. Treat the documented timeout as an explicit failed unlock and retry only according to your own safety rules.

Common failures:

• 403 integration_not_enabled - your integration is not enabled for the facility.
• 409 maintenance_mode_active - facility staff have enabled maintenance mode for the door.
• 503 device_offline - the Door/Gate Controller is offline or stale.
• 504 unlock_confirmation_timeout - the command was sent but no matching confirmation was received before timeout.

Facility Reports

A point-in-time record capturing key operational and financial metrics for a facility during a specific period.

The Report Snapshot object

Attributes

• facility_id string either/orProvide the facility identifier type configured for your integration: use facility_id for direct-link integrations, or linking_identifier for linking-identifier integrations. Do not send both; the API uses the identifier type configured for your partner account and ignores the other one. Learn more

  Unique identifier of the facility from Performance Hub.

• linking_identifier string either/orProvide the facility identifier type configured for your integration: use facility_id for direct-link integrations, or linking_identifier for linking-identifier integrations. Do not send both; the API uses the identifier type configured for your partner account and ignores the other one. Learn more

  Unique identifier value for each location that the partner uses (e.g., "Branch ID", "Location Code", "Store Number"). Learn more

• start_date string required

  Snapshot period start date in YYYY-MM-DD format.

• end_date string required

  Snapshot period end date in YYYY-MM-DD format.

• metrics object required

  Metrics object containing member and revenue data for the period.

Save report snapshots

Submits operational and financial metrics for a facility during a specific period.

Parameters

• snapshots array required

  Array of Report Snapshot objects to save. Maximum 25 items per request. Each item must include either facility_id (required if not using linking_identifier) or linking_identifier (required if not using facility_id).

Returns

Returns a simple message confirming the sync operation.

Errors

The Partner API uses standard HTTP status codes and JSON response bodies to explain why a request failed.

Error response shape

Most API errors return a JSON body with a message and, where available, structured details.

Status codes

Retry guidance

Retry these with bounded exponential backoff:

• 429
• 500
• 502
• 503
• 504

Do not blindly retry these:

• 400
• 401
• 403
• 404
• 409
• 422

For access control, always treat timeout and offline responses as failed unlocks unless your own access rules and safety processes say otherwise.

Support details to include

When contacting support, include:

• Endpoint and HTTP method.
• Timestamp and timezone.
• Partner key ID, not the secret key.
• Facility identifier used.
• Source record ID from your system.
• Response status and body.
• event_id or command_id where available.

Versioning

The Partner API is versioned in the URL. The current version is:

Change policy

Performance Hub aims to make additive, backward-compatible changes wherever possible.

Examples of backward-compatible changes:

• Adding a new optional field to a request.
• Adding a new field to a response.
• Adding a new endpoint.
• Adding a new enum value where clients are expected to handle unknown values.
• Improving validation messages without changing the status code contract.

Examples of breaking changes:

• Removing or renaming a field.
• Changing the type of a field.
• Making an optional request field required.
• Removing an endpoint.
• Changing the meaning of an existing status code or domain-specific reason.

Deprecations

When a breaking change is required, Performance Hub will avoid changing the existing version in place where possible. Instead, we will introduce a new version or migration path and communicate the change to affected partners.

Deprecation notices can include:

• A changelog entry.
• Direct partner communication.
• Notes in the Partner Console.
• Migration guidance in the docs.

Client recommendations

Build clients that tolerate additive changes:

• Ignore response fields you do not use.
• Treat unknown enum values as unsupported rather than crashing.
• Avoid strict response equality checks.
• Log unrecognized values so you can update your integration intentionally.

OpenAPI specifications

Use the published OpenAPI specifications to generate clients, validate requests, and track API shape changes over time.

See OpenAPI Specifications.

Changelog

This changelog records notable Partner API and Partner Console changes that affect integration behaviour.

2026-05-06

2026-05-01

Change categories

Future entries use these categories:

• Added - new endpoint, field, guide, or capability.
• Changed - behaviour or documentation changed without removing support.
• Deprecated - feature remains available but has a planned migration path.
• Removed - feature or endpoint removed.
• Fixed - bug fix or documentation correction.
• Security - authentication, authorization, data handling, or key-management change.