FLEXBridge Certificate Service API

FLEXBridge 2025 FLEXBridge API Documents FLEXBridge Certificate Service API

This document provides comprehensive technical documentation for the FlexBridge Certificate Service API, a RESTful API designed for adding Certificates of Deposit (CDs) to existing Credit Union member accounts within the Flex system (www.flexcutech.com). This API is crucial for third-party applications and internal systems needing to programmatically manage CDs.

1. Introduction to FlexBridge Certificate Service API

The Certificate Service API is a component of FLEXBridge that enables the addition of Certificates of Deposit to existing member accounts. It supports various functions related to CD management, from retrieving available suffixes to opening different types of certificates.

  • Available FLEX Releases: 8.05 and up
  • Certificate API Releases: 1.165 and up

2. General API Information

  • RESTful API: Follows RESTful principles for communication.
  • Authentication: Requires built-in authentication via HTTP request headers. Refer to the FLEXBridge Authentication Protocols and Other Information documentation for details.

3. FLEXBridge Functions

The FlexBridge Certificate Service API offers the following core functions:

  • Retrieve the next available suffix for a Certificate of Deposit.
  • Retrieve Certificate Type Default Information from the Credit Union’s database.
  • Open a Certificate of Deposit (Traditional/Non-IRA and IRA).

4. Retrieve Next Available Suffix/Subaccount

This endpoint retrieves the next available certificate suffix/subaccount value before opening a new certificate. While optional, using the returned value in the suffixNumber attribute during certificate creation is recommended. If excluded, Flex will assign the next available suffix.

  • GET Method:
    • URL: https://{URL_ADDRESS}/api/certificate/{ACCOUNT_NUMBER}/nextsuffix/{CERTIFICATE_TYPE}
    • Parameters:
      • {ACCOUNT_NUMBER} (Number): Account number of the member.
      • {CERTIFICATE_TYPE} (String): Certificate Type used to retrieve the next available suffix value.
  • Response Attribute (nextAvailableSuffix):
    {
      “nextAvailableSuffix”: 426 // Value of the next available certificate suffix/subaccount.
    }

5. Retrieve Certificate Type Defaults

This endpoint retrieves the Credit Union’s configured Certificate (CD) Type Default values, which can be used as a guide when creating a new CD. This endpoint is optional.

  • GET Method:
    • URL: https://{URL_ADDRESS}/api/certificate/defaults/{CERTIFICATE_TYPE}
    • Parameters:
      • {CERTIFICATE_TYPE} (String): Certificate Type code to retrieve default attribute values.
  • Response Object (certificateTypeDefaults):
    {
      “certificateTypeDefaults”: {} // Returns a list of attribute values defined for a specific certificate type.
    }

    • Key Attributes in Response: rate, daysInCalculatingYear, dividendFrequency, compoundDaily, renewalCode1-4, term, penaltyDays, minimumBalance, annualPercentageYield, and various GL account numbers.

6. Opening a Certificate

This section details how to add a Certificate of Deposit (CD) to an existing member account. There are distinct considerations for Traditional/Non-IRA and IRA Certificates.

  • POST Method (for both Traditional/Non-IRA and IRA):
    • URL: https://{URL_ADDRESS}/api/certificate/{ACCOUNT_NUMBER}
    • Parameters:
      • {ACCOUNT_NUMBER} (Number): Account number of the member.
    • Available JSON Body Objects:
      • certificate (Required, Object): The core object containing certificate details.
      • jointOwners (Optional, List): Use to add joint owners to a certificate (not allowed for IRA certificates).
      • beneficiaries (Optional, List): Use to add beneficiaries to a certificate.
      • userDefindedFields (Optional, Object): Use to add credit union defined fields.

6.1. Opening a Traditional/Non-IRA Certificate

  • JSON Body (certificate object attributes):
    • certificateType (Required, String): Max 2 chars.
    • accountNumber (Required, Number): Primary member account number. Max 9 chars.
    • suffixNumber (Optional, Number): Certificate suffix number. Max 3 chars.
    • openingTeller (Optional, String): Credit union teller ID. Max 4 chars.
    • description (Optional, String): Custom certificate description. Max 16 chars.
    • originalBalance (Required, Number): Starting or original balance. Max 9 chars.
    • agreedMonthlyDeposit (Optional, Number): Agreed monthly deposit amount. Max 9 chars.
    • rate (Required, Number): Certificate Percentage Rate (APR), e.g., 0.0125 for 1.25%. Max 5 chars.
    • dividendFrequency (Required, String): Dividend Payment Frequency (e.g., M=Monthly, Q=Quarterly). Max 1 char.
    • compoundInterestDaily (Optional, Boolean): Dividends compounded daily. Default false.
    • accountReceivingDividend (Optional, Number): Account for dividend payout. Required if whereToPayInterestCode is 2 in Certificate Type Settings.
    • suffixReceivingDividend (Optional, Number): Suffix for dividend payout. Required if whereToPayInterestCode is 2 in Certificate Type Settings.
    • variableRateCode (Optional, String): Variable rate group. Max 1 char.
    • openedDate (Required, Date): Open date of the certificate (MM/DD/CCYY).
    • maturityDate (Required, Date): Maturity date (MM/DD/CCYY).
    • nextDividendPayDate (Required, Date): Next dividend/interest payment date (MM/DD/CCYY).
    • lastDividendCalcDate (Required, Date): Last dividend/interest calculated date. Must match openedDate for new certificates (MM/DD/CCYY).
    • stepUpFrequency (Optional, String): Max number of step ups allowed. Max 1 char.
    • stepUpCount (Optional, Number): Step up frequency reference date. Max 1 char.
    • stepUpDate (Optional, String): Next step up date (MM/DD/CCYY).
    • certificateNumber (Optional, Number): Unique number assigned to certificate. Max 5 chars.
    • renewalCode1 (Required, String): Renewal option upon maturity (1=Renew, 2=Close/Transfer, 3=Close/Check, 4=Inactive). Max 1 char.
    • renewalCode2 (Required, String): Print confirmation notice (1=Print, 2=Do not print). Required if renewalCode1 is 1. Max 1 char.
    • renewalCode3 (Required, String): Increment certificate number (1=Increment, 2=Do not increment). Required if renewalCode1 is 1. Max 1 char.
    • renewalCode4 (Required, String): Adjust rate upon renewal (1=Use current rate, 2=Renew at same rate). Required if renewalCode1 is 1. Max 1 char.
    • renewType (Optional, String): Certificate Renewal Type. Max 2 chars.
    • transferSuffix (Optional, Number): Suffix to transfer dividend/interest. Required if renewalCode1 is 2. Max 3 chars.
    • penaltyDays (Required, Number): Grace days before early withdrawal penalty. Max 3 chars.
    • penaltyGracePeriod (Optional, Number): Days money can be withdrawn without penalty. Max 3 chars.
    • penaltyRate (Optional, Number): Penalty rate for early withdrawal.
    • penaltyCutIntoBalance (Optional, Boolean): Cut into certificate balance when assessing penalty.
    • referralCode (Optional/Required, String): Credit union defined code. Max 3 chars.

6.2. Opening an IRA Certificate

Opening an IRA certificate is similar to a traditional CD, but may require additional attributes.

  • Note: The jointOwners object is not allowed when opening IRA, Roth, or Educational Certificates (Certificate Groups F, J, O, Q, U).
  • Additional certificate object attributes for IRA:
    • federalWithholdingCode (Optional, String): Y=Yes, N=No. Required for Certificate Type Groups J, O, Q, U. Max 1 char.
    • stateWithholdingCode (Optional, String): Y=Yes, N=No. Required for Certificate Type Groups J, O, Q, U. Max 1 char.
    • sepIRA (Optional, Boolean): Simplified employee pension. Required for Certificate Type Groups J, O, Q, U. Default false.

6.3. Opening a Certificate Response

The response is the same for both Traditional/Non-IRA and IRA certificate opening options.

  • Response Attributes:
    • errorMessages (String): Indicates errors during unsuccessful certificate opening.
    • certificateSuffix (Number): Suffix value of the certificate created. Max 3 chars.
    • success (Boolean): Indicates if the request was successful.
    • accountNumber (Number): Account number used in opening the certificate. Max 9 chars.

7. Object Types and Attributes (Detailed Reference)

7.1. certificateTypeDefaults Object

  • Attributes: Provides default settings for a certificate type. Includes GL accounts, rates, frequencies, renewal codes, terms, penalty rules, and withholding information.

7.2. certificate Object

  • Attributes: Detailed information about the certificate being opened or retrieved. Includes all attributes listed under “Opening a Traditional/Non-IRA Certificate” and “Opening an IRA Certificate.”

7.3. jointOwners Object (for Traditional/Non-IRA Certificates only)

Adds single or multiple joint owner records.

  • Attributes:
    • emailAddress (Optional, String): Max 128 chars.
    • address (Required, Object): Joint owner primary mailing address.
    • relationshipToPrimaryEntityAttribute (Optional, String): Joint owner’s relationship to primary account holder (e.g., HU=Husband, WI=Wife). Max 4 chars.
    • relationshipToPrimaryEntity (Optional, String): Older attribute, to be phased out. Use relationshipToPrimaryEntityAttribute instead.
    • mobileAccess (Optional, String): Joint owner internet banking access (Y or N). Max 1 char.
    • rightOfSurviorship (Optional, String): Joint owner has survivorship rights (true or false).
    • createDelinquentLetters (Optional, Boolean): Joint owner receives delinquent/collection letters.
    • sendCollectionLetter (Optional, Boolean): Older attribute, to be phased out. Use createDelinquentLetters instead.
    • firstName, middleName, lastName, nameSuffix, title, name1, additionalMailingLine, taxName, taxId, taxIdFormatCode, taxIdCertified, stateTaxId, birthDate, gender, driversLicenseNumber, driversLicenseState, mothersMaidenName, deceased, deceasedDate, disabled, bankruptcy, foreignCitizen, livingInForeignCountry, causedLoss, insuranceEligible, creditUnionEmployee, employerCode, lendingLimit, activeMilitary, verifiedOFAC (all as per entity object in Account Management API).
    • phones (Required, List): Joint owner phone numbers.
    • addresses (Optional, List): Joint owner secondary addresses.
    • securityQuestion (Optional, Object): Joint owner security information.

7.4. address Object (Primary Mailing Address for Joint Owners/Beneficiaries)

  • Attributes: city, country, line1, line2, state, zipCode, zipCode4, badAddressDate, addressChangeDate, lastUpdateDate.

7.5. phones Object (for Joint Owners/Beneficiaries)

  • Attributes: areaCode, number, extension, countryCode, type, description.

7.6. addresses Object (Secondary Addresses for Joint Owners/Beneficiaries)

  • Attributes: city, country, line1, line2, state, zipCode, zipCode4, lastUpdateDate.

7.7. securityQuestion Object (for Joint Owners/Beneficiaries)

  • Attributes: question, answer.

7.8. beneficiaries Object

Adds single or multiple beneficiary records.

  • Attributes: Similar to jointOwners attributes, plus:
    • nickname, title, name1, additionalMailingLine, employerCode, suffixList (Beneficiary account suffix access).
    • info (Optional, Object): Additional beneficiary information (relationship, mobile access, death payout percentage).

7.9. info Object (for Beneficiaries)

  • Attributes: relationshipToPrimaryEntityAttribute, mobileAccess, deathPayoutPercentage.

7.10. userDefinedFields Object

Credit union defined fields for a certificate.

  • Attributes: fieldNumber01 to fieldNumber17 (similar to UDFs in Account Management API).

8. FLEX Validation Checks Included in HTTPS Status Code 500 Error

Flex provides additional information in 500 HTTP Status Code errors for troubleshooting. These errors often indicate invalid attribute values or missing configurations in the Credit Union’s database.

  • Common Error Messages (Examples):
    • “All suffixes for certificate type J7 and account number 797979 are in use.”: No available suffixes for the certificate type.
    • “Certificate Type ZZ is not defined.”: Invalid Certificate Type code.
    • “Account Number 1001429 is not valid.”: Invalid account number.
    • “java.lang.RuntimeException: certificateNumber cannot exceed total length of 5 with 0 decimals (135001).”: Certificate number too long.
    • “Certificate Type C2 not valid for suffix 8200.”: Invalid suffix for the Certificate Type.
    • “java.lang.RuntimeException: opening Teller cannot exceed 4 characters.”: Opening Teller field too long or invalid.
    • “java.lang.RuntimeException: suffix Receiving Dividend cannot exceed total length of 3 with 0 decimals (1001).”: Suffix Receiving Dividend field too long.
    • “org.hibernate.exception.GenericJDBCException: could not insert: [com.cmcflex.persistenceobjects.suffix.CertificateSuffix]”: Original Balance amount value exceeds 9 characters.
    • “Open new certificate failed due to the following errors: The Open Date and Last Dividend Calculation Date should match\n.”: Open Date and Last Dividend Calculation Date do not match.
    • “Open new certificate failed due to the following errors: Joint Owners are not allowed for this certificate group\n.”: Joint Owners are not permitted for the specified certificate type.
  • Troubleshooting Tip: Provide the exact error message to your Credit Union’s Flex support for efficient troubleshooting. They are typically familiar with these messages and how to correct the underlying data.