Purpose #
When designing an integration, you will need to think about the different Endpoints available in OS Online to send and receive data and work out how best they will fit into your current workflow and business processes. This document is designed to help support you in the design and development of your integration build between Outcomes Star Online (OS Online) and your own system, providing you with general architectural principles and tips on how to use our API endpoints in the appropriate manner. Please note that this document is for those interested in building an integration between OS Online and a Customer Relationship Management (CMS) system and is not relevant to those looking to integrate only Outcomes Star data for data analytics purposes.
This document also outlines the requirements your build should meet in order to be successful under our Quality Assurance Criteria.
Please ensure that you have read and understood the OS Online Integration Set Up Guide prior to using this document as it outlines all the terminology and contextual information to make this document useful to you.
Service User Matching #
Service Users are identified and managed through the API by using a unique identifier stored in the “id” field of OS Online.
{
"id": "3fa85f64-5717-4562-b3fc-2c963f66afa6"
}This unique identifier will need to be stored in your system for each Service User to perform API calls.
Initial Record Match
If you are already using OS Online and have existing Service Users in your OS Online account, you will need to map the existing Service Users to the Service User records in your own system by recording their id value in your system. You can do achieve this through two methods:
- Using the POST /api/patients-duplicate endpoint
This will enable you to search your OS Online account for records by either their First Name, Last Name, and DOB or by their Service User ID, depending on whether your Star Online account displays Service User Identifiable Information. This endpoint will then find matches for each Service User you search for and output their id ready to be stored in your system.
If you are designing an integration that is to be used by multiple OS Online accounts, you will need to factor in that they may or may not have Service User Identifiable Information displayed within Star Online. This could impact whether you should be searching with Name & DOB, or Service User ID when undertaking an initial record match using the endpoint and you may need to accommodate for both possibilities. For more information on Service User Identifiable Information, please consult the Setup Guide.
- Using the GET /api/patients endpoint and manually matching Service Users.
Alternatively, you could extract the ids, Names, DOBs, and Service User IDs of all the Service Users in your OS Online account using the above endpoint. You could then manually assign the ids to the corresponding Service User records in your system.
After Initial Mapping
If you intend to create new Service Users on OS Online via your own system, you will need to ensure that you save down the ids of Service Users created using the POST api/patients or POST api/patients/batch endpoints in your system upon creation. This way your Service Users will be continually linked to OS Online.
If you are not making use of the POST api/patients or POST api/patients/batch endpoints to create new Service Users in OS Online via your own system, you will need to consider how you will manually assign the IDs of new Service Users created in OS Online.
Practitioners
You will need to think carefully about the visibility of the OS Online Service User and Star data that will enter your system via the integration, and whether there are any security risks involved. OS Online has a permissions structure so only permitted users have access to Service User records, and the API is designed so that you can replicate this functionality in your own system.
If your integration simply provides a hyperlink for a Service User record or Completed Star on OS Online then only users with the necessary permissions on the OS Online will be able to access this link, and you will not need to make further considerations.
All API endpoints have the option to pass a Practitioner ID that the Star Online permissions structure can be replicated in your integration. Therefore, you will need to make use of this functionality and consider security implications if:
- You need to ensure that only the relevant practitioner can view OS online Service User identifiable information in your system.
- You need to ensure that only the relevant practitioner can generate and view Star pdfs in your system.
- You are creating Service Users in OS Online via your own system, and you need to ensure that the correct practitioner owns the correct Service User record.
- You need to ensure that only the relevant practitioner can update their Service User information in OS Online via your system.
If any of these cases apply to you, you will need to go through an exercise of matching practitioners’ records to OS Online practitioners, like the ‘Initial Record Match’ depicted above for service users. This can be achieved by extracting your practitioner data using the GET /api/practitioners endpoint, matching practitioners to your system practitioners by their email address, then recording the Practitioner ID to each user in your system.
Please note that it is mandatory to pass a Practitioner ID for the PUT api/patients/{id}, POST api/patients and POST api/patients/batch endpoints. If you don’t need to pass a practitioner ID in your use case, you can simply pass the Practitioner ID of the Account Lead to ensure all calls are successful.
If you pass the practitioner ID of your Account Lead for all Service Users created via the POST api/patients and POST api/patients/batch endpoints, be aware that only the Account Lead will be able to link the pending Service Users to the appropriate service on the OS Online.
Integration Triggers #
The OS Online API does not yet support webhooks, and therefore you will need to set up your integration to run on a regular schedule, or via buttons within your system.
If using a schedule, you will be able to use the dates of ‘the most recent Star finalised’, ‘the Star due date’, and ‘the date the Service User was last modified’ to identify the Service Users that the integration should run on for a particular time or day. This will optimise your integration so that it doesn’t make endpoint calls on every Service User each time it runs.
These dates are recorded in the GET api/patients and GET api/patients/{id} endpoints:
{
"datelastmodified": "2000-01-01T00:00:00.000Z" *Available from November 2025
"mostRecentFinalisedStar": "2000-01-01T00:00:00.000Z"
"nextStarduedate": "2000-01-01T00:00:00.000Z"
}Integration Use Cases #
Below is a list of use cases that can be achieved with an OS Online integration build, and the endpoints you will need to use for each (after Service User and practitioner record matching has been completed).
“Jumping from a Service User record in your system directly into the relevant Service User record or Star record page in OS Online”
Endpoints required: GET api/patients/{id}
Please note that in order to move to OS Online without needing to login without a password, you will need to enable single sign on (SSO) on your Star Online account. For help getting this set up, please speak to the Star Online Helpdesk at [email protected]
“Displaying the date Service User created, total number of Stars completed, date of most recent Star completion, and Star due date in the relevant Service User record in your system”
Endpoints required: GET /api/patients/{id}
“Creating a Service User in your system, and automatically creating the corresponding record in OS Online”
Endpoints required: POST /api/patients
“Updating a Service User name, date of birth, Service User ID, or primary care ID in your system, and automatically updating the corresponding fields in OS Online”
Endpoints required: PUT /api/patients/{id}
“Generating star pdfs for a Service User from within your system”
Endpoints required: GET /api/patients/{id}/latest-stars or GET /api/patients/{id}/all-stars, GET /api/patients/{id}/stars-summary-download
Quality Assurance Criteria #
In order for your integration to be a success, in addition to the acceptable use clauses in the Integration Licence Agreement, you will need to consider and address the following criteria:
- Have a robust mechanism in place for matching the Service Users in your system with Service Users in your OS Online Account, for both existing and future Service Users.
- If there is the possibility that your integration will be used for multiple OS Online accounts, ensure your integration can be used by accounts both displaying and not displaying Service User identifiable information.
- Make careful consideration to the security models of the accounts using your integration to ensure that:
- Comply with Outcomes Star copyright and ensure all our intellectual property is recognised and credited within the software.