¶ Aidoo API Documentation
¶ Preconditions
- In order to use the API and get access to the Aidoo ecosystem, a partnership agreement has to be made with our CEO Burkhard Westermann (westermann@aidoo.de).
- Before launching the integration, any marketing efforts promoting the integration have to be aligned as a partnership campaign with our Head of Communications Jada Bednorz-Dasser (bednorz-dasser@aidoo.de).
¶ Overview
The Aidoo API provides a growing set of highly flexible features for data exchange:
- Gyms
- Members
- Employees
- Contract Types
- Contracts
- Contract Addon Types
- Contract Addons
- Appointment Types
- Appointment Slots
- Appointments
- Login, Email Verify, Passwort change
- Presences, Checkin, Checkout
- Opening Hours
- Observers (Webhooks)
This document serves both as the documentation for the released features as well as a documentation for features that are currently in development. Features are thefore marked with (Released), (Beta) and (Development).
If you encounter problems check the section for common problems!
The Aidoo API is a REST-ful JSON-based API that strives to expose as many Aidoo-features as possible to our partners in a well documented form.
The vision of the API project is to give partners an intuitive and easy to use access to the Aidoo Ecosystem, but in a way that the flexibility, nuances and specialized features of the Aidoo System are preserved. To make this possible, the complex multi-table datastructures of the Aidoo Databases are abstracted into broader, more intuitive entities: Members, Contracts, Gyms, Classes, Bookings and more. These entities live in a graph of foreign-key relationships: Gyms can have multiple Members, Members have multiple contracts etc. Inspired by GraphQL, the API allows to query, insert, update and delete entities in a way, that queries and modifications can be extended to and filtered by properties of related entities along the graph. This is achieved without having the overhead of another complex language like GraphQL, but just by using intuitive parameters and paths in a pure REST-like approach.
Here some examples:
GET specific member
<baseurl>/v2/member/202200012
{
"success": true,
"members": [{... member data ...}]
}
POST new member with a new contract
<baseurl>/v2/members
{
"members": [{
"gym_id": ...,
"name": ...,
...
"contracts": [{
"contract_type_id": ...,
...
}]
}]
}
For now, <baseurl> is https://api.aidoo-online.de:10015.
The port 10015 is currently required for the api to work, we are working to free up the port 443 on the server soon to have a link without the port. (Development)
The API constrains access to features via api key scopes. We want to limit the security risks and therefore expose a minimal sufficient subset of the features to each partner. (Development)
¶ General information
- Every entity has an integer (or sometimes string) field "id" that is unique within the client database along all gyms.
- Each of our clients has their own database so ids are not unique between clients.
- Data is exchanged in the JSON format and the Content-Type Header is required.
- Requests always target a specific entity using the REST methods GET, POST and DELETE.
- Not all entities support all methods.
- Entities can extend to related entites along the entity graph, so a whole tree of different entities can be queried, created or changed
- Batch processing is easily possible, as the data is always packed in a JSON-Array in requests and responses.
- GET allows filters and extensions to related entities along the graph in the url parameters.
- POST requests do not use the url parameters, as the data contains all information necessary.
- POST acts like an upsert, creating data without id specified and updating data having an id
- Data can only be deleted directly using the DELETE endpoint with a specific id. Dependend data will be deleted as well. This feature will be highly restricted for safety reasons
- Data access is limited to max 100 elements per request. Use the url parameters limit and offset to utilize paging
¶ Authentication
The API uses scoped bearer token api keys to manage access to clients and features. The client is automatically identified by the api key and the features of the api are limited to the scope given to the api key. For security, we want to expose only the most powerful features for the actual usecases of a partner but not more. The key ist just a bearer token, so it can be used by adding a Header field Authorization: Bearer xxxx to each request. In order to receive an API Key, contact our CEO Burkhard Westermann (westermann@aidoo.de) for an initial partnership meeting to negotiate the conditions for using the API.
¶ Request structure
- url:
<base_url>/v2/<entityname>sWrite the entity name in plural form unless you use an implicit filter. - parameters: filters and extensions
For GET and DELETE requests, each entity exposes a set of url parameters to add filters, include special data and extend to related entities.
For POST requests, request parameters are not required, as all information is contained in the json data. Replace <entityname> with the entity you want to insert or update, e.g. "member" or "contract". You can batch insert/update resources by adding multiple entries to the array. Always wrap your entity in a root object like this:
{
"<entityname>s": [{...json model...}, {...}, ...]
}
¶ Response structure
Same as request structure but with a success flag and a message if an error occurs.
{
"<entityname>s": [{...}, {...}, ...],
"success": false,
"message": "Something specific went wrong"
}
¶ URL Filters (Beta)
The API supports filtering on properties along the entity graph, using url path and parameters. There are filters for equality, max, min, exclusive max, exclusive min and being in a list of elements. The type of the filter is identified by a prefix, the navigation through the graph is done by further prefixes to the fieldname using the traversed entity names.
Filter prefixes:
- <property>: equals
- min_<property>
- max_<property>
- emin_<property> - exclusive min
- emax_<property> - exclusive max
- in_<property> - followed by a csv list of ids/dates/values
Tipp: Writing the entity name in singular form in the path allows adding an implicit filter to the path on the id.
Examples:
<baseurl>/v2/members?id=202200012
is the same as
<baseurl>/v2/member/202200012
min/max filters:
Classes between 2024-02-12 (incl) and 2024-02-19 (excl)
<baseurl>/v2/classes?min_begin=2024-02-12&emax_begin=2024-02-19
filter along the graph:
Trainers whose classes member 202200022 attended
<baseurl>/v2/trainers?class_attendee_id=202200022
-> 'class' joins the classes of the trainer
-> 'attendee' joins the attendee members of the class
-> 'id' adds a filter on the id of the class attendee member
This only adds filters on the joined data, the result still only contains the trainer data. Add extensions to also include the class data in the results!
¶ Extensions (Development)
As mentioned before, entities can extend to related entities along the graph. The related entities are then joined in the result set as subobjects of the root entities. This allows high flexibility for querying data in an intuitive way.
<baseurl>/v2/member/202200022?with_class_trainers
{
"members": [{
... member 1 data ...
"classes": [{
... class 1 data ...
"trainer": {
... trainer data ...
}
},{
... class 2 data ...
"trainer": {
... trainer data ...
}
}]
}]
}
¶ Common Problems
¶ 1. Expected an id.
-> Singular form of endpoint expects id in the next path section
Example: /member/202202022 is the same as /members?id=202202022
Solution: Use plural form or set the id in the next path section
¶ 2. No data provided
Always wrap you json data into the request structure:
{
"members": [
{...member json structure...}
]
}
In general use the entity name in plural form as
¶ 3. 503 Error
-> The api key is not configured to a backend
Solution:
- Check the api key (Authorization: Bearer ...key...)
- Make sure the port is right
- Reach out to us so we check the config
¶ Currently Supported Graph
¶ Gym location (gym)
(Released)
Supported methods:
- GET
¶ Examples
Get all gyms:
GET https://api.aidoo-online.de:10015/v2/gyms
{
"success": true,
"gyms": [{...gym1 json...}, {...gym2 json...}, ...]
}
¶ JSON Structure
{
"id": 25,
"name": "Testgym",
"street": "Alte Poststraße",
"houseNumber": "116a",
"zip": "46514",
"city": "Schermbeck",
"phone": "123456789",
"email": "test@test.de"
}
¶ Documentation of the fields:
- id : integer
- name : string
- street : string
- houseNumber : string
- zip : string
- city : string
- phone : string
- email : string
¶ Additional extensions
- usage (with_usage) -> gymUsage subobject
- max_usage int
- usage_percent int
- usage int
¶ Member or Lead (member)
Supported methods:
- GET (Released)
- POST (Released)
- PUT (Development)
- DELETE (Development)
¶ Examples
Get a member:
GET <base_url>/v2/member/202202022
or
GET <base_url>/v2/members?id=202202022
Result:
{
"member": [
{... member data ...}
]
}
Add a member:
POST <base_url>/v2/members
{
"members": [{
"address_city":"",
"address_country":"Germany",
"address_number":"",
"address_street":"",
"address_zip":"",
"birthday":"2022-03-21",
"email":"a.b@c.de",
"firstname":"Rudolph",
"gym_id":2,
"is_lead":false,
"mobile":"",
"name":"Plitt",
"phone":"",
"sepa_bankname":"",
"sepa_bic":"",
"sepa_iban":"",
"sex":"f"
}]
}
¶ JSON Structure
{
"address_city":"",
"address_country":"Germany",
"address_number":"",
"address_street":"",
"address_zip":"",
"birthday":"2022-03-21",
"email":"a.b@c.de",
"firstname":"Rudolph",
"gym_id":2,
"id":202200055,
"is_lead":false,
"mobile":"",
"name":"Plitt",
"phone":"",
"sepa_bankname":"",
"sepa_bic":"",
"sepa_iban":"",
"sex":"f"
}
¶ Documentation of the fields:
- id (int): The member id.
- gym_id (int): The members gym id.
- name (string): The members last name.
- firstname (string): The members first name
- sex (string): The members sex (m or f).
- birthday (datetime): The members birthday.
- email (string): The members email address
- phone (string): The members phone number.
- mobile (string): The members mobile number.
- address_street (string): The members street.
- address_number (string): The members house number.
- address_zip (string): The members zip code.
- address_city (string): The members city.
- address_country (string): The members country.
- is_lead (bool): The members lead status.
- sepa_iban (string): The members SEPA IBAN.
- sepa_bic (string): The members SEPA BIC.
- sepa_bankname (string): The members SEPA bank name.
¶ Additional extensions
- image - image object
¶ Contract Type (contractType)
Supported methods:
- GET (Released)
- POST (Development)
- DELETE (Development)
¶ JSON Structure
{
"bonus_credit":0,
"bonus_days":0,
"bonus_months":0,
"cancel_days":28,
"duration_days":182,
"extend_days":0,
"extend_months":3,
"extend_price":0,
"id":58,
"name":"YOU ABO 25",
"payment_days":7,
"payment_dynamic":
{
"duration_days":0,
"duration_months":6,
"interval_days":0,
"interval_months":0,
"max_value":0,
"not_exact":false,
"start_days":0,
"start_months":0,
"value":0
},
"payment_once":false,
"price":9.07
}
¶ Documentation of the fields:
- id (int): The id of the contract type
- name (string): The name of the contract type
- description (string): The description of the contract type
- price (double): The price of the contract type
- header_images (array of image ids): The header images of the contract type if set
- cancel_months (int): The months of the cancellation period if set in months
- cancel_days (int): The days of the cancellation period if set in days
- duration_months (int): The months of the duration of the contract type if set in months
- duration_days (int): The days of the duration of the contract type if set in days
- payment_months (int): The months of the payment interval if set in months
- payment_days (int): The days of the payment interval if set in days
- payment_once (bool): The payment type of the contract type
- payment_dynamic (contractDynamicModel): The dynamic payment settings of the contract type. This is just a substructure, not an own entity
- type (string): The type of the dynamic payment settings ("Amount", "Percentage", "Disabled")
- value (double): The value of the dynamic payment settings
- start_months (int): The months of the start of the dynamic payment settings if set in months
- start_days (int): The days of the start of the dynamic payment settings if set in days
- interval_months (int): The months of the interval of the dynamic payment settings if set in months
- interval_days (int): The days of the interval of the dynamic payment settings if set in days
- duration_months (int): The months of the duration of the dynamic payment settings if set in months
- duration_days (int): The days of the duration of the dynamic payment settings if set in days
- max_value (double): The max value of the dynamic payment settings
- not_exact (bool): If not exact, touching a payment period increases the value, else it's exactly calculated per day
- bonus_credit (double): The bonus credit money of the contract type
- bonus_days (int): The days of the bonus period if set in days
- bonus_months (int): The months of the bonus period if set in months
- extend_months (int): The months of the extension period if set in months
- extend_days (int): The days of the extension period if set in days
- extend_price_value (double): A value reflecting the price change of the extension period
- extend_price_type (string): The type of the the price change of the extension period ("None", "Last Price", "Set Price", "Increase", "Increase Percentage")
- online_first (bool): The online availability as a first contract (optional)
- online_second (bool): The online availability as a second contract (optional)
¶ Contract (contract)
Supported methods
- GET (Released)
- POST (Development)
- PUT (Development)
- DELETE (Development)
<base_url>/v2/contracts?member_id=202202022
{
"contracts": [{...contract data...}]
}
¶ JSON Structure
{
"id": 123,
"name": "Mitgliedschaft Plus",
"member_id": 202200022,
"contract_type_id": 132,
"start": "2020-01-01T00:00:00",
"end": "2021-01-01T00:00:00",
"payment_start": "2020-02-01T00:00:00",
"active": true,
"cancelled": "2024-12-12",
"notice_period": "2024-12-31",
"sepa_iban": "DE89370400440532013000",
"sepa_bic": "COBADEFFXXX",
"sepa_kto": "1234567890",
"sepa_blz": 37040044,
"adv_member_id": 202200023,
"adv_member_text": "Some text",
"ba_street": "teststreet",
"ba_nr": "123",
"ba_surname": "testname",
"ba_name": "testfirstname",
"ba_phone": "123456789",
"ba_mobile": "123456789",
"ba_email": "test@test.test"
}
¶ Documentation of the fields
- id (int): The id of the contract
- name (string): The title of the contract
- member_id (int): The id of the member
- contract_type_id (int): The id of the contract type
- start (datetime): The start date of the contract
- end (datetime): The end date of the contract
- payment_start (datetime): The first payment
- cancelled (datetime): date of cancellation
- notice_period (datetime): cancellation period
- sepa_iban (string): The SEPA IBAN of the contract payment
- sepa_bic (string): The SEPA BIC of the contract payment
- sepa_kto (string): The SEPA account number of the contract payment
- sepa_blz (int): The SEPA bank code of the contract payment
- adv_member_id (int): The id of the advertising member
- adv_member_text (string): The advertising text of the advertising member
In case the member is not the bank account owner: - ba_street (string): The street of the bank account
- ba_nr (string): The house number of the bank account
- ba_surname (string): The surname of the bank account owner
- ba_name (string): The name of the bank account owner
- ba_phone (string): The phone number of the bank account owner
- ba_mobile (string): The mobile number of the bank account owner
- ba_email (string): The email of the bank account owner
¶ Contract Addon Type (contractAddonType)
(Development)
to be done
¶ Addon (contractAddon)
(Development)
¶ JSON Structure
¶ Documentation of the fields
- id: int - The id of the contract add-on
- name: string - The name of the contract add-on
- type: int - The type of the contract add-on
- member_id: int - The id of the member
- contract_id: int - The id of the contract
- start: datetime - The start date of the contract add-on
- end: datetime - The end date of the contract add-on
- price: double - The price of the contract add-on
¶ Appointment Type (appointmentType)
(Released)
Supported methods
- GET
¶ JSON Structure
{
"id":96,
"sign": "SG",
"name":"Sales Gespräch",
"gym_id": 2
}
¶ Documentation of the fields
- id (int): The id of the appointment type
- sign (string): Short sign of appointment type
- name (string): The name of the appointment type
- gym_id (int): Gym id this type is registered in
¶ Appointment Slots (appointmentSlot)
Supported methods
- GET (Released)
- POST (Development)
- PUT (Development)
- DELETE (Development)
Additional query parameters:
- from (datetime)
- to (datetime)
- member_id (int)
- type_id (int)
- gym_id (int)
- per_user (bool): if true each user has their own slots. If false slots are without user id and mean at least one user is free.
¶ JSON Structure
{
"begin":"2024-05-31T16:00:00",
"end":"2024-05-31T16:30:00",
"price":"0,00",
"product_id":0,
"room_id":3,
"type_id":96,
"user_id":3
}
¶ Documentation of the fields
- begin (datetime): The begin of the appointment slot
- end (datetime): The end of the appointment slot
- price (string): The price of a payed appointment slot (irrelevant for now)
- product_id (int): The product of a payed appointment slot (irrelevant for now)
- room_id (int): The room id where the appointment will happen
- type_id (int): The appointment type id
- employee_id (int): The employee having this as a free slot
- Deprecated: user_id (int): The employee having this as a free slot
¶ Appointment (appointment)
Supported methods
- GET (Released)
- POST (Released)
- PUT (Released)
- DELETE (Beta)
¶ JSON Structure
{
"type_id": 96,
"member_id": 201901069,
"user_id": 3,
"creator_id": 3,
"begin": "2024-05-31T14:30:00",
"end": "2024-05-31T15:00:00",
"room_id": 3
}
¶ Documentation of the fields
- type_id (int): The appointment type id
- member_id (int): The member id
- user_id (int): The id of the user involved
- creator_id (int): The id of the user that created the appointment
- begin (datetime): The begin of the appointment
- end (datetime): The end of the appointment
- room_id (int): The room id where the appointment will happen
- gym_id (int): The gym where the appointment is booked
- thread_id (int): Remains the same on updates
- title (string): Title of the appointment
- state (string): PLANNED, FINISHED or CANCELLED
- state_info (string): What happened?
- employee_id (int): Employee / trainer id
- note (int): Interesting info
- Deprecated: user_id (int): Employee / trainer id
¶ Presence (presence)
GET
- member_id
- gym_id
- user_id
- checkin
- checkout
- duration
¶ Checkin
¶ Checkout
¶ Login
¶ Email Verify (emailVerify)
/emailVerify
Supported methods
- POST
¶ JSON Structure
In this case this has to be the root object.
{
"email": "..."
}
Result:
{
"email": "...",
"emailVerify": {
"email_found": true,
"login_available": false,
"member_id": 202202022
}
}
curl Example:
curl --request POST --url 'https://api.aidoo-online.de:10015/v2/emailVerify' --header "Content-Type: application/json" -d '{"email": "XXX-EMAIL-XXX"}' --header 'Authorization: Bearer XXX-KEY-XXX'
¶ Passwort change
¶ Webhooks (Observers)
The API supports registering an observer with a webhook to changes occuring to the supported entities. This features is highly customizable as well: You can set filters and extensions for the entity such that your changes are filtered by the filters and extended by the extensions.
Supported methods
- POST (Beta)
- PUT (Beta)
- DELETE (Beta)
¶ Currently Supported Entities
- contract
- appointment
- presence
¶ JSON Structure
{
"cached":true,
"entity_name":"contract",
"interval_seconds":10,
"observer_name":"my_amazing_company",
"webhook":{
"api_gym_id":"",
"api_key":"Bearer xxxxxxxxx",
"api_name":"test_webhook",
"api_url":"https://webhook.site/2205cb66-d9d7-4e9b-b52b-18625b61ccdc",
"header_field":"Authorization"
}
}
¶ Documentation of the fields
- cached: only receive actual changes to the data
- entity_name: the entity to observe, for example contract
- interval_seconds: interval between checking for changes
- observer_name: choose your own (e.g. your company name)
- webhook: endpoint object
- api_url: The actual endpoint url
- api_name: e.g. your companies name + "_webhook"
- api_gym_id: gym_id of the gym to observe
you can have different webhooks for different gyms data
not set -> you get changes for the whole chain - api_key: choose a key to secure your endpoint
- header_field: Where to put the api_key
- filter: object of filter key value pairs (same as in urls)
- cancelled: true for example for cancelled contracts
- ext: object of extension key value pairs (same as in urls but without the with_)
- member: true for example also gives back the member of the contract
¶ Receiving changes
After the webhook is created, it may take up to 1 Minute before it is active. Afterwards, changes fitting the observers criteria are dispatched to the observer endpoint using POST:
¶ Example change of a contract observer:
{
"change_type": "create",
"changed_key": "10961",
"entity_data": {
"active": false,
"adv_member_id": 0,
"adv_member_text": "",
"contract_type_id": 312,
"end": "2025-02-28",
"id": 10961,
"member_id": 202200267,
"name": "00JensFitnessvertrag",
"notice_period": "2025-01-31",
"payment_start": "2024-03-01",
"start": "2024-03-01"
},
"entity_name": "contract"
}
- change_type (create, update, delete) describes the kind of change.
- changed_key is the id of the changed entity.
- entity_name describes which kind of entity has changed.
- entity_data is the json structure of the changed entity with extensions applied