How to connect to the Fisikal API using Postman

Use Postman to investigate the Fisikal API for your advanced integrations.

Pre-requisites

1. Obtain permission from the data owner:
   • If you are from a third-party integrator you must obtain written permission from the company that owns the client data to gain access to the data.
   • Please contact your Fisikal representative to arrange.
2. Obtain Fisikal API credentials:
   • You must request these from your Fisikal representative.
   • These credentials are valuable, please do not share wildly.
     • Base URL of the instance holding the data
     • Username of a user with a suitable role for the integration (usually a Manager)
     • Password for the user
     • oAuth Client ID for authentication
     • oAuth Client Secret for authenticationThe information required is:
   • It is common for these details to be shared as a Postman Environment File, along with a Postman Collection that has examples of some API calls.
3. Locate the Fisikal API documentation
   • There is API documentation for each instance in the form <base_url>/#/home/developers
   • There is a shared version here: https://cuttingedge.fisikal.com/#/home/developers
   • There are 5 areas of documentation for the roles that can access the API. Note it is possible for the same endpoint to behave differently depending on the role:
     • Guests
     • Clients
     • Trainers
     • Managers
4. Obtain Postman:

• • Download and log in from here: https://www.postman.com/
  • You can use other API tools, but this document is specific to Postman.

How to use Postman to log in to the Fisikal API

If you have received a Postman Collection file then you can proceed easily. Otherwise please refer to the API documentation for examples of calls.

If you have received Fisikal API credentials in the form of a Postman Environment file then you can jump straight in. If not, it is easy to create a new environment file in Postman and enter the credentials you have received and proceed from there. See below for details.

1. Open Postman
2. Click File > Import
3. Import the Collection and Environment files from Fisikal
4. Select the Environment file
   
    
5. Click the Collection and then the Authorization tab.
   Note that the options are prefilled with variables from the Environment file.
   
   
6. Click Get New Access Token, then Proceed, then Use Token
   
7. You are now logged into Fisikal.
8. Test that you are logged in as the right person by finding the GET my_profile API request and click Send. The response contains your user details.
   
9. It is now possible to run the other API calls as required.
10. After some time of inactivity your user will become logged out and you may need to repeat the steps above.

Useful Information

Dates and times

All dates and times in responses from the API are in UTC.

Use the time_zone value to convert them to the display date and time in the location where they occur.

The API is expecting to receive date and time values in UTC, use the location or user's time_zone to convert the selected value to UTC before sending.

Showing the timetable

There are two methods for retrieving the timetable data:

• GET /api/unified/schedule/occurrences
• GET /api/unified/schedule/occurrences/timetable

The timetable method returns a lightweight version of the response with all the required information in order to display the time table on a website or in-club screen. It is also much easier on the server. We recommend using the timetable method wherever possible.

We also recommend filtering the timetable data to a single week, and if possible a single location to make the view for the recipient as clear as possible.

Troubleshooting

400 Bad Request - Perform method should be defined

If the response contains text like 

400 Bad Request - no message

The most common reason for a 400 Bad Request response is a missing comma (,) between parameters.

For example on line 5 there is a missing comma at the end.

500 Internal Server Error

This indicates that there is an error on the server end trying to process this request.

If this happens and is unexplainable then please raise it to your Fisikal support team.

Check for the following:

• Requesting an ID that does not exist. The API documentation adds random example values into the description of the parameters. It is easy to copy the example values and attempt a call with them which can lead to issues. Check that the values are realistic.
• Check for nonsense values. Sometimes the validation will not detect nonsense, for example a backwards from and till date range can cause an error.
• Check the documentation to see whether there is a difference between the call format for Clients versus Managers.