What is an API?
An API will allow you to connect certain applications or have a developer create code to feed/pull data from your Hive.
How to enable the external API
In your Hive admin, visit Settings -> External API Integrations. Enable the API and configure the API key. The base endpoint url will be displayed below the API key. Every Hive's API base endpoint url is unique.
Configure the remaining settings in this area to enable the portions of the API you would like to be available externally.
About the API
The API is a restful http api. Responses from the API will use standard http status codes and return a json body.
Authenticating requests to the API
Every call to the API must be authenticated with your unique API key. Set the "X-API-KEY" http header on all requests with your API key.
API Responses
The API response body will be a json object with a minimum set of status indication fields for success (boolean) to explicitly indicate whether the result operation was successful and message (string/text) which will include any response message for the operation (typically used for error messages when success is false).
Specific Endpoints
/test
If you would like to test the API to verify that you are able to authenticate and parse the response body, create a call to /test on your base endpoint url.
/contact
This endpoint will allow you to push contacts into your hive from external sources. Use the http POST method with application/x-www-form-urlencoded post body
Attributes/Parameters of Post body
email string (required)
Unique email address for the contact to be created on your hive. If email already exists in your hive a new contact will not be created.
first_name string (optional)
First name to be put on the contact
last_name string (optional)
Last name for the contact
phone string (optional)
Phone number for the contact
tags string, comma delimited (optional)
Comma delimited list of tags to be added on the contact (when email exists for a contact, these tags will get added to the existing contact).
test integer (optional)
Boolean 1 or 0 value. When truthy no contacts will be created, but the fields submitted will be validated
/attendance
This endpoint will allow you to pull general attendance records from your hive. Use the http POST method with application/x-www-form-urlencoded post body
Attributes/Parameters of Post body
start integer unix timestamp (required)
Unix timestamp representing the start date of the range to pull attendance records for
end integer unix timestamp (required)
Unix timestamp representing the end date of the range to pull attendance records for
page integer (optional, default 1)
Page number to retrieve for the paginated set, defaults to first page
Response (json) will contain standard response fields (success and message)
next_page integer or falsey
Falsey value if there are no more pages to retrieve, otherwise integer page number of the next page in the paginated set
results array
Array of result objects in format
day integer unix timestamp
Unix timestamp representing the day/date of the attendance record, will always have time/minute set to noon as this only represents the date and not the time.
created_time integer unix timestamp
Unix timestamp of the record creation date, usually coincides with day
user_id integer
System user id number for the specific user
first_name string
First name of the user
last_name string
Last name of the user
email string
Email of the users (unique among users)
/schedule
This endpoint will allow you to retrieve scheduled classes (inactive/cancelled classes will not be returned). Use the http GET method with query string / url params
URL parameters / Query String
start integer unix timestamp (required)
Unix timestamp representing the start time of the range to pull classes for. Will retrieve classes that have a class start time at/after start time provided.
end integer unix timestamp (required)
Unix timestamp representing the end time of the range to pull classes for. Will retrieve classes that have a start time at/before end time provided.
*If neither start or end is provided, start will default to today 12am hive timezone and end will default to 7 days from that start time 11:59:59pm. If either start or end is provided, then both will be required
schedule_class_id integer (optional)
Class id to filter results to. Integer, if not provided will show all classes.
schedule_class_type_id integer (optional)
Class type id to filter results to. Integer, if not provided will show all class types.
page integer (optional, default 1)
Page number to retrieve for the paginated set, defaults to first page
Response (json) will contain standard response fields (success and message) along with the following additional fields:
next_page integer or falsey
Falsey value if there are no more pages to retrieve, otherwise integer page number of the next page in the paginated set
results array
Array of result for the scheduled events/times in format below
schedule_event_id integer
Unique Integer ID for the event/instance
schedule_class_id integer
Unique Integer ID for the class grouping, may be blank/falsey if none selected for the class
schedule_class_name string
String name for the class, may be blank/falsey if none selected for the class
schedule_class_type_id integer
Unique Integer ID for the class type, may be blank/falsey if none selected for the class
schedule_class_type_name string
String name for the class type, may be blank/falsey if none selected for the class
when_start integer unix timestamp
Unix timestamp representing the start time of the class
when_end integer unix timestamp
Unix timestamp representing the end time of the class
num_attendees integer
count of attendees currently registered for class (not cancelled)
created_time integer unix timestamp
record creation time, ie the time the class was added to the schedule
registrants array
Array of users registered for the class (cancelled registrants will not be included), with the format below
registration_id integer
System registration id number for the specific registration for this class
user_id integer
System user id number for the specific user
email string
Email of the users (unique among users)
first_name string
First name of the user
last_name string
Last name of the user
dob integer (or null if not provided)
Date of birth formatted YYYYMMDD as an integer. May be null if user has not supplied birth date
gender string (or null if not provided)
M for male, F for female, or null if user has not provided
is_soft_registration integer boolean
boolean, 1 or 0. set to 1 if the user has confirmed/paid for the class
checked_in integer boolean
boolean, 1 or 0. set to 1 if the user has checked in for the class
created_time integer unix timestamp
unix timestamp for the time that the user registered for the class
Example call with cURL
curl -G https://hivespecificdomain/api-extern/schedule \ -H "X-API-KEY: yourapikey" \ -d start=1704092400 \ -d end=1709319599
Example response
{
"success": true,
"message": "",
"next_page": false,
"results": [
{
"schedule_event_id": 600,
"schedule_class_id": 20,
"schedule_class_name": "Cycling",
"schedule_class_type_id": 3,
"schedule_class_type_name": "Cycling",
"when_start": 1706569200,
"when_end": 1706569200,
"num_attendees": 1,
"created_time": 1709241043,
"registrants": [
{
"registration_id": 194,
"user_id": 207,
"email": "bikerider@myfithive.com",
"first_name": "Bike",
"last_name": "Rider",
"dob": 19890220,
"gender": "M",
"is_soft_registration": 0,
"checked_in": 1,
"created_time": 1709241251
}
]
},
...
]
}
Category > Section:Business Management >Settings
