Skip to main content
POST
/
v1
/
loans
/
{applicationId}
/
submit-underwriting
Submit Underwriting
curl --request POST \
  --url https://carbonapistagingsecure.getcarbon.co/baas/api/v1/loans/{applicationId}/submit-underwriting \
  --header 'Content-Type: application/json' \
  --header 'apikey: <api-key>' \
  --header 'x-carbon-key: <x-carbon-key>' \
  --data '
{
  "monthly_revenue": 5000000,
  "years_in_business": 3,
  "num_employees": 10,
  "business_sector": "RETAIL"
}
'
{
  "status": "success",
  "message": "Underwriting data submitted"
}

​
Overview

Sends business structure, address, and profile data required by the credit decision engine. Must be called after POST /v1/loans/apply. The optional userIdentity object provides additional KYC data.

​
Request

Method: POST
URL: /v1/loans/:applicationId/submit-underwriting

​
Parameters

NameInTypeRequiredDescription
x-carbon-keyHeaderstringYesAPI key for authentication.
applicationIdPathstringYesApplication ID from apply step.

​
Request Body

{
  "structure": {
    "hasWebsite": true,
    "hasSocialMediaHandles": true,
    "hasAuditedFinancialStatement": false,
    "payPension": false,
    "hasPayeeReceipt": false,
    "hasBusinessInsurance": false,
    "hasTaxClearanceCert": false,
    "hasManagementAccounts": false,
    "hasAccountant": true,
    "hasStaffHealthCare": false,
    "ownProperty": false,
    "payRent": true
  },
  "address": {
    "lga": "Lagos Island",
    "city": "Lagos Island",
    "state": "LAGOS",
    "country": "Nigeria",
    "addressVerificationType": "POWER_BILL"
  },
  "profile": {
    "yearsInBusiness": "TWO_TO_FIVE",
    "numberOfLocations": "ONE",
    "numberOfStaff": "ONE_TO_FIVE",
    "grossProfitMargin": 35,
    "operatingExpenses": 150000,
    "businessRole": "OWNER",
    "averageDailyCustomers": "FIVE_TO_FOURTEEN",
    "businessStartDate": "2022-01-15"
  },
  "userIdentity": {
    "idType": "NIN",
    "idNumber": "11111111111"
  }
}
structure — all boolean: hasWebsite · hasSocialMediaHandles · hasAuditedFinancialStatement · payPension · hasPayeeReceipt · hasBusinessInsurance · hasTaxClearanceCert · hasManagementAccounts · hasAccountant · hasStaffHealthCare · ownProperty · payRent address:
FieldRequiredAllowed values
lgaYesLocal government area string
cityNo
stateNo
countryNo
addressVerificationTypeNoPOWER_BILL · INTERNET_BILL · WATER_CORPORATION_BILL · WASTE_MANAGEMENT_BILL · STAMPED_RENT_RECEIPT
profile:
FieldRequiredAllowed values
yearsInBusinessYesONE · TWO_TO_FIVE · SIX_OR_MORE
numberOfLocationsYesONE · TWO_TO_FIVE · SIX_OR_MORE
numberOfStaffYesONE_TO_FIVE · SIX_TO_FIFTEEN · SIXTEEN_OR_MORE
grossProfitMarginYesNumber between 1 and 100
operatingExpensesYesPositive number (kobo)
businessRoleYesOWNER · PARTNER
averageDailyCustomersYesONE_TO_FOUR · FIVE_TO_FOURTEEN · FIFTEEN_TO_TWENTYFOUR · TWENTYFIVE_TO_FORTYNINE · FIFTY_OR_MORE
businessStartDateYesYYYY-MM-DD
userIdentity — optional. Both fields required if the object is included:
FieldDescription
idTypee.g. NIN, DRIVERS_LICENSE, PASSPORT
idNumberThe identity number

​
Response

​
200 OK

{
  "status": "success",
  "message": "Underwriting data submitted"
}

​
Error Responses

StatusMessageCause
400Application not foundInvalid applicationId
400structure is requiredMissing structure object
400address.lga is requiredMissing lga in address
400profile.yearsInBusiness must be one of: ...Invalid enum
400profile.grossProfitMargin must be a number between 1 and 100Out of range
400userIdentity.idType is required when userIdentity is providedIncomplete identity object
422Application has no loan IDApplication not yet registered in lending engine

Authorizations

​
apikey
string
header
required

Provide your API key in the 'apikey' header.

Headers

​
x-carbon-key
string
required

Path Parameters

​
applicationId
string
required

Body

application/json

Provide the required values for the request body.

​
monthly_revenue
number
required
Example:

5000000

​
years_in_business
number
required
Example:

3

​
num_employees
number
required
Example:

10

​
business_sector
string
required
Example:

"RETAIL"

Response

200 - application/json

Successful response

The response is of type object.