Quick Start

This guide takes you from zero to a connected consumer with a full debt profile, and shows you how to read the capabilities matrix to see what else you can do with each liability listed in their profile.

Leverage our sandbox and test users to see it in action.

We'll walk through it with Christy Jenoval, Spinwheel's default sandbox test user (date of birth 1967-06-08). She carries multiple credit cards, student loans, auto loans, home loans, and miscellaneous liabilities, so a single walkthrough exercises most of the API surface.

The whole flow is three calls:

1. Connect a user via SMS
2. Verify the one-time passcode
3. Order a Debt Profile — the response includes everything: liabilities and the capabilities matrix

Before You Start

Get your sandbox API key from the developer portal: https://developer.spinwheel.io/

You're also responsible for capturing user consent before the first call, and displaying the required disclosure language to the user. For the SMS connect flow, here’s the exact wording below, per the docs:

"By continuing you agree to the Spinwheel End User Agreement. Further, you are providing “written instructions” to Spinwheel Solutions, Inc. authorizing it to obtain your credit profile from any consumer reporting agency."

Record the timestamp of that consent as consentTimestamp. It must be less than 24 hours old when you send it. See Why User Consent Is Critical for consent requirements across Spinwheel’s other Connect methods.

Step 1: Connect a User via SMS

📘 Reference: Connect a User via SMS

Post the user's phone number, date of birth, and a unique extUserId that identifies that user in your own system.

Spinwheel texts the user a one-time passcode that expires in 5 minutes. If you need to resend, please be sure to send no more than one request per 30 seconds per phone number.

For this guide, use any valid U.S. mobile number along with Christy Jenoval's date of birth, 1967-06-08.

Save the userId from the successful response — every other call in this guide, starting with verifying the passcode in Step 2, needs it.

Step 2: Verify the Passcode

📘 Reference: Verify an SMS Connection

Submit the code that the user received. Note that the userId returned from Step 1 goes in the path.

Spinwheel runs its verification checks synchronously and returns the status of the newly connected user. Once this succeeds, the user is connected and ready for everything else on the platform.

Step 3: Order a Debt Profile

📘 Reference: Request a Debt Profile

Once the user is connected, you can order their debt profile. This is what pulls the credit report/score and populates their liabilities.

Step 4: Read the Capabilities Matrix

This is the step that makes everything after it predictable.

Every liability in the response carries a capabilities object telling you exactly which additional services are available for that specific account before you attempt anything.

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

Capabilities vary by liability type and by institution. One credit card may support both real-time balance and APR refreshes while another supports only the balance.

This information will help you design your user experience based on what the matrix returns — show it, flag it, or filter it out — so a consumer never runs into a failed action.

What’s Next

Now that you have connected a user and have their debt profile and associated capabilities matrix in hand, you're ready to act on individual liabilities.

• Real-Time Liability Data: Get the current balance, APR, or payoff amount on an account as of the moment you ask, rather than the last reporting cycle.
• Debt Profile Refresh Subscriptions: Keep a debt profile current over time without managing repeat refreshes yourself.
• Payments: Submit payments against liabilities where capabilities.payments.billPayment is SUPPORTED.
• Credit Card Brand Assets: Retrieve a card's real program name and card art so your product shows the card the consumer recognizes. Note: Christy Jenoval's data isn't supported on this endpoint. To test Card Brand Assets, use Tara Misu (DOB 1990-09-20) as the test user.