free html website templates

Using the API for online bookings

You can incorporate Physiodiary in your own website and allow patients to book appointments directly

Physiodiary provides a powerful API which you can call from your own website to allow patients to make bookings directly into your diary.  We should point out at this stage that this form of tight integration will require a reasonable amount of programming knowledge and may be best left to your web designer.  We will be unable to do the required work on your website for you.  Also, this type of integration is not for everyone - you may feel that you loose some elements of control over your appointments.  There are other methods available which still allow patients to request appointment and cancellation but allow you to maintain full control over them.  Please contact us for further details.

Click here to see a real life example of our API in use (many thanks to ARC Physiotherapy)

Physiodiary's API works by listening for 'request' from your website and returns information in response to those requests. You will need to fully understand how to make calls to a remote service and how to interpret the returned data before you start.

Assuming you do know what to do it is actually quite simple to request the data from the API.

Firstly you will need to contact us for an API 'Key' you will also need to let us know the IP Address of the server that will be sending the requests. Once you have done that we will supply the key and a URL, initially, to one of our reference servers. This will allow you to develop your applications without being connected to the live system. Once you have completed your integration we will supply you with a live key and URL.

Other than the URL both the Ref servers and the Live servers work in exactly the same way...

1) Your system sends a request to our server as a correctly formatted JSON message.
2) Physiodiary returns data to you, again, formatted as a JSON message. This message will contain the requested data, a confirmation of a valid booking or an error code if there was something wrong with the request.

Please note the keys supplied ONLY work with the IP Address registered as your server. You can request a change of keys and/or IP Addresses at any time but we will will ask for some proof that the server is actually the one that hosts your website.

If you are a web designer please feel free to contact us so that we can work together to develop your solution. We make no charge for our side of the integration.

If you are a practice and do not have a web designer we would be happy to recommend one.

All the requests should be sent to the url supplied by us which will look something like:


https://api456.physiodiary.co.uk:1234/api/request


Your requests should be formatted as shown below:


To get a list of Members of Staff:

    {

        "action" : "staffList",

        "apiKey" : "Your-API-Key"

    }


This would return something like:


{"staff":[{"id":42228,"name":"John"},{"id":42230,"name":"Anna"},{"id":42229,"name":"Jayne"},{"id":42233,"name":"Chris"},{"id":42227,"name":"Demo User"}]}


To get a list of Sections (rooms):

    {

        "action" : "sectionList",

        "apiKey" : "Your-API-Key"

    }


This would return something like:


{"sections":[{"id":7322,"name":"Treatment Room 1"},{"id":7323,"name":"Treatment Room 2"},{"id":7324,"name":"Treatment Room 3"}]}


To get a list of free appointments for a given future period:

    {

        "action" : "freeList",

        "apiKey" : "Your-API-Key",

        "date" : "20171007",

        "numDays" : 2,

        "sectionId" : 1245,

        "staffId" : 43987

}


Note: the 'date' in this instance is the date you would like the system to start looking for appointments from - the 'numDays' is the maximum period to return free appointments for (this can be up to 90 days) beyond the 'date' so in the example shown it would return any free appointments for 07/10/2017 and 08/10/2017.


This would return something like:


{"slotLength":45,"free":[{"date":"20171007","times":["1415","1500","1715","1800","1845","1930","1415","1500","1715","1800","1845","1930"]}],"staffId":43,"staffName":"Anna","sectionId":2,"sectionName":"Treatment Room 2"}


To book an appointment:

    {

        "action" : "book",

        "apiKey" : "Your-API-Key",

        "date" : "20171007",

        "time" : "0915",

        "sectionId" : 1245,

        "staffId" : 43987,

        "name": "Fred Smith",

        "phone" : "123456",

        "email" : "fred@smith.co.uk",

        "desc" : "Pain in back"

}


This will return either:


{"result":"Confirmed","date":"20171007","time":"0745","duration":45,"section":"Treatment Room 2","staff":"Anna"}


or


{"errors":[{"error":12,"fieldName":"booking","message":"Date/time/section is unavailable."}],"timestamp":"Oct 7, 2017 3:25:07 PM","numErrors":1,"action":"book"}


Error handling (generally):

When an error has occurred (ie missing fields etc) a JSON string containing the error/s will be returned rather than the expected message: something like:


{"errors":[{"error":4,"fieldName":"staffId","message":"Is zero or negative."},{"error":8,"fieldName":"name","message":"Must not be empty"},{"error":9,"fieldName":"phone","message":"Must not be empty"}],"timestamp":"Oct 7, 2017 3:28:32 PM","numErrors":3,"action":"book"}


The exception to this is where the request comes from an unexpected IP Address or the API key is not valid. It that case the system will just return a 404.


Normal error numbers will be one of the following:

    NO_ERROR = 0;

    INVALID_ACTION = 1;

    INVALID_API_KEY = 2;

    INVALID_SECTION_ID = 3;

    INVALID_STAFF_ID = 4;

    INVALID_NUM_DAYS = 5;

    INVALID_DATE = 6;

    INVALID_TIME = 7;

    INVALID_NAME = 8;

    INVALID_PHONE = 9;

    INVALID_EMAIL = 10;

    INVALID_DESCRIPTION = 11;

    ALREADY_BOOKED = 12;

    UNKNOWN_ERROR = 13;