Overview

The Real-Time Data APIs enable you to request the most up-to-date information available for an individual liability as of the COMPLETED call. Depending on the liability type and lender, this may include:

• Credit Card Balances
• Credit Card Annual Percentage Rates (APRs)
• Payoff Quotes

Real-time data retrieval ensures you are working with the most current financial data available and prevents you from needing to solely rely on statement data as reported to the bureaus.

All real-time liability refreshes follow the same asynchronous workflow:

1. Determine whether the requested capability is supported.
2. Initiate a refresh.
3. Wait for the refresh to complete.
4. Retrieve the updated liability data.

Real-time data retrieval is not always supported for every liability or financial institution. Before initiating a refresh, always perform an eligibility check to verify that the requested liability supports the desired real-time capability.

Determining Eligibility

Every liability exposes a capabilities object via the /v1/users endpoint within a capabilities matrix that indicates which real-time operations are supported. Depending on the liability type, this may include:

• annualPercentageRate
• realTimeBalance
• payOffSummary

Not every liability supports every capability. For example, a credit card may support both real-time balance and APR refreshes while another may only support the real-time credit card balance.

The following examples demonstrate how supported and unsupported real-time liability capabilities are represented in the capabilities matrix. Supported capabilities return an availability of SUPPORTED, while unsupported capabilities return NOT_SUPPORTED along with a description, when applicable.

Supported Example:

{
  "capabilities": {
    "payments": {
      "billPayment": {
        "availability": "SUPPORTED"
      }
    },
    "data": {
      "realtimeBalance": {
        "availability": "SUPPORTED"
      },
      "annualPercentageRate": {
        "availability": "SUPPORTED"
      },
      "payOffSummary": {
        "availability": "SUPPORTED"
      }
    }
  }
}

Unsupported Example:

{
  "capabilities": {
    "payments": {
      "billPayment": {
        "availability": "SUPPORTED"
      }
    },
    "data": {
      "realtimeBalance": {
        "availability": "NOT_SUPPORTED",
        "description": "CLOSED_ACCOUNT_NO_BALANCE"
      },
      "annualPercentageRate": {
        "availability": "NOT_SUPPORTED",
        "description": "INSTITUTION_NOT_SUPPORTED"
      },
      "payOffSummary": {
        "availability": "NOT_SUPPORTED"
      }
    }
  }
}

If availability is NOT_SUPPORTED, do not attempt a refresh as a refresh would be unsuccessful.

Requesting Real-Time Liability Data Updates

To request real-time liability data, initiate a request for the desired liability and capability, then listen for webhook updates to determine when the data is available from the /v1/users endpoint.

1. Request Real-Time Liability Data - Initiates the refresh for the supplied liability and requested capability. Only request liabilities and capabilities that are marked as SUPPORTED.
2. Check Refresh Status - Since the refresh can take some time, we recommend using this webhook to be notified as soon as this process is finished. The three statuses are IN_PROGRESS, FAILED, COMPLETED
3. Retrieve a User - Following aCOMPLETED status, call the Retrieve User endpoint to access the updated liability data. Depending on the requested capability, refreshed data with an updatedOn timestamp may be returned in:
   • data.creditCards[].balanceDetails
   • data.creditCards[].aprs
   • data.autoLoans[].payoffSummary
   • data.studentLoans[].payoffSummary

Real-Time Liability Data Request Statuses

Below are the statuses you can receive from the refresh webhook:

Unsupported Liabilities

If we are unable to support ra requested real-time data capability for a liability, you will see one of the following objects in the capabilities matrix for that liability. This will provide additional detail on why that capability is unavailable.

Real-Time Balances

"realtimeBalance": {
  "availability": "NOT_SUPPORTED",
  "description": "CLOSED_ACCOUNT_NO_BALANCE"
}

"realtimeBalance": {
  "availability": "FIELD_ERROR",
  "fieldErrors": [
    {
      "field": "CREDIT_CARD_NUMBER",
      "error": "NOT_PRESENT"
    }
  ]
}

"realtimeBalance": {
  "availability": "NOT_SUPPORTED",
  "description": "REFRESH_EXHAUSTED",
  "nextEligibleRefreshOn": 1709960400000
}

"realtimeBalance": {
  "availability": "NOT_SUPPORTED",
  "description": "NOT_PRIMARY_ACCOUNT_HOLDER"
}

"realtimeBalance": {
  "availability": "NOT_SUPPORTED",
  "description": "ACCOUNT_TERMINATED"
}

"realtimeBalance": {
  "availability": "NOT_SUPPORTED",
  "description": "INSTITUTION_NOT_SUPPORTED"
}

APRs

"annualPercentageRate": {
  "availability": "NOT_SUPPORTED",
  "description": "INSTITUTION_NOT_SUPPORTED"
}

"annualPercentageRate": {
	"availability": "NOT_SUPPORTED",
	"description": "REFRESH_EXHAUSTED",
	"nextEligibleRefreshOn": 1770000000000
}

Payoff Quotes

"payOffSummary": {
  "availability": "NOT_SUPPORTED"
}

Implementation Checklist

Before going live, confirm that your integration does the following:

• Reads capability availability, from the latest GET /v1/users response.
• Skips liabilities where refresh is not SUPPORTED.
• Sends REALTIME_BALANCE, ANNUAL_PERCENTAGE_RATE, or PAYOFF_SUMMARY only for eligible liabilities.
• Stores or logs extRequestId and refreshTransactionId for troubleshooting.
• Handles both COMPLETED and FAILED webhook statuses.
• Calls GET /v1/users after a successful refresh to retrieve the updated liability data.