Barcode Check-In API Documentation

Overview

This endpoint is used to check customers into a location using their assigned barcodes. This is a write-only endpoint, and it only accepts POST requests.

Parameters

The barcode check-in endpoint accepts two parameters: barcode and location_id.

barcode
This is the barcode of the customer who will be checked in. This parameter is placed in the URL as follows:
https://api.hellocapitan.com/api/gym-endpoints/barcode-check-in/<barcode>/

location_id
This is placed in the body of the request, as a JSON object with one field. This field is optional, and unnecessary for single-location organizations. For multiple-location organizations, the endpoint will default to the requesting user's location if a location is not provided.

Fields (Success)

A successful check-in will result in a 200 response containing a JSON object with the following fields.

Name Type Description
id integer The unique identifier of the created check-in.
customer_id integer The unique identifier of the customer who was checked in.
customer_first_name string The customer's first name.
customer_last_name string The customer's last name.
customer_email string (email address) The customer's email address. This will be null if the customer does not have an email address on file.
entry_method string Which type of entry method (membership, entry pass, etc.) was used for this check-in. See the entry method values list for the possible values this can take.
entry_method_description string A human-readable description of the check-in's entry method, such as "Monthly Membership" or "10-Punch Pass".
milestones string The text of any milestones associated with the check-in. If multiple milestones apply, they will be separated by a newline character.
check_in_count integer The total number of check-ins this customer has performed, including this one.
has_any_automatic_check_ins boolean Whether the customer was automatically checked in to any events as part of this location check-in.
has_any_challenges_completed boolean Whether the customer completed any challenges with this check-in. If true, the challenges will be listed in the milestones string.
customer_alerts list of JSON objects The list of the customer's active alerts, if any. Alerts may be intended for internal use and should not generally be displayed to the customer. See the alert object section for more information.
reservations list of JSON objects The list of the customer's event reservations which are happening now, if any.
association_memberships_pending_reverification list of JSON objects The list of the customer's association memberships which are pending reverification.

Entry Method Values

Value Name Description
MEM Membership A membership was used for entry.
ENT Entry Pass An entry pass, either single- or multiple-use, was used for entry.
EVE Event Reservation The customer held an event reservation which also included entry into the location.
GUE Guest Pass The customer was checked in using another customer's guest pass.
FRE Free Entry The customer was granted free entry by a staff member.
MIG Migrated Data This check-in was migrated from another software platform. This value is only used for historical data, and should not be returned from this endpoint.

Customer Alert Object

The customer_alerts value is a list of JSON objects representing alerts added to the customer account by staff. Alerts may be intended for internal use and should not generally be displayed to the customer. Each alert object has the following fields.

Name Type Description
alert_text string The text of the alert.
created_date string (ISO-8601 date) When the alert was created.
color_hex string (6-character hex value) The color of the alert, chosen by the staff member who created it.
prevents_check_in boolean Whether the alert prevents the customer from checking in. This should always be false when included with a successful check-in response.

Fields (Failure)

A failed check-in will result in a 400 or 404 response containing a JSON object with the following fields.

Name Type Description
error string A string designating which error type prevented check-in. See the error values list for the possible values this can take.
alerts list of strings A list of strings describing the reason or reasons that the customer could not be checked in. Unlike the staff-created customer_alerts field, these alerts should be displayed to the customer, in order to explain why they cannot be checked in.
customer_id integer The unique identifier of the customer whose barcode was provided. Not included for 404 errors.
customer_first_name string The customer's first name. Not included for 404 errors.
customer_last_name string The customer's last name. Not included for 404 errors.
customer_email string (email address) The customer's email address. This will be null if the customer does not have an email address on file. Not included for 404 errors.

Error Values

Value Description
customer_not_found No active customer account was found for the provided barcode.
invalid_location No location was found for the provided location ID.
check_in_alerts The customer could not be checked in because one or more alerts prevented check-in. The individual alerts can be accessed using the alerts field.
duplicate_check_in The customer was already checked in in the last 5 minutes.
no_entry_method The customer did not have an available entry method. This includes cases such as an expired membership, a multiple-entry pass with no entries remaining, a time-limited membership which does not include the current time, or a combination of multiple entry methods which all are not available for various reasons.

Examples

Success

Request
POST /api/gym-endpoints/barcode-check-in/abc1234567890/

Response
200 OK
{
    "id": 17,
    "customer_id": 13,
    "customer_first_name": "Buzz",
    "customer_last_name": "Aldrin",
    "customer_email": "buzz@example.com",
    "entry_method": "MEM"
    "entry_method_description": "Single Monthly Membership",
    "milestones": "",
    "check_in_count": 7,
    "has_any_automatic_check_ins": false,
    "has_any_challenges_completed": false,
    "customer_alerts": [
        {
            "alert_text": "This is an alert.",
            "created_date": "2023-12-08",
            "color_hex": "a52a2a",
            "prevents_check_in": false
        }
    ],
    "reservations": [],
    "association_memberships_pending_reverification": []
}

Failure (Barcode Not Found)

Request
POST /api/gym-endpoints/barcode-check-in/abc12345678901234/

Response
404 Not Found
{
    "error": "customer_not_found"
}

Failure (No Waiver)

Request
POST /api/gym-endpoints/barcode-check-in/abc1234567890/

Response
400 Bad Request
{
    "error": "check_in_alerts",
    "alerts": [
        "No waiver."
    ],
    "customer_id": 13,
    "customer_first_name": "Buzz",
    "customer_last_name": "Aldrin",
    "customer_email": "buzz@example.com"
}

Failure (No Entry Method)

Request
POST /api/gym-endpoints/barcode-check-in/abc1234567890/

Response
400 Bad Request
{
    "error": "no_entry_method",
    "customer_id": 13,
    "customer_first_name": "Buzz",
    "customer_last_name": "Aldrin",
    "customer_email": "buzz@example.com"
}