on 25-03-2021 06:40 PM - last edited on 15-09-2023 08:48 PM by jim.farrell
This document outlines the technical information on the Iress Open API providing summary client level data to integrators.
The Iress Open API is an HTTP 1.1 REST API to allow third party systems to integrate with the Xplan platform. The Iress Open API offers access to Xplan’s core business functionality presented in a usable and consistent structure. The semantics and conventions of the Iress Open API should be immediately familiar to programmers accustomed to REST.
Some example use cases of the API are:
The Iress Open API is a gateway service that will be hosted in Australia, South Africa and UK. All integrators use the same URL to access Iress Open. The domain name resolves to the closest deployment of Iress Open.
User Acceptance Testing URL (example): https://api.iressopen.com.au/swagger/index.html?urls.primaryName=2.0
The integrator specifies the Xplan Site they wish to integrate with through an HTTP header ‘x-forwarded-host’.
In order to make requests using the Iress Open API, you must first obtain an Iress Open ‘app id’ from Iress. This app id is passed as an HTTP header when you authenticate with Iress Open, this identifies your application to us, and restricts the capabilities of the user you log in with to those required for Iress Open. Each integrator will be provided with a single app id that will be sufficient for both UAT and production environments and will work on all Xplan sites. To use OAUTH2 for authentication an app id per environment is required.
See the Authentication section for more information.
An overview of information about the HTTP transport used in the API. For more detailed documentation about the resources available please use the following links. Please ensure that the current version is selected top right:
The information is presented through the swagger UI. Swagger specification is a commonly used standard for describing APIs and supports code generation:
This section contains a detailed specification of the API transport. The specification described below applies to all interactions with the API.
The version of the API to use is passed in as a query parameter to the api endpoint as /client?api-version=<version> (e.g. /client?api-version=1.0). If the version query parameter is omitted the default version is assumed. Changing the version may affect global behaviour of the API such as object serialization, default response formats and error codes.
Integrators authenticate with a specific Xplan Site, using one of two methods supported by Xplan
OAuth 2.0 is a protocol that lets your app request authorisation to private details in a user's Xplan account without getting their password and hence more secure.
The sequence diagram below shows a typical OAUTH integration. This user story demonstrates an Xplan user navigating from Xplan to an integrator’s website, and that website being able to use Iress Open to retrieve data from Xplan.
You need to register your application with Iress before getting started. A registered application is assigned a unique app id and secret which will be used in the OAuth flow. The Secret should not be shared, and should be stored securely.
You will also need to provide a redirect URI when registering your application with Iress. Xplan will post the access token back to you at your registered redirect URI. You can register a single absolute redirect URI for your application. Should you require more than one url to be registered i.e. for development or staging environments, you will require one app id per environment.
Please see the article Xplan API OAuth 2.0 for how to connect using OAuth 2.
Requests made to the API are constrained by the visibility of the user used to login to the session - for example, getting a list of docnotes will return the docnotes visible to that user only, not all the docnotes in the system.
Each request made to the API specifies:
POST and PATCH operations often require Keys to be specified for user-defined types in Xplan, use the supplied options resource e.g. /client/address/options to retrieve a list of valid keys, e.g. for AddressType
HTTP methods specify the operation to perform on a resource. The API supports the following HTTP 1.1 methods:
GET - Retrieve a description of the resource. GET operations have no side-effects (i.e. they are safe according to HTTP 1.1
POST - For a collection of resources, creates a new item in the collection.
PATCH - Update an existing resource by merging the contents of the request with the existing resource. Only the data that is being changed should be send in the request.
DELETE - Delete the resource.
Except where specified in the resource’s documentation, responses to the API are in JSON format.
The structure of the response for a method is specified in the resource’s reference documentation.
Xplan’s error codes are consistent with HTTP/1.1 semantics as specified in RFC 7231.
Successful requests will return the following HTTP codes:
Code |
Meaning |
---|---|
200 |
Success. GET will return a copy of the resource in the body. PATCH will return the id of the item updated. |
201 |
Successful creation. POST to a collection will return a copy id for the newly created item. |
204 |
Success, with an empty body. This is returned by a successful DELETE. |
Failed requests will return the following HTTP codes:
Code |
Meaning |
---|---|
400 |
Bad request. The parameters specified by are invalid. This can indicate a problem with malformed syntax (e.g. bad JSON) or invalid arguments being passed. The body of the response will give further details. This typically indicates an issue with the request, not with Xplan or Iress Open. |
401 |
Unauthorized. The credentials provided were invalid for this resource. If credentials were provided via a session token (via cookie or otherwise), the token may have expired and the client may need to re-authenticate using a username and password. If a username and password were provided to the request that returned 401, they are not valid for this resource - either the login itself is not valid or perhaps the account is locked out. This typically indicates an issue with the request or configuration/status of the Xplan user account, please contact the site owner to resolve. |
403 |
Permission error. The session does not have sufficient Xplan capabilities to perform the operation. You can check the capabilities of your session by calling the Session endpoint. This typically indicates an issue with the capabilities configured for the Xplan user you are using, please contact the site owner to resolve. |
404 |
Not found. The resource identified is invalid. Check the URL you are using, could a mis-spelling or if not that then if a resource (client / asset etc) is identified perhaps the resource has been deleted, or is no longer visible to your user. In the first instance contact the site owner to resolve. |
409 |
Conflict. Another session was updating the resource when this request was executed. Normally the request will succeed when resent. |
500 |
Unspecified server error. Please report these errors to Iress so we can improve our service to you.See Technical Support for details on how to report. |
502 |
Upstream server failure. An error occurred when communicating with another server, this may be an unhandled error in Xplan. Please report these errors to Iress so we can improve our service to you.See Technical Support for details on how to report. |
As well as the error code, there may be further details returned in the response body that describes the problem in detail. These details will often help you to understand the cause of the error. Do not programmatically scan this string in your app; its contents are subject to change across versions. Rely on the HTTP code only.
{
"StatusCode": status code,
"Message": "A message to identify the reason for failure, may be a string or a structure"
}
Integrators can raise issues (e.g. an error code is returned) directly to Iress using the Developer Forum.
The process allows Integrators to raise issues with Iress. Iress will need information about the issue or error (see below).
Integrators should supply the following data (where applicable).
Xplan is deployed to meet expected demand, as such there are limits and Xplan customers should speak to their Iress account managers if there are significant bottlenecks.
Integrators are aware that there are restrictions on the use of the Iress Open service, appropriate use of the service should ensure there is no degradation of performance for Xplan users.
Iress Open depends on Xplan, Xplan availability targets, maintenance windows and incident response times are agreed with Xplan site owners.
Iress is a technology company providing software to the financial services industry.
Our software is used by more than 9,000 businesses and 500,000 users globally.