Developer Centre

coreplus unfolded

coreplus API

 

The Coreplus API provides access to appointment booking related end points, such as clients, practitioners, availability slots, and appointments.

It is a RESTful API, which utilizes the HTML verbs for creating and viewing objects.

coder

Develop with us

 

The coreplus API is nearing Beta release. Register your interest today to be the first to know when the API is available.

Register for API Access

Sandbox Setup

Authentication

Access to the API is controlled by authentication and authorization permissions in coreplus. Each consumer application of the coreplus API is provided with a Consumer Id and Consumer Secret for authentication.

The request should include an authorization header called “JwToken” with an authorized Json Web Token (https://en.wikip1edia.org/wiki/JSON_Web_Token) identifying the Consumer.  All communication with the API is done over HTTPS.

The API Endpoints, and consumer details (Consumer Id & Consumer Secret) are included in the “coreplus API Connection Details” document.

Example Authorization Header:

Authorization: JwToken eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9….

Keep your secret key a secret.

The API Consumer ID and Secret should only be used in server-server communications and never exposed on a client application (e.g. web browser, mobile app etc) for security reasons. Please ensure it is kept securely and not available to any external party.

Important Tips!

- All credentials should be used as they are presented in the application screen. Ie, they are not base64 encoded.

- Ensure the timestamp is correct and that your server time is synchronised.

Creating a Json Web Token to call the coreplus API

Json Web Token (hereon specified as jwtoken) passes a header, number of claims and signature from the API Consumer to the coreplus API.

All jwtokens must be signed, and currently the coreplus API supports the HMAC SHA-256 (HS256) algorithm. All systems generating jwtokens should be synchronized with internet clocks, to ensure jwtokens are not rejected.

The claims that are available are:

Claim Type Description
ciss (mandatory) String The issuer of the claim. This should be filled in as the url of the company’s web site.
aud (mandatory) String The audience of the claim. This should be filled in as the url of the company who the token is for (eg: http://coreplus.com.au).
nbf (mandatory) Long The nbf (not before) claim identifies the time before which the token MUST NOT be accepted for processing.. The UTC unix time at which this token was issued. jwtoken’s will not be accepted if the coreplus API UTC time is before this time.
exp (mandatory) Long The exp (expiration time) claim identifies the expiration time on or after which the token MUST NOT be accepted for processing. The UTC unix time at which this token was issued. This time should be set at 1 minute past the Issued time.
consumerId (mandatory) String(50) The Consumer Id of the application calling the coreplus API. This can be found in the “coreplus API Connection Details” document.
accessToken (mandatory) String(50) The Access Token used to identify which Customer the API commands should be executed on. Typically, this can be obtained from the customer as part of the setup process.
url (mandatory) String The url of the actual API request.
httpMethod (mandatory) String The http method (eg: GET, POST) used in the request.

The jwtokens should always be signed. Any jwtoken without a signature will be deemed invalid. The signature should be signed using the HMAC SHA-256 (HS256) algorithm, using the Consumer Secret, contained within the “coreplus API Connection Details” document.

Example encoded jwtoken, where blue is the header, pink is the claims and orange is the signature.

eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.
eyJjb25zdW1lcklkIjoiQ2xpZW50UG9ydGFsIiwiYWNjZXNzVG9rZW4iOiIwMGY0M jAzYi0xOTAxLTRmOGQtYjliZC05MDM2OGQ1NDMwNDkiLCJ1cmwiOiJodHRwOi8vbG 9jYWxob3N0OjIxNzc0L2FwcG9pbnRtZW50Ym9va2luZy9sb2NhdGlvbiIsImh0dHB NZXRob2QiOiJHRVQiLCJpc3MiOiJodHRwOi8vY2xpZW50cG9ydGFsLmNvcmVwbHVz LmNvbS5hdSIsImF1ZCI6Imh0dHA6Ly9jb3JlcGx1cy5jb20uYXUiLCJleHAiOjE0M
zY1MDg3MzMsIm5iZiI6MTQzNjUwODY3M30.9hJD-UR_bTvM0-OgBBKRFhYynqZtDvS5QSPX20aNInE

Jwtoken Header

{
    "typ":"JWT",
    "alg":"HS256"
}

Jwtoken Claims

{
    "iss": "<http://mydomain.com.au>",
    "aud": "<http://coreplus.com.au>",
    "nbf": 1436508673,
    "exp": 1436508733,    
    "consumerId": "",
    "accessToken": "",
    "url": “/api/core//location/”,
    "httpMethod": “POST”
}

API End Points

AvailabilitySlot

URL https://[server domain name]/api/core/[version]/AvailablitySlot/
Methods Supported GET
Description Retrieves a set available timeslots within a given date range.
Required parameters Type Description
startDate Date The start date of the period in which to search for free timeslots (yyyy-mm-dd)
endDate Date The end date of the period in which to search for free timeslots (yyyy-mm-dd)
timezoneId String(50) The timezoneId of the time zone for the search. Input times are assumed to be in this time zone, and results are returned in that time
zone. See GetLocations to determine the timezoneId for a given location.
pageNumber Int The page number of the results to return. The first page is 1, and so on. The results from row 1 to row 50 can be obtained by setting a
pageNumber 1 and a pageSize of 50. The results from row 51 to row 100 can be obtained by setting a pageNumber 2 and a pageSize of 50.
pageSize Int The maximum number of rows to return for the page. The pageSize is limited to a maximum of 100 at the time of writing.
Optional parameters Type Description
specialtyId String(50) Search filter: a list of specialties for which to search for available slots. (multiple items can be included for multiple specialties)
appointmentTypeId String(50) The id of the appointment type. (see endpoint “Specialty Types”)When this parameter is given, it will split the available time slots by the appointment type’s time duration. Otherwise the available time slots will not be split.
Example request /AvailabilitySlot/?startDate=2015-08-19&endDate=2015-08-19&&timezoneId=39D62534-501C-49CD-9DA9-6FA8D6A81F48&pageNumber=1&pageSize=50
Example response

        {
  "timeslots": [
    {
      "practitioner": {
        "practitionerId": "3dc6e75d-20b6-42bf-bb72-193ce9da85fc"
      },
      "startDateTime": "2015-08-19T10:20:00+10:00",
      "endDateTime": "2015-08-19T12:30:00+10:00",
      "locationId": "f280ef0f-3f5f-46dd-ae51-60fdd687fe13"
    },
    {
      "practitioner": {
        "practitionerId": "3dc6e75d-20b6-42bf-bb72-193ce9da85fc"
      },
      "startDateTime": "2015-08-19T13:30:00+10:00",
      "endDateTime": "2015-08-19T17:30:00+10:00",
      “locationId": "3c54fa14-648e-41f4-8f5e-8152de7dba9a"
    }
  ],
  "paging": {
    "pageNumber": 1,
    "pageSize": 50
  }
} 

Appointment

URL https://[server domain name]/api/core/[version]/Appointment/
Methods Supported POST, GET
Description GET – Get a list of appointments in a given date rangePOST – Makes an appointment booking with provided details or deletes an appointment (updating not supported at this time)
Permissions Access to this function requires advanced permissions for the calling application\user

MAKE A BOOKING (POST)

Required parameters Type Description
startDateTime DateTimeOffset The start time for the appointment (yyyy-mm-dd hh:mm + timezone offset) (24 hour time)
endDateTime DateTimeOffset The end time for the appointment (yyyy-mm-dd hh:mm+ timezone offset) (24 hour time).
practitioner Object containing Id The id of practitioner for whom to book the appointment (within a practitioner object)
locationId String(50) The id of the location for where the appointment is (see get locations).
clients Array of objects containing Ids An array of the client ids for this appointment – each within a client object (at least one).Note: Currently only 1 client is supported.
Optional parameters Type Description
appointmentTypeId String(50) The id of the applicable appointment type (see endpoint “Specialty Types”)
Subject String(300) If not provided, coreplus will use the name of the client and their date of birth as the subject.
Example request URL: https://[server domain name]/api/core/[version]/Appointment/BODY:


    {
      "startDateTime": "2015-08-19T09:40:00+10:00",
      "endDateTime": "2015-08-19T10:10:00+10:00", 
"practitioner": {
      "practitionerId": "f2542365-6fc0-4289-8911-2dec8201bdd6"
    },
 "locationId":"4027C199-2CE9-4DD9-BF17-03F3FC9E916D",
 "clients": [
      {
           "clientId":"22C6E75D-20B6-42BF-BB72-193CE9DA85FC"
      }
   ]
  }
}
Example response
{
  "appointment": {
    "appointmentId": "96dd0422-df81-486a-bf27-c85bf80c6fbd",
    "practitioner": {
      "practitionerId": "f2542365-6fc0-4289-8911-2dec8201bdd6"
    },
    "locationId": "eb7b4db7-3b33-4460-90b8-815626ab4181",
      "startDateTime": "2015-08-19T09:40:00+10:00",
      "endDateTime": "2015-08-19T10:10:00+10:00", 
    "clients": [
      {
        "clientId": "87b06ac1-b56b-4b16-af23-ff338ec63cc7"
      }
    ]
  }
}
Example response
(conflict or timeslot not available):

        {
 "result":
[
 {"severity":”error”,
  "reason":"The selected time is not available for booking an appointment"
 }
]
} 

DELETE A BOOKING (POST)

Required parameters Type Description
appointmentId String(50) The appointment Id to be deleted.
Deleted true Indicating to delete the appointment.
Optional parameters
None.
Example request URL: https://[server domain name]/api/core/[version]/Appointment/BODY:

{ 
    "appointmentId": " de4d5477-6c67-4fdb-94d0-dd06dd5e9776",  
    "deleted": "true"
}
Example response
{
  "appointment": {
    "appointmentId": "de4d5477-6c67-4fdb-94d0-dd06dd5e9776",
    "deleted": true
  }
}

GET Appointment

Required parameters Type Description
startDate Date The start date of the period in which to search for appointments (yyyy-mm-dd)
endDate Date The end date of the period in which to search for appointments (yyyy-mm-dd)
timezoneId String(50) The timezoneId of the time zone for the search. Input dates are assumed to be in this time zone, and results are returned in that time
zone. See GetLocations to determine the timezoneId for a given location.
pageNumber Int The page number of the results to return. The first page is 1, and so on. The results from row 1 to row 50 can be obtained by setting a
pageNumber 1 and a pageSize of 50. The results from row 51 to row 100 can be obtained by setting a pageNumber 2 and a pageSize of 50.
pageSize Int The maximum number of rows to return for the page. The pageSize is limited to a maximum of 100 at the time of writing.
Example request URL: https://[server domain name]/api/core/[version]/Appointment/?startDate=2014-09-01&endDate=2015-01-01&timezoneId=39d62534-501c-49cd-9da9-6fa8d6a81f48&pageNumber=1&pageSize=50
Example response
{
  "appointments": [
    {
      "practitioner": {
        "practitionerId": "3dc6e75d-20b6-42bf-bb72-193ce9da85fc"
      },
      "startDateTime": "2014-09-09T06:30:00+10:00",
      "endDateTime": "2014-09-09T07:30:00+10:00",
      "clients": [
        {
          "clientId": "87b06ac1-b56b-4b16-af23-ff338ec63cc7"
        }
      ],
      "appointmentId": "6e81de56-5411-4efd-b4c2-14b744433452"
    },
    {
      "practitioner": {
        "practitionerId": "f2542365-6fc0-4289-8911-2dec8201bdd6"
      },
      "startDateTime": "2014-09-30T09:00:00+10:00",
      "endDateTime": "2014-09-30T09:15:00+10:00",
      "clients": [
        {
          "clientId": "87b06ac1-b56b-4b16-af23-ff338ec63cc7"
        }
      ],
      "appointmentId": "68fcdbcc-af1f-493f-8aeb-6ce123bd895e"
    },
  ],
  "paging": {
    "totalRows": 2,
    "pageNumber": 1,
    "pageSize": 50
  }
}

Client

URL https://[server domain name]/api/core/[version]/Client/
Methods Supported GET, POST
Description GET – Gets a list of clients or details of a specific clientPOST – Creates a new client, if client does not already exist. It returns the client Id after matching/creation.For the matching rule, first name, last name and date of birth will be used as a default, but if the rule should be customized, please contact Coreplus support team.
Permissions Access to this function requires advanced permissions for the calling application

GET A LIST OF CLIENTS (GET)

Query String

Optional parameters Type Description
pageNumber int Used for paging the list of client – identify what page to get (default = 1)
pageSize int Used for paging the list of client – identify the number of results per page (default = 50)
Example request URL: /Client/
Example response
{
  "clients": [
    {
      "clientId": "33509f5b-bb5b-49b4-92ba-9d9240059eee"
    },
   {
      "clientId": "832b98a4-9603-47cb-9684-b4b39ddfacfb"
    },
    {
      "clientId": "fa09a4bf-9e95-4531-820e-01363c094e09"
    },
    {
      "clientId": "21271809-f27d-4d73-9dee-3d3cbab1d2a6"
    },
    {
      "clientId": "26800c60-ef23-4261-8a82-6c77091b2a87"
    },
    {
      "clientId": "81146b87-c601-4799-8ec1-d060b9888ff0"
    },
    {
      "clientId": "01282f68-9037-430a-8d0c-640661c73564"
    }
  ],
  "paging": {
    "totalRows": 7,
    "pageNumber": 1,
    "pageSize": 50
  },
  "statusMessages": []
} 

GET A CLIENT RECORD (GET)

Query String

Required parameters Type Description
clientId string The id of the client to get
Example request URL: /Client/33509f5b-bb5b-49b4-92ba-9d9240059eee/
Example response
{
  "clientId": "33509f5b-bb5b-49b4-92ba-9d9240059eee",
  "firstName": "test",
  "middleName": "",
  "lastName": "client"
}

CREATE A CLIENT (POST)

REQUEST BODY

Required parameters Type Description
firstName String(50) The client’s first name
lastName String(50) The client’s surname.
dateOfBirth Date The date of birth of the client.
Optional parameters Type Description
Gender String The gender Male or Female or empty.
medicareCardNumber String(20) The patient’s medicare card number
medicareCardIRN String(1) The patient’s medicare IRN number
medicareCardExpireDate Date The expiry date of the medicare card number (YYYY-MM-DD)
dvaCardNumber String(20) The patient’s dva card number
phoneNumberHome String(50) The patient’s home phone number
phoneNumberWork String(50) The patient’s work phone number
phoneNumberMobile String(50) The patient’s mobile phone number
Email String(50) The patient’s email address
addressResidential The patient’s address {“streetAddress”:””,”suburb”:””,”postcode”:””,”state”:””}
practitionerId String The ID of the Case Manager to be assigned to this client
Example request URL: /Client/BODY:


{
"firstName":"Phynx",
"middleName": "Huntington", 
"lastName":"Slavia",
"gender":"Male",
"dateOfBirth":"1961-07-30",
"medicareCardNumber":"214356789",
"medicareCardIRN":"1",
"medicareCardExpireDate":"2016-09-01",
"phoneNumberHome":"0334819194",
"practitionerId":"39d62534-501c-49cd-9da9-6fa8d6a81f48",
"addressResidential": {"streetAddress":"53 Barren Street",
                       "suburb":"Alexandra",
                       "postcode":"3714", 
                       "state":"VIC"}
}
Example response
{
  "client": {
    "clientId": "3dc6e75d-20b6-42bf-bb72-193ce9da85fc"
  }
}

Practitioner

URL https://[server domain name]/api/core/[version]/Practitioner/
Methods Supported GET
Description Retrieves a list practitioners based on a list of ids
Required parameters
None.
Optional parameters Type Description
pId String(50) Id of a practitioner whose profile should retrieved (multiple ids can be provided)
getSubspecialties Boolean Flag to determine whether each practitioner’s sub-specialties should be included in the response (true/false)
getAppointmentTypes Boolean Flag to determine whether the appointment types associated with the practitioner’s specialties should be included in the response.
(true/false)
Example request URL: Practitioner/?getSubSpecialties=true&getAppointmentTypes=true
Example response

{
  "practitioners": [
    {
      "practitionerId": "3dc6e75d-20b6-42bf-bb72-193ce9da85fc",
      "firstName": "Test",
      "lastName": "Practitioner",
      "email": "test.prac@email.com.au",
      "gender": "",
      "imageId": "13f5b125-1b06-4dcc-9bee-23a6de86369c",
      "description": "Practitioner profile description",
      "defaultViewingTimeZone": {
        "timezoneId": "39d62534-501c-49cd-9da9-6fa8d6a81f48",
        "tzName": "Australia\\Melbourne"
      },
      "specialties": [
        {
          "specialtyTypeId": "6af5f392-827c-49c4-9c12-9264e848fc18",
          "name": "Chripractic",
          "subSpecialties": [],
          "appointmentTypes": [
            {
              "appointmentTypeId": "a8f1c401-32ad-44a1-8177-97149248b8f6",
              "description": "Consultation",
              "durationMinutes": 60
            }
          ]
        },
         {
          "specialtyTypeId": "ffc51bc9-60dd-4976-9619-5d98d1c10a62",
          "name": "Occupational Therapy",
          "subSpecialties": [],
          "appointmentTypes": []
        }
      ]
    },
    {
      "practitionerId": "f2542365-6fc0-4289-8911-2dec8201bdd6",
      "firstName": "Practitioner",
      "lastName": "Prac Surname",
      "email": "testemail2@email.com.au",
      "gender": "Male",
      "imageId": "699e518f-baef-4b2c-9fae-5241fa5ef49f",
      "description": "test prac 2 description",
      "defaultViewingTimeZone": {
        "timezoneId": "5678c71f-7161-4e77-abe4-9337790e3996",
        "tzName": "Australia\\Adelaide"
      },
      "specialties": [
        {
          "specialtyTypeId": "6af5f392-827c-49c4-9c12-9264e848fc18",
          "name": "Chripractic",
          "subSpecialties": [],
          "appointmentTypes": [
            {
              "appointmentTypeId": "a8f1c401-32ad-44a1-8177-97149248b8f6",
              "description": "Consultation",
              "durationMinutes": 60
            }
          ]
        }
      ]
    }
  ]
} 

Location

URL https://[server domain name]/api/core/[version]/Location/
Methods Supported GET
Description Retrieves a list of locations based on a list of ids
Required parameters
None.
Optional parameters
None.
Example request URL: /Location/
Example response

    {
  "locations": [
    {
      "locationId": "30b5b0c4-18d4-4412-868c-60dbf645843c",
      "name": "Medical Centre South Australia",
      "streetAddress": "1 Main Rd",
      "postcode": "5092",
      "suburb": "Modbury SA ",
      "state": "",
      "country": "",
      "timeZone": {
        "timezoneId": "5678c71f-7161-4e77-abe4-9337790e3996",
        "tzName": "Australia\\Adelaide"
      }
    },
    {
      "locationId": "8032b32a-4f60-4667-9424-1453175ca757",
      "name": "Hawthorn",
      "streetAddress": "2/40 Barkers road hathorn",
      "postcode": "3122",
      "suburb": "HAWTHORN, VIC",
      "state": "",
      "country": "",
      "timeZone": {
        "timezoneId": "39d62534-501c-49cd-9da9-6fa8d6a81f48",
        "tzName": "Australia\\Melbourne"
      }
    }
  ]
}

SpecialtyType

URL https://[server domain name]/api/core/[version]/SpecialtyType/
Methods Supported GET
Description Retrieves a list of specialty types that can be used for searching for available time slots
Required parameters
None.
Optional parameters Type Description
getSubspecialties Boolean Flag to determine whether each practitioner’s sub-specialties should be included in the response (true/false)
getAppointmentTypes Boolean Flag to determine whether the appointment types associated with the practitioner’s specialties should be included in the response.
(true/false)
Example request URL: /SpecialtyType/?getSubSpecialties=true&getAppointmentTypes=true
Example response

            {
  "specialtyTypes": [
    {
      "specialtyTypeId": "6af5f392-827c-49c4-9c12-9264e848fc18",
      "name": "Chripractic",
      "subSpecialties": [],
      "appointmentTypes": [
        {
          "appointmentTypeId": "a8f1c401-32ad-44a1-8177-97149248b8f6",
          "description": "Consultation",
          "durationMinutes": 60
        }
      ]
    },
    {
      "specialtyTypeId": "bafe9b2b-785f-438c-a1b4-657b0040bee5",
      "name": "Osteo",
      "subSpecialties": [
        {
          "subSpecialtyTypeId": "cafe9b2b-785f-438c-a1b4-657b0040bee5",
          "name": "Osteo Sub 2"
        },
        {
          "subSpecialtyTypeId": "6e708a47-50a7-4039-9415-7252931a95a2",
          "name": "Osteo Sub 3"
        }
      ],
      "appointmentTypes": [
        {
          "appointmentTypeId": "1f50fee7-28eb-4dc1-8ba5-8f0c15e91914",
          "description": "Follow Up",
          "durationMinutes": 30
        },
        {
          "appointmentTypeId": "a8f1c401-32ad-44a1-8177-97149248b8f6",
          "description": "Consultation",
          "durationMinutes": 60
        }
      ]
    }
  ]
}

    

Timezone

URL https://[server domain name]/api/core/[version]/Timezone/
Methods Supported GET
Description Retrieves a list of timezone that can be used for api calls with time parameters\responses. Timezone is a global list across clinics/practices and has the same IDs on the sandbox and on the production.
Required parameters
None.
Optional parameters
None.
Example request URL: /Timezone/
Example response

{
  "timezones": [
    {
      "timezoneId": "beb26b96-6250-4d68-ac36-a40196805e1f",
      "tzName": "Australia\\Hobart"
    },
    {
      "timezoneId": "39d62534-501c-49cd-9da9-6fa8d6a81f48",
      "tzName": "Australia\\Melbourne"
    },
    {
      "timezoneId": "5cc83375-4b61-4a17-9a77-59657cf3da64",
      "tzName": "Australia\\Sydney"
    },
    {
      "timezoneId": "0b317300-1859-4013-9615-fe3e38732391",
      "tzName": "Australia\\Brisbane"
    },
    {
      "timezoneId": "5678c71f-7161-4e77-abe4-9337790e3996",
      "tzName": "Australia\\Adelaide"
    },
    {
      "timezoneId": "536e3831-9cf7-43ab-aa7f-acf0adcd796b",
      "tzName": "Australia\\Darwin"
    },
    {
      "timezoneId": "571c7138-03f1-4e9f-8315-78caad82f2a3",
      "tzName": "Australia\\Perth"
    }
    ]
} 

21 October 2015: API almost ready for Beta release

Not sure where to begin?

Read through our Developer Sandbox: Using the Developer Tools Help Centre article to get the details. In fact, you could learn how each feature of coreplus works from the wide array of Help Centre articles.

Questions? Reach out and ask.

  • Want to talk about endpoints under development?
  • Experiencing issues?
  • Need to speak with a coreplus developer?

Contact Us