FLEXBridge Internet Banking Service API: Technical Documentation

FLEXBridge FLEXBridge FLEXBridge Internet Banking Service API: Technical Documentation

This document provides a comprehensive guide to the FLEXBridge Internet Banking Service API, detailing its functionalities, how to utilize its various endpoints, and important considerations for FLEX credit union users. This API is designed to streamline the management of Internet Banking Profiles within your FLEX core system.

1. Introduction to Internet Banking Service API

The Internet Banking Service API is a vital component of the FLEXBridge System, specifically managing processes for retrieving and updating Internet Banking Profiles. It is built as a RESTful API, incorporating built-in authentication, and handles all data in JSON format.

2. Key Functions of the Internet Banking Service API

The FLEXBridge Internet Banking Service API provides a range of functions to manage member and account information related to Internet Banking Profiles:

  • Retrieval Functions:
    • Retrieve Profile by Tax ID Only: Displays a list of all Internet Banking Profiles linked to a specific Tax ID.
    • Retrieve Profile by Tax ID and Account Number.
    • Retrieve Profile by Username.
  • Profile Management Functions:
    • Create an Internet Banking Profile.
    • Reactivate Disabled Account.
    • Add New Security Contact to Profile: Existing contacts can be retrieved before adding new ones.
  • Security Management Functions:
    • Clear Member’s High-Risk Security Options: This requires the member to re-enroll upon their next login.
    • Reactivate Profile and Reset High-Risk Security: This forces the member to re-enroll in high-risk security upon their next login.
    • Reset Account Authentication When Username or Password Has Been Forgotten: This also requires the member to re-enroll upon their next login.
    • Replace an Internet Banking Profile Password: This directly resets the password for an Internet Banking Profile.

3. Understanding FLEX Internet Banking User Profiles

FLEX configures Internet Banking Profiles in two distinct ways: Account Based or User Based.

  • Initial Setup: When a credit union transitions to the FLEX core system, all existing Member Internet Banking Profiles are initially set up as Account Based profiles.
  • Conversion: Credit unions can then convert Member accounts to User Based profiles as needed.

3.1. Account Based Profiles

  • Definition: An Account Based profile is tied directly to a Member’s account number.
  • Access: All users for that specific account must use the same username and password to access Internet Banking.

3.2. User Based Profiles

  • Definition: A User Based profile is linked to a single Member by their Tax ID.
  • Access Example: For an account with a Primary Member, Joint Owner, and Authorized Signer, each individual will have their separate username and password to access the account via Internet Banking.

3.3. Important Considerations Before Profile Changes

  • Verification: FLEX strongly recommends confirming Member and profile verification before making any Internet Banking Profile changes.
  • Responsibility: Any incorrect action or update is the responsibility of the credit union to correct.
  • Historical Naming: Historically, FLEX referred to Internet Banking Profiles as FLEX Teller Users (FTUsers). You may still see references to FTUser in objects and attributes within the documentation.

4. API Endpoints: Requests, Object Types & Attributes

This section details the various API endpoints available for managing Internet Banking Profiles.

4.1. Retrieve Internet Banking Profile List

Use this endpoint to retrieve a list of Internet Banking Profiles associated with a specific Tax ID.

  • Endpoint URL Example:
    • https://example.com/api/ftuser/list/123456789
    • https://{URL_ADDRESS}/api/ftuser/list/{TAX_ID}
  • HTTP Method: GET
  • Request Parameter:
    • {TAX_ID}:
      • Type: String
      • Description: Individual’s Tax ID (maximum 9 characters).
      • Required: Yes.
    • suppresserror:
      • Type: Boolean
      • Description: An optional filter to suppress the HTTPS 500 error when no profiles are found.
        • true: Suppresses the 500 error and returns a blank “ftusers” object.
        • false: The HTTPS 500 message will still occur if no profiles are found.
      • Required: No.
      • Example with filter: https://example.com/api/ftuser/list/123456789?suppresserror=true
  • Error Message Handling:
    • If no profile is found, the service responds with “message”: “No profiles found with that SSN”.
    • This 500 error message can be suppressed using the suppresserror filter.
    • When suppressed (suppresserror=true), the response will contain an empty “ftusers” array: { “ftusers”: [] }.
  • Response Object Type:
    • ftusers: A list object containing all matching Internet Banking Profiles linked to the Tax ID.

4.2. Retrieve Internet Banking Profile by Username

Use this endpoint to retrieve an Internet Banking Profile by Username when the account number or Tax ID is unknown. The response includes Tax ID information for further inquiries.

  • Endpoint URL Example:
    • https://example.com/api/ftuser/username/jsmith
    • https://{URL_ADDRESS}/api/ftuser/username/{USER_NAME}
  • HTTP Method: GET
  • Request Parameter:
    • {USER_NAME}:
      • Type: String
      • Description: Username for lookup (maximum 16 characters).
      • Required: Yes.
  • Note: The credit union can change an individual’s Username at any time.
  • Response Object Type:
    • ftuser: An object containing the Internet Banking Profile information.

4.3. Retrieve Internet Banking User Profile by Tax ID and Account Number

This endpoint allows you to retrieve an Internet Banking Profile using both Tax ID and Account Number.

  • Endpoint URL Example:
    • https://example.com/api/ftuser/123456789/123500
    • https://{URL_ADDRESS}/api/ftuser/{TAX_ID}/{ACCOUNT_NUMBER}
  • HTTP Method: GET
  • Request Parameters:
    • {TAX_ID}:
      • Type: String
      • Description: Individual’s Tax ID (maximum 9 characters).
      • Required: Yes.
    • {ACCOUNT_NUMBER}:
      • Type: Number
      • Description: Member account number (maximum 9 characters).
      • Required: Yes.
  • Response Object Type:
    • ftuser: An object containing the Internet Banking Profile information.

4.4. Create an Internet Banking Profile

Use this endpoint to create a new Internet Banking Profile for a credit union member. FLEX recommends creating all new profiles as Account Based.

  • Endpoint URL Example:
    • https://exampleurl.com/api/ftuser/create?tellerID=77&workstation=QP
    • https://{URL_ADDRESS}/api/ftuser/create?tellerID={TELLER_ID}&workstation={WORKSTATION_ID}
  • HTTP Method: POST
  • Request Parameters (URL):
    • tellerID:
      • Type: String
      • Description: Teller ID for the request (maximum 4 characters).
      • Required: Optional.
    • workstation:
      • Type: String
      • Description: Workstation ID for the request (maximum 10 characters). Note: The parameter name was updated from workstationId or workstationID to workstation as of March 2021.
      • Required: Optional.
  • JSON Body Attributes (to create a profile):
    • recordCode:
      • Type: String
      • Description: Indicates if the profile is Account (A) or User Based (any other code or blank). FLEX recommends A for new profiles.
      • Required: Optional (default is “A” if included).
    • ssn:
      • Type: Number
      • Description: Tax ID (maximum 9 characters).
      • Required: Yes.
    • userName:
      • Type: String
      • Description: Internet Banking Profile username (maximum 16 characters).
      • Required: Yes.
    • firstAccountNumber:
      • Type: Number
      • Description: Account number displayed first on login (maximum 9 characters).
      • Required: Yes.
    • activeUser:
      • Type: Boolean
      • Description: true or false (internal tracking field).
      • Required: Optional.
    • dateActivated:
      • Type: Date
      • Description: Profile activation date (MM/DD/CCYY). API will populate current system date if not included.
      • Required: Optional.
    • disabled:
      • Type: Boolean
      • Description: true or false.
      • Required: Optional.
    • reasonDisabled:
      • Type: String
      • Description: Reason if disabled (maximum 80 characters).
      • Required: Optional.
    • dateDisabled:
      • Type: Date
      • Description: Profile disabled date (MM/DD/CCYY).
      • Required: Optional.
    • mobileUser:
      • Type: Boolean
      • Description: true or false.
      • Required: Optional.
    • requirePasswordChange:
      • Type: Boolean
      • Description: true or false.
      • Required: Optional.
    • contacts:
      • Type: List
      • Description: List of security contacts.
      • Required: Yes.
      • Nested contacts attributes:
        • label: String (e.g., “Main Email”) (maximum 20 characters). Required.
        • address: String (email address) (maximum 128 characters). Required.
        • sequenceNumber: Number (FLEX assigned, start at 1 if included) (maximum 2 characters). Optional.
  • Sample JSON Body:

{

  “recordCode”: “A”,

  “ssn”: 454110001,

  “userName”: “Pore12146”,

  “firstAccountNumber”: 12146,

  “activeUser”: true,

  “dateActivated”: “06/04/2021”,

  “disabled”: false,

  “reasonDisabled”: “”,

  “mobileUser”: false,

  “requirePasswordChange”: true,

  “contacts”: [

    {

      “label”: “Main Email”,

      “address”: “robert.tporemski@testgmail.com”,

      “sequenceNumber”: 1

    }

  ]

}

  • Response Attribute:
    • success: Boolean (indicates if the request was successful).

4.5. Add Additional Security Contacts to Internet Banking Profile

This endpoint is used to add more security contacts to an existing Internet Banking Profile. This contact information is crucial for password resets and other security options.

  • Endpoint URL Example:
    • https://example.com/api/ftuser/username/jsmith/addcontact?tellerID=9898&workstation=QQ
    • https://{URL_ADDRESS}/api/ftuser/username/{USER_NAME}/addcontact?tellerID={TELLER_ID}&workstation={WORKSTATION_ID}
  • HTTP Method: POST
  • Request Parameters (URL):
    • {USER_NAME}:
      • Type: String
      • Description: Username for the contact (maximum 16 characters).
      • Required: Yes.
    • tellerID: Optional Teller ID.
    • workstation: Optional Workstation ID.
  • JSON Body Attributes: Note: The AddContactData object header has been removed as of March 2021.
    • label:
      • Type: String
      • Description: Label for the email contact (e.g., personal, work) (maximum 20 characters).
      • Required: Yes.
    • emailAddress:
      • Type: String
      • Description: The email address (maximum 128 characters). Note: The attribute name changed from address to emailAddress as of March 2021 to ensure data populates correctly.
      • Required: Yes.
  • Sample JSON Body:

{

  “label”: “test2”,

  “emailAddress”: “test2@test.com”

}

  • Response Attribute:
    • success: Boolean.

4.6. Reactivate Disabled Internet Banking Profile

Use this endpoint to reactivate an Internet Banking Profile that has been disabled.

  • Endpoint URL Example:
    • https://example.com/api/ftuser/username/jsmith/reactivate?tellerID=A4G2&workstation=AZ
    • https://{URL_ADDRESS}/api/ftuser/username/{USER_NAME}/reactivate?tellerID={TELLER_ID}&workstation={WORKSTATION_ID}
  • HTTP Method: POST
  • Request Parameters (URL):
    • {USER_NAME}: Required Username.
    • tellerID: Optional Teller ID.
    • workstation: Optional Workstation ID.
  • JSON Body: Requires an empty JSON Body ({}).
  • Response Attribute:
    • success: Boolean.

4.7. Clear High-Risk Security for Internet Banking Profile

This endpoint allows you to reset an individual’s challenge question, secret image, or secret words without reactivating the Internet Banking profile.

  • Endpoint URL Example:
    • https://example.com/api/ftuser/username/jsmith/resetsecurity?tellerID=A4G2&workstation=AZ
    • https://{URL_ADDRESS}/api/ftuser/username/{USER_NAME}/resetsecurity?tellerID={TELLER_ID}&workstation={WORKSTATION_ID}
  • HTTP Method: POST
  • Request Parameters (URL):
    • {USER_NAME}: Required Username.
    • tellerID: Optional Teller ID.
    • workstation: Optional Workstation ID.
  • JSON Body: Requires an empty JSON Body ({}).
  • Response Attribute:
    • success: Boolean.

4.8. Reset High-Risk Security and Reactivate Profile

Use this endpoint to reset an individual’s challenge question, secret image, or secret words AND reactivate their Internet Banking Profile.

  • Endpoint URL Example:
    • https://example.com/api/ftuser/username/jsmith/reset?tellerID=A4G2&workstation=AZ
    • https://{URL_ADDRESS}/api/ftuser/username/{USER_NAME}/reset?tellerID={TELLER_ID}&workstation={WORKSTATION_ID}
  • HTTP Method: POST
  • Request Parameters (URL):
    • {USER_NAME}: Required Username.
    • tellerID: Optional Teller ID.
    • workstation: Optional Workstation ID.
  • JSON Body: Requires an empty JSON Body ({}).
  • Response Attribute:
    • success: Boolean.

4.9. Force Password Change for Internet Banking Profile

This endpoint forces an Internet Banking password change. A security contact must be present on the profile for a successful reset.

  • Endpoint URL Example:
    • https://example.com/api/modifyPassword?tellerID=9898&workstation=QQ
    • https://{URL_ADDRESS}/api/ftuser/modifyPassword?tellerID={TELLER_ID}&workstation={WORKSTATION_ID}
  • HTTP Method: POST
  • Request Parameters (URL):
    • tellerID: Optional User/Teller ID involved (maximum 4 characters).
    • workstation: Optional Workstation ID involved (maximum 10 characters).
  • JSON Body Attributes: Note: The PasswordData object header was removed from the modifyPassword endpoint as of March 2021.
    • username:
      • Type: String
      • Description: Username involved, case sensitive (maximum 16 characters).
      • Required: Yes.
    • currentPassword:
      • Type: String
      • Description: Current password (maximum 128 characters).
      • Required: Yes.
    • newPassword:
      • Type: String
      • Description: New password to replace current (maximum 128 characters).
      • Required: Yes.
    • allowPasswordToExpire: Boolean.
    • provideExpirationWarning: Boolean.
    • passwordDaysToNotify: Number.
    • passwordExpirationInterval: Number.
  • Sample JSON Body:

{

  “username”: “Pwalker”,

  “currentPassword”: “FasterDriver@5252”,

  “newPassword”: “FasterDriver@8989”,

  “allowPasswordToExpire”: false,

  “provideExpirationWarning”: false,

  “passwordDaysToNotify”: 10,

  “passwordExpirationInterval”: 90

}

  • Response Attribute:
    • success: Boolean.

4.10. Replace an Internet Banking Password

This endpoint is used to replace a Member’s current password when their current password is unknown.

  • Endpoint URL Example:
    • https://example.com/api/replacePassword?tellerID=9898&workstation=QQ
    • https://{BASE_URL}/api/ftuser/replacePassword?tellerID={TELLER_ID}&workstation={WORKSTATION_ID}
  • HTTP Method: POST
  • Request Parameters (URL):
    • tellerID: Optional User/Teller ID involved (maximum 4 characters).
    • workstation: Optional Workstation ID involved (maximum 10 characters).
  • JSON Body Attributes:
    • username:
      • Type: String
      • Description: Username involved (maximum 16 characters).
      • Required: Yes.
    • newPassword:
      • Type: String
      • Description: Password to replace the current (maximum 128 characters).
      • Required: Yes.
  • Sample JSON Body:

{

  “username”: “jsmith”,

  “newPassword”: “test123@password”

}

  • Response Attribute:
    • success: Boolean.

5. Object References

This section details the common object types returned by the Internet Banking Service API and their attributes.

5.1. ftuser and ftusers Objects

These objects contain the core Internet Banking Profile information.

  • recordCode:
    • Type: String
    • Description: Indicates if the profile is Account Based (A) or User Based (any other code or blank).
    • Max Length: 1 character.
  • ssn:
    • Type: String
    • Description: Tax ID associated with the profile.
    • Max Length: 9 characters.
  • userName:
    • Type: String
    • Description: Internet Banking Profile username.
    • Max Length: 16 characters.
  • firstAccountNumber:
    • Type: Number
    • Description: Account number displayed first when a user logs in. For User Based profiles, this can be any accessible account; for Account Based, it should be the Primary account number.
    • Max Length: 9 characters.
  • activeUser:
    • Type: Boolean
    • Description: true if active; an internal credit union tracking field.
  • dateActivated:
    • Type: Date
    • Description: Profile activation date (MM/DD/CCYY).
  • disabled:
    • Type: Boolean
    • Description: true if profile is disabled.
  • reasonDisabled:
    • Type: String
    • Description: Reason the profile was disabled.
    • Max Length: 80 characters.
  • dateDisabled:
    • Type: Date
    • Description: Profile disabled date (MM/DD/CCYY).
  • mobileUser:
    • Type: Boolean
    • Description: true if the profile is a mobile account user.
  • contacts:
    • Type: List
    • Description: A list of security contacts used for “forgot password” and other security features.

5.2. contacts Object (Nested)

This object defines the structure of security contact information.

  • label:
    • Type: String
    • Description: Label for the email contact (e.g., “personal”, “work”).
    • Max Length: 20 characters.
  • address:
    • Type: String
    • Description: Email address.
    • Max Length: 128 characters.
  • sequenceNumber:
    • Type: Number
    • Description: FLEX assigned sequence number for an email contact record.
    • Max Length: 2 characters.

6. HTTPS Status Code 500 Errors and Troubleshooting

FLEX has enhanced the 500 HTTP Status Code errors in the API Service responses to assist with troubleshooting. Most errors occur due to invalid attribute values or values not present in the credit union’s database configuration. Some errors are triggered by preset conditions to ensure data integrity.

FLEX recommends providing the error message to the credit union for troubleshooting.

Here are common 500 error messages and their meanings:

  • “message”: “Not authorized to replace passwords.”
    • Reason: The Teller ID used in the request is not authorized to maintain Internet Banking passwords.
    • Resolution: Adjust the teller’s authorization in FLEX (under the FTPSWD Security Program Profile), or use a different Teller ID for the request.
  • “message”: “Internal server error – Unable to find user”
    • Reason: The username provided in the request is invalid or does not exist in the database.
  • “message”: “The value provided for the current password is incorrect.”
    • Reason: The current password value supplied for Replace or Force password changes is incorrect.
  • “Username [Username] is already being used”
    • Reason: Occurs when attempting to create a profile with a username that already exists in the credit union database.
    • Resolution: A different profile name is required.
  • “message”: “No profiles found with that SSN”
    • Reason: Results from an Internet Banking Profile search by Tax ID where the value is invalid.
    • Resolution: Review and resubmit the request with a valid Tax ID.
  • “message”: “Account number must be greater than zero”
    • Reason: Occurs when trying to add an Internet Banking Profile, but the “firstAccountNumber” attribute is set to zero.
    • Resolution: Enter a valid, existing account number for the Member.
  • “message”: “Contact label is required”
    • Reason: The “label” attribute is missing under the “contacts” object when creating an Internet Banking Profile. This attribute is required.
  • “message”: “Contact address is required”
    • Reason: The “address” attribute is missing under the “contacts” object when creating an Internet Banking Profile. This attribute is required.
  • “Please provide label for contact email address”
    • Reason: The “label” attribute is missing under the “contacts” object when adding an additional Internet Banking Security Profile. This attribute is required.
  • “Please provide a valid email address”
    • Reason: The “emailAddress” attribute is missing in the request JSON data when adding a profile contact. This attribute is required.
  • “message”: “A matching email address already exists for this user”
    • Reason: Occurs when trying to add a profile contact, but the email already exists for that user’s profile.
    • Resolution: Provide a different email address.

7. Document Revisions

This section highlights key updates and adjustments made to the Internet Banking Service API documentation.

7.1. Updates as of January 2022

  • New Endpoints/Attributes:
    • The URL filter parameter suppresserror has been added to the Retrieve Internet Banking Profile List endpoint. When true, it suppresses the HTTPS 500 error when a profile cannot be located, returning a blank “ftusers” object instead.
  • Removed Items: None explicitly listed for Jan 2022 updates.

7.2. Updates as of March 2021

  • Adjustments Made:
    • The word “truncated” was changed to “maximum” to better reflect how the API handles data fields with excessive characters.
    • The URL Header Parameter workstationId (or workstationID) was changed to workstation. Using the old parameter name will nullify it and lead to request errors if the value is required.
    • The URL Header Parameter tellerId was changed to tellerID. Using the old parameter name will nullify it and could lead to request errors.
    • The object “AddContactData” was removed from the JSON Body request for adding new security contacts; only the attributes listed under that section are needed.
    • The attribute “address” under the Add Contact Data JSON Body was changed to emailAddress to ensure data populates correctly.
  • New Endpoints/Attributes:
    • A new endpoint was added to create an Internet Banking Profile for new or existing Members.
  • Removed Items:
    • The object header “PasswordData” was removed from the modifyPassword endpoint, as it is no longer needed in the JSON Body data.

Confidentiality Notice

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.

b