# Funding Circle Introducer API(v1)

This page contains information on how to use the Funding Circle Introducer 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 introducers to offer Funding Circle loans from within their own website, platform or mobile app.

To learn more about our introducer opportunities, visit us at [Funding Circle Introducers](/content/introducers/index.html). To gain access to our Sandbox, email us at [broker@fundingcircle.com](mailto:broker@fundingcircle.com).

# Authentication

The API is under [OAuth 2.0 Client Credentials Grant flow](https://datatracker.ietf.org/doc/html/rfc6749#section-4.4).
In order to make a request, your client must be authorised.

## access_token

The first step is to generate an `access_token`. In order to generate this, submit a `POST` request to the Authentication endpoint passing a base-64 token generated from your unique `client_id:client_secret`.

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

The `access_token` is valid for **only 24 hours** and **must** be set in the HTTP header of each request.

```plaintext
Authorization: Bearer eyJraWQiOiJkd1ZKOFFhaGNcL2V4bFBwRUN3TDVNaTA3YmRqOFhNK3MzY.....
```

**Important:** You **must not** include the `access_token` when making a PUT request to upload a document.

# Errors

An `x-amzn-trace-id` header will be returned with each request. We follow the error response format proposed in [RFC 7807](https://tools.ietf.org/html/rfc7807) also known as Problem Details for HTTP APIs.

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

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

## UNAUTHORIZED

- HTTP status: **401**

This response means that your client is not authorised to access the API.

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

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

## UNPROCESSABLE_ENTITY

- HTTP status: **422**

This response means that the API has processed the request, but the client is not allowed to proceed.

## 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

Our sandbox environment provides predefined test scenarios using specific values.

## Eligibility

To test different eligibility outcomes, use one of these specific `companies_house_id` values in your loan application requests:

- `00000000` - company with low eligibility
- `00000001` - company with medium eligibility
- `00000002` - company with high eligibility

## Loan Application

Submit a complete loan application for a term loan through a simple, step-by-step process. Make a `POST` request to start the application process and use the returned links to monitor processing status. You will receive either a credit decision or a request for additional information.

Some endpoints use background processing following the Microsoft [Asynchronous Request-Reply Pattern](https://docs.microsoft.com/en-us/azure/architecture/patterns/async-request-reply).

## Create a term loan application

Submit a term loan application for processing. Credit reports will be pulled for the company and any supplied Executive Business Owners (EBOs).

### Authorizations:

_access_token_

### Request Body schema: application/json

|     |     |
| --- | --- |
| broker_email | string<email>[ 1 .. 80 ] characters | Email address of the associated Broker, if applicable. |
| callback_url | string | When an action is required or a decision is made, we will call your webhook. |
| ... | ... |

### Responses

**202**
OK

**400**
Invalid request

**415**
Unsupported media type

**422**
Unprocessable entity

### Request samples

```json
{"broker_email": "john.smith@example.com", ...} 
```

### Response samples

- 400
- 404

```json
{"type": "BAD_REQUEST_BODY", ... }
```

## Check the status of a loan application

Retrieves a resource that describes the current status of a submitted loan application.

### Authorizations:

_access_token_

### path Parameters

|     |     |
| --- | --- |
| loan_application_uuid | string<uuid> | Unique identifier for the loan application. |

### Responses

**202**
Loan application is still being processed

**404**
Resource not found

**410**
Resource has expired

```json
{"loan_application_uuid": "a5764857-ae35-34dc-8f25-a9c9e73aa898", ... }
```

## Retrieve a loan application

Retrieve the current status of a processed loan application.

### Authorizations:

_access_token_

### Responses

**200**
OK

**404**
Resource not found

```json
{"status": "in_progress", ... }
```

## Retrieve the decision for a loan application

Retrieve the decision for a processed loan application.

### Authorizations:

_access_token_

### Responses

**200**
OK

**404**
Resource not found

```json
{"created_at": "2019-08-24T14:15:22Z", "status": "action_required", ... }
```

## Get a document upload URL for a loan application

Get a document upload URL when an action is required.

### Authorizations:

_access_token_

### Responses

**200**
OK

**403**
Forbidden request

```json
{"s3_key": "999d22d5-f5dc-4726-955a-f86b1ca34aa3/bank_statement_1.pdf", ... }
```

## Submit the required action

Submit the required action when documents have been uploaded.

### Authorizations:

_access_token_

### Request Body schema: application/json

|     |     |
| --- | --- |
| s3_keys | Array of strings | List of s3 keys representing uploaded documents. |

### Responses

**202**
OK

**400**
Invalid request

```json
{"type": "BAD_REQUEST_BODY", ... }
```