FLEXBridge Loan Processing Service API Documentation

FLEXBridge FLEXBridge FLEXBridge Loan Processing Service API Documentation

This documentation outlines the FLEXBridge Loan Processing Service API, an expert system designed to facilitate the creation and funding of new loans within financial institutions using the FLEXBridge system. This API is part of the FLEX Core System and is a RESTful API that requires built-in authentication with every request via HTTPS request headers.

I. Overview of the Loan Processing Service API

The Loan Processing Service API (versions 1.50 and up) is available for FLEX Releases 8.04 and up. It provides functionalities primarily for creating and funding new loans, while refinancing or loan add-ons are explicitly stated as not currently supported. The API manages all necessary objects and attributes for funding various loan products.

II. Core FLEXBridge Functions

The FLEXBridge Loan Processing Service API offers the following key functions:

  • Retrieval of the Next Available Loan Suffix:

    • Purpose: Used before loan funding to query for the next available Loan Type Suffix number for a credit union member.
    • Endpoint: https://{URL_ADDRESS}/api/loans/suffix/{ACCOUNT_NUMBER}/{LOAN_TYPE}
    • Method: GET
    • Required Attributes in Request URL:
      • {ACCOUNT_NUMBER}: Numeric, individual account number (max 9 characters).
      • {LOAN_TYPE}: String, credit union defined Loan Type value (max 2 alphanumeric characters).
    • Behavior: If the “loanSuffix” attribute is excluded from the JSON export during loan funding, the FLEX system will automatically assign the next suffix value.
    • Response: A successful request will contain the suffix number assigned to the loan, indicated by the nextAvailableSuffix attribute (Number type).
  • Create Loan (createloan Endpoint):

    • Purpose: Writes loan data into the credit union’s Loan Processing database as a pending (or in-process) loan. This option requires the credit union to complete the funding process within the FLEX system. It enables the credit union to finish the loan entry process, data collection, or loan form printing in the FLEX system before funding the loan to a member’s account.
    • Endpoint: https://{URL_ADDRESS}/api/loans/createloan
    • Method: POST
    • JSON Body: Requires a JSON body, using the same JSON objects and attributes as the postloan option.
  • Post Loan (postloan Endpoint):

    • Purpose: Completely funds a loan directly into the credit union’s FLEX database and performs any specified disbursement options (e.g., printing a check, disbursing funds to a member’s share suffix).
    • Endpoint: https://{URL_ADDRESS}/api/loans/postloan
    • Method: POST
    • JSON Body: Requires a JSON body, using the same JSON objects and attributes as the createloan option.
  • Response from createloan or postloan Request:

    • A successful request returns a JSON response indicating success: true.
    • The postLoanResponse object includes the loanAccountNumber and loanSuffix created for the successfully funded loan.

III. JSON Request Objects for Loan Funding

Both createloan and postloan options utilize a variety of JSON objects and attributes. The primary required object for all loan exports is loanInformation. Other objects are optional or required based on the specific loan product or requested features.

Here are some of the available loan JSON request objects:

  • loanInformation:

    • Description: Contains essential loan information for funding (e.g., member account number, loan suffix, loan types).
    • Required: Yes, for all loan exports.
    • Key Attributes (Examples):
      • loanGroup: Required. (C) = Consumer, (H) = HELOC, (L) = Line of Credit, (M) = Mobile Home, (R) = Real Estate, (S) = Share Secured, (V) = Credit Card.
      • loanType: Required. Credit union defined (max 2 characters).
      • loanAccountNumber: Required. Member account number (max 9 characters).
      • loanSuffix: Optional. Loan suffix value (max 3 characters). If excluded, FLEX assigns the next value.
      • disbursementDate: Required. Loan funding/open date (MM/DD/CCYY).
      • firstPaymentDate: Required. First payment due date (MM/DD/CCYY).
      • dueDate: Required. Loan’s due date (same as First Payment Date for new loans).
      • dateInterestCalculatedThrough: Required. Last date interest was calculated for funding.
      • scheduledPaymentAmount: Required. (max 9 characters).
      • interestRate: Required. (max 6 characters, 2 before, 4 after decimal).
      • openOrCloseEndedCode: Required. (O) = Open-Ended, (C) = Closed-Ended.
      • paymentMethod: Required. (C) = Cash, (T) = Automatic Transfer, (A) = ACH Distribution, (P) = Payroll Distribution. If not ‘C’, a corresponding payment method object must be included.
      • paymentFrequency: Required. (W) = Weekly, (1) = Monthly, etc..
      • chargeLateFee: Required. True or False.
      • lateChargeCalculationMethod: Required. Credit union defined.
      • securityCode: Required. FLEX’s collateral code (max 2 characters).
      • purposeCode: Required. Credit union defined loan purpose code (max 2 characters).
      • loanDisbursementTeller: Required. (max 4 characters).
      • loanAmountToDisburse: Required. Total loan amount (max 9 characters). Can be zero for credit card loans.
      • workStationId: Required for check printing. Credit Union defined Workstation ID (max 10 characters).
      • numberOfPayments: Required. Term or number of payments (max 3 characters).
      • variableRateGroup: Required. (F) = Fixed Rate, any other code indicates variable rate, requiring the variableRateExtension object.
  • Disbursement Objects:

    • checkDisbursementList: Optional/Required when Check disbursement is requested. Requires workStationId in loanInformation.
    • glDisbursementList: Optional/Required when GL Disbursement is requested.
    • shareDisbursementList: Optional/Required when Share Disbursement is requested.
    • loanDisbursementList: Optional/Required when Loan Disbursement is requested (payoff another loan suffix).
  • Collateral Objects:

    • comakerInformationList: Optional. Creates single or multiple Co-Borrower Records.
    • shareCollateralList: Optional. Creates single or multiple Share Collateral records. Used for securing a pledge amount against a member’s share suffix. For Share Secured Credit Cards, percentage attribute should be 999 and maximumPledgeAmount should be the total pledge value.
    • realEstateCollateralList: Optional. Creates single or multiple Real Estate Collateral records.
    • vehicleCollateralList: Optional. Creates single or multiple Vehicle Collateral records.
    • miscellaneousCollateralList: Optional. Creates single or multiple Miscellaneous Collateral records (e.g., jewelry, boats, trailers).
  • Payment Distribution Objects: Required if paymentMethod in loanInformation is not ‘C’ (Cash).

    • automaticTransfersList: Optional/Required when paymentMethod is (T).
    • achDistributionList: Optional/Required when paymentMethod is (A).
    • payrollInformationList: Optional/Required when paymentMethod is (P).
  • Loan-Specific Objects:

    • variableRateExtension: Optional/Required when loan is Variable Rate (i.e., variableRateGroup in loanInformation is not ‘F’ for Fixed Rate). Credit Card Loans do not use this object for variable rates; use attributes in creditCardCategoryList instead.
    • creditCardLoan: Optional/Required when loanGroup is (V) for Credit Card loans.
    • creditCardCategoryList: Optional/Required when loanGroup is (V) for Credit Card loans. Requires at least one category, by default code (1) for Purchases.
    • helocInformation: Optional/Required when loanGroup is (H) for HELOC loans.
    • loanTypeConversion: Optional. Used when a credit union wants a loan to convert from one loan type to another in the future, common for HELOCs.
    • amortizedFees: Optional. Creates a record to amortize a fee over a period.
  • Additional Information Objects:

    • creditScoreList: Optional. Creates a member score record in FLEX’s Score Maintenance. It’s recommended to also send creditScore and creditGrade in the loanInformation object.
    • pointsPaid: Optional. Used to add mortgage points paid. Use with Loan Type Groups (R) for Real Estate or (M) for Mortgage loans.
    • temporaryModificationList: Optional. Creates records for temporary loan modifications (e.g., skip payments, payment reductions, rate adjustments).
    • userDefinedFields: Optional. Populates credit union-defined fields for member loan account suffix.

IV. Revisions and Updates to the Loan Processing Document

The document undergoes regular updates to reflect changes in the API.

  • Updates as of September 2022:

    • delinquentNotice (under loanInformation object) changed to delinquencyNoticeCode. This attribute was changed in Sept 2020 but not listed in 2021 updates. Valid options are true or false.
      • Implementation: Should be implemented with any new integration starting on or after October 1, 2022.
      • Grace Period: FLEXBridge will accept the previous attribute delinquentNotice in loan exports until July 1, 2024, when it will be phased out.
    • certified (under currentAddress object within comakerInformationList) changed type from String to Boolean. Valid options are true or false.
      • Implementation: Should be implemented with any new integration starting on or after October 1, 2022.
      • Grace Period: FLEXBridge will accept previous string values of “Y” or “N” until July 1, 2024, when the string variable for this field is phased out.
    • shortVehicleDescription (under vehicleCollateralList object) adjusted to vehicleDescription. Still a string type, max 18 characters.
      • Implementation: Should be implemented with any new integration starting on or after October 1, 2022.
      • Grace Period: FLEXBridge will accept previous attribute shortVehicleDescription in loan exports until July 1, 2024, when it is phased out.
  • Updates as of November 2021:

    • bankrupt (under comakerInformationList object) type is Boolean, but its default setting in older documents was shown as a string. The default value was corrected to reflect the Boolean type.
  • Updates as of February 2021:

    • New attribute thirdPartyAppNumber was added under the loanInformation object. Allows up to 18 alphanumeric characters.
  • Updates as of January 2021:

    • The word “truncated” changed to “maximum” for data fields with too many characters.
    • User Defined Field attributes descriptions adjusted from 7 to 17.
    • Attributes userDefined12, userDefined13, and userDefined14 (under userDefinedFields) changed from date type to number type.
    • “LP” removed from Object Reference headings; headings set to expected JSON request values.
    • Temporary Modification object attributes removed as not needed for creating modifications.
    • GAP, VSI, and Service Warranty attributes adjusted to correct object values.
    • Attribute insurance adjusted to insuranceHeld.
    • Attribute policyNumber adjusted to insurancePolicyNumber.
    • Attribute companyName adjusted to insuranceCompanyName.
    • Attribute amount adjusted to insuranceAmount.
    • Attributes rateSentOnPreNotice and paymentSentOnPreNotice adjusted to be optional in variableRateExtension object.
    • Attribute reporting1098 (under loanInformation) changed from required to optional.
    • Attribute financedFee (under checkDisbursementList) changed from required to optional.
    • Attribute deceased (under entity object) type changed from String to Boolean.
    • Attribute certified (under address and addresses objects) type changed from String to Boolean.
    • Various attributes under creditCardCategoryList adjusted from required to optional.
    • Attribute descriptions for recalculatePaymentFlag, resetLoanOpenDate, and setOpenClosedEndCode (under loanTypeConversion object) adjusted to reflect Boolean field values.
    • Attribute frequency (under automaticTransferList) adjusted from optional to required when submitting an Automatic Transfer List in JSON data, or when paymentMethod (under loanInformation) has a value of ‘T’.
    • Attribute regDTransferAmount (under automaticTransfersList) adjusted to regDTransferFlag; remains string type with valid options (Y), (N), or blank/null.
    • Attribute uccExpiration (under miscellaneousCollalateralList) adjusted to uccExpirationDate; type is now date (MM/DD/CCYY).
    • Attributes vehicleMake, vehicleModel, and vehicleYear (under vehicleCollateralList) changed from optional to required when adding Vehicle Collateral.
    • Attribute number (under phones object) changed to phoneNumber.
    • New endpoint added to search for next available loan suffix by member account number.
    • New object creditScoreList added to create member score records.
    • New object pointsPaid added for mortgage points.
    • New objects achDisbursmentList and payrollInformationList added for ACH and Payroll Disbursements.
    • Attribute lastDepreciationDate added to amortizedFees object.
    • Attributes prenoticeTerm, prenoticeDateToBePaid, prenoticeNewRemainingTerm, prenoticeOldRemainingTerm, and preNoticeBalanceUsed added to variableRateExtension object.
    • Attributes businessName, taxName1, taxName2, proxyCode, and proxyExpirationDate added to Co-Borrower entity object.
    • Attribute description added to Co-Borrower phones object.
    • Removed bookloan endpoint (same function as createloan).
    • Removed CUNA Calculations object (not supported via API).
    • Removed currentBalance from creditCardCategoryList (not supported).
    • Removed loanAccountNumber and loanSuffix from payrollInformationList (not required).

V. Common HTTPS Status Code 500 Errors and Troubleshooting

FLEX has enhanced 500 HTTP Status Code errors in API service responses to assist with troubleshooting. Most errors arise from invalid attribute values or values not present in the credit union database configuration. These messages are designed to ensure data integrity.

It is recommended to provide the error message to the credit union for troubleshooting, as they are often familiar with these messages and how to correct the data.

Common error messages include:

  • {“message”: “Internal server error – Loan type na is not defined.”}:
    • Cause: Loan Type value not capitalized.
    • Correction: Ensure Loan Type value is all caps.
  • {“message”: “Internal server error – A loan in process for account: 898990 suffix: 824 already exists”}:
    • Cause: Suffix value sent in JSON data already exists for the member account.
    • Correction: A different suffix value is needed.
  • {“message”: “Internal server error – Loan Type RV not valid for requested suffix 990”}:
    • Cause: Loan Type value not assigned to the JSON data suffix value.
    • Correction: Credit union needs to add suffix value(s) to the Loan Type or validate the value is correct.
  • {“message”: “Internal server error – Loan Account Number 333555 is not valid”}:
    • Cause: Invalid account number.
    • Correction: Account number needs to be corrected.
  • {“message”: “Internal server error – Loan Distributions do not match the loan amount”}:
    • Cause: Loan disbursement amount is zero or does not match the total distribution amount.
  • {“message”: “Internal server error – The general ledger distribution for amount $250.00 does not contain a general ledger account number \r\n The general ledger distribution for amount $150.00 does not contain a general ledger account number \r\n “}:
    • Cause: General ledger disbursement account number is missing or invalid.
  • {“message”: “Internal server error – Loan Account Number 29998 is dormant. Please change account dormancy status before posting”}:
    • Cause: Attempting to post a loan to a dormant Member Account.
    • Correction: A different account number is needed, or the account needs to be adjusted by the credit union to be no longer dormant.
  • {“message”: “Internal server error – Teller 78 is blocked from posting loans to account 10487”}:
    • Cause: Loan officer is blocked from funding to the account number (e.g., credit union employee account, or intentionally blocked).
  • {“message”: “Internal server error – Member on Do Not Allow list. Unable to open loan.”}:
    • Cause: Attempting to fund to a member Tax ID that is on the credit union’s Do Not Allow list.
  • {“message”: “Internal server error – No matching service found”}:
    • Cause: The Loan Processing Service API is not running on the credit union’s bridge server.
    • Correction: Credit union needs to contact FLEX to resolve.
  • Caused by: com.ibm.as400.access.AS400JDBCSQLSyntaxErrorException: [SQL0204] SUFFIXJSON in *LIBL type *N not found.:
    • Cause: Missing data file within the credit union database.
    • Correction: Credit union needs to contact FLEX to resolve.

VI. Appendix Information (Key Concepts and Codes)

The appendix provides various reference information relevant to loan processing:

  • Pre-Decision Information: Potential member information (e.g., frozenFlag, doNotAllow, riskLevel, bankruptcy, causedLoss, activeMilitary, chargeOffCode, delinquentLoan, creditScore, creditGrade) that a credit union may use in the decisioning process. This information is available from responses of FLEX Account Inquiry API Service queries.
  • Type Groups: FLEX assigned Group type codes for loan suffixes.
    • C = Consumer
    • M = Mobile Home
    • R = Real Estate
    • L = Line of Credit
    • H = HELOC
    • V = Credit Card
    • S = Shared Secured
  • Relationship to Primary Member Examples: Common relationship values for co-borrowers (e.g., WI = Wife, HU = Husband, FA = Father, MO = Mother).
  • Charge Off Codes: Codes indicating the status of a charged-off account (e.g., R = Resolved, 97 = Unpaid balance reported as a loss by the creditor).
  • Loan Payment Frequencies: Various payment schedules supported (e.g., W = Weekly, 1 = Monthly, Y = Yearly).
  • Credit Bureau Reporting Codes: Codes used for reporting loan status to credit bureaus (e.g., 11 = Current account, 71 = Account 30 days past due date).

This document is published by Computer Marketing Corporation/FLEX and is intended solely for its contracted clients. It may contain information that is privileged, confidential, or otherwise protected from disclosure. Dissemination, distribution, or copying of this document and any accompanying attached information by someone other than the intended recipient(s), or an employee or agent acting on behalf of the intended recipient, is strictly prohibited.