Introduction

Midwinter’s API allows its customers and third party software providers to integrate with Midwinter’s AdviceOS product. This User Guide provides information specific to connecting, accessing and using the Midwinter API for all AdviceOS environments.

Midwinter’s standard API is JSON based and the latest documentation is available on Swaggar. If you have any questions regarding this User Guide or the Swagger documentation, please email [email protected].

The legacy Midwinter API (XML based) is no longer supported. Please contact Midwinter for any questions in regards to the legacy API.

This guide requires a technical understanding of APIs and is intended to be a user guide for qualified developers.

Governance

Access and use of Midwinter’s API is governed by the terms and conditions set out in an agreement between Midwinter’s customers or Midwinter’s third party software providers and Midwinter Financial Services Pty Ltd ABN 22 121 020 620.

Definitions

The following terms will be used throughout this document:

Term	Description
AdviceOS	The application that hosts the Midwinter API outlined in this guide.
Source Application	The client application (third party to AdviceOS) that is making/originating the API  call.
Source Application User	The user (username and password) of the source application that is prompting the call (note the application user is not an administration user).
Source Application ID	A client ID to identify the source application in AdviceOS.
Source Application URL	A URL provided to AdviceOS that is used as part of the authorisation of each web API call.
Secret Key	A code provided to the Source Application (by AdviceOS) to use as part of the authorisation of each web API.
Token	A value generated by AdviceOS (using the Source application – ID and Secret Key) when the Source Application calls the security API using postman. The service can be accessed via Production: Http POST https://adviceos.com.au/appapi/v1/security/token Staging: Http POST https://staging.adviceos.com.au/appapi/v1/security/token
AdviceOS user	The corresponding user in AdviceOS (i.e. a Source Application user who has access to AdviceOS).
OAuth	Framework used to authenticate a web service call between AdviceOS and the Source Application.
Swagger	An API developer tools for the OpenAPI Specification enabling development across the entire API lifecycle. Please see the Swagger documentation for more technical details regarding requests and responses. The service can be accessed via Production: https://adviceos.com.au/appapidocsui/index Staging: https://staging.adviceos.com.au/appapidocsui/index

Public API Overview

The Midwinter API endpoints are documented on Swaggar. This includes technical specification, request parameters, body parameters and expected response body. This information is updated in line with the API functionality.

Links to environments and documentation

Midwinter provides three environments that can be used with the Public API. Each environment has a corresponding AdviceOS user interface that can be accessed to support testing activities. The environments and their corresponding URIs are in the below table:

Environment	Swaggar Link	AdviceOS UI Link
Production	https://adviceos.com.au/appapidocsui/index	www.adviceos.com.au
Staging	https://staging.adviceos.com.au/appapidocsui/index	www.staging.adviceos.com.au
Test	https://test.adviceos.com.au/appapidocsui/index	www.test.adviceos.com.au

The Swaggar link in the table above will reflect the documentation that is relevant for that environment. When API changes are planned, the changes can be reviewed in the relevant Swaggar (Test and Staging) link before they are made live in production.

Environment refreshes

Data in non-production environments are refreshed with sanitised production data in line with Midwinter’s release cycle. The test environment will be refreshed every weekend and staging will be refreshed every fortnight on the day of a production release. Please contact [email protected] for specific release dates.

Authorisation scope

Access to the API is provisioned at either the Licensee or Practice level. When provisioned at the Licensee level, all client data for practices under that licensee is available via the API. When provisioned at the Practice level, all client data for that practice is available via the API.

AdviceOS users

Authorisation for existing users can be arranged at either the Licensee or Practice level depending on the requestor’s position. Midwinter will only provision access to a practice or licensee if the requestor is part of that organisation.

Third parties

Once an agreement is in place with Midwinter, third parties can be provided access to a ‘dummy site’ for the purpose of development and testing an integration. For individual practice or licensee data to be made available for an integration with third parties, Midwinter will require additional agreements to be in place with all relevant entities.

Getting Started

Authorisation

Once Midwinter has provided an API secret, you will be able to authenticate to the Public API. AdviceOS uses the Microsoft Identity Framework and the OAuth 2.0 Authorisation framework to authenticate and authorise each API call based on the originating source user.

Process

The process below outlines how to authenticate to the Midwinter Public API. Note, screenshots are from the third-party tool Postman, however any tool or application may be used for testing.

Step 1: Prepare a request for authorisation to the authorisation URL (refer to Swaggar). The request body should include the following text, replacing [Secret] with the secret provided by Midwinter without square brackets.

Step 2: If the authorisation request was valid, you will receive a token in response.

Step 3: This token should be included in all subsequent calls to the Public API.

Step 4: You can create multiple tokens for one user based on the maximum limit (currently 10).

Appendix

HTTP status codes

Code	Response
200 Ok	Everything worked as expected.
401 Unauthorized	Access token is invalid or expired.
400 Bad Request	Invalid data in the request payload.
402 Not Found	No linking record exists for external ID of the user.
403 Forbidden	Authentication was provided, but the authenticated user is not permitted to perform the requested operation.
500 Internal Server Error	Something wrong in API server.

Error Result messages

If there was an error in executing services, the error description will be presented in response. The list below is the list of common errors in the Public API.

Service name	Description	Common cause
Get(ID)	No link record exists for externalId { } for this user.	For Get(ID) calls the provided ID does not exist or user has not permission to access it.
Post(ID)	Entity to be updated from ID { } does not exist for this user.	For Post(ID) calls, there is no entity based on provided ID to be updated from XML or user has not permission to access it.
Delete(ID)	No Entity found for ID {}	For Delete(ID) calls, there is no entity based on provided ID or user has not permission to access it.
Put(ID) / Delete(ID) / Get(ID)	User doesn’t have permission to access the client with ID .	The login user has no permission to the externalID that is provided.
Post/Put	{fieldname} data is not valid.	Some payload fields must match master data in AdviceOS and will return an error if a known value is not provided. Master data links are available in swagger model sample.
Get(ID)	No link record exists for externalId { } for this user.	For Get(ID) calls the provided ID does not exist or user has not permission to access it.