Brainysoft Docs

English

Русский

English

Русский

Appearance

Step-by-Step Business Process Guide ​

Step 1: Client Initialization ​

GET /bs-core/main/clients/init

Description

Before creating a client, you need to obtain their "template" with pre-filled system values. Returns a client object with default values filled in (e.g., bureauConsentDate, personalDataConsentDate). This object will be used in the request body in the next step, with the default values transferred.

Documentation: Client Initialization

Request Parameters

The method does not accept parameters.

Request Example

GET /bs-core/main/clients/init

Successful Response Example

The method will return a JSON client object. Save it for use in Step 2.

Step 2: Creating a Client ​

POST /bs-core/main/clients

Description

This step creates a permanent client record in the system.

Documentation: Creating a Client

Request Parameters

Form the client object based on data received in Step 1 GET /clients/init.

Important

To create a client, you need to fill in the required fields listed in the table below.

Field GroupParameterRequiredTypeDescriptionNote
BasicfirstNameRstringFirst Name"Friedrich"
lastNameRstringLast Name"Ebert"
birthDateRdateDate of Birth (YYYY-MM-DD)"1982-12-20"
mobilePhoneRstringPhone Number (digits only)"797762007719"
sexIdRintGender Identifier (101251-M, 101252-F)101251
Passportpassport.noRstringPassport Number"07825730"
passport.issueDateRdateIssue Date (YYYY-MM-DD)"2012-01-23"
AddressaddressData.fiasRstringFIAS Code for Actual Address(FIAS code, in the example "a0ed83c6-19b1-4d47-8c6d-0d2ed45b36c1")
addressData.fullAddressTextRstringText Representation of Address"Moscow, Tverskaya St, bldg 1, apt 10"
ConsentsbureauConsentPre-filled by default from initboolConsent to Credit Bureau Transfertrue
bureauConsentDatePre-filled by default from initdateCredit Bureau Consent Date (YYYY-MM-DD)"2019-04-30"
personalDataConsentPre-filled by default from initboolPersonal Data Processing Consenttrue
personalDataConsentDatePre-filled by default from initdatePersonal Data Consent Date (YYYY-MM-DD)"2019-04-30"

Notes:

  • The managerId field must be filled from the "Loan Specialists" directory. (See section – Creating a Loan Specialist/Manager)
  • The bureauConsent (consent to credit bureau transfer) and personalDataConsent (consent to personal data processing) fields are required and pre-filled from the client initialization step. You can verify data correctness: you can edit the consent dates or leave them unchanged as received in step 1.
  • The "registrationAddressData" field (registration address) should be filled if necessary, otherwise pass it empty.

Request Example

The example below shows the minimum set of required fields to create a client.

POST /bs-core/main/clients
json
{
  "firstName": "Friedrich", // First Name
  "lastName": "Ebert", // Last Name
  "birthDate": "1982-12-20", // Date of Birth (YYYY-MM-DD)
  "mobilePhone": "797762007719", // Phone Number (digits only)
  "sexId": 101251, // Gender Identifier (101251-M, 101252-F)
  "managerId": 101091, // Loan Specialist Identifier (from "Loan Specialists" directory)
  "passport": {
    // Passport Data
    "no": "07825730", // Passport Number
    "issueDate": "2012-01-23" // Passport Issue Date (YYYY-MM-DD)
  },
  "addressData": {
    // Actual Residence Address
    "fias": "a0ed83c6-19b1-4d47-8c6d-0d2ed45b36c1", // FIAS Code for Actual Address
    "fullAddressText": "Moscow, Tverskaya St, bldg 1, apt 10" // Text Representation of Address
  },
  "registrationAddressData": {}, // Registration Address (pass empty if not required)
  "bureauConsent": true, // Consent to Credit Bureau Transfer (pre-filled from step 1)
  "bureauConsentDate": "2019-04-30", // Credit Bureau Consent Date (YYYY-MM-DD, pre-filled from step 1)
  "personalDataConsent": true, // Consent to Personal Data Processing (pre-filled from step 1)
  "personalDataConsentDate": "2019-04-30" // Personal Data Consent Date (YYYY-MM-DD, pre-filled from step 1)
}

Successful Response Example

json
{
  "status": "ok", // Response Status
  "timestamp": 1764048282284, // Response Timestamp
  "data": {
    // Created Client Object
    "id": 41364, // Created Client Identifier (save for use in step 3)
    "firstName": "Friedrich", // First Name
    "lastName": "Ebert", // Last Name
    "patronymic": "", // Patronymic
    "sexId": 101251, // Gender Identifier
    "birthDate": "1982-12-20", // Date of Birth
    "deathDate": null, // Date of Death
    "birthPlace": "", // Place of Birth
    "birthCountryId": null, // Birth Country Identifier
    "educationId": null, // Education Identifier
    "highSchool": "", // Educational Institution
    "faculty": "", // Faculty
    "studyGraduationYear": "", // Graduation Year
    "studyForm": "", // Form of Study
    "professionId": null, // Profession Identifier
    "maritalStatusId": null, // Marital Status Identifier
    "dependent": false, // Has Dependents
    "passport": {
      // Passport Data
      "id": 151098, // Passport Identifier
      "seria": "", // Passport Series
      "no": "07825730", // Passport Number
      "extraNumber": null, // Additional Number
      "issueDate": "2012-01-23", // Issue Date
      "closeDate": null, // Close Date
      "manager": "", // Manager
      "subdivisionCode": "", // Subdivision Code
      "citizenshipId": null, // Citizenship Identifier
      "complementaryDocTypeId": null // Complementary Document Type Identifier
    },
    "mobilePhone": "797762007719", // Mobile Phone
    "mobileNumberOwner": null, // Phone Number Owner
    "additionalPhone": "", // Additional Phone
    "homePhone": "" // Home Phone
    // ... other client fields
  }
}

Save the client id (value of the "data.id" field) — it will be needed for creating an application in step 3.

Step 3: Application Initialization ​

GET /bs-core/main/loan-apps/init/client-id/{clientId}

Description

Initialization of a new loan application for subsequent field filling and saving. The application is initialized by the specified client Id (created in the previous step). Returns an application object. This object will be used in the request body in the next step.

Documentation: Application Initialization

Request Parameters

{clientId} (integer, required) — unique identifier of the client created in step 2.

Request Example

GET /bs-core/main/loan-apps/init/client-id/39208

Successful Response Example

The method will return a JSON loan application object. Save it for use in Step 4.

Step 4: Adding a Credit Product to the Application ​

POST /bs-core/main/loan-apps/products/{creditProductId}/apply

Description

The method automatically adds a credit product to the application. To do this:

  1. Specify the credit product identifier (creditProductId) in the request URL.
  2. In the request body, pass the application object received in Step 3 (response from GET /bs-core/main/loan-apps/init/client-id/{clientId}).

The method automatically fills the application fields with parameters from the selected credit product (including creditFieldReq). The received response with filled credit product data is used in the next step to create the application.

Documentation:

MethodURLDescription
GET|HEAD/bs-core/dicts/credit-productsGet "Credit Products" Directory Items
GET|HEAD/bs-core/dicts/credit-products/{id}Get Credit Product by ID
POST/bs-core/main/loan-apps/products/{creditProductId}/applyAutomatic Credit Product Addition to Application

Request Parameters

{creditProductId} (integer, required) — Credit product ID. For credit product creation description, see section Creating a Credit Product. The example uses the "Basic Tariff" credit product.

Request Body

Use the response from GET /bs-core/main/loan-apps/init/client-id/{clientId} method in step 3.

Request Example

POST /bs-core/main/loan-apps/products/101704/apply
json
{
  "type": "LoanApplication", // Application Type
  "id": null, // Application Identifier. Not specified when creating a new application
  "name": null, // Application Code
  "externalName": "",
  "creationDate": 1763138367184, // Creation Date in milliseconds
  "clientId": 39208, // Client Identifier (from step 2)
  "activitySubtypeId": 1014167, // Activity Subtype Identifier
  "loanTypeId": 101531, // Loan Type Identifier
  "loanStage": 1, // Loan Stage
  "liabilityId": 101931, // Financial Position Identifier
  "creditProductId": null, // Credit Product Identifier (will be filled automatically by the method)
  "creditProductName": "", // Credit Product Name (will be filled automatically by the method)
  "creditFieldReq": {
    // Credit Conditions (will be filled automatically from credit product)
    "id": null, // Credit Product Identifier
    "dateCalcMethodId": null, // Date Calculation Method
    "allowHolidaysPayment": false, // Do not shift from holidays and weekends
    "shortTermControl": false, // Short-term Loan Control
    "shiftFirstRepaymentDate": true,
    "interestChargeMethodId": null,
    "interestCalcMethodId": null, // Interest Calculation Method
    "repaymentNorm": 0.0, // Repayment Norm
    "calcIntOnIssueDate": false, // Charge interest on contract issue date (in this case interest is charged on both first and last day of tranche)
    "calcInterestOnDelinqBalance": false, // Charge interest on delinquent principal
    "calcIntOnDelinqBalanceOnlyAtDelinqIntRate": null,
    "calcArrearInterest": false, // Charge additional interest on delinquent principal (as separate amount type)
    "arrearInterestFirstDay": 1, // First day of additional interest on delinquent principal
    "arrearInterestLastDay": 9999, // Last day of additional interest on delinquent principal
    "principalDistribMethodId": null, // Principal Distribution Method
    "forepaymentConsiderationMethodId": null, // Prepayment Consideration Method
    "creditLineId": null, // Credit Line Type
    "trancheDuration": 0, // Duration of Period Between Repayments
    "interestForTranche": 0.0, // Interest Rate
    "interestRateForPeriodList": [],
    "delinquencyIntRate": 0.0, // Interest Rate for Delinquency
    "delinqIntRateDelay": 0,
    "delinqIntDaysLimit": 0,
    "useDelinqIntRateTillNextTranche": true,
    "keepUsingDelinqIntRate": false,
    "interestRateTypeId": null, // Interest Rate Type
    "chargeExtraInterest": false, // Charge interest after loan term end
    "extraIntDaysQty": null,
    "interestLgotPeriod": 0, // Interest-free Period in Days
    "interestLgotRate": 0.0,
    "interestGracePeriod": 0, // Interest-free Grace Period (in days)
    "gracePeriodDefermentMode": "RESTART",
    "trancheCount": 0, // Number of Tranches
    "repaymentSequenceId": null, // Repayment Sequence
    "mandatoryChargePeriod": 0, // Mandatory Interest Charge Period
    "allowPrepayment": false, // Prepayment possible with auto-acceptance
    "prolongationPeriod": 0, // Prolongation Period
    "earlyProlongationFromCurrentDate": false, // Early prolongation from current date (otherwise prolongation from current tranche end date)
    "prolongationOnNewSchedule": false,
    "prolongedIntToLastTranche": true,
    "penaltyTypeId": null, // Penalty Accrual Type
    "calendarDaysPenalty": false, // Penalty by Calendar Days
    "firstWeekendWithoutPenalty": false, // No penalties on first weekend
    "stopPenaltyOnClose": false, // Stop penalties after schedule end
    "qtyDaysStopPenaltyOnClose": 0, // Days after schedule end until penalty stop
    "fixedDelayPenalty": 0.0, // Delay Penalty (Fixed Amount)
    "delayPenaltyDay": 1, // Delinquency Day for Delay Penalty
    "inviteAmountPct": 0.0, // Percentage of Issue Amount (to determine if counted as friend)
    "inviteDiscountPerFriend": 0.0, // Interest Rate Reduction per Friend
    "inviteMinIntRate": 0.0, // Minimum Interest Rate
    "scheduleRecalcEnabled": false, // Schedule Recalculation on Scheduled Payment Date
    "fullScheduleDatesRecalc": false, // Full Schedule Shift from Actual Issue Date
    "useDelinqIntRateForPsk": false,
    "discountingEnabled": false, // Discounting Enabled
    "useEirForDiscounting": false,
    "fees": [], // Fees
    "principalParts": [], // Principal Parts
    "penaltyRates": [], // Penalty Rates
    "qtyTranchesFirstPeriod": 0, // Number of Tranches in 1st Period
    "intRateFirstPeriod": 0.0, // Interest Rate in 1st Period
    "qtyTranchesSecondPeriod": 0, // Number of Tranches in 2nd Period
    "intRateSecondPeriod": 0.0, // Interest Rate in 2nd Period
    "amountSecondPeriod": null,
    "qtyTranchesRepNormSecondPeriod": 0, // Number of Tranches for Second Period Repayment Norm Calculation
    "interestOnLoanAmount": false, // Calculate Interest from Contract Amount
    "penaltyRatePeriodFrom": "FROM_TRANCHE_REPAYMENT_DATE",
    "agreedRepaymentAmount": null,
    "disableLgotTrancheOnERN": false,
    "penaltyLimitValue": null,
    "penaltyLimitUnit": null,
    "lgotTranchesQty": null,
    "manualIntRateForFullCostCalc": null
  },
  "secondaryCreditProductId": null,
  "secondaryCreditField": null,
  "currencyId": 101011, // Application Currency Identifier
  "loanAmount": 0.0, // Loan Amount
  "subsidyAmount": 0.0, // Subsidy Amount
  "commissionAmount": 0.0, // Commission Amount
  "loanDeniedRejectionId": null, // Rejection Reason Identifier
  "creditPurposeId": 101682, // Credit Purpose Identifier
  "creditSecondPurposeId": null,
  "managerId": null, // Loan Specialist
  "mainManagerId": null, // Main Loan Specialist
  "collateralLineId": null,
  "contractName": 0, // Contract Name. This field is filled if you need to know the contract number at the application stage when the contract does not exist yet
  "collateralIds": [], // Collateral Identifiers
  "coborrowers": [], // Co-borrowers
  "issueSteps": [], // Issue Steps
  "gettingMoneyMethodId": 102396, // Money Receiving Method
  "bureauScoringPoint": 0.0, // Credit Bureau Scoring Point
  "siteName": "", // Website Application Number
  "ipAddress": "", // IP Address
  "applyPlace": "", // Client Application Place
  "socialNetwork": "", // Social Network (vk; ok; fb)
  "userIDinSocialNetwork": "", // User ID in Social Network
  "friendsQuantityInSocialNetwork": "", // User's Friends Count in Social Network
  "mainPhotoLinkOnSocialNetwork": "", // Main Photo Link from Social Network
  "selectedPhotosLinksWithLike": "", // Selected Photo Links with "Like" Mark (maximum 100)
  "selectedPhotosLinksWithMarkedPersons": "", // Selected Photo Links with Tagged People (maximum 100)
  "groupsListFromSocialNetworks": "", // Groups List from Social Network (maximum 100)
  "groupsLinksofFromSocialNetworks": "", // Group Links from Social Network (maximum 100)
  "age": "", // Age
  "monthlyIncome": null,
  "monthlyPayment": null,
  "debtRatioCoef": null,
  "personalIncomes": [],
  "tenderName": null, // Tender Name
  "tenderNo": null, // Tender Number
  "tenderNoticeNo": null, // Tender Notice Number
  "tenderDelayedAppNo": null, // Tender Delayed Application Number
  "tenderPlatformCode": null, // Platform Code
  "repeatedLoan": false, // Repeated Loan
  "premiumLoan": false, // Premium Client
  "shopAddressId": null, // Store Address
  "outletId": null,
  "contractorId": null,
  "merchantId": null,
  "consultantId": null,
  "conclusionDate": null, // Agreement Conclusion Date
  "signingDate": null, // Signing Date
  "decisionExpDate": null, // Decision Validity Period
  "initialInstallment": 0.0, // Initial Installment
  "fullTaxAmount": 0.0,
  "originalLoanApplicationId": null,
  "restructedLoanApplicationId": null,
  "marketingOfferId": null,
  "contractUID": "01f0c196-0bd2-1b9a-a705-eb79bf07c851-0",
  "subrent": null,
  "rentalObjectResidualValue": null
}

Successful Response Example

The method will return a JSON loan application object with automatically filled credit product fields:

  • creditProductId: 101704
  • creditProductName: "Basic Tariff"
  • creditFieldReq: credit product parameters

Save the received response — it will be used in the request body in Step 5.

Step 5: Creating a Loan Application ​

POST /bs-core/main/loan-apps

Description

At this step, the final loan application creation is performed. The method saves all data collected in the previous steps (application initialization from Step 3 and credit product addition from Step 4).

Upon successful application creation, the system automatically:

  • creates a Lead object through the intake channel "channel": "LOAN_APPLICATION".
  • runs checks in the DMS (Decision Making System) according to the configured scoring scheme.
  • assigns a status and identifier to the application.

Documentation: Creating an Application

Request Parameters

The request body is formed based on the JSON response received in Step 4 from the POST /bs-core/main/loan-apps/products/{creditProductId}/apply method.

Instructions:

  1. Copy the entire JSON object from the Step 4 response
  2. Change the loanAmount field value from 0.0 to the required loan amount (e.g., 10000.0)

Request Example

http
POST /bs-core/main/loan-apps
Content-Type: application/json

Request Body:

json
{
  "type": "LoanApplication",
  "id": null,
  "name": null,
  "externalName": "",
  "creationDate": 1763138367184,
  "clientId": 39208, // Client Identifier (from Step 2)
  "activitySubtypeId": 1014167,
  "loanTypeId": 101531,
  "loanStage": 1,
  "liabilityId": 101931,
  "creditProductId": 101704, // Credit Product Identifier (from Step 4)
  "creditProductName": "Basic Tariff", // Credit Product Name (from Step 4)
  "creditFieldReq": {
    /* ... parameters from Step 4 ... */
  },
  "currencyId": 101011,
  "loanAmount": 10000.0, // Loan Amount (changed from 0.0)
  "subsidyAmount": 0.0,
  "commissionAmount": 0.0,
  "creditPurposeId": 101682,
  "managerId": null,
  "gettingMoneyMethodId": 102396,
  "contractUID": "01f0c196-0bd2-1b9a-a705-eb79bf07c851-0"
  /* ... other fields from Step 4 response ... */
}

Successful Response Example

json
{
  "status": "ok",
  "timestamp": 1764048282284,
  "data": {
    "id": 12345, // Created Application Identifier
    "name": "LA-2025-001234", // Application Code
    "clientId": 39208,
    "creditProductId": 101704,
    "loanAmount": 10000.0,
    "loanStage": 1, // Application Stage
    "status": "Ready for Issue" // Application Status (depends on channel settings)
    /* ... other application fields ... */
  }
}

Important

The presence of a filled id in the response means that the application was successfully created, the lead was formed, and the DMS checks passed.

Notes

Application Status and Contract

Depending on the lead intake channel settings, the following scenarios are possible after application creation:

Channel ParameterApplication StatusContract
autoCreateContract: true"Ready for Issue"Created but not issued
autoCreateContract: true
autoIssueContract: true		"Issued"Created and issued
autoCreateContract: false
autoIssueContract: false		"Ready for Issue"Not created

Automatic Lead Creation

In the example above, the lead is automatically created through the "channel": "LOAN_APPLICATION" channel and goes through the DMS check scheme configured on this lead intake channel.

Automatic Contract Creation Settings

To manage automatic contract creation and issuance, use the following parameters in the lead intake channel settings:

  • Automatic Contract Creation (autoCreateContract):

    • true — the contract will be created automatically.
    • false — the contract will not be created automatically.

  • Automatic Contract Issuance (autoIssueContract):

    • true — the contract will be automatically issued (requires autoCreateContract: true).
    • false — the contract will not be automatically issued.

Configuration Examples:

  • Contract creation and issuance: "autoCreateContract": true, "autoIssueContract": true.
  • Contract creation only: "autoCreateContract": true, "autoIssueContract": false.
  • Without automatic creation: "autoCreateContract": false, "autoIssueContract": false.

Additional Information

For more details on intake channel configuration, automatic contract creation, and working with scoring schemes, see the documentation section: Lead, Intake Channels, Scoring Schemes (Decision Making Systems).

Error Handling ​

If you encounter errors during client creation step (Step 2), here are the most likely causes:

Error CodeCause
METADATA__EMPTY_REQUIRED_FIELDOne of the required fields is not filled (first name, last name, date of birth, etc.)
NO_PASSPORT_ERRORPassport data is not specified or incorrectly specified
NO_ADDRESS_ERRORActual address is not specified
NO_MANAGER_ERRORmanagerId is not specified
NO_BUREAU_CONSENT_DATE_ERRORConsent date is not specified when bureauConsent: true is passed

Possible Solution: Make sure that in the Admin Panel in the "Model Editor" section for the "Individual" entity (/admin/model-editor/person – method for obtaining metadata properties of a given model - https://docs.brainysoft.ru/documentation/page/267) there is no excessive Required setting for fields not used in this scenario.