🚧

Please be aware that the refresh user endpoint is a billable event for fetching a new credit report. Utilize your best judgement when calling this endpoint given that information.

Overview

To support the most up to date information for a user, we provide a function which will refresh the credit report data that is provided back with each /v1/users endpoint call. This endpoint is typically leveraged to evaluate if there are new tradelines for a user, or to fetch the latest credit report based information set, such as statementBalance, credit limit, credit score, etc.

Requesting a User Refresh

To request a user refresh, there are two endpoints that you should be aware to both kick the request off, as well as be aware of when the updated balance is then available for retrieval from /v1/users endpoint.

1. Refresh User - This endpoint will kick off the refresh functionality for the supplied userId to the API endpoint. Please be aware that for certain data providers, this initial call can complete synchronously instead of needing to proceed to step 2. Ensure that your implementation allows for COMPLETED to be returned from this endpoint.
2. Check User Refresh Status - Once the refresh request has been kicked off, you will want to monitor the status of the refresh transaction using this polling endpoint. User refreshes are typically a quick process, so the general recommendation would be to start polling after 5 seconds and in 5 second intervals. The three statuses are IN_PROGRESS, FAILED, COMPLETED
3. Retrieve User - Following a COMPLETED status for an individual user, you will call the retrieve user endpoint and any data that was available to be updated will be updated at that point. Be aware that creditors typically only report once per mont to the credit bureaus.

Recommended Refresh Cadence

As a general rule, we recommend to refresh the user once per month for use cases with an ongoing need to stay up to date with user liabilities. As noted, the creditors only report to the bureaus once per month and on different intervals.

If your use case has a need for ad-hoc refreshes intra-month, this can be supported but please reach out to your Spinwheel contact to review best practices before you proceed with this.