FLEXBridge Certificate Service API Documentation

FLEXBridge FLEXBridge FLEXBridge Certificate Service API Documentation

The Certificate Service API is a vital component of FLEXBridge, designed to facilitate the addition of Certificates of Deposit (CDs) to existing credit union member accounts. This API is compatible with FLEX Releases 8.04 and up.

FLEXBridge Overview

  • FLEXBridge is a RESTful API.
  • It incorporates built-in authentication, with authentication details attached to every request as HTTP request headers. For more information on authentication protocols, refer to the “FLEXBridge Authentication Protocols and Other Information documentation”.

Key Functions Available in the Certificate Service API The Certificate Service API provides 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.
  • Opening a Certificate of Deposit.

1. Retrieve Next Available Suffix/Subaccount

This endpoint is used to retrieve the next available certificate suffix/subaccount value before opening a new certificate.

  • Usage: Retrieving the next available suffix/subaccount is optional.
    • If used, the returned value should be sent in the JSON data using the suffixNumber attribute.
    • If the suffixNumber attribute is excluded from the JSON data, the FLEX system will assign the next available suffix/subaccount during certificate creation and return the value in a successful response.
  • Method: GET
  • REST URL: https://{URL_ADDRESS}/api/certificate/{ACCOUNT_NUMBER}/nextsuffix/{CERTIFICATE_TYPE}
  • Parameters for Request:
    • {ACCOUNT_NUMBER}:
      • Type: Number
      • Description: Account number of the member
    • {CERTIFICATE_TYPE}:
      • Type: String
      • Description: Certificate Type used to retrieve the next available suffix value
  • Sample Request: https://101.513.26.19/api/certificate/551286/nextsuffix/J1
  • Response Attributes:
    • nextAvailableSuffix:
      • Type: Number
      • Description: The value of the next available certificate suffix/subaccount
  • Example Response:

{

  “nextAvailableSuffix”: 426

}

2. Retrieve Certificate Type Defaults

This endpoint retrieves the credit union’s configured Certificate (CD) Type Default values. These values can be used when creating a new CD.

  • Usage: This endpoint is optional and not required to successfully add a CD to a credit union’s database. The returned values can aid in populating the JSON data for the Opening Certificate endpoint.
  • Method: GET
  • REST URL: https://{URL_ADDRESS}/api/certificate/defaults/{CERTIFICATE_TYPE}
  • Parameters for Request:
    • {CERTIFICATE_TYPE}:
      • Type: String
      • Description: Certificate Type code to retrieve certificate default attribute values defined in the credit union’s database.
  • Sample Request: https://10.0.5.115/api/certificate/defaults/J2
  • Response Attributes:
    • certificateTypeDefaults:
      • Type: certificateTypeDefaults object
      • Description: Returns a list of attribute values defined for a specific certificate type in the credit union database.
  • Important Note: The credit union must provide the vendor with a list of all their configured certificate types when needed.
  • Example Response (partial):

{

  “certificateTypeDefaults”: {

    “liabilityOrCapitalGL”: 90743,

    “dividendOffsetGL”: 38143,

    “dividendPayableGL”: 85443,

    “rate”: 1.21,

    “term”: 24,

    “termCode”: “M”,

    “penaltyDays”: 180,

    “penaltyGraceDays”: 10,

    “active”: true,

    “minimumBalance”: 8500,

    “type”: “J2”,

    “description10”: “24 MO IRA”,

    “group”: “J”

  }

}

3. Opening a Certificate

This section details how to add a Certificate of Deposit (CD) to an existing member account.

  • Recommendation: FLEX advises working with the credit union to determine which attributes they require to be populated when opening a Certificate (CD), in addition to those marked as required by FLEX in the Object Reference section.
  • Method: POST
  • REST URL: https://{URL_ADDRESS}/api/certificate/{ACCOUNT_NUMBER}
  • Parameter for Request:
    • {ACCOUNT_NUMBER}:
      • Type: Number
      • Description: Account number of member
      • Required: Yes
  • Available JSON Body Objects for Opening a Certificate:
    • certificate:
      • Type: certificate object
      • Description: The primary object required in the JSON for opening a certificate.
      • Required: Yes
    • jointOwners:
      • Type: List of jointOwners objects
      • Description: Used to add one or more joint owners to a certificate.
      • Required: No (Optional)
      • Important Note: The jointOwners object is not allowed when opening an IRA, Roth, or Educational Certificate (this includes certificate groups F, J, O, Q, and U).
    • beneficiaries:
      • Type: List of beneficiaries objects
      • Description: Used to add one or more beneficiaries to a certificate.
      • Required: No (Optional)
    • userDefinedFields:
      • Type: userDefinedFields object
      • Description: Used to add credit union defined fields tied to a certificate.
      • Required: No (Optional)

3.1. Opening a Traditional/Non-IRA Certificate

  • Sample Request: https://16.23.4.236/api/certificate/300220
  • JSON Body Structure: Includes certificate, jointOwners, beneficiaries, and userDefinedFields objects as applicable.

3.2. Opening an IRA Certificate

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

  • Recommendation: FLEX recommends verifying with the credit union which fields need to be populated.
  • Potentially Needed Attributes:
    • Federal Withholding Code
    • State Withholding Code
    • SEP IRA
  • Key Restriction: The Joint Owner object is not allowed when opening an IRA, Roth, or Educational Certificate. This applies to all certificates in groups (F) = HAS Certificate, (J) = IRA Certificate, (O) = Roth Certificate, (Q) = Education Certificate, and (U) = Roth Conversion Certificate.
  • Available JSON Body Objects for Opening an IRA Certificate:
    • certificate: Required
    • beneficiaries: Optional
    • userDefinedFields: Optional
  • Sample Request: https://19.10.4.58/api/certificate/300220
  • JSON Body Structure: Includes certificate, beneficiaries, and userDefinedFields objects (notice the absence of jointOwners).

3.3. Opening a Certificate Response

The service response is identical for both Traditional/Non-IRA and IRA certificate opening options.

  • Response Attributes:
    • errorMessages:
      • Type: String
      • Description: Indicates errors during unsuccessful certificate opening (refer to HTTPS Status 500 Error section).
    • certificateSuffix:
      • Type: Number
      • Description: Suffix value of the certificate created (max 3 characters).
    • success:
      • Type: Boolean
      • Description: Indicates if the request was successful. Valid Options: true or false.
    • accountNumber:
      • Type: Number
      • Description: Account number used in opening the certificate (max 9 characters).
  • Example Response:

{

  “errorMessages”: null,

  “certificateSuffix”: 61,

  “success”: true,

  “accountNumber”: 101429

}

4. Object Types and Attributes

The following sections detail the various objects and their attributes used within the Certificate Service API.

4.1. Certificate Type Defaults Object

This object contains the credit union’s configured Certificate (CD) Type Default values.

  • Attributes (partial list with examples):
    • type: Current certificate type (String)
    • description4, description6, description10, description16: Credit union defined descriptions (String)
    • group: Certificate group type defined by FLEX. Options: (F) HSA, (J) IRA, (K) Regular, (O) Roth, (Q) Education, (U) Roth Conversion.
    • liabilityOrCapitalGL: Capital Account ledger debited/credited with certificate balance changes (Number).
    • dividendOffsetGL: Certificate ledger debited when dividends are accrued or paid (Number).
    • dividendPayableGL: Certificate ledger credited for accruing dividends (Number).
    • penaltyRevenueGL: Certificate ledger credited with an early withdrawal penalty fee (Number).
    • backupWithholdingGL: General ledger for Backup Withholding Fees (Number).
    • rate: Certificate Annual Percentage Rate (APR) (Number).
    • annualPercentageYield: Certificate Annual Percentage Yield (APY) (Number).
    • daysInCalculatingYear: Number of calendar days for dividend calculation. Options: 360, 365, 366 (Number).
    • dividendFrequency: Dividend Payment Frequency (String). Options include Weekly (W), Monthly (M), Quarterly (Q), Yearly (Y), At Maturity (T), etc..
    • compoundDaily: Indicates if dividends are compounded daily. Options: true or false (Boolean).
    • renewalCode1: Renewal code for maturity action. Options: (1) Auto Renew, (2) Close & transfer to share, (3) Close & send check, (4) Leave inactive (String).
    • renewalCode2, renewalCode3, renewalCode4: Further renewal options for printing confirmation, incrementing certificate number, and rate adjustment (String).
    • term: Term of the certificate (Number).
    • termCode: How term attribute is defined. Options: (D) Days, (M) Months, (Y) Years (String).
    • penaltyDays: Grace days before early withdrawal penalty (Number, max 3 chars).
    • penaltyGraceDays: Days from renewal/opening for penalty-free withdrawal (Number, max 3 chars).
    • penaltyCutIntoBalance: Indicates if penalty can cut into balance (Boolean).
    • penaltyFromOriginalOrCurrentBalanceCode: Balance used for early withdrawal fee calculation. Options: (O) Original, (C) Current (String).
    • penaltyBasisForPartialWithdrawal: Which balance used for partial withdrawal penalty. Options: (O) Original, (C) Current, (P) Partial Balance, (T) Transaction Amount (String).
    • federalWithholdingGL, federalWithholdingRate, federalWithholdingCode: Federal withholding details for IRA certificates (Number, String).
    • dividendOrInterest: Word used for member notifications. Options: (D) Dividend, (I) Interest (String).
    • stateWithholdingGL, stateWithholdingRate, stateWithholdingCode: State withholding details for IRA certificates (Number, String).
    • active: Whether the certificate type is active for opening (Boolean).
    • minimumBalance, minimumAddOnAmount, maximumBalanceAmount: Balance thresholds (Number).
    • whereToPayInterestCode: Where dividend/interest is paid. Options: (1) Current certificate, (2) Transfer to share suffix, (3) Pay by check (Number).
    • transferSuffix: Suffix for dividend/interest transfer if Renewal Code 1 is 2 (Number).
    • variableRateCode: Variable rate group (String).
    • requiredToWithdrawInterest: If member must withdraw dividend/interest (Boolean).
    • adjustRateOnInitialDeposit: If rate can be adjusted with initial deposit (Boolean).
    • backupWithholdingRate: Set rate for backup withholding (Number).
    • stepUpFrequency, stepUpMaxAllowed, stepUpDateReference: Details for rate step-ups (String, Number).
    • renewAsType: Credit union defined certificate renewal type (String).
    • maturityDate, nextDividendPayDate, forfeitInterestOnEarlyWithdraw: Additional details (Date, Boolean).

4.2. Certificate Object

This object contains all the details for a specific Certificate of Deposit being opened.

  • Attributes (partial list with examples, noting requirements and updates):
    • group: Certificate group type (FLEX defined). Informational, not needed in export data.
    • certificateType:
      • Type: String (max 2 chars)
      • Required: Yes
    • accountNumber:
      • Type: Number (max 9 chars)
      • Required: Yes
    • suffixNumber:
      • Type: Number (max 3 chars)
      • Optional: If excluded, FLEX selects the next available suffix.
    • openingTeller:
      • Type: String (max 4 chars)
      • Optional: New attribute as of July 2023.
    • description:
      • Type: String (max 16 chars)
      • Optional
    • originalBalance:
      • Type: Number (max 9 chars)
      • Required: Yes
    • agreedMonthlyDeposit:
      • Type: Number (max 9 chars)
      • Optional
    • rate:
      • Type: Number (max 5 chars)
      • Required: Yes. Send as a value divided by one hundred (e.g., 1.25% as .0125).
    • annualPercentageYield:
      • Type: Number
      • N/A: Do not send in the export, FLEX determines this.
    • dividendFrequency:
      • Type: String (max 1 char)
      • Required: Yes. Options: (W) Weekly, (B) Bi-Weekly, (F) Semi-Monthly, (1) Monthly (open date), (M) Last day of month, (3) Quarterly (open date), (Q) End of calendar quarter, (6) Semi-annually (open date), (S) Twice a year (June 30/Dec 31), (Y) Yearly (open date), (A) Annually (Dec 31), (T) At Maturity.
    • compoundInterestDaily:
      • Type: Boolean
      • Optional: Default = false. Note: Different from compoundDaily in certificateTypeDefaults.
    • accountReceivingDividend, suffixReceivingDividend:
      • Type: Number
      • Optional: Required if whereToPayInterestCode is 2 in Certificate Type Settings. Added Oct 2019.
    • variableRateCode:
      • Type: String (max 1 char)
      • Optional
    • openedDate, maturityDate, nextDividendPayDate, lastDividendCalcDate:
      • Type: Date (MM/DD/CCYY format)
      • Required: All. lastDividendCalcDate must match openedDate for new CDs.
    • stepUpFrequency, stepUpCount, stepUpDate:
      • Type: String, Number, Date
      • Optional.
    • certificateNumber:
      • Type: Number (max 5 chars)
      • Optional: FLEX assigns if blank/excluded.
    • renewalCode1, renewalCode2, renewalCode3, renewalCode4:
      • Type: String (max 1 char)
      • Required: renewalCode1 is always required. renewalCode2, renewalCode3, renewalCode4 are required if renewalCode1 has a value of 1.
    • renewType:
      • Type: String (max 2 chars)
      • Optional: Must be in the same type group as original.
    • transferSuffix:
      • Type: Number (max 3 chars)
      • Optional: Required if renewalCode1 has a value of 2.
    • penaltyDays:
      • Type: Number (max 3 chars)
      • Required: Yes. Value can be from Type Default search.
    • penaltyGracePeriod:
      • Type: Number (max 3 chars)
      • Optional. Note: Different from penaltyGraceDays in certificateTypeDefaults.
    • penaltyRate:
      • Type: Number
      • Optional: Added Oct 2019. Value is subtracted from current pay rate.
    • penaltyCutIntoBalance:
      • Type: Boolean
      • Optional: Adjusted from String to Boolean in Oct 2019 updates. Valid options: true or false.
    • federalWithholdingCode, stateWithholdingCode, sepIRA:
      • Type: String, String, Boolean
      • Optional: Required for specific FLEX Certificate Groups (J) IRA, (O) Roth, (Q) Education, and (U) Roth Conversion Certificates. sepIRA default is false.
    • referralCode:
      • Type: String (max 3 chars)
      • Optional/Required: Adjusted from required to optional in July 2023. May be required if configured in credit union’s database.

4.3. Joint Owner Information Object (jointOwners)

This object list is used to add single or multiple joint owner records when opening a traditional/non-IRA certificate.

  • Important: This object is not allowed for IRA, Roth, or Educational Certificates.
  • Address Object Lists Usages:
    • address: Use for the joint owner’s primary mailing address. This object list is required.
    • addresses: Use for other mailing addresses for the joint owner, different from the primary. This object list is optional. FLEX allows saving multiple addresses but advises against sending the same address in both objects.
  • Attributes (partial list with examples, noting requirements and updates):
    • emailAddress:
      • Type: String (max 128 chars)
      • Optional
    • address:
      • Type: address object
      • Required: Yes.
    • relationshipToPrimaryEntityAttribute:
      • Type: String
      • Optional: FLEX recommends using this attribute as of July 2023 to populate relationship data in place of relationshipToPrimaryEntity. Values vary per credit union (e.g., AU, BR, HU, WI).
    • relationshipToPrimaryEntity:
      • Type: String
      • Optional: Will be phased out as of Oct. 2024. FLEX recommends using relationshipToPrimaryEntityAttribute instead.
    • mobileAccess:
      • Type: String (max 1 char)
      • Optional: Indicates Internet Banking access. Options: Y, N.
    • rightOfSurviorship:
      • Type: String
      • Optional: Indicates survivorship rights. Valid options: true or false. Note: FLEX is aware of the misspelling and will correct it in future versions.
    • createDelinquentLetters:
      • Type: Boolean
      • Optional: Should the Joint Owner receive collection letters? Valid options: true or false. FLEX recommends using this attribute as of July 2023 in place of sendCollectionLetter. Added July 2023.
    • sendCollectionLetter:
      • Type: Boolean
      • Optional: Will be phased out as of Oct. 2024. FLEX recommends using createDelinquentLetters instead.
    • firstName, lastName:
      • Type: String (max 40 chars)
      • Required: Yes (if account type = Individual or Non-Citizen).
    • middleName, nameSuffix, title, name1, additionalMailingLine, taxName, stateTaxId:
      • Type: String
      • Optional (except name1 which is required for Business/Organization/Non-profit).
    • taxId:
      • Type: String (max 9 chars)
      • Required: Yes.
    • taxIdFormatCode:
      • Type: String
      • Required: Yes. Options: (T) EIN or (S) SSN.
    • taxIdCertified:
      • Type: Boolean
      • Required: Yes. Options: true or false.
    • birthDate:
      • Type: Date (MM/DD/CCYY)
      • Required: Yes.
    • gender:
      • Type: String (max 1 char)
      • Optional. Options: “F”, “M”.
    • driversLicenseNumber, driversLicenseState:
      • Type: String
      • Optional.
    • mothersMaidenName:
      • Type: String (max 40 chars)
      • Optional.
    • deceased, deceased date, disabled, bankruptcy, foreignCitizen, livingInForeignCountry, causedLoss, insuranceEligible, creditUnionEmployee, activeMilitary, verifiedOFAC:
      • Type: String/Boolean, Date
      • Optional: Most have default values (e.g., disabled=false, insuranceEligible=true).
    • employerCode, lendingLimit:
      • Type: String, Number
      • Optional.
    • phones:
      • Type: List of phones objects
      • Required: Yes, one number is required.
    • addresses:
      • Type: List of addresses objects
      • Optional: For informational addresses other than primary.
    • securityQuestion:
      • Type: securityQuestion object
      • Optional: New object added July 2023. Contains question (String, max 4 chars) and answer (String, max 32 chars) attributes.

4.4. Beneficiaries Information Object (beneficiaries)

This object list is used to add single or multiple beneficiary records when opening a certificate.

  • Address Object Lists Usages:
    • address: Use for the beneficiary’s primary mailing address. This object list is required.
    • addresses: Use for other mailing addresses for the beneficiary, different from the primary. This object list is optional. FLEX allows saving multiple addresses but advises against sending the same address in both objects.
  • Attributes (partial list with examples, noting requirements):
    • firstName, lastName:
      • Type: String (max 40 chars)
      • Required: Yes.
    • middleName, nameSuffix, title:
      • Type: String
      • Optional.
    • taxId:
      • Type: String (max 9 chars)
      • Required: Yes.
    • taxIdFormatCode:
      • Type: String
      • Required: Yes. Options: (T) EIN or (S) SSN.
    • taxIdCertified:
      • Type: Boolean
      • Required: Yes. Options: true or false.
    • birthDate:
      • Type: Date (MM/DD/CCYY)
      • Required: Yes.
    • gender:
      • Type: String (max 1 char)
      • Optional. Options: “F”, “M”.
    • driversLicenseNumber, driversLicenseState:
      • Type: String
      • Optional.
    • mothersMaidenName:
      • Type: String (max 40 chars)
      • Optional.
    • deceased, deceased date, disabled, bankruptcy, foreignCitizen, livingInForeignCountry, causedLoss, activeMilitary, insuranceEligible, creditUnionEmployee:
      • Type: String/Boolean, Date
      • Optional: Most have default values (e.g., disabled=false, insuranceEligible=true).
    • employerCode:
      • Type: String (max 4 chars)
      • Optional.
    • address:
      • Type: address object
      • Required: Yes.
    • info:
      • Type: info object
      • Optional: Contains relationshipToPrimaryEntityAttribute, mobileAccess (default ‘N’), deathPayoutPercentage.
    • phones:
      • Type: List of phones objects
      • Required: Yes, one number is required.
    • securityQuestion:
      • Type: securityQuestion object
      • Optional: Contains question (String, max 4 chars) and answer (String, max 32 chars) attributes.
    • addresses:
      • Type: List of addresses objects
      • Optional: For informational addresses other than primary.

4.5. User Defined Fields Information (userDefinedFields)

User Defined Fields are credit union defined fields used to track and store information.

  • Recommendation: FLEX recommends speaking to the credit union to determine if they use any user defined fields when opening a certificate.
  • Attributes:
    • fieldNumber01 – fieldNumber08:
      • Type: String
      • Description: Allows up to 38 alphanumeric characters.
      • Optional.
    • fieldNumber09 – fieldNumber11:
      • Type: Number
      • Description: Used as an amount or balance field, allows up to 11 numeric characters (positive and negative).
      • Optional.
    • fieldNumber12 – fieldNumber14:
      • Type: Number
      • Description: Allows up to 6 characters.
      • Optional.
    • fieldNumber15:
      • Type: Number
      • Description: Used as an alternative SSN field (formats as 999-99-9999), allows up to 9 numeric characters.
      • Optional.
    • fieldNumber16:
      • Type: Number
      • Description: Used as an alternative phone number field (formats as 999-999-9999), allows up to 10 numeric characters.
      • Optional.
    • fieldNumber17:
      • Type: Number
      • Description: Used as an alternative amount field (formats as 99,999,999,999), allows up to 11 numeric characters.
      • Optional.
  • Note: Field descriptions are credit union defined and vary per installation. Confirm usage with the credit union.

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

FLEX provides information within the 500 HTTP Status Code errors in API Service responses to assist with troubleshooting.

  • Troubleshooting: Once an error is corrected, the request should be attempted again.
  • Common Causes: Most errors stem from invalid attribute values or values not configured in the credit union database. Some messages are triggered by preset conditions to ensure data integrity.
  • Recommendation: FLEX recommends providing the error message directly to the credit union for troubleshooting, as they are typically familiar with the messages and how to correct the data.
  • Common Error Messages:
    • “Internal server error – All suffixes for certificate type J7 and account number 797979 are in use.”
      • Result: The Certificate Type has no available suffixes/subaccounts.
      • Action: Credit union needs to update FLEX Certificate Type configuration with more subaccount values.
    • “Internal server error – Certificate Type ZZ is not defined.”
      • Result: Invalid or undefined Certificate Type code in the credit union database.
      • Action: Verify the product code value is correct.
    • “Account Number 1001429 is not valid.”
      • Result: Invalid account number.
      • Action: Verify the account number is correct.
    • “java.lang.RuntimeException: certificateNumber cannot exceed total length of 5 with 0 decimals (135001).”
      • Result: certificateNumber value exceeds five characters.
      • Action: Adjust the value to be five characters or less.
    • “Certificate Type C2 not valid for suffix 8200.”
      • Result: Invalid suffix/subaccount value for the Certificate Type.
      • Action: Adjust the suffix/subaccount value.
    • “java.lang.RuntimeException: openingTeller cannot exceed 4 characters.”
      • Result: openingTeller field has too many characters.
      • Action: Value cannot exceed four characters and must be valid in credit union’s Teller Configurations.
    • “java.lang.RuntimeException: suffixReceivingDividend cannot exceed total length of 3 with 0 decimals (1001).”
      • Result: suffixReceivingDividend field has too many characters.
      • Action: suffixReceivingDividend field cannot exceed three characters.
    • “org.hibernate.exception.GenericJDBCException: could not insert: [com.cmcflex.persistenceobjects.suffix.CertificateSuffix]”
      • Result: The Original Balance amount value exceeds nine characters.
      • Action: Adjust the Original Balance value.
    • “Open new certificate failed due to the following errors: The Open Date and Last Dividend Calculation Date should match\n.”
      • Result: Open Date and Last Dividend Calculation Date do not match.
      • Action: Adjust the dates to be the same.
    • “Open new certificate failed due to the following errors: The Open Date and Last Accrual Date should match\n.”
      • Result: Open Date and Last Dividend/Accrual Date do not match.
      • Action: Adjust the dates to be the same.
    • “Open new certificate failed due to the following errors: Joint Owners are not allowed for this certificate group\n.”
      • Result: Some certificate types do not allow joint owners.
      • Action: Remove the joint owner reference.