Clearmatch integration - API

Clearmatch integration - API

1.  Introduction

The purpose of this document is to provide a high-level explanation on how the Clearmatch Public API is used by a partner.

Clearmatch provides a REST based API to retrieve information from the platform. Some highlights include:
  1. The consumer of an API is a system in a partner's environment and not a real person. This API consumer should reside on a partner's server infrastructure and the API is not intended to be used directly from a browser.
  2. Full cross platform support, as we use standard HTTP protocol.
  3. REST over HTTP and security is easy to manage like any other website.
  4. Data provided in API is near real-time for all transactional resources e.g. Application. Some aggregate resources e.g. InvestmentSummary provide data from the Datawarehouse.
  5. Full support for OpenAPI spec including field level documentation. Swagger UI is provided in non-production environments.
  6. Secured with Oauth2 bearer token issued by Single SignOn service.
  7. The ability to add new data elements within a minor release that is fully backwards compatible within the same major release. Partners should set MissingMemberHandling to Ignore an API consumer.
  8. Non backward compatible changes are released with a new major version number.

2. Client generation using Swagger spec

The Clearmatch API generates live documentation using OpenAPI-Specification (formerly swagger spec) Version 2.0. Below is screenshot of how the spec looks in Swagger-UI:





The current version of this documentation can be retrieved using curl 
curl -k https://demo-api.clearmatch.co/swagger/docs/v1


3. Client generation using Swagger spec

If you would like to generate a client to consume the Clearmatch API, please navigate to the following URL http://editor.swagger.io and import the swagger document from the previous step. Once the document is imported you can generate a bootstrap application in the language of your choice.


Figure 1 - Generate Rest Client

4. Authentication

The Clearmatch Identity service needs to be used in order to generate Oauth2 token’s that are used for secure authentication. Currently we support Resource Owner flow and Authorisation Code flow.

Sample token request 
curl -X POST -H "Cache-Control: no-cache" -H "Content-Type: application/x-www-form-urlencoded" -d
'client_id=XXXClientId&client_secret=password&grant_type=password&username=XXXServiceAccount&password=password&scope=api'

Sample token response

{
  "access_token": "c85cd5dd7eb0204a83c44253e71e1bf6",
  "expires_in": 3600,
  "token_type": "Bearer"
}


5. Resources Overview

API is split into multiple resources, each exposing specific functionality in Clearmatch. Unless specifically mentioned, all data is returned in near real-time.

5.1  Application Resource

This resource is used to manage Application and Listing functionality. In the v1 of API you can search for an application, retrieve application details, cancel an application, place bids and update some details.

5.2  Investment Resource

Provides functionality to summarise investments you have access to with various criteria. These reports are generated from the Datawarehouse which is refreshed every morning.

5.3  Investor Resource

Provides functionality to search for investors and retrieve their investment mandates

5.4  ReferenceData (reference codes) Resource

Provides access to retrieve various reference codes setup in Clearmatch.

5.5  Sample API Requests

  • Search for an application

curl -X GET --header 'Accept: application/json' 'https://demo-api.clearmatch.co/v1/unsecuredLoans/application?applicationNumber=A1000'


  • Retrieve an application

curl -X GET --header 'Accept: text/plain' --header 'Authorization: Bearer 1f0f04867e751caf1e29f9d9d3346eaf' 'https://demo-api.clearmatch.co/v1/unsecuredLoans/application/A039626'


  • Update an application 
curl -X PATCH --header 'Content-Type: application/json' --header 'Accept: application/json' --header 'Authorization: Bearer 1f0f04867e751caf1e29f9d9d3346eaf' -d ' [
  { "op":"replace", "path":"/amountFinanced","value":7000 },
  { "op":"replace", "path":"/interestRate","value":33.86 },
  { "op":"replace", "path":"/term","value":12 },
  { "op":"replace", "path":"/paymentFrequency","value":"Monthly" },
  { "op":"replace", "path":"/remoteApplications", "value":[{ "remoteApplicationId":"LATITUDEAPP03"}]}
]' 'https://demo-api.clearmatch.co/v1/unsecuredLoans/application/A039626/updateTransferredApplication'

  • Change the status 
curl -X PUT --header 'Content-Type: application/json' --header 'Accept: application/json' --header 'Authorization: Bearer 1f0f04867e751caf1e29f9d9d3346eaf' -d '{status: Assess}' 'https://demo-api.clearmatch.co/v1/unsecuredLoans/application/A039626'

  • Cancel an application 
curl -X DELETE --header 'Authorization: Bearer 1f0f04867e751caf1e29f9d9d3346eaf' 'https://demo-api.clearmatch.co/v1/unsecuredLoans/application/A039626'

    • Related Articles

    • Clearmatch integration - overview

      1.  Introduction The Clearmatch platform consists of the following external facing application components: 1. Single Sign On – The single sign on service is a central service where registered users are authenticated. Additionally, the service can ...

    • Clearmatch integration - partner process

      1. Introduction The purpose of this document, is to provide a high-level walk-through of different components involved in a Finance Company's integration with Clearmatch API focusing on the following: Partner Process Manager Notification Processor ...

    • Clearmatch integration - notification

      1.  Introduction The purpose of this document is to provide a high-level explanation on how Clearmatch Notifications are used by a partner.           A Clearmatch platform can be setup to send notifications when a certain “event” happens. For ...

    • Office 365 - API setup

      1. Login to https://apps.dev.microsoft.com use admin account create app, note down Application Id, Application Secrets, Redirect URL. 2. Choose Native platform, Setup Microsoft Graph Permissions as below: Read mail in all mailboxes Read and write ...

    • Clearmatch statuses

      The list of status's used in Clearmatch for applications, finance agreements, bids, investments and call accounts can be found here