Publish information about a gym member to the EGYM system. The method updates or creates a dataset for the regarding user.
MMS Api v1 (1.0.0)
This API enables gym management software to connect to the EGYM system and transmit important pieces of information from the data sphere of the gym to the EGYM system. The "data privacy concept" section in the overview document explains more about the overall logic of data access. This API baiscally operates in "data processing" mode from a gyms' data privacy perspective, i.e. member data can be transmitted without prior individual consent of a user.
This API provided by EGYM covers three different use-cases:
- **User Profile" related operations ("user path") like creating and updating member records
- Trainer Task related Operations
- Product/Experience related operations ("gym" path)
This is the most important and most basic form of integration. The "publish" method allows for a combined create/update of whole member records and should be called whenever there is a new member created inside the MMS or meterial details of that record are changed. It also contains the methods to signal a "check-in" and "check-out" event.
The Trainer Task API allows to interact with the tasks that are created and worked through on the trainer app. It provides CRUD functionalities for those tasks.
This API enables gym management software to create and update EGYM products for users on behalf of the gym.
- It provides methods to retrieve all products that are available in a gym.
- These products can be activated for users in the gym.
- The active and future products for a user in a gym can be retrieved.
We provide a test environment for integration testing of the API which is particularly helpful during development. Before entering productive mode, we will jointly test all functionalities to ensure that data is correctly sent, received and interpreted.
The endpoint for test environment is: https://mms.api.egym.com/gymapi/v1
Making requests via this ui is not allowed but one can generate an example curl request by clicking "Try it out", filling in some parameters and clicking "Execute". Note the upper- and lower cases and use attribute exactly as indicated. Please note that due to technical reasons the environment may temporarily not be available.
EGYM uses the fields userId, membershipId, and eMail to identify members. Since EGYM can accept data from multiple source (EGYM compatible fitness equipment, EGYM apps, and third parties), it is important to use these identifiers correctly.
userId is the identifier assigned to this member by the EGYM server. When publishing data of a member for the first time, the client omits this field since the userId is unknown to the client. The server replies with a valid userId for this member that needs to be stored. On subsequent requests, the client must include the userId received previously.
membershipId is a String identifier used by the gym. This must be unambiguously assigned to this person and must never be reused for other members. membershipIds must be unique within all gyms that share member data (i.e. within the gym chain). The membershipId is not a contractId.
Any publish request must include a valid email address. For members who have previously used the EGYM ecosystem, e.g. our fitness machines, this must be identical to the email address used as EGYM account. It is important to include the correct email address with the first request sent for this member since the first API request will merge this user with pre-existing data for this person.
All fields noted as 'required' or 'optional' must be supported by the client software and included in the request if this data is available. Fields with the remark '(optional)' should be supported within the constraints of the client application, if possible.
If the value of an optional field is not known, the client must omit the the field in the request. The EGYM server will then assume that last known value (which may have been retrieved by other channels) is still valid. Please never sent an empty String ("") or empty list ([]) when the actual value is unkown.
Example imageData: The imageData field has due to its nature a larger size than other fields. Thus, it make sense to include this field only if this is the first publish request for this user or if the image has changed. Please do not include an unchanged image in subsequent requests. However, if the first requests failed for any reason (e.g. internet unavailable or HTTP status > 299), then the client must include the image when retrying.
Example rfidList: Sending rfidList: [] will overwrite the list of RFIDs for this member with the emtpy list. That is, this user will not be able to use EGYM equipment. On the other hand, if rfidList is missing from the request, the list of RFIDs is unchanged.
Example dateOfBirth: If the member's birthday is not known, it is OK to omit the field. However sending "dateOfBirth":"" (empty String) is invalid.
All endpoints use the JSON data type for request and response bodies and UTF-8 character encoding. In your HTTP request, please declare the Content-Type for your JSON body: "Content-type: application/json"
Requests which cannot be processed will return a special JSON object with "error" and optionally "error text" fields. Authentication problems, for example, return the following JSON: {"error":401, "errorText":"The provided user name or password is incorrect."}
Error codes
Informational
- 200 OK - successful request
- 204 No Content - successful request with empty response body
Client Error
- 400 Bad Request - The email is invalid. (Email field does not match the expected format of valid email addresses)
- 401 Unauthorized - The provided login credentials are wrong. (The combination of accessToken and gymID are wrong.)
- 403 Forbidden - Blacklisted user (Email address is blacklisted)
- 404 Not Found - User not found. (GET request with userId for user that does not exist)
- 404 Not Found - Email address not found. (GET request with userId for user with email address that does not exist)
- 404 Not Found - Could not find any user with RFID = 0x.... (GET request with RFID for user that does not exist)
- 405 Method Not Allowed - Method Not Allowed (Using GET without required data to be presented via POST)
- 409 Conflict - Conflict in the request (Request could not be processed because of conflict.)
- 415 Unsupported Media Type - Unsupported Media Type (Unsupported Media Type; add "Content-type: application/json" to the header of your request)
404 error codes can indicate that user was deleted on EGYM server (e.g. he deleted his own account via the website).
Server Error
- 500 Internal Server Error - Internal Server Error (A bug in the server. If this occurs in productions it is probably caused by unexpected behavior of the client, i.e. there is also a bug in the client.)
Authentication is validated via an access token that is generated by EGYM for each gym location. EGYM requires a unique email for each member. EGYM uses the email address or other keys such as RFID-Id to initially match existing users in our data base. Server authentication of a request requires 2 additional parameters:
- gymId: the gym location ID, as assigned by EGYM – gym chains will receive one gymId for each location
- accesstoken: access token, provided by EGYM – each gym has a unique token
Example: https://mms.api.egym.com/gymapi/v1/user/publish?gymId=123
X-ACCESS-TOKEN: ABCDE
To test, use the Authorize-Button on the right to insert the token as a query parameter to every request.
Bodyapplication/jsonrequired
Information about the member
Unique ID that identifies the EGYM user in the EGYM system. Please include the userId that you have received as a response to the previous requests for this user.
Example: 123
Member ID of the gym software (must be unique for exactly one member in the gym (chain)); The membershipId must be unique for exactly one member in the gym. The membershipId should never changes, i.e. you cannot use a contract id or similar, which would change when the contract is renewed, changed or a new contract is signed.
Example: "membership_id"
The agreement number is the number of the membership between the member and the gym chain.
Example: "agreement_number"
Type of the member's membership to determine available features, can be BASIC/PREMIUM/PROSPECT
Example: "BASIC"
Extension of membershipStatus for further customization for this user. One membershipStatus can have multiple membershipSubType.
Example: "membership_sub_type"
MembershipId of the member who referred this member.
Example: "referring_number_id"
The EGYM interface requires that each member has a unique email address.
Before implementing the API in a gym, the software provider needs to run a search for email addresses that are used multiple times for different gym members (think fake addresses or family members). Obvious fake addresses (e.g. test@test.com) should be deleted. A list of email addresses used multiple times shall be given to the gym to enter unique addresses.
Any umlaut in email addresses is not accepted and will be answered by an error message.
A warning must be shown in the software if a member is created without a valid email address - validity check needs to cover typos (such as name@provider. / nameqprovider.com / etc)
Two members can never share an email address and no member can be submitted without an email address. The software vendor must ensure that if two members share an email address, both will not be transmitted to EGYM. A warning should be shown to gym staff if a member is created with the same email address of an existing user until the problem is resolved.
Example: "example@egym.com"
Birthday of the member as date in format YYYY-MM-DD
Example: "1990-11-20"
BASE64 encoded image (JPEG or PNG): Photo of the member. Does not need to be sent with every request but can be transmitted after changes. Please note that the overall request size is limited to 16 MB, so please make sure your images (after base64 encoding) are small enough to fit into the request, otherwise, we'll throw a 413 and reject the whole request
Example: "N/A"
Motivation list of the member. Possible Strings: GENERAL_FITNESS, HEALTH, SHAPE, SOCIAL, RELAX, ACTIVATION
Items Enum"GENERAL_FITNESS""HEALTH""SHAPE""SOCIAL""RELAX""ACTIVATION"
Example: "[\"HEALTH\", \"SHAPE\"]\n"
Number of training sessions the member wants to conduct per week
Example: 3
Time (in minutes) a training session should take for the member
Example: 90
Date when the member's contract ends. For gyms with automatic contract renewal, send the date when the contract would run out, if cancelled. Update the field when the contract was renewed.
Please update the field when the customer renews their contract (manually and automatically renewals).
Example: "2016-12-31"
Date when the member joined the gym
Example: "2018-01-01"
List of strings representing long numbers OR hex strings (with leading "0x").
This field is used for synchronizing all RFIDs of a user with EGYM.
Note: If this field is sent we will replace the RFID list of this user with the info sent (for an empty list, we will delete all RFID connections of this user). Please ensure that only RFID information is sent in this field but no other medium like magnetic stripe card numbers or bar codes.
Example: ["0x04AABBCCDDEEFF"]
telephone number of the member
There is just one field for the phone number in the EGYM Trainer App, so implement the way that first the mobile phone number is sent, and if that field is empty, the land line phone number. If that field is empty, do not send the phone field at all.
Member's barcode to checkin in the gym. Can be visualised on the Branded Member App and used for lookup to verify membership
Example: "123456789-10"
Indicates that the member is a prospective member, who has not yet signed up for the gym membership
Example: true
- Mock serverhttps://developer.egym.com/_mock/mms-api-v2/gymapi/api/user/publish
- Testhttps://mms.api.ed.ts.egym.coffee/v1/user/publish
- Prodhttps://mms.api.egym.com/v1/user/publish
- curl
- JavaScript
- Node.js
- Python
- Java
- C#
- PHP
- Go
- Ruby
- R
- Payload
curl -i -X POST \
'https://developer.egym.com/_mock/mms-api-v2/gymapi/api/user/publish?gymId=234' \
-H 'Content-Type: application/json' \
-H 'X-ACCESS-TOKEN: YOUR_API_KEY_HERE' \
-d '{
"eMail": "example@egym.com",
"firstName": "Hans",
"lastName": "Mustermann",
"dateOfBirth": "1990-11-20",
"endOfContract": "2016-12-31",
"gender": "MALE",
"rfidList": [
"0x04AABBCCDDEEFF"
]
}'Response
application/json
{ "userId": "id12" }
- Mock serverhttps://developer.egym.com/_mock/mms-api-v2/gymapi/api/user/profile
- Testhttps://mms.api.ed.ts.egym.coffee/v1/user/profile
- Prodhttps://mms.api.egym.com/v1/user/profile
- curl
- JavaScript
- Node.js
- Python
- Java
- C#
- PHP
- Go
- Ruby
- R
- Payload
curl -i -X GET \
'https://developer.egym.com/_mock/mms-api-v2/gymapi/api/user/profile?userId=123&rfid=0xAA&email=example%40egym.com&membershipId=23ljlsJKLD&gymId=123' \
-H 'X-ACCESS-TOKEN: YOUR_API_KEY_HERE'The member information.
Unique ID that identifies the EGYM user in the EGYM system. Please include the userId that you have received as a response to the previous requests for this user.
Example: 123
Member ID of the gym software (must be unique for exactly one member in the gym (chain)); The membershipId must be unique for exactly one member in the gym. The membershipId should never changes, i.e. you cannot use a contract id or similar, which would change when the contract is renewed, changed or a new contract is signed.
Example: "membership_id"
The agreement number is the number of the membership between the member and the gym chain.
Example: "agreement_number"
Type of the member's membership to determine available features, can be BASIC/PREMIUM/PROSPECT
Example: "BASIC"
Extension of membershipStatus for further customization for this user. One membershipStatus can have multiple membershipSubType.
Example: "membership_sub_type"
MembershipId of the member who referred this member.
Example: "referring_number_id"
The EGYM interface requires that each member has a unique email address.
Before implementing the API in a gym, the software provider needs to run a search for email addresses that are used multiple times for different gym members (think fake addresses or family members). Obvious fake addresses (e.g. test@test.com) should be deleted. A list of email addresses used multiple times shall be given to the gym to enter unique addresses.
Any umlaut in email addresses is not accepted and will be answered by an error message.
A warning must be shown in the software if a member is created without a valid email address - validity check needs to cover typos (such as name@provider. / nameqprovider.com / etc)
Two members can never share an email address and no member can be submitted without an email address. The software vendor must ensure that if two members share an email address, both will not be transmitted to EGYM. A warning should be shown to gym staff if a member is created with the same email address of an existing user until the problem is resolved.
Example: "example@egym.com"
Birthday of the member as date in format YYYY-MM-DD
Example: "1990-11-20"
BASE64 encoded image (JPEG or PNG): Photo of the member. Does not need to be sent with every request but can be transmitted after changes. Please note that the overall request size is limited to 16 MB, so please make sure your images (after base64 encoding) are small enough to fit into the request, otherwise, we'll throw a 413 and reject the whole request
Example: "N/A"
Motivation list of the member. Possible Strings: GENERAL_FITNESS, HEALTH, SHAPE, SOCIAL, RELAX, ACTIVATION
Items Enum"GENERAL_FITNESS""HEALTH""SHAPE""SOCIAL""RELAX""ACTIVATION"
Example: "[\"HEALTH\", \"SHAPE\"]\n"
Number of training sessions the member wants to conduct per week
Example: 3
Time (in minutes) a training session should take for the member
Example: 90
Date when the member's contract ends. For gyms with automatic contract renewal, send the date when the contract would run out, if cancelled. Update the field when the contract was renewed.
Please update the field when the customer renews their contract (manually and automatically renewals).
Example: "2016-12-31"
Date when the member joined the gym
Example: "2018-01-01"
List of strings representing long numbers OR hex strings (with leading "0x").
This field is used for synchronizing all RFIDs of a user with EGYM.
Note: If this field is sent we will replace the RFID list of this user with the info sent (for an empty list, we will delete all RFID connections of this user). Please ensure that only RFID information is sent in this field but no other medium like magnetic stripe card numbers or bar codes.
Example: ["0x04AABBCCDDEEFF"]
telephone number of the member
There is just one field for the phone number in the EGYM Trainer App, so implement the way that first the mobile phone number is sent, and if that field is empty, the land line phone number. If that field is empty, do not send the phone field at all.
Member's barcode to checkin in the gym. Can be visualised on the Branded Member App and used for lookup to verify membership
Example: "123456789-10"
Indicates that the member is a prospective member, who has not yet signed up for the gym membership
Example: true
Response
application/json
{ "eMail": "example@egym.com", "firstName": "Hans", "lastName": "Mustermann", "dateOfBirth": "1990-11-20", "endOfContract": "2016-12-31", "gender": "MALE", "rfidList": [ "0x04AABBCCDDEEFF" ] }
- Mock serverhttps://developer.egym.com/_mock/mms-api-v2/gymapi/api/user/product
- Testhttps://mms.api.ed.ts.egym.coffee/v1/user/product
- Prodhttps://mms.api.egym.com/v1/user/product
- curl
- JavaScript
- Node.js
- Python
- Java
- C#
- PHP
- Go
- Ruby
- R
- Payload
curl -i -X GET \
'https://developer.egym.com/_mock/mms-api-v2/gymapi/api/user/product?userId=-qwn9fgz5sa3i&membershipId=23ljlsJKLD&gymId=234' \
-H 'X-ACCESS-TOKEN: YOUR_API_KEY_HERE'An array of active or future products for the user.
The description of the product.
Example: "Enables Premium training features for the users on all EGYM machines."
The date from which the specified product is active and can be used by the user.
Example: "2018-09-11"
The date to which the specified product is active and can be used by the user.
Example: "2018-10-11"
Response
application/json
[ { "productId": "1337", "productTitle": "PREMIUM SELECT", "productDescription": "Enables Premium training features for the users on all EGYM machines.", "start": "2018-09-11", "end": "2018-10-11" } ]
Request
Activates or updates a product for a user in a gym. A product can be activated for a specified user and gym. The product is active starting from the specified start date to the end date. In case the product is already active for the user, the start and end date are updated to the transmitted dates.
Security
accesstoken
A product with start and end dates to be activated for the user in the given gym.
The date from which the specified product is active and can be used by the user.
Example: "2018-09-11"
- Mock serverhttps://developer.egym.com/_mock/mms-api-v2/gymapi/api/user/product
- Testhttps://mms.api.ed.ts.egym.coffee/v1/user/product
- Prodhttps://mms.api.egym.com/v1/user/product
- curl
- JavaScript
- Node.js
- Python
- Java
- C#
- PHP
- Go
- Ruby
- R
- Payload
curl -i -X PUT \
'https://developer.egym.com/_mock/mms-api-v2/gymapi/api/user/product?userId=-qwn9fgz5sa3i&membershipId=23ljlsJKLD&gymId=234' \
-H 'Content-Type: application/json' \
-H 'X-ACCESS-TOKEN: YOUR_API_KEY_HERE' \
-d '{
"productId": "1337",
"start": "2018-09-11",
"end": "2018-10-11"
}'Response
application/json
{ "productId": "1337", "productTitle": "PREMIUM SELECT", "productDescription": "Enables Premium training features for the users on all EGYM machines.", "start": "2018-09-11", "end": "2018-10-11" }
Bodyapplication/jsonrequired
Information about the member
Unique ID that identifies the EGYM user in the EGYM system
Example: "-qwn9fgz5sa3i"
ID that identifies the RFID Chip (either a long number OR a hex string with '0x' as leading characters)
Example: "0xAA"
- Mock serverhttps://developer.egym.com/_mock/mms-api-v2/gymapi/api/user/checkin
- Testhttps://mms.api.ed.ts.egym.coffee/v1/user/checkin
- Prodhttps://mms.api.egym.com/v1/user/checkin
- curl
- JavaScript
- Node.js
- Python
- Java
- C#
- PHP
- Go
- Ruby
- R
- Payload
curl -i -X POST \
'https://developer.egym.com/_mock/mms-api-v2/gymapi/api/user/checkin?gymId=234' \
-H 'Content-Type: application/json' \
-H 'X-ACCESS-TOKEN: YOUR_API_KEY_HERE' \
-d '{
"userId": "-qwn9fgz5sa3i"
}'Bodyapplication/jsonrequired
Information about the member
Unique ID that identifies the EGYM user in the EGYM system
Example: "-qwn9fgz5sa3i"
ID that identifies the RFID Chip (either a long number OR a hex string with '0x' as leading characters)
Example: "0xAA"
- Mock serverhttps://developer.egym.com/_mock/mms-api-v2/gymapi/api/user/checkout
- Testhttps://mms.api.ed.ts.egym.coffee/v1/user/checkout
- Prodhttps://mms.api.egym.com/v1/user/checkout
- curl
- JavaScript
- Node.js
- Python
- Java
- C#
- PHP
- Go
- Ruby
- R
- Payload
curl -i -X POST \
'https://developer.egym.com/_mock/mms-api-v2/gymapi/api/user/checkout?gymId=234' \
-H 'Content-Type: application/json' \
-H 'X-ACCESS-TOKEN: YOUR_API_KEY_HERE' \
-d '{
"userId": "-qwn9fgz5sa3i"
}'