Profile Enhancements

A bureau file is limited. It tells you what a lender reported on its last cycle — which can be weeks old by the time you see it, and says nothing about what's true on the account right now. Some integrations claim to close that gap and don't: partial institution coverage, silent failures, and stale caches that pass as "real time."

Spinwheel's refresh APIs are built to give you the current state of a liability, not a reporting cycle's worth of history. Different questions need different data, so we expose that as separate, purpose-built capabilities rather than one generic "refresh" button:

• Real-Time Balances: The current balance on a credit card, as of the moment you ask.
• Real-Time APR: The actual rate on the account today, not one inferred from statement data.
• Payoff Quotes: A good-through payoff figure for auto and student loans, direct from the servicer.

With our capability matrix, every one of these tells you upfront whether it's available for a given liability — supported, needs something from you, or not possible for that institution — before you spend a call finding out the hard way. No guessing, and no second request just to get the answer you could have had the first time.

Input requirements for refresh functions:

• Real-Time Balances: liabilityId(s)
• Refreshing Users: userId

All three capabilities share 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:

• realtimeBalance
• annualPercentageRate
• 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.

Supported capabilities return an availability of SUPPORTED, while unsupported capabilities return NOT_SUPPORTED along with a description, when applicable — so you always know which case you're in before you act.

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 — the refresh would be unsuccessful.

Requesting a Refresh

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.

• 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.
• 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.
• Retrieve a User: Following a COMPLETED 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

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

The sections below walk through each capability in detail — what makes it eligible, how to trigger it, and how to read the result.