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

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.

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

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.