Facility users API

List the users HybridAF holds for a gym, look one up by email, and send users from your membership system. Authentication and errors are described on the overview.

GET/v1/facilityUsers

Returns every user HybridAF holds for the facility. Add email or userExternalId to narrow the list.

ParameterRequiredTypeDescription
codeYesstringThe function key issued by HybridAF support.
facilityUidYesstring (GUID)The facility identifier. Provided by support team.
subscriberAccessKeyYesstring (GUID)The subscriber key. Provided by support team.
emailNostringReturn only the user with this email address.
userExternalIdNostringReturn only the user with this external ID.

Request

curl -X GET "https://integration.hybridaf.com/api/v1/facilityUsers?code=<function-key>&facilityUid=<facility-uid>&subscriberAccessKey=<subscriber-access-key>"

Response

An array of user objects. The fields are listed under Fields.

[
  {
    "firstName": "Example",
    "lastName": "Member",
    "email": "member@example.com",
    "cellPhone": "5555550100",
    "userExternalId": "ext-0001",
    "isActive": true,
    "facilityOfferConfigs": [
      {
        "facilityOfferActionType": "NameVerify",
        "offeringName": "Open Gym",
        "offeringNameNormalized": "open-gym",
        "externalId": null,
        "startDateTime": "0001-01-01T00:00:00+00:00",
        "endDateTime": "0001-01-01T00:00:00+00:00",
        "hasTimeWindow": false,
        "durationInMinutes": 0
      }
    ],
    "activeStatusReason": null,
    "lastchangeReason": "User from provider added to integration user state. New user added. New user gym association added."
  }
]

GET/v1/facilityUser

Returns one user, found by email address. The answer is 404 when the user is not found.

ParameterRequiredTypeDescription
codeYesstringThe function key issued by HybridAF support.
facilityUidYesstring (GUID)The facility identifier. Provided by support team.
subscriberAccessKeyYesstring (GUID)The subscriber key. Provided by support team.
emailAddressYesstringEmail address of the user to return. A request without it answers 404.

Request

curl -X GET "https://integration.hybridaf.com/api/v1/facilityUser?code=<function-key>&facilityUid=<facility-uid>&subscriberAccessKey=<subscriber-access-key>&emailAddress=member@example.com"

Response

A single user object with the same fields as one element of the list response. The top-level field names in this response start with a capital letter, for example FirstName and Email. Fields inside facilityOfferConfigs keep the lowercase names shown in the field tables.

{
  "FirstName": "Example",
  "LastName": "Member",
  "Email": "member@example.com",
  "CellPhone": null,
  "UserExternalId": "ext-0001",
  "IsActive": true,
  "FacilityOfferConfigs": [
    {
      "facilityOfferActionType": "NameVerify",
      "offeringName": "Open Gym",
      "offeringNameNormalized": "open-gym",
      "externalId": null,
      "startDateTime": "0001-01-01T00:00:00+00:00",
      "endDateTime": "0001-01-01T00:00:00+00:00",
      "hasTimeWindow": false,
      "durationInMinutes": 0
    }
  ],
  "ActiveStatusReason": null,
  "LastchangeReason": "User from provider added to integration user state. New user added. New user gym association added."
}

This route finds a user once HybridAF has added the user to the facility. A user HybridAF has only recorded as inactive, and never added, answers 404. The list route shows those users.

{"status":404,"detail":"User could not be found."}

POST/v1/facilityUser

Creates the user, or updates the user when the email already exists at the facility. Send the user object as the JSON body. firstName, lastName, email and userExternalId are required.

ParameterRequiredTypeDescription
codeYesstringThe function key issued by HybridAF support.
facilityUidYesstring (GUID)The facility identifier. Provided by support team.
subscriberAccessKeyYesstring (GUID)The subscriber key. Provided by support team.

Request body

A JSON object. These four fields are required on every call. The remaining fields, including facilityOfferConfigs, are optional and are described under Fields, the same table the read routes use.

FieldTypeDescription
firstNamestringFirst name. Required when you send a user.
lastNamestringLast name. Required when you send a user.
emailstringEmail address. Required when you send a user. It identifies the user at the facility.
userExternalIdstringYour own ID for the user, so HybridAF can match the record to your system. Required when you send a user.

Request

curl -X POST "https://integration.hybridaf.com/api/v1/facilityUser?code=<function-key>&facilityUid=<facility-uid>&subscriberAccessKey=<subscriber-access-key>" \
  -H "Content-Type: application/json" \
  -d '{
    "firstName": "Example",
    "lastName": "Member",
    "email": "member@example.com",
    "userExternalId": "ext-0001",
    "isActive": true,
    "facilityOfferConfigs": [
      { "facilityOfferActionType": 10000, "offeringName": "Open Gym" }
    ]
  }'

Response

200 when the user was accepted.

{"status":200}

The facility's access method decides whether the user ends up with access, so read the user back to confirm. See How access is decided.

POST/v1/facilityUsers

Accepts an array of user objects in one request. It takes the same query parameters as the single-user POST. Users are processed in order of email address.

  • An empty array is rejected with 400.
  • A request can carry at most 50 users. A larger array is rejected with 400, so split big exports into batches of 50 or fewer.
  • One bad user does not stop the batch.
  • The response is one status for the whole request. A 200 can still include users that failed, and the response does not list them. Send a single user when you need a result per user.

Request body

A JSON array of user objects. Each element follows the same field rules as the single-user POST, including the four required fields. See Fields.

Request

curl -X POST "https://integration.hybridaf.com/api/v1/facilityUsers?code=<function-key>&facilityUid=<facility-uid>&subscriberAccessKey=<subscriber-access-key>" \
  -H "Content-Type: application/json" \
  -d '[
    { "firstName": "Example", "lastName": "Member", "email": "member@example.com", "userExternalId": "ext-0001", "isActive": true, "facilityOfferConfigs": [] },
    { "firstName": "Sample", "lastName": "Athlete", "email": "athlete@example.com", "userExternalId": "ext-0002", "isActive": false, "facilityOfferConfigs": [] }
  ]'

How access is decided

Each facility uses one of two access methods. The method decides which part of the user object HybridAF follows.

  • By user. HybridAF follows isActive. Send true to give the user access and false to take it away. A user who is already active in the HybridAF app stays active.
  • By offering. HybridAF ignores isActive. A user gets access when at least one entry in facilityOfferConfigs has facilityOfferActionType 10000 (name.verify) and an offeringName that matches an enabled offering at the facility, ignoring case. The matching offering cannot have a time window. Entries without that action type are recorded and grant nothing. To take access away, send the user without those entries.

A new user who arrives without access and without any offerings is recorded as inactive and is not added to the facility. After any write, read the user back to confirm the result.

Fields

One reference for every route on this page. The same user object comes back from the read routes and goes in the body of the write routes. "Required on write" marks the fields every POST must carry.

User object

FieldTypeRequired on writeDescription
firstNamestringYesFirst name. Required when you send a user.
lastNamestringYesLast name. Required when you send a user.
emailstringYesEmail address. Required when you send a user. It identifies the user at the facility.
cellPhonestringNoMobile number.
userExternalIdstringYesYour own ID for the user, so HybridAF can match the record to your system. Required when you send a user.
isActivebooleanNotrue if the user should have access. Send false when access should stop. A facility that grants access by offering ignores this field. See How access is decided.
facilityOfferConfigsarray of facilityOfferConfigDtoNoThe offerings the user holds in your system. Each entry can carry a time window. See the offering fields below.
activeStatusReasonstringNoFree text. Why the user is active or inactive.
lastchangeReasonstringNoFree text. Why the record last changed. In the list response and in write requests the name is spelled with a lowercase c, exactly as shown.

Offering object

Each entry in facilityOfferConfigs describes one offering the user holds in your system.

FieldTypeDescription
facilityOfferActionTypeintegerWhat the entry represents. See the action types below. Send 10000 (name.verify) on an entry that should grant access at a facility that grants access by offering. Leave it out for an offering that does not grant access by itself.
offeringNamestringName of the offering as it appears in your system.
offeringNameNormalizedstringCalculated by HybridAF from offeringName. Do not send it.
externalIdstringYour ID for the offering. Optional.
startDateTimestring (ISO 8601 date and time)Start of the access window. Use an ISO 8601 value with an offset, for example 2026-12-01T06:00:00-05:00.
endDateTimestring (ISO 8601 date and time)End of the access window. An entry whose end is already in the past is dropped when the user is received.
hasTimeWindowbooleanCalculated by HybridAF. true when both times are present, the end is after the start, and the action type is not name.verify. Do not send it.
durationInMinutesintegerCalculated by HybridAF from the window. Do not send it.

Action types

facilityOfferActionType is a number when you send it. Responses show the name instead, such as AppointmentScheduled. These are the values in use.

ValueName in responsesMeaning
100AppointmentScheduledappointment.scheduled
200AppointmentReScheduledappointment.rescheduled
300AppointmentCanceledappointment.canceled
10000NameVerifyname.verify
-999999999NotSpecifiedNot Specified

Errors on these routes

Status codes are explained on the overview. These are real responses from these routes.

List or read for a facility HybridAF cannot find

{"status":400,"detail":"Value cannot be null. (Parameter \u0027No facility configuration could be found for facility <facility-uid>\u0027)"}

Read without an email address

{"status":404,"detail":"Email address is required."}

Write for a facility HybridAF cannot find

{"status":400,"detail":"A problem occurred processing the request for facility <facility-uid>. Please report this to support and reference this log id: <log-id>."}

Quote the log ID to support when a response includes one.