Check-in events

When a member opens a door with HybridAF, HybridAF can tell your system. It sends one HTTPS request to an address you host for each successful door open, so you can record the visit against the member. This page describes that request and how to answer it.

How it works

Your system hosts a receiving address. HybridAF calls it, and you do not call HybridAF to get these events. The flow for each door open:

  1. A member unlocks a door through HybridAF.
  2. HybridAF sends a POST to the address configured for that facility, with the details of the event in a JSON body.
  3. Your system records the visit and answers with a success status.

HybridAF sends events only for doors that opened. It sends nothing when a member is turned away. The facility must also have check-in sending switched on, which HybridAF support does when it sets up your address.

The request

Each event is one HTTP request.

PartValue
MethodPOST
AddressThe address you gave HybridAF support for the facility.
Content typeapplication/json
AuthorizationBearer followed by your token, sent only when you gave HybridAF a token. With no token, the header is left out.

The body is a JSON object with one property, event. This is an event for a normal unlock:

{
  "event": {
    "facilityUid": "3f2b8c1e-5d4a-4e7b-9c1d-0a6e2f7b8d41",
    "checkInStatus": true,
    "checkInIsEmergency": false,
    "userExternalId": "MEMBER-1042",
    "userFullName": "Jordan Example",
    "userEmail": "jordan@example.com",
    "locationId": "front-door",
    "locationName": "Example Fitness",
    "doorId": 1187,
    "doorName": "Front door",
    "classId": null,
    "accessReason": [],
    "accessDateTime": "2026-11-16T14:05:32+00:00",
    "doorAccessCorrelationId": 90412
  }
}

For emergency access the two emergency fields change. Everything else keeps the same shape:

"checkInIsEmergency": true,
"accessReason": ["Emergency", "Forgot to book a class"],

Fields

Every field is always present. A value HybridAF does not have is null where the table says so.

FieldTypeDescription
facilityUidGUIDThe facility the door belongs to. The same UID you use on the facility users API.
checkInStatusbooleanAlways true. HybridAF does not send events for doors that did not open.
checkInIsEmergencybooleantrue when the member got in through emergency access. false for a normal unlock.
userExternalIdstringThe userExternalId you sent for this member. Use it to find the member in your system.
userFullNamestringThe member’s first and last name as HybridAF holds them.
userEmailstringThe member’s email address as HybridAF holds it.
locationIdstringThe ID for the door as set up for your integration.
locationNamestring or nullThe facility name for the door. null when HybridAF has none.
doorIdintegerThe HybridAF ID for the door.
doorNamestring or nullThe door’s display name. null when HybridAF has none.
classIdstring or nullThe reservation ID when the member opened the door with a class reservation. null otherwise.
accessReasonarray of stringsAn empty array for a normal unlock. For emergency access, two entries: the word Emergency, then the reason the member gave.
accessDateTimestringWhen the door opened, in UTC, as an ISO 8601 date and time with an offset.
doorAccessCorrelationIdintegerThe HybridAF ID for this door event. It is different for every event, so you can use it to spot a repeat delivery.

Responding

Answer with any 2xx status. HybridAF does not read the response body, so an empty 200 or 204 is fine.

  • A 2xx status marks the event as delivered.
  • A 429 status makes HybridAF wait and try once more. It waits for the number of seconds in a Retry-After header when you send one, and otherwise a few seconds.
  • Any other status marks the delivery as failed and is not retried by that send. Fix the receiving address, then ask HybridAF support to check the facility's recent events.

Use doorAccessCorrelationId to ignore an event you have already stored. The member's door has already opened by the time you receive the event, so a slow or failing receiver never keeps a member out.

Setup and testing

Contact HybridAF support with the address that should receive events for each facility and, if you want one, the bearer token. Use an HTTPS address. HybridAF support sets it up per facility, so each facility you connect needs its own request, even when the address is the same.

Before you ask, test your receiver with a request shaped like the real one:

curl -i -X POST "https://your-host.example.com/hybridaf/check-ins" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer <your-token>" \
  -d '{"event":{"facilityUid":"3f2b8c1e-5d4a-4e7b-9c1d-0a6e2f7b8d41","checkInStatus":true,"checkInIsEmergency":false,"userExternalId":"MEMBER-1042","userFullName":"Jordan Example","userEmail":"jordan@example.com","locationId":"front-door","locationName":"Example Fitness","doorId":1187,"doorName":"Front door","classId":null,"accessReason":[],"accessDateTime":"2026-11-16T14:05:32+00:00","doorAccessCorrelationId":90412}}'

The receiver should answer with a 2xx status. Check that your system finds the member from userExternalId, which is the same ID you send through the facility users API.

Questions about check-in events: contact HybridAF support or call 844-927-4313.