openapi: 3.0.0
info:
title: Application API
contact:
name: Capitalise
email: engineering@capitalise.com
url: https://capitalise.com
description: >-
# Introduction
This API provides a way for lenders to receive applications from clients on
the Capitalise Platform and to return offers or rejections.
The API also supports retrieval of documentation, and a set of web hooks to
receive updates for applications when the user accepts or rejects an offer.
## Application Flow
---
A typical integration would follow the following flow, typically:
1. A client matches to lenders on the Capitalise Platform
2. Client completes required fields for a lender's API
3. Capitalise API dispatches application to Webhook
4. Lender processes application and responds with an offer or rejection
5. Client accepts or rejects offer
6. Capitalise redirects user to lender onboarding to finalize
A more detailed version of this flow is displayed below:
![API Application Flow](/img/API%20Application%20Flow.png)
## Prerequisites & Requirements
---
### Required Fields
Lenders need to provide us the list of required fields (optionally with rules for requirements, e.g. only if field a > 100)
Some sample required field rules:
- Simply requiring a field to be complete
- `Sector`
- A field is required based on the value of another field
- `Contact Number` required if `Company Type = Sole Trader`
- More complex field requirements based on values and multiple conditions
- `Personal Guarantees` required if `Company Type = Sole Trader` and `Revenue < £100,000` and `Sector in (IT Services, Business Services)`
---
### API Setup
Lender needs to provide Capitalise a webhook for sending applications to. You can optionally provide a separate webhook for sending updates too, or use one for all.
> Capitalise has an iPaaS platform which allows us to connect internal
software without an API, or existing lender APIs with our API without the
need for the lender to provide a webhook, if they provide endpoints to send
an application to. This path is suitable for lenders we have an existing
high-volume relationship with. Please speak to our product team about this
integration path.
---
### Authentication
Authentication uses oAuth via our Auth0 provider. We will provide you a client secret and credentials.
To authenticate, call our oAuth provider, `https://capitalise.eu.auth0.com/oauth/token`, as per the sample below:
```json
{
"audience": "https://capitalise.eu.auth0.com/api/v2/",
"client_id": "your_client_id",
"client_secret": "your_client_secret",
"grant_type": "password",
"password": "your_password",
"scope": "openid email profile",
"username": "your_username"
}
```
Ensure you also send a header:
```json
"content-type": "application/json"
```
You will receive a payload back like the following, use the id_token as the bearer token in all authenticated requests. These tokens usually expire within 2 minutes, so we recommend authenticating before each request, rather than storing and refreshing the token.
```json
{
"access_token": "....",
"id_token": "....",
"scope": "openid email profile ....",
"expires_in": 120,
"token_type": "Bearer"
}
```
----
### API
Use your Bearer token to access the API at the below URL:
`https://capitalise.com/api/platform/v1/funding`
---
## Go-live sign-off
In order to obtain production keys and configuration, you will need to demonstrate several standard scenarios:
Minimum application
Ensure that your API is able to deal with only the minimum mandatory fields
being entered. Any additional mandatory fields required should be discussed,
as lender specific requirements on existing fields can be custom configured.
Outright rejection
If for any reason you will fully reject an application, e.g. due to poor
credit or similar scenarios, you must demonstrate the response you give to
the user is clear.
Failed validation
For validation issues where the user may correct the input, you should
demonstrate the error message is clear and actionable to the user. Examples
of post validation here could include address verification, director lookup
verification etc
Manual Review
If you will direct applications for manual review, you should show that
acknowledgement made along with a clear message indicating a timeline for
update.
Indicative/Underwritten Offer
You should demonstrate that a full and complete offer is returned to the end
user if implementing offer responses.
---
# Schema
## Funding Application
It contains:
- apiProvider: *Lender can use this to verify the request is genuine*
- application: *The packaged Capitalise Application*
- fundingSearch: *Key details about the users search requirements*
- fundingMatch: *Key details about the lenders product the client has matched with*
- profile: *The clients application form*
- accountantDetails: *The clients accountant, if any.*
- assetsToFinance: *(Optional) Assets the client is looking to obtain finance for*
- basicCompanyDetails: *Details about the company and the primary contact for the client*
- companyCredit: (Optional) *Unverified details of the companies credit standing*
- directorOrSecretaryDetails: *Detail and credit information about each director, owner or secretary involved in the application*
- eposTerminalInfo: *(Optional) Details of the clients primary EPOS and monthly takings*
- guarantorAssetsForSecurity: *(Optional) Any assets the applicants are providing as security*
- invoiceFinancing: *(Optional) Summary details of the clients outstanding invoice debtors and value*
- tradeFinanceProfile: *(Optional) Summary details of the clients outstanding trade debtors and value*
- tradeHistory: *Annualised revenue, asset and profit figures of the companies history*
- attachments: *A list of documents attached to this application*
```json
{
"apiProvider": {
"url": "https://webhook-url/",
"updateUrl": "https://webhook-url/",
"authorizationToken": "1234a"
},
"application": {
"id": 10000,
"reference": "Q43RT7",
"status": "In Review",
"responseReason": null,
"comment": null,
"fundingSearch": {
"id": 10001,
"status": 2,
"amount": "15000.00",
"period": 12,
"statusLabel": "Reviewing",
"author": {
"id": 10002,
"entity": {
"id": 10003,
"entityId": 10004,
"companyName": "Acme Introducer"
},
"userType": "business",
"name": "John Smith",
"email": "johnsmith@email.com"
},
"manager": {
"id": 10005,
"entity": {
"id": 10006,
"entityId": 10007,
"companyName": "Acme Introducer"
},
"userType": "business",
"name": "John Smith",
"email": "johnsmith@email.com"
},
"useOfFunds": "Business expansion",
"urgency": "ASAP"
},
"fundingMatch": {
"id": 10008,
"offerId": null,
"products": [
1
],
"productNames": [
"Term Loans"
],
"statusReason": null,
"statusComment": null,
"canUseInstantOffer": true,
"canUseInstantApplication": true,
"lender": {
"id": 10009,
"entityId": 10010,
"companyName": "Lender Name",
"logo": "https://logo-url",
"icon": "https://icon-url"
},
"status": 1
},
"profile": {
"accountantDetails": { # only provide for searches though introducers
"name": "Acme Accountants",
"address": "12 Road Name",
"town": "London",
"contactName": "John Surname",
"telephone": "01234567890",
"email": "john@acmeacc.com"
},
"assetsToFinance": [
{
"assetCost": null,
"assetSerialNumber": null,
"depositAvailable": null,
"assetType": null,
"assetTypeName": null
}
],
"basicCompanyDetails": {
"contactName": "John Companyman",
"contactEmail": "john@company.com",
"contactPhone": "01234567890",
"companyName": "Companman Company",
"companyTradingName": "CC Company LTD",
"companyNumber": "12345678A",
"companyType": "Limited Company",
"vatRegistered": 1,
"address": "100 Road Name, Town Name",
"city": "London",
"postalCode": "LO4 0ON",
"tradingFrom": 1568718000,
"tradingPeriod": "3",
"creditScore": "3",
"numberOfEmployees": 2,
"percentageOfSalesOnline": 10,
"companyWebsite": "https://beta.companieshouse.gov.uk/company/123456789A",
"sectorName": "Construction"
},
"companyCredit": {
"unpaidItems": 0,
"behindOnTaxPayments": 0,
"officialsDeclaredBankrupt": true,
"officialsFailedBusiness": 0,
"exceededAgreedOverdraft": 0,
"overdraftWorstMonth": 8,
"daysOverdrawn": 13,
"debtRepayments": 86000,
"expectedTurnover": 1200000, # only for companies trading sub 12 months
"expectedNetProfit": 350000 # only for companies trading sub 12 months
},
"directorOrSecretaryDetails": [
{
"title": "Mr",
"fullName": "John Companyman",
"email": "jc@email.com",
"phone": "01234567890",
"dateOfBirth": -51926400,
"position": "Director",
"addressResidential": "125 Street, London, LO4 0ON",
"ownershipPercentage": 100,
"residentialStatus": "homeowner",
"personalGuarantee": true,
"monthlyRentOrMortgage": 245,
"mortgageValue": 39000,
"monthlyBusinessIncome": 6500,
"monthlyNonBusinessIncome": null,
"monthlyOtherHouseholdIncome": null,
"personalCreditLimit": 75000,
"ccjsValue": null,
"personalDefaultsValue": null,
"dependants": 3,
"oldestCreditAccountAge": null,
"missedPaymentsBusiness": null,
"missedPaymentsPersonal": null,
"personalDefaults": null
}
],
"eposTerminalInfo": {
"transactionsPerMonthAvg": 2500,
"monthsUsingCCProcessing": 28,
"monthsRemainingOnBusinessLease": 4,
"terminalId": null,
"terminalProvider": null
},
"guarantorAssetsForSecurity": {
"hasUkHomeownerDirector": true,
"estimatedSecurity": 40000,
"guarantorAssets": [
{
"owner": "John Companyman",
"estimatedValue": 79000,
"totalDebt": 39000,
"address": "125 Street, London, LO4 0ON"
}
]
},
"invoiceFinancing": {
"debtorsValue": null,
"debtorDays": null,
"invoicesNumber": null,
"creditNotesGrossValue": null,
"creditNotesNumber": null,
"customersNumber": null
},
"tradeFinanceProfile": {
"currentValueOfDebtors": 11000,
"approxNoOfCustomers": 2,
"currentValueOfConfirmedOrders": 22750,
"approxGrossMargin": 35,
"madeADozenWebsiteSales": false
},
"tradeHistory": [
{
"year": "2020",
"yearEndTimestamp": 1598832000,
"revenue": "45000",
"profitNet": "4500",
"debtorsOutstanding": null,
"debtorsInvoicesDue": null,
"fixedAssets": null
}
],
"attachments": []
},
"acceptedAt": null,
"invalidatedAt": null
}
}
```
## Offer
An offer is our accepted format to receive a lenders format in. Not all fields are required.
---
### Term Loan
**Request**
```json
{
"reference": "lender_quote_ref", #required #unqiue [string]
"expiryDate": "2012-11-04T14:51:06.157Z", #nullable [iso2701 date+optional time]
"status": "FINAL", #required [INDICATIVE or FINAL]
"comment": "Other terms include x, y z", #nullable string
"termLoan": {
"maximumAmount": 1000, #required [currency amount]
"minimumAmount": 500, #nullable [currency amount]
"term": 18, #required [1 - 240]
"interestRate": 3.29, #required [0.00 - 100.00] monthly rate
"representativeAPR": 4.00, #nullable [0.00 - 100.00] annual rate
"monthlyRepayment": 834.73, #nullable [currency amount]
"totalRepayment": 123456.72, #nullable [currency amount]
"arrangementFee": 100, #nullable [currency amount]
"promotion": "first month free", #nullable [string]
"likelihoodOfRate": 0.90, #nullable [0.00 - 1.00]
"likelihoodOfAcceptance": 0.94, #nullable [0.00 - 1.00]
}
}
```
**Response**
`termLoan.totalFees` is returned when fetching an offer, calculated as
`abs(termLoan.totalRepayment - termLoan.maximumAmount)`
### Invoice Finance
```json
{
"reference": "lender_quote_ref", #required #unqiue [string]
"expiryDate": "2012-11-04T14:51:06.157Z", #nullable [iso2701 date+optional time]
"status": "FINAL", #required [INDICATIVE or FINAL]
"comment": "Other terms include x, y z", #nullable string
"invoiceFinance": {
"maximumCreditLine": 500000, #required, currency
"minimumCreditLine": 50000, #currency
"serviceFee": 0.025, #required, decimal % [0.00 - 1.00]
"discountFee": 0.025, #required, decimal % [0.00 - 1.00]
"advanceRate": 0.80, #required, decimal % [0.00 - 1.00]
"additionalFees": "£1500 setup", #string
"minimumMonthlyFee": 1500 #currency
"concentrationLimit": 0.23 #decimal % [0.00 - 1.00]
"contractLength": 6, #required 0 = rolling contract
"creditInsurance": 0.55, #decimal % [0.00 - 1.00]
"creditInsuranceRequired": true #bool
"facility" : "DISCOUNTING", #required, [DISCOUNTING or FACTORING]
"selective" : true, #bool
"confidential" : true, #bool
"promotion": "first month free", #string
"likelihoodOfRate": 0.90, #decimal % [0.00 - 1.00]
"likelihoodOfAcceptance": 0.94, #decimal [0.00 - 1.00]
}
}
```
### Merchant Cash Advance
```json
{
"reference": "lender_quote_ref", #required #unqiue [string]
"expiryDate": "2012-11-04T14:51:06.157Z", #nullable [iso2701 date+optional time]
"status": "FINAL", #required [INDICATIVE or FINAL]
"comment": "Other terms include x, y z", #nullable string
"merchantCashAdvance": {
"fundingAmount": 500000, #required, currency
"sweep": 0.80, #required, decimal % [0.00 - 1.00]
"totalRepayment": 58000 #currency
"totalFees": 58000 #currency
"ratio": 1.3 #decimal % [1.00 - 100.00]
"promotion": "first month free", #string
"likelihoodOfRate": 0.90, #decimal % [0.00 - 1.00]
"likelihoodOfAcceptance": 0.94, #decimal [0.00 - 1.00]
}
}
```
### Asset Finance
```json
{
"reference": "lender_quote_ref", #required #unqiue [string]
"expiryDate": "2012-11-04T14:51:06.157Z", #nullable [iso2701 date+optional time]
"status": "FINAL", #required [INDICATIVE or FINAL]
"comment": "Other terms include x, y z", #nullable string
"assetFinance": {
"advanceAmount": 500000, #required, currency
"term": 12, #required, number
"deposit": 58000 #required, currency
"cost": 500 #currency
"vat": 15000 #currency
"totalPrice": 15000 #currency
"representativeAPR": 0.90, #decimal % [0.00 - 1.00]
"productOption": "Hire Purchase" #list [Hire Purchase, Finance Lease]
"monthlyRepayment": 500 #currency
"additionalFees": "£1500 setup", #string
"optionToPurchaseFee": 125 #currency
"description": "Custom text" #string
"promotion": "first month free", #string
"likelihoodOfRate": 0.90, #decimal % [0.00 - 1.00]
"likelihoodOfAcceptance": 0.94, #decimal [0.00 - 1.00]
}
}
```
### Trade Finance
```json
{
"reference": "lender_quote_ref", #required #unqiue [string]
"expiryDate": "2012-11-04T14:51:06.157Z", #nullable [iso2701 date+optional time]
"status": "FINAL", #required [INDICATIVE or FINAL]
"comment": "Other terms include x, y z", #nullable string
"tradeFinance": {
"maximumCreditLine": 500000, #required, currency
"minimumCreditLine": 50000, #currency
"serviceFee": 0.025, #required, decimal % [0.00 - 1.00]
"discountFee": 0.025, #required, decimal % [0.00 - 1.00]
"advanceRate": 0.80, #required, decimal % [0.00 - 1.00]
"additionalFees": "£1500 setup", #string
"minimumMonthlyFee": 1500 #currency
"contractLength": 6, #0 = rolling contract
"promotion": "first month free", #string
"likelihoodOfRate": 0.90, #decimal % [0.00 - 1.00]
"likelihoodOfAcceptance": 0.94, #decimal [0.00 - 1.00]
}
}
```
### Commercial Property
```json
{
"reference": "868/3301", #required #unqiue [can default to search ID / match ID for manual]
"expiryDate": ..., #nullable [date+time]
"status": "Final", #required [INDICATIVE or FINAL]
"comment": "Other terms include x, y z", #nullable string
{
"amount": 1000, #required [currency amount]
"ltv": 34.3, #nullable [percentage 0.00 - 100.00]
"mortgageTerm": 18, #required [1 - 240]
"dealTerm": 18, #required [1 - 240]
"interestRate": 3.29, #required [percentage 0.00 - 100.00]
"arrangementFee": 955, #nullable [currency amount]
"valuationFee": 599, #nullable [currency amount]
"exitFee": 599, #nullable [currency amount]
"productOption": "BTL" #list [BTL, Interest Only, Repayment]
"rateType": "Fixed" #list [Variable, Fixed]
"propertyChargeAddress": "12 Street Name" #string
}
}
```
---
# Webhooks
## New Application Webhook
When a user submits an application, a payload with a [Funding
Application](#funding-application) is sent to the lender's provided webhook
URL.
You must return an HTTP 204 to this dispatcher, otherwise the dispatcher
will attempt to resend the application at exponential intervals.
## Application Updated Webhook
When a user marks an offer as accepted or rejected, an updated payload with
a Funding Application is sent to the lender's provided webhook URL. You
should filter updates sent to this webhook and only use what you need (e.g.,
Status is Client Accepted or Client Declined) to avoid confusion.
> We recommend using separate endpoints for New Applications and Application
Updated. Our Updated endpoint will provide updates for all status changes.
You must return an HTTP 204 to this dispatcher, otherwise the dispatcher
will attempt to resend the application at exponential intervals.
---
servers:
- url: https://demo.capitalise.com/api/marketplace/v2
description: Demo
- url: https://capitalise.com/api/marketplace/v2
description: Production
paths:
/applications:
get:
summary: List Applications
description: >
Fetches an array of [Funding Applications](#funding-application).
You can pass an optional `?reference` as a filter to find only
applications matching your provided reference.
tags:
- Endpoints
/applications/{id}:
get:
summary: Fetch Application
description: >-
Fetch a specific [Funding Application](#funding-application) by
application.id.
tags:
- Endpoints
/v1/funding/search/{id}/document/{document_id}:
get:
summary: Fetch Document
description: >
Fetch a document from a specific [Funding
Application](#funding-application) by application.id and
application.profile.attachment.id.
tags:
- Endpoints
/applications/{id}/acknowledgement:
post:
summary: Acknowledge Application
description: >
On receipt of a [New Application Webhook](#new-application-webhook),
this endpoint allows you to provide an optional reference number to be
used in later lookups.
In addition, this endpoint can receive comments until such time as a
quote or rejection is provided.
**Create a reference for a Funding Application after receipt**
```json
{
"reference": "lenders_unique_reference"
}
```
**Create a reference for a Funding Application after receipt, with
comment**
```json
{
"reference": "lenders_unique_reference",
"comment": "This application requires a manual credit review."
}
```
**Provide an update comment only**
```json
{
"comment": "This application requires a manual credit review."
}
```
tags:
- Endpoints
/applications/{id}/offer:
post:
summary: Provide Quote/Offer
description: "Once a [Funding Application](#funding-application) is received, this endpoint allows a quote or offer to be provided in response.\n\nIn addition, this endpoint can receive updated offers at any time, which will replace the previous offer supplied.\n\n**Send an Initial Quote**\n```json\n{\n \"reference\": \"lender_quote_ref\",\n \"expiryDate\": \"2012-11-04T14:51:06.157Z\",\n \"status\": \"INDICATIVE\",\n \"comment\": \"Other terms include x, y z\", #nullable string\n \"termLoan\": {\n \t\t\"maximumAmount\": 15000,\n \"term\": 12,\n \"interestRate\": 12.29,\n \"representativeAPR\": 13.99,\n \"monthlyRepayment\": 834.73,\n \"totalRepayment\": 17456.72,\n \"arrangementFee\": 100,\n \"likelihoodOfRate\": 0.90,\n \"likelihoodOfAcceptance\": 0.94\n }\n}\n```\n\n**Send an Underwritten Offer**\n```json\n{\n \"reference\": \"lender_quote_ref\",\n \"expiryDate\": \"2012-11-04T14:51:06.157Z\",\n \"status\": \"INDICATIVE\",\n \"comment\": \"Other terms include x, y z\", #nullable string\n \"termLoan\": {\n \t\t\"maximumAmount\": 15000,\n \"term\": 12,\n \"interestRate\": 12.29,\n \"representativeAPR\": 13.99,\n \t\t\"monthlyRepayment\": 834.73,\n \t\t\"totalRepayment\": 17456.72,\n \t\t\"arrangementFee\": 100\n }\n}\n```\n"
tags:
- Endpoints
requestBody:
content:
application/json:
schema:
type: object
properties:
reference:
type: string
description: lender_quote_ref
expiryDate:
type: string
format: date-time
description: '2012-11-04T14:51:06.157Z'
status:
type: string
description: INDICATIVE
comment:
type: string
description: Other terms include x, y z
termLoan:
type: object
properties:
maximumAmount:
type: number
description: 15000
term:
type: integer
description: 12
interestRate:
type: number
description: 12.29
representativeAPR:
type: number
description: 13.99
monthlyRepayment:
type: number
description: 834.73
totalRepayment:
type: number
description: 12.29
arrangementFee:
type: number
description: 100
likelihoodOfRate:
type: number
description: 0.9
likelihoodOfAcceptance:
type: number
description: 0.94
/applications/{id}/rejection:
post:
summary: Fail or Reject Application
description: >
Once a [Funding Application](#funding-application) is received this
endpoint allows a failure or rejection to be provided in response.
Failing an application allows the client to resubmit and should be used
to report formatting, processing or data errors.
Rejecting an application is terminal. A client cannot resubmit.
The comment and reference are optional, but a reason must be provided.
**Fail an application**
```json
{
"reason": "Failed",
"comment": "Unable to verify directors address. Please check and resubmit.",
"reference": "y76fga78s"
}
```
**Reject an application**
```json
{
"reason": "Ineligible",
"comment": "A directors credit checks did not pass our requirements",
"reference": "y76fga78s"
}
```
tags:
- Endpoints
requestBody:
content:
application/json:
schema:
type: object
properties:
reason:
type: string
description: Failed
comment:
type: string
description: >-
Unable to verify directors address. Please check and
resubmit.
reference:
type: string
description: y76fga78s
components: {}