Profile

Overview

Spinwheel’s Debt Profile is a snapshot of every liability a consumer holds — sourced from a credit report — and the foundation on which Spinwheel builds everything else.

You get a complete, permissioned picture of a consumer's liabilities: debts, balances, borrowing costs, and account relationships — unified into a single standardized view. What’s more, you can trust Spinwheel from a data integration standpoint because we’re committed to meeting requirements and regulatory standards to operate as a Consumer Reporting Agency.

Once a user is connected, ordering their Debt Profile is what turns a verified identity into an addressable set of liability accounts. Every other capability in the platform such as real-time balances, payoff quotes, card brand and art, and embedded payments operates on the liabilities this call establishes.

📘 API Reference: Request a Debt Profile

Using Multi-Bureau Support

Credit bureaus go down. Data feeds lag. Formats change without warning. When your credit infrastructure depends on a single bureau, any one of these becomes your outage.

Spinwheel’s multi-bureau endpoint gives you credit reports and scores backed by multiple bureaus, with automatic failover built in. If your primary source has an issue, Spinwheel routes around it — no code changes, no downtime, no explaining to your users why the report didn't come through.

Today, we support both TransUnion and Equifax.

Choose Your Bureau Strategy

• Let Spinwheel handle it: Omit sourceBureau and Spinwheel routes to your configured default bureau, automatically failing over to a secondary bureau in the rare event of an outage.
• Control it yourself: Set sourceBureau explicitly for full control. You lose automatic failover in exchange for certainty about which bureau served a given report.
  You can request a credit report, a credit score, or both in the same call — just include or omit the creditReport and creditScore objects accordingly. Credit scores are available as VantageScore 3.0, FICO 4, or FICO 8, with more models being added.

A few constraints:

• FICO scores require separate approval and are only available through TransUnion. Talk to your Spinwheel Customer Success Manager to get enabled before requesting one.
• Future refresh requests must use the bureau the user was originally connected with.

Notes on refreshing:

• Refresh requests must use the bureau used for the original user connection..
• If you don't specify a bureau, Spinwheel routes the request to your configured default automatically, applying the same failover protection.
• For repeat refreshes, Debt Profile subscriptions are recommended to keep data current across bureaus without extra work on your end.

Example Request: Report and Score

POST /v1/users/USERID/debtProfile
{"creditReport": { "sourceBureau": "TransUnion", "type": "1_BUREAU.FULL" }, "creditScore": { "sourceBureau": "TransUnion", "model": "VANTAGE_SCORE_3_0" }}

Example Request: Score Only

POST /v1/users/USERID/debtProfile {"creditScore": { "sourceBureau": "TransUnion", "model": "VANTAGE_SCORE_3_0" }}

As always, to order or access unmasked account numbers or other secure data, use the secure endpoint.

Don't have permissions for the secure endpoint? Contact your Spinwheel Customer Success representative for details on requirements and access.

Summary vs. Tradeline Detail

The response gives you two levels of information on the same data:

• Summary level: Liabilities rolled up by category (credit cards, personal loans, auto loans, mortgages, and more) and by secured vs. unsecured debt, plus aggregate attributes like overall credit utilization.
• Tradeline level: Every individual account's own detail: balance, credit limit, payment history, statement balance, per-card credit utilization, and account-specific fields like a student loan's loanType (public, private, or unverified).

This structure means you're never forced to parse every tradeline just to answer a simple question like "does this consumer have any auto loans?". Depth is there the moment you need it.

The Type of Data You Get

Liabilities are grouped into creditCards, autoLoans, studentLoans, homeLoans, personalLoans, and miscellaneousLiabilities. Each carries bureau-reported detail — balances, limits, payment history, bankruptcies, and inquiries — alongside enrichment Spinwheel layers on top:

• Credit Scores: VantageScore 3.0, FICO 4, FICO 8, with contributing factors.
• Account Numbers: In the case you utilize the full account number for a given liability in your flows, we make the full account number available to consume via the profile data.
• Credit Card Name & Art: A consumer's real card program and card art, without needing sensitive account details.
• Vehicle Attributes: Make, model, trim, and year, from a VIN or license plate.
• Real-time balances and payoff summaries: Layered on top of the bureau data via the capabilities matrix above.

The result is one standardized view instead of stitching together a bureau feed, a card-art vendor, and a vehicle-data provider yourself.

The Capabilities Matrix

Every liability comes back with a capabilities object that tells you exactly what else you can do with each account, before you try:

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

This matrix will show you 3 states to design around:

---

Our capability matrix ensures that enhanced liability intelligence is predictable instead of a trial-and-error exercise. You can check the matrix once per liability, and every downstream decision — show a refresh button, offer a payoff quote, enable bill pay — follows directly from it.

📘 Reference: Real-Time Liability Data · Embedded Payments

Subscriptions vs. Ad Hoc Reports

There are two ways to keep a Debt Profile current, and they solve different problems:

• Ad hoc: Call POST /v1/users/{userId}/debtProfile whenever you need a fresh pull.

• Subscriptions: Enroll a user’s Debt Profile in automatic weekly or monthly refreshes. Spinwheel will keep the profile current without the need for you to manage repeat calls.
  
  Note: A user needs an ad hoc Debt Profile pulled first before you can enroll them in a subscription. You can't subscribe to someone who doesn't have a profile yet.
  
  For best results, you should set up the subscription shortly after that first pull, so the next refresh lands a week or a month later rather than immediately. Once a subscription refresh completes, retrieve the updated data with Get User Profile.
  
  Subscriptions notify you via webhook SUBSCRIPTION_ACTIVATED, SUBSCRIPTION_FAILED, USER_CREDIT_PROFILE_TRANSACTION, USER_CREDIT_PROFILE_TRANSACTION_FAILED) instead of requiring you to poll.
  
  📘 Reference: Debt Profile Refresh Subscriptions

  Where to Go Next

• Multi-Bureau Support: Migrate from the legacy Equifax-only endpoint, and secure-endpoint access for unmasked account numbers.

• Real-Time Liability Data: Refresh balances and payoff summaries on individual liabilities.

• Debt Profile Refresh Subscriptions: Set up recurring refreshes.

• Credit Card Brand Assets: Retrieve card name and art.
  Webhooks: Subscribe to profile and subscription events instead of polling.

• Webhooks: Subscribe to profile and subscription events instead of polling.

Profile Enhancements: Credit Card Brand Assets

Consumers don't think of their cards as "Visa ending in 4242." They think "my Chase Sapphire" or "my Freedom card." When your product shows a generic bank name and stock icon instead, it reads as a step removed from the accounts people actually use — and that gap shows up in the numbers, not just the user experience.

Spinwheel’s Credit Card Brand Assets let you retrieve a card's real program name (e.g., Chase Sapphire Preferred) and its actual card art, so your product shows the exact card consumers use. That precision does real work:

• Increased top-of-wallet behavior: People engage more with the card they recognize. Showing the real name and art keeps that card top of mind in your product the same way it is in their wallet.
• Higher conversion on offers: Recommendations and offers land better when they're tied to a specific, recognizable card rather than a generic "credit card" placeholder. Consumers can tell the offer is actually relevant to what they hold.
• Stronger trust: Accurate brand detail signals that your product actually understands a consumer’s accounts. Generic art and placeholder names do the opposite, even when the underlying data is correct.

Two Ways to Retrieve Assets

Via Id: For consumers already connected with Spinwheel, fetch all of their credit card brand assets with their userID or get specific brand assets by specifying the creditCardId.

Va Card Details: For users not already connected via Spinwheel APIs, bring your own card data (BYOD). Send credit card details, such as the credit card number, to retrieve the brand assets.

Examples of Assets Returned

Credit Card Name: "Chase Freedom Visa Signature"

Credit Card Art

Profile Enhancements: Real-Time Data

A bureau file is a snapshot. 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.

Profile Subscriptions

Profile Subscriptions allow you to periodically refresh a consumer’s credit data so that their Spinwheel Profile reflects the latest information available from the credit bureau.

A Profile refresh can identify new or updated tradelines and refresh available information such as statement balances, credit limits, credit scores, and other liability details.

Profile Subscriptions are useful for applications that have an ongoing need to maintain current information about a user's liabilities without initiating individual refreshes manually.

Note: Profile Subscriptions generate a billable event each time a new credit report is fetched for the subscribed user. Consider the appropriate refresh cadence for your use case before creating a subscription.

Setting Up a Profile Subscription

The Profile Subscription workflow consists of three primary steps:

1. Create a subscription: Use Subscribe a User to Debt Profile Refreshes to subscribe a user to recurring Profile refreshes. Configure the applicable bureau and supported refresh cadence when creating the subscription.
2. Monitor refresh activity: Subscribe to the Profile Subscription webhooks below to receive updates when the subscription is established and when subsequent Profile refreshes succeed or fail.
3. Retrieve the updated Profile: After a refresh completes, use Retrieve a User to retrieve the user's Profile with any newly available or updated data.

You can also use Get User Refresh Subscriptions to retrieve the details of a user's existing subscription.

📘Subscribe to Profile Subscription Webhooks

Configure the following webhooks when integrating with Profile Subscriptions:

• SUBSCRIPTION_ACTIVATED
• SUBSCRIPTION_FAILED
• USER_CREDIT_PROFILE_TRANSACTION
• USER_CREDIT_PROFILE_TRANSACTION_FAILED

SUBSCRIPTION_ACTIVATED and SUBSCRIPTION_FAILED communicate the result of establishing the subscription. The transaction webhooks communicate the results of subsequent Profile refreshes.

See the Webhooks Guide and Create a Webhook for configuration details.

Recommended Refresh Cadence

For use cases that require ongoing access to current liability information, Spinwheel generally recommends a monthly refresh cadence. Creditors typically report updated account information to credit bureaus approximately once per month and may report at different times throughout the month.

A weekly cadence may also be available when supported by your agreement with Spinwheel.

If your use case requires more frequent or ad hoc Profile refreshes within a month, contact your Spinwheel representative to determine the appropriate approach.

Changing a Subscription's Cadence

The cadence of an existing Profile Subscription cannot be modified directly.

To change the cadence:

• Delete the existing subscription using our API Reference Guide.
• Create a new subscription with the desired cadence.