Risk Layer: Enhanced Fraud Protection & User Corrections
Overview
While our standard flows provide sufficient fraud protection, sometimes customers prefer a deeper understanding of a user's risk profile. This addition allows partners to:
- Surface risk and identity details directly when connecting an individual via Spinwheel's apis.
- Have customized, fine grained control over evaluating end user eligibility.
- Meet internal or regulatory requirements for identity verification (e.g., CIP/KYC).
- Collect and re-submit updated Personally Identifiable Information (PII) from end users all while ensuring strong fraud protection.
The result is stronger fraud prevention, higher confidence in user identity, and improved conversion rates.
Surfacing Risk Using Connect Flows
Once enabled, certain user connect flows (SMS and Pre-verified) will return an additional riskAssessments object encompassing risk and identity insights. More details on the content of these can be found here.
Relavant Endpoint & Additions
POST /v1/users/:userId/connect/sms/verify
POST /v1/users/:userId/connect/preverified/phoneNumber
"riskAssessments": [
{
"vendor": "PROVE",
"version": "trust/v2",
"details": { /* trust signals */ }
},
{
"vendor": "PROVE",
"version": "identity/v2",
"details": { /* identity signals */ }
}
]
Enhanced User Verification and Making Corrections
In addition to the insights provided during the pre-verified phone or sms connections, a subsequent call can be made to retrieve additional risk information or to verify corrections provided by the end user. A full specification can be found here.
Note: This functionality has associated business requirements, and must be enabled for your organization before use.
{
"connectionStatus": "SUCCESS",
"profile": { /* verified profile */ },
"riskAssessments": [
{
"vendor": "PROVE",
"version": "verify/v2",
"details": { /* CIP, KYC, AML, confidence signals */ }
}
]
}
Scope
These features are currently supported across the following flows:
- Connect a user via SMS
- Connect a user with a pre-verified phone number
Flow
Step 1: Connect the User
Connect the user using either the SMS or Pre-Verified (Phone) endpoint. These flows establish the initial user profile and return available risk assessments.
Step 2: Evaluate Risk Eligibility
Review the returned risk assessments and determine whether the user meets your organization’s risk and policy requirements.
If the user does not meet your eligibility criteria, please fall back to an alternative verification strategy, such as knowledge-based authentication (KBA). The standard errors apply as seen on the existing Connect SMS or Pre-Verified (Phone) endpoints when there is a failure to identify the user.
Step 3: Confirm Profile Details with the User
Please present the returned user profile to the end user for review and confirmation.
Step 3a: Collect Corrections (Optional)
If the user identifies inaccuracies, collect the corrected information and update the user profile accordingly.
Step 4: Run Enhanced Risk Verification (Optional)
Call the Enhanced Risk Verification endpoint with the confirmed profile data, including any user-provided corrections.
- If the system successfully verifies the user’s identity, the user profile is updated and returned in the response.
- If verification fails, an error is returned. In this case, please proceed with an alternate verification strategy, such as KBA.
After receiving the response, please evaluate the updated risk assessments to determine whether the user satisfies your organization’s risk tolerance.
Note: This functionality must be enabled for your organization before use.
Testing in Sandbox
To test this functionality in the sandbox environment, please use one of the documented Sandbox Test Users. The name and date of birth provided to the verification endpoint must exactly match a listed test user in order to receive a successful response.
If the provided name or date of birth does not match a documented identity, the system will return a VERIFICATION_FAILED error.
Other PII fields (such as phone number, address, or identifiers) may be updated as needed and will not impact the verification outcome in the sandbox environment.
Connect Preverified Phone & SMS Insights
URL
POST https://sandbox-api.spinwheel.io/v1/users/:userId/connect/sms/verify
POST https://sandbox-api.spinwheel.io/v1/users/:userId/connect/preverified/phoneNumber
Response
{
"status": {
"code": 201,
"desc": "success"
},
"data": {
"userId": "7c749a10-98b9-451e-bb19-d99b6fd26c9c",
"extUserId": "1f087b15-db74-4b28-859b-1ba4a5cf829a",
"connectionId": "0fad3d0a-6b8e-430d-b9cb-a442cda4cc75",
"connectionStatus": "SUCCESS",
"profile": {
"firstName": "CHRISTY",
"lastName": "JENOVAL",
"ssnLastFourDigits": "4123",
"phoneNumber": "+16102458296",
"dateOfBirth": "1901-03-07",
"addresses": [
{
"addressLine1": "5396 NORTH REESE AVENUE",
"city": "FRESNO",
"state": "CA",
"zip": "93722"
},
{
"addressLine1": "305 LINDEN AVE",
"city": "ATLANTA",
"state": "GA",
"zip": "30316"
}
]
},
"riskAssessments": [
{
"vendor": "PROVE",
"version": "identity/v2",
"details": {
"phoneNumber": "2009043541",
"lineType": "Mobile",
"carrier": "Verizon",
"countryCode": "US",
"reasonCodes": [
"S4",
"OL"
],
"individual": {
"addresses": [
{
"address": "5396 NORTH REESE AVENUE",
"extendedAddress": "",
"city": "FRESNO",
"region": "CA",
"country": "US",
"postalCode": "93722",
"firstSeen": "2022-10-20T00:00:00.000Z",
"lastSeen": "2022-10-20T00:00:00.000Z"
},
{
"address": "305 LINDEN AVE",
"extendedAddress": "",
"city": "ATLANTA",
"region": "GA",
"country": "US",
"postalCode": "30316",
"firstSeen": "2022-10-20T00:00:00.000Z",
"lastSeen": "2022-10-20T00:00:00.000Z"
}
],
"firstName": "CHRISTY",
"lastName": "JENOVAL",
"dob": "1901-03-07",
"ssnLastFourDigits": "4123",
"emailAddresses": [],
"aliases": []
}
}
},
{
"vendor": "PROVE",
"version": "trust/v2",
"details": {
"phoneNumber": "+16102458296",
"lineType": "Mobile",
"carrier": "Verizon",
"countryCode": "US",
"statusIndex": "1",
"isBaselined": true,
"trustScore": "980",
"enrollStatus": "enrolled",
"carrierStatus": "OK",
"reasonCodes": [
"FF",
"RL"
],
"phoneNumberVelocity": 0,
"portVelocity": 0,
"simVelocity": 0,
"deviceVelocity": 0,
"payfoneTenure": {
"minimumDate": "2020-01-01",
"maximumDate": "2025-01-01"
},
"carrierTenure": {
"minimumDate": "2020-01-01",
"maximumDate": "2025-01-01"
},
"phoneNumberTenure": {
"minimumDate": "2020-01-01",
"maximumDate": "2025-01-01"
},
"simTenure": {
"minimumDate": "2020-01-01",
"maximumDate": "2025-01-01"
},
"deviceTenure": {
"minimumDate": "2020-01-01",
"maximumDate": "2025-01-01"
},
"portedDate": {
"minimumDate": "2020-01-01",
"maximumDate": "2025-01-01"
},
"phoneRisk": false
}
}
]
}
}
Note: Standard failure responses apply.
Enhanced Risk Verification Specification
URL
POST https://secure-sandbox-api.spinwheel.io/v1/users/:userId/connect/verification
Secure URL
When calling this endpoint be sure to use the secure url (https://secure-api.spinwheel.io and https://secure-sandbox-api.spinwheel.io)
Request
{
"extUserId": "{{$randomUUID}}",
"firstName": "Christy",
"lastName": "Jenoval",
"dateOfBirth": "1967-06-08",
"phoneNumber": "+15555555555",
"ssn": "999999998",
"addresses": [
{
"addressLine1": "21 Pacific St",
"city": "Pittsfield",
"state": "MA",
"zip": "01201"
}
]
}
Response - Success
{
"status": {
"code": 200,
"desc": "success"
},
"data": {
"userId": "7c749a10-98b9-451e-bb19-d99b6fd26c9c",
"extUserId": "1f087b15-db74-4b28-859b-1ba4a5cf829a",
"connectionId": "0fad3d0a-6b8e-430d-b9cb-a442cda4cc75",
"connectionStatus": "SUCCESS",
"profile": {
"firstName": "Christy",
"lastName": "Jenoval",
"ssnLastFourDigits": "9998",
"phoneNumber": "+15555555555",
"dateOfBirth": "1967-06-08",
"addresses": [
{
"addressLine1": "21 Pacific St",
"city": "Pittsfield",
"state": "MA",
"zip": "01201"
},
{
"addressLine1": "305 LINDEN AVE",
"city": "ATLANTA",
"state": "GA",
"zip": "30316"
}
]
},
"riskAssessments": [
{
"vendor": "PROVE",
"version": "verify/v2",
"details": {
"phoneNumber": "12009041044",
"lineType": "Mobile",
"carrier": "AT&T Wireless",
"countryCode": "US",
"verified": true,
"multiVerified": true,
"multiCipConfidence": "low",
"cipConfidence": "low",
"enrollStatus": "enrolled",
"name": {
"firstName": 94,
"lastName": 94,
"nameScore": 94
},
"address": {
"streetNumber": 100,
"street": true,
"city": true,
"region": true,
"postalCode": true,
"distance": 0,
"addressScore": 100
},
"email": {
"emailAddress": true
},
"identifiers": {
"ssn": true,
"last4": true,
"dob": true,
"driversLicenseNumber": true,
"driversLicenseState": true
},
"knowYourCustomer": {
"TotalHits": 1,
"AmlTypeLists": [
{
"AmlType": "sanction",
"ListHits": 1,
"Fields": [
{
"Source": "hm-treasury-list",
"Name": "example",
"Value": "example"
}
]
}
],
"AliasList": [
"alias1",
"alias2"
],
"AdverseMediaList": [
{
"Date": "2025-12-12T22:28:11.262Z",
"Snippet": "example",
"Title": "example",
"Url": "https://example.com"
}
]
},
"reasonCodes": [
"FN",
"P5"
],
"dataSource2": {
"name": {
"firstName": 99,
"lastName": 99,
"nameScore": 94
},
"address": {
"streetNumber": 100,
"street": true,
"city": true,
"region": true,
"postalCode": true,
"distance": 0,
"addressScore": 100
},
"email": {
"emailAddress": true
},
"identifiers": {
"ssn": true,
"last4": true,
"dob": true,
"driversLicenseNumber": true,
"driversLicenseState": true
},
"reasonCodes": [
"NC"
],
"cipConfidence": "low",
"verified": true
}
}
}
]
}
}
Response - Failure
{
"status": {
"code": 400,
"desc": "VERIFICATION_FAILED",
"messages": [
{
"desc": "Verification Failed"
}
]
}
}
Updated 6 days ago