https://bpapi.britishpearl.com

Introduction

British Pearl has transformed the way people invest in UK property. We are the first platform to enable people to invest as either a shareholder or lender in properties of their choice. Our automated Resale Market provides investors with the ability to trade property shares and loans delivering valuable liquidity to an illiquid asset class. We are now rolling out our API offering to our partners gradually pushing the real estate investment boundaries even further!

This document sets out our API capabilities and instructions on integrating it into your organisation's infrastructure.

Versioning

Custom media types are used to let clients decide the format and the version of the data they wish to receive. This is done via the HTTP Accept request header. Media types are specific to resources, allowing them to change independently and support formats that other resources do not. Currently, our API only supports the JSON format. We endeavour to open up our software to more formats in the near future.

We require that all British Pearl media types adhere to the following format:

Accept: application/vnd.britishpearl[.VERSION]+json

Please note that the resource version does not need to be specified, for example:

Accept: application/vnd.britishpearl+json

In such a case British Pearl's API will always return the latest resource representation. Please note however, our API can have multiple versions. We encourage our partners to request a specific version of the resource in order to enhance the stability of their application and avoid future incompatibility issues. To use v1.0 set the following header:

Accept: application/vnd.britishpearl.v1.0+json

Signup and authorization

We use standard OAuth 2.0 Authorization Code Grant type to allow users to authorize third party applications (clients; client is used interchangeably with application throughout this documentation), whether web or native, to interact with British Pearl API on behalf of their users. The first two steps are signup related and involve contacting us with the following information:

1. Please email api-client-signup@britishpearl.com briefly describing your application, user base, stage of your project and intended usage of our API for our review.

2. Once we have reviewed and approved your application, we will ask you to deliver your redirect_uri and then we will issue your client_id and client_secret. The client_id is public and can be shared, but keep your client_secret private at all times and transmit only over a secured connection.

Your application will now have all the necessary details to access the British Pearl API data on behalf of your users. Every time a user wants to go through this process the following steps have to be taken:

1. Your client has to initiate the authorization flow by directing the user (resource owner), in web browser, to the following URL:

https://authorize.britishpearl.com

The following URL encoded query parameters identify your application and the scope of access. Please note that client_secret is not passed here so as not to expose it to the web browser:

Please note that if the user is not already authenticated, there will be additional steps involved to authenticate the user before the application authorization process can continue. Once authenticated the above URL will render a consent page for the user asking to grant permissions.

2. After the permissions have been granted by the user, the web browser will be redirected to the following URI:

[REDIRECT_URI]?code=[CODE]&state=[STATE]

The code is a string that ultimately enables your application access to the British Pearl API. This HTTP GET request to redirect_uri is simply an entry point leading back to your application, so it can read the received code and exchange it for an access token via a secure channel in the next step. The state query parameter is equal to the state query parameter that was passed in the authorization step and should be verified to prevent a CSRF attack.

3. Once your application receives the code it has to send an HTTP POST request to the following endpoint to finish off the exchange process:

https://bpapi.britishpearl.com/oauth2/access_token

The following form URL encoded parameters are used to identify your application and verify validity of the call:

Upon successful request a JSON response conforming to the AccessToken response format will be returned, for example:

{
  "tokenType": "Bearer",
  "accessToken": "8c85371bea45893b02264bfe",
  "refreshToken": "1c29d33ecde82432e4885cbe",
  "expiresIn": 3599,
  "scope": "read:user read:user-address"
}

Now the accessToken can be used to call any of the documented API endpoints and retrieve public data (like investments) or scope-restricted data specific to the requesting user.

Errors

HTTP response codes are used to indicate the result of an API request. Codes in the range of 2xx indicate success, and 4xx indicate failure. Failure can occur due to for example data validation or British Pearl being unable to fulfil the request given the input provided. Codes in the range of 5xx indicate internal server error.

Some of the above error responses will return a JSON body to help understand what might have caused the problem. In certain instances, the HTTP code by itself may not be enough. The JSON body will always conform to our ClientEror type format:

{
  "correlationId": "required error id representing this error instance",
  "errors": [
    {
      "key": "required error key",
      "message": "optional human readable error description"
    }
  ]
}