Funding Circle Partner API (v1)

Download OpenAPI specification:Download

Overview

This page contains documentation on how to use the Funding Circle Partner API.

We believe that small businesses deserve access to finance that’s quick and hassle-free.

That’s why we have launched a Funding Circle lending API. Our API makes it fast, simple and straightforward for partners to offer Funding Circle loans from within their own website, platform or mobile app.

We also offer other ways to partner with us including referrals and co-branded landing pages. To learn more about partnership opportunities or to gain access to our Sandbox, email us at fcpartner@fundingcircle.com or register your interest using this link.

Authentication

The API is under OAuth 2.0 Client Credentials Grant flow. In order to make a request, your client must be authorised.

access_token

A first step is to generate an access_token, the way to do this is to make a POST request to the Authentication endpoint, passing a base 64 token generated from your unique client_id:client_secret:

curl --request POST \
--url "https://auth.sandbox.api.fundingcircle.co.uk/oauth2/token" \
--header "Authorization: Basic 'base64(client_id:client_secret)'" \
--data-urlencode "grant_type=client_credentials"

The access_token can only be used for 24 hours and must be set in the HTTP header of each request:

Authorization: Bearer eyJraWQiOiJkd1ZKOFFhaGNcL2V4bFBwRUN3TDVNaTA3YmRqOFhNK3MzY.....

Note that you must not include the access_token when making the PUT request to upload a document.

Errors

An x-amzn-trace-id header will be returned with each request. We can use this ID to debug problems with a particular API request. Ideally, you should store the x-amzn-trace-id so we can look into a specific request, if required.

We follow the error response format proposed in RFC 7807 also known as Problem Details for HTTP APIs. As with our normal API responses, your client must be prepared to gracefully handle additional members of the response.

BAD_REQUEST_BODY

  • HTTP status: 400

This response means that the API cannot process your request due to something that is perceived to be a client error (e.g., malformed request query, invalid request body, or deceptive request routing). To resolve this, please ensure that the request syntax is correct and includes all mandatory fields.

BAD_REQUEST_PARAMETERS

  • HTTP status: 400

This response means that the API cannot process your request due to a wrongly typed or malformed path parameter. To resolve this, please ensure that the parameter value matches the expected pattern.

UNAUTHORIZED

  • HTTP status: 401

This response means that your client is not authorised to access the API, make sure you've called the Auth endpoint first to fetch the access_token. Note that each token expires in 24 hours.

ACCESS_DENIED

  • HTTP status: 403

This response means that your access_token might be valid, but you're temporarily not allowed to access the API.

FORBIDDEN

  • HTTP status: 403

This response means that the API understands the request, but refuses to authorise it. To resolve this, please ensure you have permission to access the resource.

RESOURCE_NOT_FOUND

  • HTTP status: 404

This response means that the API has processed your request, but the resource could not be found.

GONE

  • HTTP status: 410

This response means that the API has processed your request, but the resource has now permanently expired.

UNSUPPORTED_MEDIA_TYPE

  • HTTP status: 415

This response means that the API refuses to accept the request because of the payload format. To resolve this, please select content-type application/json.

UNPROCESSABLE_ENTITY

  • HTTP status: 422

This response means that the API has processed the request, but the client is not allowed to proceed. Some of the highlighted reasons are:

  • The email provided is already in use by another Funding Circle non-borrower account.
  • We are unable to identify the business provided in our database or the business is dormant or inactive.
  • The application cannot be processed because this company either has an ongoing application with Funding Circle, or they have recently been rejected.
  • The total percentage of the shares held submitted is less than 50%.
  • None of the EBOs submitted holds a minimum of 20% of shares.

FAILED_DEPENDENCY

  • HTTP status: 424

This response means that the requested action couldn't be performed because it depends on another action that has failed.

Sandbox

Approved partners will be provided access to our sandbox, which contains scenarios that can be used for testing.

Eligibility

The companies_house_id included in the request will result in the below eligibilities:

  • 00000000 - an eligibility with a low score
  • 00000001 - an eligibility with a medium score
  • 00000002 - an eligibility with a high score

Requests including a different value, will return a not-eligible score, which means the company is not currently eligible for any of the Funding Circle products.

Loan application

The business_name used in the loan application will result in different journeys, as described below:

  • Bighead Catshark Ltd - a successful application with a credit offer
  • Blotchy Swellshark Ltd - an application that requires action
  • Loop Shark Ltd - an application that remains in "processing"
  • Broadmouth Shark Ltd - a rejected application
  • Inflight Shark Ltd - an application that triggers an error due to another ongoing application from the same company

Requests with no business name or with a different value to any of the above, will also lead to an application that remains in "processing".

As a current limitation, uploading and submitting documents will change the status of the loan application to "in progress" indefinitely.

Eligibility

The eligibility endpoints can be used to get a view of a company's eligibility for our Term Loan product.

Eligibility does not provide a full credit decision, but instead presents an indicative representation of a company's likeliness of receiving a credit offer, based on a small number of data inputs.

Two endpoints are available which allow for a variety of use cases. The suggested use cases for each endpoint are explained below. The eligibility endpoints will return a score of “H”, “M”, “L” or “N” for each.

Score Eligibility
H High
M Medium
L Low
N Not scored

Check eligibility for single company

The single eligibility endpoint should be used to receive eligibility for a single company. This allows introducers to use eligibility data in real time, to help optimise their customer journey.

Authorizations:
access_token
path Parameters
companies_house_id
required
string^[0-9]{8}$|^[A-Z]{2}[0-9]{6}$
Example: SC645837

Company ID as per the Companies House registration.

Responses

Response samples

Content type
application/hal+json
{
  • "companies_house_id": "SC645837",
  • "eligibility": [
    ],
  • "_links": {
    }
}

Check eligibility for multiple companies

The bulk eligibility endpoint should be used to receive eligibility for multiple companies in bulk. This allows introducers to optimise marketing campaigns and target customer segments, based on eligibility outcomes. The endpoint can handle up to 400k companies in one single bulk to process.

Authorizations:
access_token
Request Body schema: text/csv
string <binary>

Csv file containing the eligibility batch. Every row should only contain a Companies House ID.

Responses

Request samples

Content type
text/csv
companies_house_id
00000000
00000001

Response samples

Content type
text/csv
companies_house_id,term_loan_score
00000000,L
00000001,M

Loan Application

Submit a full application for a term loan. The initial POST initiates the application process and returns a link to a resource that provides information on this process. When processing is complete this resource will contain a link to a resource showing the credit decision, or a resourcing indicating what further information is needed; the API provides endpoints to upload documents when required for a credit decision.

The overall flow is shown below:

Main application flow


Some of our endpoints follow the Microsoft Asynchronous Request-Reply Pattern, meaning that the actual processing will happen in the background even though the call returns immediately. The response will contain a placeholder rather than the actual result. To know when the result is ready, you should fetch by the related uuid.

Most of the loan applications will receive an instant decision, but for some applications we will require additional information. For this reason, some of the enpoints are not required to be called for every application and have the optional tag tag applied.

Create a term loan application

Submit a term loan application for processing. Credit reports will be pulled for the company and any supplied EBOs (Executive Business Owner). The duration of processing will vary depending on the loan details, availability of 3rd party data providers and internal Funding Circle business rules. Successful calls to this endpoint contain a link to a status resource containing any available information on the expected duration.

Authorizations:
access_token
Request Body schema: application/json
callback_url
string^https:\/\/[\w\.-]{2,}\.[\D]{2,}\b([-\w_.?&\/...

(BETA) If included in the request, when an action is required or a decision is made, we will call your webhook using the payload described in the callbacks section.

partner_reference
string [ 1 .. 36 ] characters

A free value supplied by the partner for their own reference, e.g. an internal identifier for the customer or loan.

required
object

A reference uniquely identifying a business. This must contain the Companies House ID.

required
Array of objects non-empty unique

List of Executive Business Owners (EBOs). These are shareholders that play a day-to-day role in the business and add up to 50% or more ownership of the applicant company, with at least one EBO holding 20% or more shares. Names need to match what is listed on companies house.

required
object

Information about the applicant. This must be a director of the business.

required
object

Please provide the following inputs for the company requesting finance.

required
object

Information about the loan.

required
object

Purpose of the loan.

required
object

Client consent.

broker_commission
number (Amount between 0-6.5%, must be an incremental input of 0.5%)
Enum: 0 0.5 1 1.5 2 2.5 3 3.5 4 4.5 5 5.5 6 6.5

Commission rate must be included for all broker requests. If you are set up as a partner then your commission will be pre-determined from our partner agreement. Therefore partners do not need to share a commission amount as these will be ignored if sent. Fee may change depending on whether the loan offer falls under our core lending product or the Recovery Loan Scheme. Please reach out to your Partnership Manager if you have any questions.

Responses

Callbacks

Request samples

Content type
application/json
{
  • "partner_reference": "HG79872",
  • "business_reference": {
    },
  • "ebo_list": [
    ],
  • "customer_info": {
    },
  • "business_info": {
    },
  • "loan_info": {
    },
  • "loan_purpose": {
    },
  • "client_consent": {
    },
  • "broker_commission": 0.5
}

Response samples

Content type
application/problem+json
{
  • "type": "BAD_REQUEST_BODY",
  • "title": "Invalid request body",
  • "detail": "[Object has missing required properties (['some_property'])]"
}

Callback payload samples

Callback
POST: Loan application status update
Content type
application/json
{
  • "callback_uuid": "a5764857-ae35-34dc-8f25-a9c9e73aa898",
  • "created_at": "2017-07-21T17:32:28Z",
  • "submitted_at": "2017-07-21T17:32:28Z",
  • "status_uri": "/v1/loan_application_status/a5764857-ae35-34dc-8f25-a9c9e73aa898"
}

Create a flexipay application

Submit a FlexiPay application for processing. Credit reports will be pulled for the company and any supplied EBOs (Executive Business Owner). The duration of processing will vary depending on the loan details, availability of 3rd party data providers and internal Funding Circle business rules. Successful calls to this endpoint contain a link to a status resource containing any available information on the expected duration.

Authorizations:
access_token
Request Body schema: application/json
required
object

A reference uniquely identifying a business. This must contain the Companies House ID.

required
Array of objects non-empty unique

List of Executive Business Owners (EBOs). These are shareholders that play a day-to-day role in the business and add up to 50% or more ownership of the applicant company, with at least one EBO holding 20% or more shares. Names need to match what is listed on companies house.

required
object

Information about the applicant. This must be a director of the business.

required
object

Please provide the following inputs for the company requesting finance.

Responses

Request samples

Content type
application/json
{
  • "business_reference": {
    },
  • "ebo_list": [
    ],
  • "customer_info": {
    },
  • "business_info": {
    }
}

Response samples

Content type
application/problem+json
{
  • "type": "BAD_REQUEST_BODY",
  • "title": "Invalid request body",
  • "detail": "[Object has missing required properties (['some_property'])]"
}

Check the status of a loan application

Retrieves a resource that describes the current status of a submitted loan application. This endpoint is intended to be polled and clients should adjust their polling frequency as follows:

  • After sending a loan application:
Interval Polling frequency
0 to 2 minutes Every second
2 to 10 minutes Every minute
10 minutes to 6 hours Every hour
6 hours and over Every 12 hours
  • After submitting a required action:
Interval Polling frequency
0 to 2 minutes Every second
2 minutes and over Every 12 hours
Authorizations:
access_token
path Parameters
loan_application_uuid
required
string <uuid> ^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]...
Example: 22e0ee76-e496-4488-b813-2de2c90c5e0f

Unique identifier for the loan application.

Responses

Response samples

Content type
application/hal+json
{
  • "loan_application_uuid": "a5764857-ae35-34dc-8f25-a9c9e73aa898",
  • "reason": "processing",
  • "created_at": "2017-07-21T17:32:28Z",
  • "updated_at": "2017-07-21T17:32:28Z",
  • "_links": {
    }
}

Retrieve a loan application

Beta

Retrieve the current state of a processed loan application. The loan application can be one of three states:

  • in_progress Funding Circle are actively processing the application.
  • action_required the application requires an action to be taken before a decision can be made. See more details on how to upload documents here.
  • decision_made a credit decision has been reached. A link to the decision is provided.
Authorizations:
access_token
path Parameters
loan_application_uuid
required
string <uuid> ^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]...
Example: 22e0ee76-e496-4488-b813-2de2c90c5e0f

Unique identifier for the loan application.

Responses

Response samples

Content type
application/hal+json
Example
{
  • "status": "in_progress",
  • "loan_application_uuid": "22e0ee76-e496-4488-b813-2de2c90c5e0f",
  • "loan_application_details": {
    },
  • "_links": {
    }
}

Retrieve the decision for a loan application

Retrieve the decision for a processed loan application. The decision is either:

  • offered the application was successful and the offer details are contained within the payload.
  • rejected the application was not successful, and a high level reason for the rejection is contained within the payload.
  • action_required the application requires an action to be taken before a decision can be made. See more details on how to upload documents here.
Authorizations:
access_token
path Parameters
loan_application_uuid
required
string <uuid> ^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]...
Example: 22e0ee76-e496-4488-b813-2de2c90c5e0f

Unique identifier for the loan application.

Responses

Response samples

Content type
application/hal+json
Example
{
  • "created_at": "2019-08-24T14:15:22Z",
  • "status": "action_required",
  • "actions": [
    ],
  • "amend_bank_statements_reasons": [
    ],
  • "_links": {
    }
}

Get a document upload url for a loan application

Beta

Get a document upload url when an action is required.

A pre-signed url can be used to upload a document. Documents can only be uploaded when an application has one of the following required actions:

  • upload_bank_statements: upload bank statements of the last 6 months
  • amend_bank_statements: allow to reupload bank statements if previous upload had wrong or insufficient data
  • upload_filed_accounts: upload most recent set of financial statements

The upload has to be a PUT request with the header x-amz-server-side-encryption:aws:kms. For this request do not include the access_token:

curl ${document_upload_url} -X PUT -T ./document.pdf -H "x-amz-server-side-encryption:aws:kms"

Each pre-signed url has a lifespan of 30 seconds and can be used to upload a single document.

A document must be in PDF format and the maximum permitted file size is 100 MB.

Authorizations:
access_token
path Parameters
loan_application_uuid
required
string <uuid> ^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]...
Example: 22e0ee76-e496-4488-b813-2de2c90c5e0f

Unique identifier for the loan application.

Responses

Response samples

Content type
application/hal+json
{}

Submit the required action

Beta

Submit the required action when there are documents that have been uploaded.

The duration of processing will vary depending on the number of documents.

Authorizations:
access_token
path Parameters
loan_application_uuid
required
string <uuid> ^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]...
Example: 22e0ee76-e496-4488-b813-2de2c90c5e0f

Unique identifier for the loan application.

Request Body schema: application/json
s3_keys
required
Array of strings [ 1 .. 30 ] items unique

List of s3 keys representing uploaded documents.

Responses

Request samples

Content type
application/json
{
  • "s3_keys": [
    ]
}

Response samples

Content type
application/problem+json
{
  • "type": "BAD_REQUEST_BODY",
  • "title": "Invalid request body",
  • "detail": "[Object has missing required properties (['some_property'])]"
}