Connect

Connect a User - Phone

Changed on Nov 3, 2026

Connect a User that has already been pre-verified by phone number/SMS. Identify the user by date of birth, by legal first and last name as it appears on their credit file, or by the last four digits of their Social Security number. One of the three is required. This API requires Spinwheel Support approval to enable it before it can be used.

post/v1/users/connect/preverified/phoneNumber

Request

Base URL
https://sandbox-api.spinwheel.io
URL
https://sandbox-api.spinwheel.io/v1/users/connect/preverified/phoneNumber
Auth
- API key in header Authorization
- or API key in header Authorization

Request body

phoneNumberstring required

The phone number in E.164 format.

dateOfBirthstring

The date of birth. Formatted as YYYY-MM-DD. Supply one of dateOfBirth, firstName + lastName, or ssnLastFourDigits. If more than one is provided, dateOfBirth is used to resolve the identity and the others narrow the match.

firstNamestring

The user's legal first name, as it appears on their credit file. Must be sent together with lastName. One of dateOfBirth, firstName + lastName, or ssnLastFourDigits is required.

lastNamestring

The user's legal last name, as it appears on their credit file. Must be sent together with firstName. One of dateOfBirth, firstName + lastName, or ssnLastFourDigits is required.

ssnLastFourDigitsstring

The last four digits of the user's Social Security number. One of dateOfBirth, firstName + lastName, or ssnLastFourDigits is required.

userIdstring required

An existing userId to connect with. One of extUserId or userId is required.

extUserIdstring required

A unique external ID for the user. One of extUserId or userId is required.

Example request

{
  "phoneNumber": "+14155552671",
  "dateOfBirth": "2000-01-01",
  "firstName": "Christy",
  "lastName": "Jenoval",
  "ssnLastFourDigits": "1234",
  "userId": "7519c55d-68aa-4b21-b580-d70d4fb4f2ab",
  "extUserId": "1166d9a1-5718-4443-a677-cc40627c5575",
  "audit": {
    "consentTimestamp": "2025-03-15T14:30:00Z",
    "tosVersion": "v1.1",
    "tosLanguage": "en",
    "consentType": "WRITTEN",
    "verificationDate": "2023-01-15",
    "identityVerifiedTimestamp": "2025-03-15T14:30:00Z",
    "userConsentDate": "2023-01-15",
    "verificationType": "SMS"
  }
}

Response

Success

Example response

{
  "status": {
    "code": 200,
    "desc": "success",
    "messages": [
      {
        "desc": "Example description"
      }
    ]
  },
  "data": {
    "userId": "9226245b-4a4c-48e2-a8cb-9a0e114ed4af",
    "extUserId": "e3119f3a-ac24-4fa8-839b-c9db75848453",
    "connectionId": "e3119f3a-ac24-4fa8-839b-c9db75848453",
    "connectionStatus": "IN_PROGRESS",
    "profile": {
      "addresses": [
        {
          "addressLine1": "123 Main Street",
          "addressLine2": "Unit 208",
          "city": "San Francisco",
          "state": "CA",
          "zip": "90211",
          "zipExtension": "1234"
        }
      ]
    }
  }
}

Changes

Nov 3, 2026aa032469622f Revision changes
- breaking
  the response property ////// became optional for the status
- breaking
  the response property ////// became optional for the status
- warning
  added the new FAILED enum value to the / response property for the response status
- warning
  added the new IN_PROGRESS enum value to the / response property for the response status
- warning
  added the new SUCCESS enum value to the / response property for the response status
- info
  added the new optional request property
- info
  added the new optional request property
- info
  added the new optional request property
- info
  the request property became optional
- info
  added the non-success response with the status

Operation history