Performance Hub LogoPerformance Hub

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.

Publish Access Time Windows safely

Treat each member's access_time_windows value as a complete, independently revisioned snapshot:

  • Coordinate one monotonically increasing access_time_windows_revision stream across incremental and reconciliation workers.
  • Retry an uncertain or transient delivery with the same revision and normalized payload.
  • Omit access_time_windows when you are not updating it.
  • Send [] only after a successful authoritative source fetch proves that no windows remain. Never turn an upstream timeout, partial result, or parse failure into revocation.
  • Keep external_id and scope_key stable, and certify every scope mapping before production.
  • Monitor source age against the freshness policy agreed for that integration.

See the authoritative Access Time Windows producer guide for complete snapshots, timezones, DST, cancellation, and test vectors.

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.