EZFacility API FAQs

General

Q: What is the EZFacility API?

A: The EZFacility API is a RESTful interface that gives you programmatic access to your EZFacility account data. You can retrieve and manage information such as members, schedules, billing records, and facility details to build integrations or automate workflows.

Q: Who can use the EZFacility API?

A: API access is available to EZFacility customers on eligible plans. Both developers building integrations and business users working alongside a development team can take advantage of the API.

Q: How do I get access to the API?

A: Contact your EZFacility Account Manager to learn about available plans and pricing that include API access. They can walk you through your options and get your account enabled.

Q: Does the API support webhooks or event triggers?

A: No. The EZFacility API does not currently support webhooks or event-based triggers. All data must be retrieved by making direct API requests (polling). If this is a requirement for your integration, please speak with your Account Manager about future roadmap options.

Q: Where can I find the API documentation?

A: Two reference resources are available to help you build your integration:

Swagger / API Reference: [Insert Swagger Doc URL here]

Code Examples & Guides: [Insert Examples Doc URL here]

Contact api-support@ezfacility.com if you need help accessing either resource.

Authentication & Setup

Q: How does authentication work?

A: The EZFacility API uses the OAuth 2.0 Resource Owner Password Credentials (ROPC) flow. Authentication requires two sets of credentials:

• Application credentials — your Client ID and Client Secret, found in your Developer Portal
• User credentials — the username and password of a user account from the system indicated by your chosen scope. The scope determines which platform the user credentials must come from: realm:tms for a TMS/EZFacility user, realm:self_service for a Self Service user, realm:ezleagues for an EZLeagues user, or realm:none if no user credentials are required (username and password can be left blank)

Once you successfully authenticate, the response will contain an access_token and a refresh_token. The access_token is the bearer token you pass in the Authorization header of every subsequent API call. The refresh_token can be used to obtain a new access token once the current one expires, without needing to provide user credentials again — see "How long do access tokens last?" for more detail.

Q: How do I obtain my API credentials?

A: Once your Account Manager confirms your account is eligible for API access, you will receive an email with credentials for your Developer Portal. There are three separate sets of credentials to understand:

1. Developer Portal credentials

• Used only to log in to the Developer Portal where you can look up your Client ID and Client Secret
• These credentials are not used in API authentication and cannot be used to make API calls

2. Sandbox credentials (if applicable)

• A separate login provided for testing purposes only
• Grants access to a shared test location (Location ID: 10504)
• There is no connection to your production data — changes made in the sandbox have no effect on your live EZFacility account

3. Production API user

• To authenticate against the production API, you must create a dedicated user account within your EZFacility account
• The username and password of that user, combined with your Client ID and Client Secret from the Developer Portal, are the credentials you will use to authenticate and obtain a bearer token

Q: How do I get an access token?

A: To request a token, you will need your Client ID, Client Secret, and the credentials of the user account for the appropriate scope. 

Follow these steps:

Step 1 — Encode your application credentials

• Concatenate your Client ID and Client Secret with a colon: clientId:clientSecret
• Base64-encode the resulting string

Example:

Client ID:      d53cda87

Client Secret:  6ea16cd986eee2c8acbf337d0f519010

Concatenated:   d53cda87:6ea16cd986eee2c8acbf337d0f519010

Base64-encoded: ZDUzY2RhODc6NmVhMTZjZDk4NmVlZTJjOGFjYmYzMzdkMGY1MTkwMTA=

Step 2 — POST to the token endpoint

• Set the Authorization header to: Basic {base64-encoded string}
• Set the scope to the appropriate realm: realm:tms, realm:self_service, realm:ezleagues, or realm:none
• For realm:none, username and password can be left blank

Request:

POST https://api.ezfacility.com/token

Content-Type:  application/x-www-form-urlencoded

Accept:        application/json

Authorization: Basic ZDUzY2RhODc6NmVhMTZjZDk4NmVlZTJjOGFjYmYzMzdkMGY1MTkwMTA=

grant_type=password&username=john.doe&password=123456789&scope=realm:self_service

Step 3 — Use the token in API calls

A successful response returns both an access_token and a refresh_token, along with an expires_in field indicating how many seconds the access token is valid for. Pass the access_token as the bearer token in the Authorization header of every API request:

Successful token response:

HTTP/1.1 200 OK

Content-Type: application/json;charset=UTF-8

{"access_token":"WyLA11-Zbvf5C8-ngqHm4KWJdkv...ZW1xbCyeZ",

 "refresh_token":"eyJhbGciOiJSUzI1NiJ9...dGVzdA==",

 "expires_in":86400,

 "token_type":"bearer"}

Example API call using your token:

GET https://api.ezfacility.com/v2/sessions/123456

Authorization: Bearer WyLA11-Zbvf5C8-ngqHm4KWJdkv...ZW1xbCyeZ

Accept:        application/json

Q: How long do access tokens last?

A: Access tokens are currently valid for 24 hours. The exact expiration is returned as the expires_in field in the token response (in seconds), so you should always read this value rather than assuming a fixed duration, as it may change in the future.

When an access token expires, you have two options:

• Request a new token — re-authenticate using your Client ID, Client Secret, and user credentials
• Use the refresh token — the refresh_token returned during authentication can be used to obtain a new access token using only your application credentials (Client ID and Client Secret), without requiring the user to log in again. Refresh tokens are valid for up to 30 days.

Using refresh tokens can be useful when building systems where you do not want users to have to re-authenticate frequently. However, refresh tokens must be stored and handled securely. If a refresh token leaks along with your application credentials, an attacker could mint new 24-hour access tokens for up to 30 days without ever knowing the user's password.

Q: What should I do if my credentials are compromised?

A: Contact api-support@ezfacility.com immediately. Take the following steps as quickly as possible:

• Notify the support team so your Client ID and Client Secret can be revoked and reissued
• Change the password of the EZFacility user account used for API authentication
• Revoke any active refresh tokens if possible

Do not continue using any credentials that may have been exposed.

Testing & Getting Started

Q: Is there a sandbox environment for testing?

A: Yes. EZFacility provides a sandbox environment so you can develop and test your integration safely without affecting live account data. It is strongly recommended to complete all testing in the sandbox before moving to production.

To request sandbox access, contact api-support@ezfacility.com.

Q: What do I need before making my first API call?

A: Before making your first call you will need:

• An active EZFacility account with API access enabled
• OAuth 2.0 credentials (Client ID and Client Secret) from your Developer Portal
• A valid access token obtained from the token endpoint
• Familiarity with REST APIs and HTTP requests (for the developer on your team)
• Access to the Swagger reference and examples documentation (links above)

Q: How do I structure an API request?

A: Each API call requires the following:

• The endpoint URL for the data you want to access
• An HTTP method — GET to retrieve data, POST to create, PUT to update, DELETE to remove
• An Authorization header containing your access token (Bearer {your_token})
• Any required query parameters or a JSON request body, as described in the Swagger docs

Q: How does paging work for large result sets?

A: Some endpoints implement paging when results may be large. Use the ez-page-number request header to specify which page to retrieve, starting at 1.

Every paging endpoint returns these response headers:

• ez-total-count — total number of objects across all pages
• ez-per-page — maximum objects returned per page (usually 100)
• ez-total-pages — total number of available pages
• ez-current-page — the page number returned (mirrors your ez-page-number request)

When ez-total-pages is greater than 1, repeat the same request while incrementing ez-page-number until all pages are retrieved. Requesting a page number beyond ez-total-pages will return an empty result set rather than an error.

Support & Resources

Q: How do I get help with the API?

A: Reach out to the EZFacility API support team at api-support@ezfacility.com. To help us assist you quickly, please include:

• Your account name and contact information
• A clear description of the issue or question
• The endpoint or feature you are working with
• Any error codes or response messages you received
• The full API request and full API response if you have them — this is extremely helpful for diagnosing issues. Please review before sending to ensure they do not contain any personally identifiable information (PII) such as member names, email addresses, or other sensitive data

Q: What are the expected support response times?

A: The support team aims to respond within one business day. For urgent production issues, include "URGENT" in your email subject line to help prioritize your request.

Q: Will I be notified of API changes or updates?

A: Yes. Breaking changes, deprecations, and major updates are communicated in advance via email. Ensure the address on your EZFacility account is current so you receive these notifications.

Q: Who do I contact about plans and pricing?

A: For information on plans, pricing, and upgrading your API access, contact your EZFacility Account Manager directly. They can help identify the right option for your use case.