Image Retrieval

In this guide, we’re going to explore how to fetch transaction images through our API.

Transaction images are images that are attached to specific transactions. They can be helpful in providing necessary context for a transaction.

There are two types of transaction images our API can fetch - user uploaded images, which are images a user associates with particular transactions, and check images, which are images obtained when users utilize remote check deposits.

We will illustrate simple methods to retrieve both types of transaction images using varied API endpoints.

Prerequisites

To be successful, you will first need to authenticate and have a valid Access Token. Take a look at the Authentication Quickstart (Command Line) for a walkthrough of how to authenticate.

After authenticating, you will also need to use the token to access the User ID (this is the sub key) – more documentation about tokens can be found in the Authentication Framework documentation. It’s worth noting that the Identity Token is separate from the Access Token.

Required OpenID Scopes

• https://api.banno.com/consumer/auth/transactions.detail.readonly
• https://api.banno.com/consumer/auth/transactions.images.readonly

Requests

As previously mentioned, there are two types of transaction images, user uploaded and check images - the process for retrieving both types of images starts the same, fetching transactions.

GET /users/{userId}/accounts/{accountId}/transactions

curl https://{CONSUMER_API_ENVIRONMENT}/a/consumer/api/{API_VERSION}/users/{userId}/accounts/{accountId}/transactions \
    -H "Authorization: Bearer {access_token}"

This endpoint requires the https://api.banno.com/consumer/auth/transactions.detail.readonly OpenID scope.

Parameters:

• userId: The User ID of the user you would like to access transactions for
• accountId: The Account ID that you would like to access transactions for

Response:

{
  ...
  "transactions": [
    {
      ...
      "id": "string",
      "userImageIds": [
        "string"
      ],
      "hasProviderImages": "boolean",
      ...
    }
  ],
  ...
}

This endpoint will return a JSON object, the target key that we will work with is transactions. The transactions key will contain an array of transactions.

Each transaction in the array will contain information about the transaction, however, we will specifically target 3 keys for the purpose of this guide.

1. id will be the transaction ID that we will use later
2. userImageIds, will be an array of any receipt and check image IDs (it will be a combination of both) associated with this transaction
3. hasProviderImages boolean will be true if there are check images.

Based on your needs there are now two paths for retrieving images, based on the type of image (check image and user image). Continue to the appropriate section below for the specific steps for each.

Retrieving Check Images

After accessing the list of transactions above, if a transaction has provider images (hasProviderImages is true), these are the steps to access them.

GET /users/{userId}/accounts/{accountId}/check-image/transaction/{transactionId}

curl https://{CONSUMER_API_ENVIRONMENT}/a/consumer/api/{API_VERSION}/users/{userId}/accounts/{accountId}/check-image/transaction/{transactionId} \
    -H "Authorization: Bearer {access_token}"

Parameters:

• userId: The User ID of the user you would like to access transactions for
• accountId: The Account ID that you would like to access transactions for
• transactionId: The transaction ID from the previous step (from a transaction where hasProviderImages is true)

{
  "checkImages": [
    {
      "id": "string",
      "checkNumber": "string",
      "amount": "string"
    }
  ]
}

The endpoint will return an array if any check images exist. The id will be different from the transaction ID, this will be used to fetch the image.

GET /users/{userId}/accounts/{accountId}/check-image/{transactionImageId}

curl https://{CONSUMER_API_ENVIRONMENT}/a/consumer/api/{API_VERSION}/users/{userId}/accounts/{accountId}/check-image/{transactionImageId}?side=front \
    -H "accept:image/png" \
    -H "Authorization: Bearer {access_token}"

This endpoint requires the https://api.banno.com/consumer/auth/transactions.images.readonly OpenID scope.

Parameters:

• userId: The User ID of the user you would like to access transactions for
• accountId: The Account ID that you would like to access transactions for
• transactionImageId: A specific check image ID from the previous step (an ID from the checkImageIds array)
• side: Specify which side of the check you would like an image for (front/back)

Response: A successful request will return a PNG image.

Retrieving User Images

GET /users/{userId}/accounts/{accountId}/transactions/{transactionId}/images/{imageId}

curl https://{CONSUMER_API_ENVIRONMENT}/a/consumer/api/{API_VERSION}/users/{userId}/accounts/{accountId}/transactions/{transactionId}/images/{imageId} \
    -H "Authorization: Bearer {access_token}"

This endpoint requires the https://api.banno.com/consumer/auth/transactions.images.readonly OpenID scope.

Parameters:

• userId: The User ID of the user you would like to access transactions for
• accountId: The Account ID that you would like to access transactions for
• transactionId: A specific transaction ID from the first step
• imageId: A specific image ID from the first step (an ID from the userImageIds array)

Response: A successful request will return a PNG image.

Next steps

Take a look at specific documentation in the API Reference.