Please sign in or register to access software information via the Iress Community.
Xplan Integrations
Showing results for 
Show  only  | Search instead for 
Did you mean: 

Iress Open Standard Integration - Technical Overview

Iress People


Document Purpose

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:

  • Back-end system integration
  • Rich web applications running inside a web browser
  • Native applications (Mobile or Desktop)

The Iress Open API is a gateway service that will be hosted in multiple regions. The first two of these regions are United Kingdom, and Australia. 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):

The integrator specifies the Xplan Site they wish to integrate with through an HTTP header ‘x-forwarded-host’.



Iress Open App ID

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.


API Technical Overview

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 V2 is selected top right:

UK Region - UAT (external)

AU Region - UAT (external)

ZA Region - UAT (external)

The information is presented through the swagger UI. Swagger specification is a commonly used standard for describing APIs and supports code generation:

  • Authentication is performed using OAUTH2 (Authorization Code Grant).
  • The API is accessed using typical JSON API and HTTP 1.1 conventions.
  • Resources are located through hierarchical paths.
  • The actions to be performed on a resource is specified by the HTTP method.
  • Request parameters must be encoded either in the URL’s query component (for GET requests) or, for other method types, in the request body
  • Request bodies containing structured data must be encoded as application/json with the Content-Type HTTP header set accordingly.
  • Responses containing structured data are encoded as application/json.
  • HTTP 1.1 status codes are used to indicate success (using a 2xx code) or error (4xx or 5xx). When an error occurs, HTTP status messages and JSON data in the body may give more information about the problem.


HTTP Transport Reference

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:

  • The resource to operate on (specified by the URL path)
  • The operation to perform (specified by the HTTP method)
  • Parameters that modify the behaviour of the request (query parameters for GET requests, encoded in the request body for other methods).


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

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:






GET will return a copy of the resource in the body.

PATCH will return the id of the item updated.


Successful creation. POST to a collection will return a copy id for the newly created item.


Success, with an empty body. This is returned by a successful DELETE.



Failed requests will return the following HTTP codes:




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.


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.


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.


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.


Conflict. Another session was updating the resource when this request was executed.

Normally the request will succeed when resent.


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.


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"



Technical Support

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).

  • URL of Iress Open service they are using (i.e.
  • Date and time of request that failed.
  • Target Xplan site.
  • Username of the user being used.
  • RequestId as returned by Iress Open in HTTP headers. e.g. x-Iress-RequestId:"9e34d227-1e41-11e9-b831-3b763a116d23"
  • The resource requested e.g. /client/1234/asset and the request body if a POST or PATCH
  • The full error details returned including any details in the response body.



  • Iress Open does not store any client data. All client data is stored in Xplan.
  • All communication between the integrator and Iress Open and between Iress Open and Xplan uses TLS/SSL to ensure encryption of data in transit.
  • Integrators will automatically use the closest Iress Open service to them.
  • All cookies passed back to the Integrator have cookie protection and are secured with the HTTPOnly and Secure flags.
  • Authorisation is delegated to Xplan to secure and is handled by the existing user mechanism tied in with the permission granted with the associated API key sent in the request. Privilliages for the user come from the Xplan capabilities and licenses associated with the user. (See Authentication section)
  • Iress Open is subject to annual 3rd party penetration tests, as well internal vulnerability assessments as part of any major release.


Scalability & Performance

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.


Service Availability

Iress Open depends on Xplan, Xplan availability targets, maintenance windows and incident response times are agreed with Xplan site owners.


At Iress we are committed to ensuring that your experience using our community gets better. Did you find what you were looking for today?
We will use your feedback only for the purposes in which it was intended; to improve our products and services to you. At Iress, we always respect your privacy. To view our privacy notice, please visit our website