New Liabilities Subscription
Overview
Spinwheel’s New Liability Subscription Service enables your platform to receive real-time notifications when new liability updates are available for your users. This ensures your users stay informed and your app remains proactive and responsive.
Key Benefits
✅ Real-Time Notifications for new liabilities
📅 Awareness to power reminders or triggers to fetch new user data
🔄 Easy Subscription Management via standardized APIs
Getting Started
Step 1: Subscribe to a New Liability update
Use the following endpoint to subscribe a user to new liability reported events:
POST /v1/users/{userId}/creditProfile/equifax/subscriptions/liabilities
Example Request Body:
[
{
subscriptionType: NEW_LIABILITIES,
},
]
If a subscription already exists, a 409 conflict will be returned.
Example Response Body:
{
"status": {
"code": 201,
"desc": "success"
},
"data": [
{
subscriptionType: NEW_LIABILITIES,
userId: {{uuid}},
subscriptionId: {{uuid}},
updatedOn: {{timestamp}}
createdOn: {{timestamp}}
}
]
}
Step 2 (Optional): Verify Active Subscriptions
To verify existing subscriptions or confirm that one has been successfully created, use:
GET /v1/users/{userId}/creditProfile/equifax/subscriptions/liabilities
If the user already has an active subscription, this endpoint will return that subscription to you.
Step 3: Handle Real-Time Webhook Notifications
Once a user is subscribed, Spinwheel will send webhook notifications whenever a new liability is reported on a user credit profile.
Sample Payload – NEW_LIABILITIES_REPORTED
{
"webhookId": "1714461341615-0",
"subscriptionId": "28ddf73b-bd93-4c06-afa5-fd4e3994d23f",
"eventType": "NEW_LIABILITIES_REPORTED",
"userId": "abc123",
"data": {
"creditCards": [
{
"creditCardId": "f6815836-0bcd-4b37-8f6c-5a0ad70360ff",
"displayName": "Mastercard",
"logoUrl": "http://d1z5aldt6j0m0y.cloudfront.net/e0044362-f6c6-4343-abf7-ae148c88082b.png",
"cardProfile": {
"creditCardNumberMasked": "123456******3456",
"accountOriginationDate": "2020-01-02T00:00:00.000Z",
"status": "OPEN",
"creditLimit": 500,
"accountRating": "1",
"liabilitySubtype": "CreditCard",
"debtType": "UNSECURED",
"availableCreditDerived": 243.57,
"accountOwnershipType": "INDIVIDUAL",
"termsFrequency": "MONTHLY",
"accountType": "REVOLVING",
"reportedDateWithFormat": {
"value": "2024-06-28",
"format": "YYYY-MM-DD"
},
"lastActivityDateWithFormat": {
"value": "2024-06-28",
"format": "YYYY-MM-DD"
},
"consumerDisputeStatus": "NOT_DISPUTED",
"derogatoryDataStatus": "NOT_DEROGATORY",
"reviewedInMonths": 12,
"collectionStatus": "NOT_IN_COLLECTION",
"chargeOffStatus": "NOT_CHARGED_OFF",
"accountTypeCode": "R",
"ecoaCode": "I",
"adverseRatingCount": 0,
"paymentHistory": {
"lastAssessedStatementDate": "2024-05-01",
"details": [
{
"date": "2024-05-01",
"description": "No data available for this period",
"code": "D"
},
{
"date": "2024-04-01",
"description": "No data available for this period",
"code": "D"
},
{
"date": "2024-03-01",
"description": "No data available for this period",
"code": "D"
},
{
"date": "2024-02-01",
"description": "No data available for this period",
"code": "D"
},
{
"date": "2024-01-01",
"description": "No data available for this period",
"code": "D"
},
{
"date": "2023-12-01",
"description": "No data available for this period",
"code": "D"
},
{
"date": "2023-11-01",
"description": "No data available for this period",
"code": "D"
},
{
"date": "2023-10-01",
"description": "No data available for this period",
"code": "D"
},
{
"date": "2023-09-01",
"description": "No data available for this period",
"code": "D"
},
{
"date": "2023-08-01",
"description": "The account is current",
"code": "0"
},
{
"date": "2023-07-01",
"description": "The account is current",
"code": "0"
},
{
"date": "2023-06-01",
"description": "The account is current",
"code": "0"
}
]
},
"limitType": "REGULAR",
"creditUtilization": 51.29
},
"balanceDetails": {
"outstandingBalance": 240,
"updatedOn": 1719532800000
},
"statementSummary": {
"statementBalance": 256.43,
"statementDateWithFormat": {
"value": "2024-06-28",
"format": "YYYY-MM-DD"
},
"minimumPaymentAmount": 100,
"lastPaymentDateWithFormat": {
"value": "2021-01",
"format": "YYYY-MM"
},
"dueDate": "2024-07-28T00:00:00.000Z",
"overduePeriod": "NOT_OVERDUE",
"updatedOn": 1719532800000
},
"capabilities": {
"payments": {
"billPayment": {
"availability": "SUPPORTED"
}
},
"data": {
"realtimeBalance": {
"availability": "SUPPORTED"
},
"statementSummary": {
"availability": "SUPPORTED"
}
}
},
"creditor": {
"industryType": "National credit card companies",
"industryCode": "ON",
"phoneNumber": "11708747346",
"originalName": "MASTERCARD",
"bureauSubscriberCode": "401ON02149",
"address": {
"addressLine1": "5396 NORTH REESE AVENUE",
"city": "FRESNO",
"state": "CA",
"zip": "93722"
}
},
"updatedOn": 1719584284061,
"createdOn": 1719584284061
}
]
}
}
The payload includes the new liabilities (across all liabilityTypes) that have been reported
Step 5: Unsubscribe users from the new liabilities subscription
You can delete existing subscriptions as needed—either to stop webhook notifications or to allow recreation of a new one (since only one subscription per type is allowed per liability).
Delete Subscription Endpoint
DELETE /v1/users/{userId}/creditProfile/equifax/subscriptions/liabilities
Example Request Body:
{
"subscriptionIds": ["your-subscription-id"]
}
Updated 1 day ago