API V1 - Prospect Services – Club OS Help Center

Important Note: API V1 is no longer the recommended API when integrating with Club OS. To build a new integration, please refer to our API v3 Documentation for the most up to date APIs and documentation.

Available Services

Service Name	Description
/prospects	Add and update prospects.
/referrals	Add referrals to existing members.

GET /prospects

Verifies that the given prospect userId exists in Club OS and you have access to it.

GET https://api.club-os.com/prospects?clubLocationId=[clubLocationId]&userId=[userId]

Parameters

The following fields must be included as parameters in the URL of the request.

Variable	Type	Description
clubLocationId	Integer	The Club OS unique id for the club location you wish to access. Club OS will provide these to you.
userId	Integer	The Club OS unique id for the prospect you are requesting.

Response Message

The following message will be returned when the request succeeds.

Message	Description
Prospect was found	The prospect was found and you have access to them.

POST /prospects

Add a prospect to the system.

POST https://api.club-os.com/prospects?clubLocationId=[clubLocationId]

Parameters

The following fields must be included as parameters in the URL of the request.

Variable	Type	Description
clubLocationId	Integer	The Club OS unique id for the club location you wish to access. Club OS will provide these to you.

Request Body

The following fields must be included in the body of the HTTP request as a valid JSON string.

Property	Type	Required	Default	Description
address1	String	N		Prospect address line 1.
address2	String	N		Prospect address line 2.
barcode	String	N		The barcode of the prospect
billingSystemId	String	N		The id of the prospect that was created by the integrated billing system.
birthDate	Date (M-d-YYYY)	N		Prospect date of birth.
city	String	N		Prospect full city.
dontPushToBillingSystem	Boolean	N	false	If set to true, Club OS will not sync this prospect to the integrated billing system.
email	String	C		Prospect email address. Email or 1 phone number is required.
emailOptOut	Boolean	N	false	If true, the prospect will be opted out of email.
firstName	String	Y		Prospect first name.
gender	String	N	M	'M' for male, 'F' for female.
guestPassEnd	Date (M-d-YYYY)	N		The end date of the prospect's guest pass.
guestPassStart	Date (M-d-YYYY)	N		The start date of the prospect's guest pass.
homePhone	String	C		Prospect home phone number with no formatting (e.g. 5555555555). Email or 1 phone number is required.
ignorePhoneNumberMatching	Boolean	N	false	If true, phone numbers will not be used to lookup an existing prospect.
interests	String[]	N		Array of Strings that should match the interests in your Club OS account. Ideal for content marketing. Example: ["Personal Training","Smoothies","Tanning"]
lastName	String	Y		Prospect last name.
mobilePhone	String	C		Prospect mobile phone number with no formatting (e.g. 5555555555). Email or 1 phone number is required.
notes	String	N		Optional notes about the prospect.
salespersonId	Integer	N		The Club OS unique ID for the salesperson of the prospect being added. This salesperson will be assigned for the prospect's follow-up.
sendCampaignResponseEmail	Boolean	N	false	Send a campaign response email to this prospect. Only applies if the club is setup to receive these within Club OS.
sendPresaleResponseEmail	Boolean	N	false	Send a Presale response email to this prospect. Only applies if the club has this email configured within Club OS.
sendWebleadResponseEmail	Boolean	N	false	Send a Weblead response email to this prospect. Only applies if the club has this email configured within Club OS.
smsOptOut	Boolean	N	false	If true, the prospect will be opted out of text messages.
source	String	N		The marketing source of the prospect, i.e. tv ad, mailer, internet, etc.
state	String	N		Prospect 2 letter state code, i.e. PA for Pennsylvania.
walkIn	Boolean	N		If true, the prospect will be created with an origin of walk-in.
workPhone	String	C		Prospect work phone number with no formatting (e.g. 5555555555). Email or 1 phone number is required.
zip	String	N		Prospect zip code.
originId	Integer	N		The prospects origin. If 'walkIn' is true then origin will always be set to 'Walk In'/ 1. The following values are supported: 1(Walk In), 2(T.I.), 3(Web), 4(Referral), 5(Other), 6(Outreach), 7(Student), 8(Paid Pass), 9(Lost Join), 10(Social Media), 11(Pay as You Go)
originName	string	N		The prospects origin. Can be specified in addition to or in place of the originId. If 'walkIn' is true then origin will always be set to 'Walk In'/ 1. The following values are supported: Walk In, T.I., Web, Referral, Other, Outreach, Student, Paid Pass, Lost Join, Social Media, Pay as You Go

Response Messages

One of the following messages will be returned when the request succeeds.

Message	Description
Prospect Created	Prospect account successfully created.
Prospect Found	Prospect account exists in the system already based on the email, phone number, or name provided.

PUT /prospects

Update an existing prospect. The prospect will be looked up by name, email and phone number(s).

PUT https://api.club-os.com/prospects?clubLocationId=[clubLocationId]

Parameters

The following fields must be included as parameters in the URL of the request.

Variable	Type	Description
clubLocationId	Integer	The Club OS unique id for the club location you wish to access. Club OS will provide these to you.

Request Body

The following fields must be included in the body of the HTTP request as a valid JSON string.

Property	Type	Required	Default	Description
userId	Integer	Y		The Club OS userId of the propspect.
firstName	String	N		Prospect first name.
lastName	String	N		Prospect last name.
email	String	N		Prospect email address.
homePhone	String	N		Prospect home phone number.
workPhone	String	N		Prospect work phone number.
mobilePhone	String	N		Prospect mobile phone number.
notes	String	N		Notes about the prospect.
guestPassStart	Date (M-d-YYYY)	N		The new start date of the prospect's guest pass.
guestPassEnd	Date (M-d-YYYY)	N		The new end date of the prospect's guest pass.
smsOptOut	Boolean	N	false	If true, the prospect will be opted out of text messages.
emailOptOut	Boolean	N	false	If true, the prospect will be opted out of email.

Response Messages

One of the following messages will be returned when the request succeeds.

Message	Description
Notes have been added.	Notes were successfully added to the prospect's account.
Prospect Not Found	Prospect account was not found based on name, email, and phone number lookup.

POST /referrals

Add a referral to the system. Referrals will only be added if they are not already in the system. We match based on email or phone number; if no email is provided and the phone number is invalid, we will reject the record and not add the user.

The memberEmail must be attached to a member within a club in which you are authorized.

POST https://api.club-os.com/referrals

Request Body

The following fields must be included in the body of the HTTP request as a valid JSON string.

Property	Sub-Properties	Type	Required	Default	Description
memberEmail		String	C		The email of the member who submitted the referrals. Required if memberUserId is not provided.
memberUserId		Integer	C		The Club OS userId of the member who submitted the referrals. Required if the memberEmail is not provided.
clubLocationId		Integer	Y		The referrals that are added will be created at this club location. The member must also exist at this club location in order for the referral to be added.
salespersonId		Integer	N		The Club OS unique id for the salesperson who collected the referrals. Referrals will be assigned to this salesperson for follow-up.
skipResponseEmails		Boolean	N	false	When set to true, Club OS system and campaign emails will NOT be sent to the referrals or referring members.
referrals					A list of one or more referrals, each having the below properties.
	firstName	String	Y		Referral first name.
	lastName	String	Y		Referral last name.
	email	String	C		Referral email address. Email or 1 valid phone number is required.
	gender	String	N	M	'M' for male, 'F' for female.
	homePhone	String	C		Referral home phone number. Email or 1 valid phone number is required.
	workPhone	String	C		Referral work phone number. Email or 1 valid phone number is required.
	mobilePhone	String	C		Referral mobile phone number. Email or 1 valid phone number is required.
	source	String	N		The marketing source of the Referral, i.e. tv ad, mailer, internet, etc.
	relationship	String	N		Free form text that describes the relationship of the referral to the member, "Spouse" for example.
	notes	String	N		Free form text with any additional notes about the prospect. This will show on the referral's prospecting profile.

Response Messages

One of the following messages will be returned when the request succeeds.

Message	Description
Referrals Added	List of ReponseMessages that show the number referrals added, as well as any referrals that weren't added and the reason why
Request Failed	If the memberEmail could not be found, or there were no valid referrals submitted.

How can we help?