Building User Support Tools

In this guide, we will walk through how to utilize the Admin API to build integrations for your support team with your existing customer relationship management (CRM).

You most likely use an existing platform to manage your user support needs. This allows you to manage tickets, conversations, and ensure a high-level experience for your users. Rather than training your existing team to use an additional platform, use the Admin API to integrate back office operations directly into your current CRM platform.

We will simulate a simple user support integration and demonstrate how to use various Admin API endpoints to perform various actions.

If you’d like, we’ve also provided a companion video which follows the guide.

Prerequisites

To be successful, you will first need to authenticate and have a valid Access Token.

Take a look at the Authentication Quickstart for a walkthrough of how to authenticate.

Scenario

A Banno-powered financial institution uses a CRM as the interface for their user support team who handles all inbound support calls from their banking users.

1. A user calls in and the support agent needs to look up the user’s userID based on their email.
2. The support agent then needs to get additional user details based on the userID.
3. The support agent then wants to check the status of the user and unlock the account if necessary.
4. The support agent then can send the user a password reset email.

Requests

Based on the above scenario, we will now walk through each of the endpoints you would use to build your CRM integration.

GET /a/consumer-user-search/api/v0/institutions/{institutionId}/users

curl --request GET \
  --url 'https://banno.com/a/consumer-user-search/api/v0/institutions/[INSTITUTION_ID]/users?query=[USER EMAIL]' \
  --header 'authorization: Bearer [ACCESS_TOKEN]'

In this case, we are using the user’s email to look up their account at the financial institution.

Response

The consumer user search endpoint will return an array of JSON objects with users matching the query parameter.

{
  "users": [
    {
      "userId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
      "userActive": true,
      "primaryInstitutionUsername": "KathySmith",
      "primaryInstitutionId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
      "firstName": "Kathy",
      "middleInitial": "",
      "lastName": "Smith",
      "userAdded": "2022-01-21T16:45:47.118Z",
      "userModified": "2022-01-21T16:45:47.118Z",
      "email": "user@example.com",
      "userVerified": false,
      "businessName": null,
      "userType": "Individual",
      "reviewInstitutionId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
      "middleName": "string",
      "mobilePhoneNumber": "+15555551234",
      "maskedSsn": "null",
      "preferredName": null,
      "employeeStatus": "NE",
      "lastSeen": "2022-01-21T16:45:47.118Z"
    }
  ],
  "totalCount": 0
}

You can then use the response data to identify a userId (or multiple if the response returns more than 1 possible user).

GET /a/mobile/api/v0/institutions/{institutionId}/users/{userId}/details

curl --request GET \
  --url https://banno.com/a/mobile/api/v0/institutions/[INSTITUTION_ID]/users/[USER_ID]/details \
  --header 'authorization: Bearer [ACCESS_TOKEN]'

In this case, we are using the userID that we retrieved from the previous step to get more information about the user.

Response

The consumer user search endpoint will return an array of JSON objects with users matching the query parameter.

{
  "userId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
  "firstName": "string",
  "middleInitial": "string",
  "lastName": "string",
  "email": "user@example.com",
  "primaryInstitutionId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
  "primaryInstitutionUsername": "string",
  "userType": "Individual",
  "businessName": "string",
  "address": {
    "addressLineOne": "string",
    "addressLineTwo": "string",
    "city": "string",
    "state": "string",
    "zip": "string",
    "zipPlusFour": "string"
  },
  "abilities": {
    "rdc": true,
    "billPay": true,
    "accountToAccount": true,
    "schedulableTransfers": true,
    "separateBillPayAccounts": true,
    "externalAccounts": true,
    "payeeCreation": true,
    "p2pEnabled": true,
    "rdcOnboarddingEnabled": true,
    "paymentCardManagement": true,
    "rdcOnboardingByAccountsEnabled": true,
    "externalTransferInbound": true,
    "externalTransferOutbound": true,
    "memberToMemberTransfers": true,
    "billPayEnrollment": true,
    "zelle": true
  },
  "lastSeen": "2022-01-21T17:31:11.337Z",
  "userAdded": "2022-01-21T17:31:11.337Z",
  "phone": "string",
  "demographic": {
    "customerCode": "string",
    "customerImportance": "Yes",
    "customerDescription": "string",
    "gender": "Male",
    "birthday": "2000-01-01",
    "homeBranchId": "string",
    "educationLevel": "AssocDegree",
    "employerName": "string",
    "employeeTitle": "string",
    "netWorth": "string",
    "employeeData": "E",
    "lastUpdated": "2022-01-21T17:31:11.337Z"
  },
  "maskedSsn": "string",
  "lockedOutOfRSA": true,
  "netTellerId": "string",
  "customerId": "string",
  "memberNumber": "0000070000"
}

The response will provide the support agent with more details about the user; this could potentially be used for a simple verification step.

GET /a/consumer-status/api/v0/users/{userId}/status

curl --request GET \
  --url https://banno.com/a/consumer-status/api/v0/users/[USER_ID]/status \
  --header 'authorization: Bearer [ACCESS_TOKEN]'

We are again using the userID that we retrieved from the first step to check the status of the user to determine whether the account is locked or in a normal state.

Response

The status endpoint will return a JSON object with the user’s account status.

{
  "status": "Locked"
}

In this case, the user’s account is locked. Let’s enable the support agent to unlock the account.

PUT /a/consumer-status/api/v0/users/{userId}/status/locked

curl --request PUT \
  --url https://banno.com/a/consumer-status/api/v0/users/[USER_ID]/status/locked \
  --header 'authorization: Bearer [ACCESS_TOKEN]' \
  --header 'content-type: application/json' \
  --data '{"state": false}'

We are again using the userID that we retrieved from the first step to change the status of the user.

Response

If successful, the consumer status locked endpoint will only return a 204 No Content response to verify that the account was unlocked.

Finally, we will allow the support agent to send a password reset email to the user.

POST /a/password-reset/api/v0/institutions/{institutionId}/users/{userId}/password/reset

curl --request POST \
  --url https://banno.com/a/password-reset/api/institutions/[INSTITUTION_ID]/users/[USER_ID]/password/reset \
  --header 'authorization: Bearer [ACCESS_TOKEN]' \
  --header 'content-type: application/json' \
  --data '{"method": "email"}' 

We are using the same institutionId and userID from before to send the user a password reset email.

Response

The password reset endpoint will return an empty JSON object response.

{}

The user will receive an email with the password reset link.

Conclusion

Now that you have completed this walkthrough, you are ready to create your own integrations with your existing CRM platforms.

If you are interested in more detail on any of the endpoints, please visit our reference documentation for information.

Next steps

• Take a look at specific documentation in the API Reference.