Connect API - SMS

The following guide will provide guidance on connecting users with our SMS OTP flow via API.

Before getting started

As you look to integrate with the Connect API, please note that you will be responsible for displaying the Spinwheel End User Agreement, along with capturing consent to proceed with a connection to the platform. This Connect API will trigger an OTP via SMS with an expiration of 5 minutes. This is necessary to ensure that the user is still run through the proper confirmation checks and validity scoring functions that Spinwheel performs natively within the Drop-in Modules.

πŸ“˜

Subscribe to the USER_LIABILITIES_CONNECTED webhook to stay updated

Check out the webhook here!

Steps

We have designed this API to enable flexibility and customization to the process, all while ensuring we can securely connect users with the highest connection rates. The process of connecting users is broken out into the following key steps as noted below.

The steps are as follows:

  1. Send a connect request via a POST to /v1/users/connect/sms/ with the end user's phone number, date of birth, and a unique extUserId that represents that user in your system.
  2. Upon the submission of the information at the first step, the user will be texted an OTP with a unique code to be presented back via the API
  3. The code texted to the user is submitted back to Spinwheel via /v1/users/connect/sms/verify
  4. Once the code is sent, Spinwheel will perform synchronous checks and provide the status back of the newly connected user.
  5. If you are looking to pull a user's liability information, you will need to call to order a credit report via [/v1/users/{userId}/creditProfile/equifax]

As with the Drop-in Modules, the connected users will have their information pulled into their user object which can be accessed from the /v1/users endpoint.

Recipe

For a coded example of the implementation, please refer to the Connect API - SMS Recipe provided below

Sandbox User Data

User identities have been set up in the sandbox environment providing a variety of scenarios that you can use to test your integration against.

Default users need any valid US phone number plus date of birth; for specific debt profiles, refer to the accompanying table.

Date of birthDescription
1990-01-01This user has debt totaling $5,000 distributed across an auto loan, home loan, student loan, and two credit cards.
1990-03-01This user has debt totaling $20,000 distributed across an auto loan, home loan, student loan, two credit cards, a personal loan, and a miscellaneous liability.
1990-04-10This user has debt totaling $25,000, distributed across an auto loan, home loan, student loan, two credit cards, a personal loan, and a miscellaneous liability.
1990-04-12This user has debt totaling $30,000, distributed across auto loans, a home loan, a student loan, two credit cards, a personal loan, and miscellaneous liabilities.

πŸ“˜

Fallback

In a small number of cases, we won't be able to verify a user's identity using only a phone number and date of birth. In those cases, we recommend that you fall back to the KBA connection API instead.