API Setup Guide

OS Online Configurations #

Service User Identifiable Information – at Account Level #

The configuration of your Star Online platform for Service User Identifiable information at an Account level will impact how you use the API Endpoints. The Service User Identifiable Information settings control how the following fields are used in the system:

• Forename
• Surname
• Preferred Name
• DOB
• Service User ID

Service User ID is a free text field that you have in Star Online to add extra reference data for a patient. For example, some clients use this field to store a Patient’s NHS number. This field is mandatory if you choose to have Service User Identifiable Information (SUII) disabled in your SOL configuration.

There are 3 options for how this data is used in Star Online:

Option 1  – Fully Enabled

This is the default setting

Option 2 – Partially Enabled

This means that only the DOB is visible on Star Online

Option 3 – Fully disabled

All 4 fields are hidden.

Please note that if Service User Identifiable Information is disabled for an account then the API will not permit you to post Patient data across containing these fields.

Consent permissions in Star Online (at a user level) #

In line with GDPR legislation, SOL has a consent feature that is managed at a User level. This means that SOL requires the Service User to give consent before a record can be created.

When this feature is activated, the API will only create or edit an existing Patient record via the API if the Service User has actively given consent. On the endpoints:

POST /api/patients

POST /api/patients/batch

The following data items are included in the Request body on the POST endpoints:

• ConsentGiven (true/false)
• whoGaveConsent (ServiceUser/PatientRepresentative)
• ConsentGivenByPatientRepresentativeDetails (optional)

The ConsentGiven must = true for the endpoint to succeed. If ConsentGiven = false then a 400 (Bad Request) will be returned.

If ConsentGiven = true, whoGaveConsent must be populated.

Similarly, to make amendments to a Service User record in SOL, the Service User must give consent when this feature is activated.

Therefore, you will be prevented from using the following endpoint unless the Service User has actively given consent in the SOL platform:

PUT /api/patients/{id} 

Please note: it your organisation’s responsibility to ensure the process for obtaining and recording service user data is in line with the data privacy policies and legislation affecting your organisation, such as GDPR.

The table below helps to illustrate these rules for mandatory fields with posting Patient data to Star Online when using the API for the endpoints:

POST /api/patients

POST /api/patients/batch

Option on SOL	Status on account	Mandatory fields on SOL	Mandatory fields via POST PATIENT API
Service User Identifiable Information	Fully enabled	ForenameSurnameDOB	ForenameSurnameDOB
	Partially enabled	Service User ID	Service User IDDOB
	Fully disabled	Service User ID	Service User ID
Service User Consent	Enabled	Consent given (tick box) Who provided consent	Consent given (must be true) Who gave consent
	Disabled	None	None

Practitioner Permission Settings #

Note that your Star Online configuration allow for different Practitioner permissions, and these determine different outcomes in the API when requesting or attempting to edit Patient records.

Type	Description
Unrestricted	Allows practitioners linked to a service to view and edit all engagements (and associated service user records) linked to that service
Partially Restricted	Allows practitioners linked to a service to view all engagements (and associated service user records) linked to that service but to only edit where they are the Lead Practitioner
Restricted	Allows practitioners linked to a service to only view and edit engagements (and associated service user records) where they are the Lead Practitioner.

Connecting to the API #

Test Environment #

When you are ready to start development, there is a Sandbox Swagger site available online where you can view the Request body required by each endpoint and also view the Response codes and their various meanings.

HTTP Request URL:

To access the data-only exports, you will need to make a HTTP request using the following URL:

The request URL you will need to make HTTP requests from the Sandbox is:

https://triangle.qes-online.com/ApiSandboxApi/api/{endpoint}/{possible id}?{possible parameter}={parameter id}

HTTP Request Headers:

Bearer token

This needs to be passed along with the URL as a HTTP header with the following format:

– header name:

Authorization

– header value:

Bearer [api key]

HTTP Request Body:

You may be required to pass a body to the request dependent on the endpoint you are using, see section 5 for more details.

The Outcomes Star support team will provide you with access to a developer sandbox where you will have a test account that you can use to send data to / export data from. This test account will have an Integration Lead user licence – you will need to decide which email address will be used as the Integration lead. This person will be able to create the API key(s). See more information on this process in Section 3 of this document.

The Outcomes Star Support Team will need to setup this Integration Lead user. They will also be able to setup test Account Lead and Practitioner accounts on this test account so that you can fully test the User Journey related to PUT & POST /api/patients.

Who should be the Account Lead on the Sandbox at my organisation?

It probably makes the most sense to have the person who is leading the API integration project at your organisation assigned to the Account Lead role on the SOL Sandbox. This may not be the same person who is your Account Lead on the live SOL site. This Account Lead will need some knowledge of SOL as they will need to add some test data. But they will also be able to add Practitioner users to the Sandbox environment and these users will be able to assist with data entry and testing.

Who should be the Integration Lead at my organisation? (Sandbox & Live)

If you have an in-house tech team that develop your Primary System, then the person responsible for managing the API development should have this Integration Lead role on SOL. If you use a 3^rd party provider for your Primary System, then we would recommend that the person in your organisation who is the primary contact for your software provider should take on this role although the 3^rd party can take this role if required.

Go-Live #

When you are ready to go live, the Triangle Support Team will need to add the Integration Lead user to your live account so that this user can then generate a new API key. You will need to update your code to reflect this change in API key. They will also provide access to the live SWAGGER site.  You will also need to update the Request URL to point at the live server.

From this for the Sandbox:

https://triangle.qes-online.com/ApiSandboxApi/api/{endpoint/{possible id}?{possible parameter}={parameter id}

 To this for live for live:

https://triangle.qes-online.com/LiveApi/api/patients/{endpoint/{possible id}?{possible parameter}={parameter id}

Bearer token

This needs to be passed as a HTTP header with the following format:

– header name:

Authorization

– header value:

Bearer <api key>

Import SOL Patient IDs into your Primary system

You will need to be able to store the SOL Patient ID in your system as a Foreign Key in your Patient records to be able to successfully use the Endpoints. Use the GET /api/patients endpoint for this task.

Import SOL Practitioner IDs into your Primary System

This is optional but if you wish to be able to enable your practitioners to manually post new patients into SOL or edit existing Patient records in SOL via the API then you need this data.  

Use the GET /api/practitioners endpoint for this task.Note that having knowledge of the Practitioner ID will also be useful if you wish to Request data in the following Endpoints which have an option to restrict the data returned by Practitioner Service assignment:

GET /api/patients/{id}
GET /api/patients
GET patients/{id}/latest-stars
GET patients/{id}/all-stars
GET patients/{id}/star-summary-download

API keys #

Generation and Use of API Keys #

The API keys are generated on SOL – Your organisation will be given a licence for the Integration Lead role by the Triangle Support Team.  This IL user can then login to SOL and generate one or more keys for use in the API. If you are intending to setup multiple systems to integrate with the SOL API then we recommend that each system should use its own API key as this will make auditing and troubleshooting easier.

Once you have generated and named the API key – you will then need to save this securely elsewhere as it will not be retrievable on SOL for security reasons.

You can also then upload a logo for the software that will be integrating with SOL and this will then be displayed on the SOL Service User Details interface. Note also the Download Logs button – this is a useful auditing feature that enables you to download an extract detailing API activity. There is also a feature on this interface to Revoke a given API key if needed.

NOTE: If the staff member leaves who held the Integration Lead role and you wish to retain the existing API key(s) then you can overwrite their user record in SOL with the details of the new staff member and the existing API key(s) will remain active.

API Security – IP limiting #

The API includes an optional feature that you can use to restrict access to the API by the IP address of your server that will be managing the integration.

When you create the API key you are prompted to enter an IP address. You can enter multiple IP addresses separated by a comma if needed. You can also leave it blank or enter a default value of a * which allows any IP address to make a valid request. Then whenever a request is made, we will make sure that it originated from an accepted IP address.

API Security – Rate Limiting #

With regards to rate limiting, this is limited to 10 requests per second for anything other than the extract endpoints from a given IP address. If it’s the extract you are calling, the rate limiting is set to 1 request every 10 seconds from a given IP address. If you exceed the rate limit then you will receive a http 429 response (Too Many Requests). 

Troubleshooting and contacting the Support Team #

Contacting SOL

If you need any support with using the API please contact the OS Online Helpdesk [email protected]

Correcting errors

 Generally the PUT /api/patients/{id} can be used to correct any errors in data that you may have sent to SOL.

An explanation of the GUID’s and ID’s in OS Online #

Field Name	Description
id	This is the GUID for the Patient Record. This unique reference is only used by the API and is not the same as the Primary Key for the Patient record used in the OS Online database. This ID is not visible anywhere on the OS Online Interface.
primaryCareId	This is the system ID used in the database of your Primary Care System. We ask you to send this to us so that we can store the primary key for patient records from your system within OS Online in the same way that we ask you to store the ID field for Patients (GUID) in your Primary Care System.
serviceUserId	This is a free text field that you have in OS Online to add extra reference data for a patient. For example, some clients use this field to store a Patient’s NHS number.   See section 2 below for more detail on how to use this field in the API.
practitionerId	This is a GUID used in the API for a Practitioner record. Used optionally in the Endpoints: GET /api/patients/{id} GET /api/patients/ GET /api/patients/{id}/latest-stars GET /api/patients/{id}/all-stars GET /api/patients/{id}/star-summary-download   Returned in the Endpoints: POST /api/patients POST /api/patients/batch
starOnlineId	This is a GUID used in the API for a Practitioner record.   Used in the Endpoint GET /api/practitioners/{id}
id	This is a GUID used in the API for a Practitioner record.   Requested in the endpoint: GET/api/practitioners/{id}

Screenshot illustrating where the Service User ID and Primary Care ID can be viewed on the OS Online interface. Note that the Primary Care ID can only be edited via the API.

Glossary of Terms

• Account Lead – this user is responsible for setting up and administering the OS Online account and being the first point of contact for questions from your colleagues using the system. The Account Lead does not need to have any advanced technical skill, but does to be aware and compliant with the organisation’s data protection policies.
• FHIR – Fast Healthcare Interoperability Resources. The global standard that defines how data can be shared between different Healthcare Information Systems.
• Integration Lead – this user can log into OS Online and generate API key(s). No other user is able to generate these keys.
• Patient – This term refers to a Service User. We have used this expression in order to be compliant with FHIR data format.
• Patient URL – this is the URL that will link the user directly to the Patient record in SOL – note that the user may need to login first and if they do not have the correct service assignment in SOL then this Patient record may not be displayed to them.
• Primary Care ID – this is a term for the Primary Key used in the database of your Primary Care System for a patient record. This may not be the same as the ID displayed on the UI for the Patient record.
• Primary software – the software sending data / receiving data, will usually be a case management/electronic patient record system
• Service User ID – this is the free text field in SOL (called Service User ID on screen on the Edit Service User screen) that you may have used to add a User’s NHS number, room number, Primary System ID or any other data that you use to uniquely identify your service user.
• SOL – Outcomes OS Online