Spinwheel Multi-Bureau Support

Overview

The multi-bureau endpoint (/v1/users/{userId}/debtProfile) gives you access to credit reports and scores from multiple bureaus with automatic failover. It’s designed to replace the Equifax-only endpoint while staying backwards compatible.

How to Use the Multi-Bureau Endpoint

🎯 Choose Your Bureau Strategy

Let Spinwheel handle failover:
Omit the sourceBureau in your request. Spinwheel will use your default bureau, and in the rare event of an outage, it will failover to a secondary bureau. We’ll assist you with the default bureau configuration during onboarding. If you need to update it later, please reach out to our support team.
Manually control bureau selection:
Explicitly set sourceBureauparameter to the bureau of your choice`. This gives you full control, however, it also prevents automatic failover during credit bureau outages.

Notes on refreshing:

Refresh requests must use the bureau the user was originally connected with.
If you don’t provide a bureau explicitly, Spinwheel will handle it automatically and send the request to your configured default bureau.
For repetitive refreshes in general, subscriptions are recommended to ensure ongoing updates across bureaus.

📝 Build Your Request

You may request both a credit report and a credit score in the same call, or only one of them.

To request both, include both creditReport and creditScore objects.
To request only one, simply omit the other object from the request body.

Example Request - Report and Score

POST /v1/users/{userId}/debtProfile
{
  "creditReport": {
    "sourceBureau": "TransUnion",
    "type": "1
  },
  "creditScore": {
    "sourceBureau": "TransUnion",
    "model": "VANTAGE_SCORE_3_0"
  }
}

Example Request - Only a Score

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

🔄 Migration Guide

To migrate from the POST /v1/users/{userId}/creditProfile/equifax endpoint.

Switch URL
/creditProfile/equifax → /debtProfile
Update request body
- Add sourceBureau if you want to force Equifax or TransUnion
- Change type to "1_BUREAU.FULL"
- Change model to "VANTAGE_SCORE_3_0"

The response is fully backwards compatible with your existing flow. However, it includes some new fields:

{
  "status": {
    "code": 200,
    "desc": "success"
  },
  "data": {
    "userId": "c3cf91d9-21c8-413c-82bf-286d6e05593e",
    "extUserId": "7ca88034-29ff-4402-a1a8-b371aea4b457",
    "creditReports": [
      {
 +      "sourceBureau": "TransUnion",
 +      "type": "1_BUREAU.FULL",
        "id": "0af305ab-75b7-4f34-9112-089813a00216",
        "profile": {...},
        "inquiries": [
          {
            "inquirerName": "Reilly, McLaughlin and Gulgowski",
            "inquiryDate": "2020-01-01",
            "inquirerIndustryCode": "ZB",
            "purposeType": "HARD",
            "sourceBureau": "TransUnion",
            "bureauSubscriberCode": "244ZB00566"
          }
        ],
        "bankruptcies": [...],
        "creditScoreDetails": [
          {
            "reportedDate": "2024-03-04",
            "creditScore": 691,
            "sourceBureau": "TransUnion",
  +         "model": "VANTAGE_SCORE_3_0",
            "modelName": "EquifaxVantageScore3.0",
            "factors": [...]
          }
        ],
        "creditAttributes": [...],
        "updatedOn": 1719584251805,
        "createdOn": 1719584251805
      }
],
     ...
}

creditReports[].sourceBureau → bureau the report came from  
creditReports[].type → report type requested  
creditReports[].creditScoreDetails[].model → scoring model used