FLEXBridge Share Service API: Comprehensive Guide

The Share Service API, a key component of FLEXBridge, provides essential functions for managing member share suffixes, which include account types like checking, draft, and money market. This API allows for the creation of secondary member share suffixes and, when applicable, their closure. It includes various objects and attributes to define detailed information about the share itself, as well as associated parties such as Joint Owners, Authorized Signers, and Beneficiaries.

FLEXBridge operates as a RESTful API and requires built-in authentication attached to every request as HTTP request headers. For details on adding authentication headers, refer to the FLEX Core System documentation. The Share Service API is available for FLEX Releases 8.04 and up.

Key Functions Available

The FLEXBridge Share Service API offers the following primary functions for managing secondary share suffixes:

• opensharesuffix: This is a quick open option that uses a limited set of attributes. Successful requests may require the credit union to maintain additional information within FLEX.
• opennewshare: This is an expanded option for opening a secondary share suffix. It supports various attributes, overdrafting information, and allows for the inclusion of Joint Owners, Beneficiaries, and Authorized Signers within the request.
• closesharesuffix: This option is used to close an existing member share suffix, provided it has a zero balance.

Opening a Share Suffix – Quick Open (opensharesuffix)

This endpoint facilitates the creation of a new share suffix for an existing member account using a limited set of attributes, such as share suffix, share type, account number, and description.

Endpoint Path Information:

• Method: POST.
• REST URL: https://{BASE_URL}/api/accountmanagement/opensharesuffix?tellerID={TELLER_ID}&workstation={WORKSTATION_ID}.
• Parameters:
  • opensharesuffix: Required URL path to open a share on an existing member account.
  • tellerID: Optional credit union-defined Teller ID.
  • workstation: Optional credit union-defined Workstation ID.

JSON Request Attributes:

• accountNumber:
  • Type: Number
  • Description: Member account number (maximum 9 characters).
  • Required: Yes.
• shareType:
  • Type: String
  • Description: Credit union-defined share type (maximum 3 characters).
  • Required: Yes.
• suffixNumber:
  • Type: Number
  • Description: Credit union-defined suffix value. If not included, FLEX assigns the next available value. (maximum 3 characters).
  • Required: No (Optional).
• description:
  • Type: String
  • Description: Description of the share. If left blank, the system adds the credit union default (maximum 16 characters).
  • Required: No (Optional).

Example Open Share Suffix Request:

https://{BASE_URL}/api/accountmanagement/opensharesuffix?tellerID=77&workstation=QP

JSON Body:

{

  “accountNumber”:12345,

  “shareType”:”CK”,

  “description”:”Premier Checking”

}

Open Share Suffix Response Information:

• success:
  • Type: Boolean
  • Description: Indicates if the request was successful. An exception occurs if there’s an error.
• suffixNumber:
  • Type: Number
  • Description: The suffix number used for the added share suffix.
• description:
  • Type: String
  • Description: Description for the added share suffix.

Example Open Share Suffix Response:

{

  “success”: true,

  “suffixNumber”:125,

  “description”:”Premier Checking”

}

Opening a New Share Suffix – Expanded Options (opennewshare)

This endpoint creates a new share suffix for an existing member account with additional share attributes. It also allows for the addition of Joint Owners, Authorized Signers, and/or Beneficiaries within the same request.

Endpoint Path Information:

• Method: POST.
• REST URL: https://{BASE_URL}/api/accountmanagement/opennewshare?tellerID={TELLER_ID}&workstation={WORKSTATION_ID}.
• Parameters:
  • opennewshare: Required URL path to open a share on an existing member account.
  • tellerID: Optional credit union-defined Teller ID.
  • workstation: Optional credit union-defined Workstation ID.

Available Share JSON Request Objects:

• share:
  • Type: share
  • Description: Contains essential share information (e.g., member account number, share subaccount suffix, share type).
  • Required: Yes (in JSON for all share exports).
• jointOwners:
  • Type: List of jointOwners
  • Description: A list of Joint Owners to be added to the secondary subaccount.
  • Required: No (Optional).
• authorizedSigners:
  • Type: List of authorizedSigners
  • Description: A list of Authorized Signers to be added to the secondary subaccount.
  • Required: No (Optional).
• beneficiaries:
  • Type: List of beneficiaries
  • Description: A list of Beneficiaries to be added to the secondary subaccount.
  • Required: No (Optional).

Open New Share Response Information:

• suffixNumber:
  • Type: Number
  • Description: The suffix number used for the added share suffix.
• description:
  • Type: String
  • Description: Description for the added share suffix.

Example Open New Share Response:

{

  “suffixNumber”:400,

  “description”:”Premier Checking”

}

Closing a Share Suffix (closesharesuffix)

This endpoint is used to close an existing member share suffix. The suffix balance must be zero at the time of the request.

Endpoint Path Information:

• Method: POST.
• REST URL: https://{BASE_URL}/api/accountmanagement/closesharesuffix?tellerID={TELLER_ID}&workstation={WORKSTATION_ID}.
• Parameters:
  • closesharesuffix: Required URL path to close an existing share on a member account.
  • tellerID: Optional credit union-defined Teller ID.
  • workstation: Optional credit union-defined Workstation ID.

JSON Request Attributes:

• accountNumber:
  • Type: Number
  • Description: Account number.
  • Required: Yes.
• suffixNumber:
  • Type: Number
  • Description: Suffix number.
  • Required: Yes.
• reasonCode:
  • Type: String
  • Description: Credit union-defined close reason (maximum 3 characters).
  • Required: No (Optional in the JSON Body).
  • Note: The attribute name was changed from “closeReasonCode” to “reasonCode” as of October 1, 2022, for new integrations where third parties close member share subaccounts.

Example Close Share Suffix Request:

https://{BASE_URL}/api/accountmanagement/closesharesuffix?tellerID=77&workstation=QP

JSON Body:

{

  “accountNumber”:12345,

  “suffixNumber”:15,

  “reasonCode”:”E”

}

Close Share Suffix Response Information:

• success:
  • Type: Boolean
  • Description: Indicates if the request was successful. An exception occurs if there was an error.

Example Close Share Suffix Response:

{

  “success”: true

}

Object References

This section details the various objects and their attributes used within the Share Service API, particularly with the opennewshare endpoint.

1. Share Object

The Share object contains essential share information when adding a new share suffix via the opennewshare path.

Key Attributes:

• shareType: Credit union defined share type value (max 2 characters). Required.
• suffixNumber: Credit union defined suffix value. FLEX will assign the next available if not included (max 3 characters). Optional.
• description: Description of base share (max 16 characters). Optional.
• openedDate: Open date of base share (MM/DD/CCYY format). Optional.
• insuranceEligible: Boolean, indicates if individual is insurance eligible (true/false). Optional.
• courtesyPayAllowed:
  • Type: Boolean (adjusted from String in September 2022 and March 2021 revisions).
  • Description: Is courtesy pay allowed? Valid Options: true or false.
  • Note: FLEXBridge accepts “Y” or “N” (string) until July 1, 2024, for older integrations.
  • Optional.
• defaultOverDraftCode:
  • Type: Number
  • Description: Overdraft code. Valid options: 0 (no overdrafting), 1 (transfer from share account only), 2 (transfer from loan account only), 3 (transfer from shares, then loan), 4 (transfer from loan, then shares), 5 (use transfer/overdraft file).
  • Optional.
• defaultOverdraftShareSuffix: Share suffix for overdrafting. Required if defaultOverDraftCode is 1, 3, or 4.
• defaultOverdraftLoanSuffix: Loan suffix for overdrafting. Required if defaultOverDraftCode is 2, 3, or 4.
• overdraftInformationList:
  • Type: List of overdraftInformationList
  • Description: Member’s preferred overdraft sequence. Required when defaultOverDraftCode equals 5.
  • Optional/Required.
• userDefinedFields:
  • Type: userDefinedFields object
  • Description: Credit union-defined fields for additional information not in the FLEX Core Database.
  • Optional (in JSON data).

2. Share User Defined Fields (` fields. Optional.

• UDF12 – UDF14: Number, allows up to 6 characters, mainly used as additional date tracking fields (no slashes). Optional.
• UDF15: Number, allows up to 9 numeric characters, used as alternative SSN field (creates 999-99-9999 format). Optional.
• `UDF1 or set to zero.

defaultOverDraftCode Values:

• 0: No Overdraft (or omit attribute).
• 1: Share Only. Requires defaultOverdraftShareSuffix.
• 2: Loan Only. Requires defaultOverdraftLoanSuffix.
• 3: Share and Loan, but Share First. Requires defaultOverdraftShareSuffix and defaultOverdraftLoanSuffix5**.

Key Attributes:

• sequenceNumber: Indicates sequence order for overdrafting (always starts with 1) (max 1 character). Optional/Required.
• overdraftAccountNumber: Account number associated to overdrafting sequence (max 9 characters). Optional/Required.
• overdraftSuffix: Suffix number associated to overdrafting sequence (max 3 characters). Optional/Required.

5. Joint1, 16, 86].

*   **Description**: Does the Joint Owner have the rights of survivorship? Valid Options: `true` or `false`.

*   **Note**: FLEX is aware of the misspelling (“rightOfSurviorship”) and it should be used as shown; a correction will occur in a future version.

*   **Note**: FLEXBridge accepts “Y” or “N” (string) until July 1, 2024, for older integrations.

*   Optional.

• relationshipToPrimaryEntity: Joint Owner relationship to Primary Member (max 4 characters). Optional.
• emailAddress: Joint Owner email address (max 128 characters). Optional.
• suffixList:
  • Type: suffixList
  • Description: Indicates Joint Owner’s account/suffix access. [] or grants full access to all account suffixes. grants access only to the base share suffix or 01 suffix. (max 1 character).
  • Optional.
• mobileAccess: Is Joint Owner allowed internet banking access? Valid Options: Y (Yes), N (No), or Null. Optional.

Joint Owner Entity Object: Contains various Joint Owner information including phone numbers, additional addresses, and other member flags.

• Key Attributes: firstName, lastName (Required). taxId, taxIdFormatCode, taxIdCertified, birthDate (Required). gender, driversLicenseNumber, mothersMaidenName, deceased, disabled, bankruptcy, activeMilitary, foreignCitizen, livingInforeignCountry, causedLoss, verifiedOFAC, creditUnionEmployee, phones (Required), addresses (Optional).
  • Note: The taxId attribute type was changed from String to Number as of March 2021.
  • Note: The deceased attribute type was changed from String to Boolean as of September 2022 and March 2021; valid options are true or false.

Joint Owner Address Object: Required in JSON data when creating a Joint Owner. Includes city, country, line1, state, zipcode (all Required).

Joint Owner Entity Phone Object: Required under the jointOwners object. Includes areaCode, number, type (all Required).

Joint Owner Entity Address Object: Allows for single or multiple secondary addresses for the Joint Owner. This object type is optional. Includes city, country, line1, state, zipcode (all Required).

6. Authorized Signer Information Object

The authorizedSigners object allows for the creation of single or multiple records linked to a member account.

Key Attributes:

• emailAddress (Optional).
• firstName, lastName (Required).
• taxId, taxIdFormatCode, taxIdCertified, birthDate (Required).
  • Note: The taxId attribute type was changed from String to Number as of March 2021.
• gender (Optional).
• suffixList: Indicates Authorized Signer’s account/suffix access. [] or grants full access. grants access only to the base share suffix. Optional.
• deceased:
  • Type: Boolean (adjusted from String in September 2022 and March 2021 revisions).
  • Description: Is Member deceased? Valid Options: true or false.
  • Optional.
• address: address object, required Authorized Signer physical mailing address.
• info: info object, indicates relationship to Primary Member and other flags. Optional.
• securityQuestion: securityQuestion object, Authorized Signer security information. Optional.
• phones: List of phones objects, required Authorized Signer phone number.
• addresses: List of addresses objects, Authorized Signer secondary address information. Optional.

Authorized Signer Address Object: Required in JSON data when an Authorized Signer is added. Includes city, country, line1, state, zipcode (all Required).

Authorized Signer Phone Number Object: Required. Includes areaCode, number, type (all Required).

**Authorized Signerbeneficiaries` object allows for the addition of single or multiple Beneficiaries to the account. This object is optional.

Key Attributes:

• firstName, lastName (Required).
• taxId, taxIdFormatCode, taxIdCertified, birthDate (Required).
  • Note: The taxId attribute type was changed from String to Number as of March 2021.
• gender (Optional).
• deceased:
  • Type: Boolean (adjusted from String in September 2022 and March 2021 revisions).
  • Description: Is Member deceased? Valid Options: true or false.
  • Optional.
• suffixList: Indicates Beneficiary account suffix access. 0 means access to all. Default for new accounts is 1 for base share suffix only. Consult credit union for specific handling. Optional.
• address: address object, required Beneficiary physical mailing address.
• phones: List of phones objects, required Beneficiary phone number information.
• addresses: List of addresses objects, Beneficiary secondary address information. Optional.
• info: info object, indicates relationship to Primary Member, mobile access, and death payout percentage. Optional.
• securityQuestion: securityQuestion object, indicates Beneficiary security information. Optional.

Beneficiary Address Object: Required in JSON data when a Beneficiary is created. Includes city, country, line1, state, zipcode (all Required).

Beneficiary Phone Number Object: Required. Includes areaCode, number, type (all Required).

Beneficiary Secondary Address Object: Optional, allows for single or multiple secondary addresses. Includes city, country, line1, state, zipcode (all Required).

Beneficiary Security Question Object: Optional, provides security information. Includes question, answer (both Optional).

Beneficiary Information (Info) Object: Optional, provides information like relationship to Primary account holder, mobile access flag, and deathPayoutPercentage.

Error Handling

FLEX has enhanced the 500 HTTP Status Code errors in the API Service responses to aid in troubleshooting. Most errors arise from invalid attribute values or values not present in credit union database configurations. It is recommended to provide the error message to the credit union for troubleshooting, as they are often familiar with these messages.

Common Error Messages:

• {“message”: “Internal server error – Share Suffix 280 already exists on Account 100799.”}:
  • Cause: The suffix value provided is already in use for the account.
  • Correction: Select another suffix value and retry the request.
• {“message”: “Internal server error – share type is required”}:
  • Cause: The Share Type value is blank or invalid.
  • Correction: Provide a valid Share Type value.
• {“message”: “Internal server error – Share Type not valid for suffix selected”}:
  • Cause: The suffix value is not assigned to the selected Share Type.
  • Correction: The credit union may need to add additional share suffixes to the type, or a different share type is required.
• {“message”: “Internal server error – Suffix 70 does not exist for Account 89891”}:
  • Cause: A Close Suffix request was made with an invalid suffix value.
  • Correction: Verify the suffix number.
• {“message”: “Internal server error – Suffix 3 should have zero current balance before closing”}:
  • Cause: A Close Suffix request was made for a suffix with a balance.
  • Correction: The credit union must adjust the suffix’s balance to zero before retrying the request.

Appendix

Type Groups (Share Group Codes)

These are FLEX-assigned Group Codes indicating the grouping description for the suffix.

• A = Auxiliary
• B = Base Share
• D = Draft
• E = Escrow
• I = IRA
• M = Money Market
• N = Roth IRA
• P = Educational IRA
• T = Roth Conversion IRA
• G = Health Savings

Relationship to Primary Member Examples

• AU = Aunt
• BO = Beneficial Owner
• BR = Brother
• BU = Business Owner
• CO = Cousin
• DA = Daughter
• FA = Father
• MO = Mother
• GRF = Grandfather
• GRM = Grandmother
• HU = Husband
• WI = Wife
• NIEC = Niece
• NEPH = Nephew
• OR = Other Relative
• SI = Sister
• SO = Son
• UN = Uncle

Charge Off Codes

• R -7** – Unpaid balance reported as a loss by the creditor

Account Suffix Access Information

The suffix attribute (under the share object) is a system field that designates account suffix access.

• Primary Account Holder: Typically has total account suffix access, including all certificates of deposit, IRAs, share, and loan suffixes (attribute value 0).
• Joint Owner: Usually has access to all account shares suffixes, excluding IRAs. Suffix value will be 0 for full access or reflect specific suffix values like 1 or 115 for limited access.
• Authorized Signer: Access is defined by the credit union and depends on the account type (e.g., Individual or Business). Suffix value will be 0 for full access or reflect specific suffix values.
• Co-Borrower: Usually has access only to the account loan suffix they were assigned to. They typically do not have access to the account’s share suffixes.
• Beneficiary: Usually only has account access after the death of the Primary account holder. They typically have the least amount of account access, reflecting credit union industry standards. For new accounts, the default suffixList value is 1 for base share suffix only. Consult the credit union for handling beneficiary access. Beneficiary information is generally found via Tax ID searches.

Account suffix access is credit union-defined and can vary by institution. FLEX advises using the Suffix List attribute found in Account Detail search responses.