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.

1. Switch URL
   /creditProfile/equifax → /debtProfile
2. 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

🛑 Deprecation Notice

The old /v1/users/{userId}/creditProfile/equifax endpoint will remain available for now but will be removed from documentation. Ample notice will be provided before it is officially retired.