Overview

Custom User Fields give your club up to 10 additional text fields on every user record (prospects, leads, and members). You choose what each field is called, who on your staff can see it, and who can edit it.

They were built to solve a common problem: when leads come into Club OS from an outside source — a web form, a marketing campaign, a referral partner, or a franchise portal — that source often sends extra information that doesn't fit any existing Club OS field. Instead of dropping that information into a note or overloading your Marketing Source list, it can now be stored in a dedicated field on the user record.

Common uses include:

• Campaign identifiers (UTM-style values) from third-party lead sources
• Affiliate or referral partner names
• "Lead intent" or product interest captured on an external form
• Region or location codes for franchise reporting
• Any other partner-provided detail you want visible to your sales team

Custom User Fields are optional. Until a club admin sets them up, nothing changes in your day-to-day workflow. Values can also be sent in through the Club OS API by an integration partner, whether or not you've set up labels yet.

Before You Begin

Setting up Custom User Fields requires an unrestricted Club Admin login. Front desk staff, trainers, and restricted admins can see and edit the fields on a user record (based on how they're configured) but cannot change the field setup itself.

Setting Up Your Custom Fields

1. Log in to Club OS as a Club Admin.
2. In the left navigation, go to My Club (or Settings) → Admin settings.
3. Select the Custom fields tab, to the right of Memberships.
4. You'll see the Club Custom User Fields section with 10 rows — Custom Field 1 Label through Custom Field 10 Label.
5. Fill in the settings for each field you want to use (see below).
6. Click Save.

Field settings explained

Each of the 10 rows has three settings:

A few things to know about saving:

• Whatever is in each Label box when you click Save becomes the stored label. If you clear a label and save, the previous label is removed.
• Checkbox changes save at the same time as labels — one Save covers the whole page.
• When you return to the tab later, your saved labels and checkbox settings load automatically.

Where Custom Fields Appear on a User Record

Visible custom fields appear on the Prospect Details / user prospecting page, below the Interests section and above Referred By.

Fields display in numerical order, left to right, with a maximum of five fields per row, and they reflow as your browser window changes size.

How the two checkboxes work together

Hiding a field never deletes the data behind it. The value stays on the user record and can still be retrieved through the API.

Saving changes from a user record

When a staff member clicks Save Details on the prospecting page:

• Any custom field marked Staff Editable saves along with the rest of the page.
• Any read-only (non-editable) field is left untouched, even though it's on screen.

Field Rules and Limits

• Number of fields: 10 per club.
• Field type: text only.
• Label length: up to 30 characters.
• Value length: up to 255 characters.
• Display length: the first 30 characters of a value are shown in the input. You can click into the field and use your mouse, arrow keys, or Ctrl/Cmd+A to move through the full value.
• Required? No. All custom fields are optional and default to empty.

Sending Custom Field Data Through the API

If you work with an integration partner or send leads into Club OS through the API, custom field values can be included directly in the request. This is what makes campaign and attribution data arrive already attached to the lead.

Custom field values are passed as a customFields array supporting customField1 through customField10:

"customFields": [
  {
    "key": "customField1",
    "label": "Campaign ID",
    "value": "SUMMER2026"
  },
  {
    "key": "customField2",
    "label": "Referral Partner",
    "value": "GymPass"
  }
]

Creating a user — POST /users

Include the customFields array in the request body when adding a user to Club OS. The array is entirely optional: a POST without it works exactly as it always has.

Updating a user — PUT /users

Include the customFields array to update values on an existing user. If you send a key and label but no value (or a null value), the existing stored value is left unchanged.

Retrieving values — GET /users

Custom fields are not returned by default. Add the optional query parameter includeCustomFields=true to GET /users or GET /users/{id}:

GET /api/v3/users/{id}?includeCustomFields=true

The response then includes the customFields array with key, label, and value for each field. When the parameter is omitted, set to false, or given an invalid value, the array is left out of the response.

If a field has a stored value but no label, the response still returns the key and value. If a field has a label but no value, the response still returns the key and label.

Error handling

Standard Club OS API validation and error handling apply. One custom validation is specific to this feature — sending a label and value without a key:

{
  "timestamp": "2026-03-12T00:27:43.907+00:00",
  "status": "BAD_REQUEST",
  "error": "Bad Request",
  "messages": {
    "code": "INVALID_FORMAT",
    "message": "Customfield key is required"
  }
}

What Happens in Special Scenarios

No labels have been set up yet, but a partner sends values through the API. The values are stored successfully. API calls work regardless of whether labels have been configured in Admin settings. Fields with no label display as "Custom Field 1", "Custom Field 2", and so on if they're marked Staff Visible.

A field is marked visible but has no value for that user. The label displays with an empty input box.

A field is hidden after data has already been collected. The data is retained. It simply isn't displayed, and saving other changes on the user record won't alter it. Turn Staff Visible back on to see it again.

A staff member tries to edit a read-only field. The input is disabled — it can't be typed into, and clicking Save Details makes no change to it.

A value longer than 255 characters is sent. Standard API validation applies. Keep values within the 255 character limit.

Frequently Asked Questions

Can I use these fields on members, not just leads? Yes. Custom User Fields live on the user record, so they apply to prospects, leads, and members alike.

Can I rename a field after we've started using it? Yes. Change the Label in Admin settings and click Save. The label is just a display name — renaming it does not change or clear any stored values.

Do I have to use all 10 fields? No. Leave any field's Label blank and Staff Visible unchecked and it won't appear anywhere in the UI.

Can staff change the field names? No. Only an unrestricted Club Admin can change labels and visibility settings in Admin settings. Staff can only edit values, and only on fields marked Staff Editable.

Can a partner overwrite the label we chose? No. The API can only set values. The label property is accepted in requests for readability but is never used to create or change your configured labels.

Will custom fields show up in my reports and exports? Not yet. Reporting and export support is planned — see Coming Soon below. Today, values are visible on the user record and retrievable via the API.

Are these fields required? No. All 10 are optional and default to empty.