Appearance
Endpoints
Submit Application
POST {environment}/api/inbound-api/v1/SubmitApplicationV1
This method creates, and immediately validates and submits an application for review.
Headers
| Name | Type | Description |
|---|---|---|
| Content-Type | string | application/json |
| X-CloseConnectApiKey | string | See Authentication |
| X-CloseConnectApiSecret | string | See Authentication |
Request Body
INFO
See ApplicationModel for details on how to submit an application.
| Name | Type | Description |
|---|---|---|
| onBehalfOf | string | Email of the Close Connect user who will become the owner of the application. If the current API user should be the owner, this should be left empty. If creating for a user who has not given an API consent, this will fail with error 401. |
| caseId | string | A case identifier. If this is null, a new case will be created with the uploaded data, if this has the identifier of an existing case it will update the case with the uploaded data. |
| borrower | object | The borrower payload to submit. This object is of type BorrowerDetailsModel |
| loanDetails | object | The loan details payload to submit. This object is of type LoanDetailsModel |
Response
200 - Success
Application has been created and submitted successfully. CaseId can be used to identify the application in the Close Connect UI, as well as being used in other API requests.
INFO
See SubmitApplicationResponseModel for details on the response model.
javascript
// The application was created and submitted successfully
{
"caseId": "BL120000015",
"isSubmitted": true,
"validationErrors": []
}
// The application already exists
{
"caseId": "BL120000015",
"isSubmitted": true,
"validationErrors": [
{
"Model": "",
"Type": "ChangeDenied",
"Message": "Change Denied, Application already submitted"
}
],
}
// The application 'BL120000020' was created, but was not
// submitted for review due to validation errors.
{
"caseId": "BL120000020",
"isSubmitted": false,
"validationErrors": [
{
"Model": "Applicants[0].DateOfBirth",
"Type": "isAtLeastTimeAgo",
"Message": "Minimum applicant age is 21 years"
},
{
"Model": "Term",
"Type": "termValidationBasedOnCarYear",
"Message": "The minimum term for this loan is 24 months"
}
]
}401 - Unauthorized
If the authentication headers are missing or invalid.
(no response body)WARNING
If there is any quote validation error that prevents successful submission, the application will be created, but will stay in the "Open" status (instead of "Submitted"). This is usually caused by invalid/missing data and a detailed list of validation errors will be returned in the response.
In this case, the quote may be opened in the Close Connect UI application and fixed/submitted manually by a Close Connect User.
Request Body Example
javascript
{
"onBehalfOf":"dealer2@example.com",
"caseId": null,
"borrower": {
"borrowerType": "individual",
"bankDetails": {
"accountType": "individual",
"accountName": "John Account",
"bank": "alliedIrishBanks",
"yearsWithBank": 8
},
"applicants": {
"1": {
"title": "mr",
"firstName": "John",
"lastName": "AACcr",
"dateOfBirth": "1991-12-18",
"gender": "male",
"maritalStatus": "single",
"nationality": "IRL",
"primaryApplicant": true,
"ppsNumber": "5759043U",
"email": "a@co.com",
"mainPhone": "0862504814",
"secondaryPhone": "0862504815",
"addresses": {
"1": {
"line2": "55C",
"currentAddress": true,
"line1": "Dublin Landings Carpark and Estate",
"county": "Co. Dublin",
"country": "Ireland",
"posttown": "Dublin 1",
"eirCode": "D01 V4A3",
"timeAtAddress": "morethan10"
},
"2": {
"line2": "11V",
"currentAddress": false,
"line1": "Sean MacDermott Street Lower",
"county": "Co. Dublin",
"country": "United Kingdom",
"posttown": "Dublin 1",
"eirCode": "D01 VE44",
"timeAtAddress": "1year"
},
"3": {
"line2": "55C",
"currentAddress": false,
"line1": "Dublin Landings Carpark and Estate",
"county": "Co. Dublin",
"country": "Ireland",
"posttown": "Dublin 1",
"eirCode": "D01 V4A3",
"timeAtAddress": "morethan10"
}
},
"residentialStatus": "homeOwner",
"numberOfDependents": 0,
"employment": {
"industry": "Accounting",
"title": "Director",
"employmentType": "fulltime",
"status": "permanent",
"employerName": "CompanyA",
"employerAddress": {
"line2": "55C",
"line1": "Dublin Landings Carpark and Estate",
"county": "Co. Dublin",
"country": "Ireland",
"posttown": "Dublin 1",
"eirCode": "D01 V4A3"
},
"employerContact": {
"email": "testnotifications@bluestone.co.uk",
"mainPhone": "0862504814",
"secondaryPhone": ""
},
"timeInEmployment": "4years"
},
"incomeExpenditure": {
"netSalaryPerMonth": 3000,
"otherIncomePerMonth": 1000,
"mortgageRent": 1200,
"otherIncomeType": "other",
"otherIncomeDescription": "online selling"
}
}
}
},
"loanDetails": {
"term": "60",
"furtherInformation": "No",
"vehicle": {
"isNewCar": false,
"vehicleType": "car",
"registrationNumber": "211D12345",
"vin": "JT2BF22K1W0123456",
"isJapaneseImport": true,
"odometer": 50000,
"purchasePrice": 30000,
"deposit": 3000,
"tradeIn": 9000,
"tradeInRegistrationNumber": "192D54321"
}
}
}For a list of comprehensive validation rules, please refer to Data Models.
Get Application Status
GET {environment}/api/request-api/v1/GetStatusV1/{caseId}
Gets the current status of an application that was previously created by a call to the Submit Application endpoint, along with the agreed loan figures and any outstanding document requirements.
INFO
See StatusResponseModel for details on the response model.
Path Parameters
| Name | Type | Description |
|---|---|---|
| caseId | string | The case id of an existing application, as returned by Submit Application |
Headers
| Name | Type | Description |
|---|---|---|
| X-CloseConnectApiKey | string | See Authentication |
| X-CloseConnectApiSecret | string | See Authentication |
Response
200 - Success
The request was successful and the application status was retrieved.
javascript
{
"status": "Underwriting",
"quoteReference": "B1951693544567",
"date": "2026-06-04T14:52:56.803+00:00",
"loanAmount": 15000,
"monthlyPayment": 312,
"rate": 14.75,
"aprc": 16.2,
"requirements": [
"Proof of Residency",
"Proof of Address",
"Payslips"
]
}The loan figures and requirements are only populated once the application has progressed far enough for them to exist. An application that has just been submitted will report its status and date with the remaining fields empty.
400 - Bad Request
If the case id is missing from the request path.
(no response body)401 - Unauthorized
If the authentication headers are missing or invalid.
(no response body)404 - Not Found
If the application does not exist, or is not visible to the API client making the request. An application belonging to a different API client is deliberately indistinguishable from one that does not exist.
(no response body)Status Values
status reports the pipeline stage the application has reached. It is the same value that the Status Change webhook sends as newStage.
| Status | Description |
|---|---|
Open | Created, but not yet submitted for review. Usually means submission was blocked by validation errors |
Submitted | Submitted and waiting to be picked up for review |
Underwriting | Under review by an underwriter |
Referred | Referred for a further decision, for example a telephone assessment, an alternative offer, or a request for more information |
Approved | Approved, with the contract documents available for signing |
Payout | Signed contract documents received, awaiting review and payout |
Settled | Complete |
Declined | Declined |
Not Proceeding | Withdrawn or otherwise not going ahead |
INFO
Settled is the successful end state - there is no "Completed" status. Not Proceeding contains a space.
Settled, Declined and Not Proceeding are treated as closed: Start E-Sign will not act on an application in one of them. A declined or not proceeding application may still be reinstated by Close Connect, in which case it returns to the status it held before.
Start E-Sign
POST {environment}/api/inbound-api/v1/StartEsignV1
Starts the electronic signing process for the contract documents of an approved application, and reports how far that process has already got.
Headers
| Name | Type | Description |
|---|---|---|
| Content-Type | string | application/json |
| X-CloseConnectApiKey | string | See Authentication |
| X-CloseConnectApiSecret | string | See Authentication |
Request Body
| Name | Type | Description |
|---|---|---|
| caseId | string | The case id of the application to sign, as returned by Submit Application |
javascript
{
"caseId": "B1951693544567"
}Response
200 - Success
The request was received and answered. The outcome is carried by status in the body - see Response Statuses below.
INFO
See StartEsignResponseModel for details on the response model.
javascript
{
"caseId": "B1951693544567",
"status": "Initiated"
}400 - Bad Request
If the request body is missing or cannot be read.
(no response body)401 - Unauthorized
If the authentication headers are missing or invalid.
(no response body)Response Statuses
| Status | Description |
|---|---|
Initiated | The signing process has just been started for this application |
In progress | Signing was already under way, so the request had no further effect |
Completed | The contract documents have already been signed in full |
Not ready | There are no contract documents to sign yet, or the application is closed (Settled, Declined or Not Proceeding) |
Not permitted | The application does not exist, was not created through the API, or belongs to a different API client |
WARNING
All five outcomes are returned as HTTP 200. Only a failed authentication (401) or an unreadable request body (400) produces anything else - a refused request is still a 200 carrying "status": "Not permitted". Always branch on status, never on the HTTP status code.
INFO
Initiated means the process has been accepted and started, not that there is anything to sign yet. The signing invitation is prepared afterwards and the signers are contacted directly. The request is safe to repeat: calling it again returns In progress, and then Completed once signing is finished.
The contract documents become available when the application reaches the Approved status. Calling this method before then returns Not ready. Once the signed documents are returned for review the application moves on to Payout.