​

Identity Reason Codes

When you create or update a customer using Straddle’s API, our system performs an identity verification process. This process returns reason codes that provide insights into the verification results. These codes are crucial for understanding the risk assessment and decision-making process.

​

Overview

Reason codes are alphanumeric identifiers that explain specific aspects of the identity verification process. They are categorized into different types, each starting with a specific letter:

• I: Informational codes
• R: Risk indicator codes
• BI: Business Identity Informational codes
• BR: Business Identity Risk indicator codes

​

Accessing Reason Codes

You can access the reason codes in the response when creating or retrieving a customer. The codes are located in the identity_details object of the response.

const response = await straddle.customers.create({
  // customer details
});

const reasonCodes = response.identity_details.breakdown.reason_codes;
console.log(reasonCodes);

​

Interpreting Reason Codes

​

Informational Codes (I, BI)

Informational codes provide context about the verification process and the data used. They don’t necessarily indicate a risk but offer additional insights.

​

Risk Indicator Codes (R, BR)

Risk indicator codes highlight potential risks or discrepancies in the provided information. These codes are crucial for assessing the overall risk of a customer.

​

Using Reason Codes in Your Application

When implementing identity verification in your application, you can use these reason codes to:

1. Provide specific feedback to users about their verification status
2. Implement custom logic based on certain codes
3. Flag high-risk applications for manual review

Here’s an example of how you might use reason codes in your application:

function handleVerificationResult(customer) {
  const reasonCodes = customer.identity_details.breakdown.reason_codes;
  
  if (reasonCodes.includes('R201')) {
    console.log('Invalid SSN provided');
    // Prompt user to re-enter SSN
  } else if (reasonCodes.includes('R520')) {
    console.log('High risk email detected');
    // Flag for manual review
  } else if (reasonCodes.some(code => code.startsWith('I'))) {
    console.log('Verification successful with additional information');
    // Proceed with account creation
  }
}

​

Best Practices

When working with identity reason codes, consider the following best practices:

1. Regularly review and update your handling of reason codes: As Straddle may introduce new codes or modify existing ones, ensure your application can handle new codes gracefully.
2. Combine multiple codes for a comprehensive risk assessment: Don’t rely on a single code to make decisions. Consider the full picture provided by all returned codes.
3. Provide clear feedback to users: When possible, use reason codes to give specific instructions to users for resolving verification issues.
4. Monitor code frequencies: Keep track of which codes appear most often in your verifications. This can help you identify patterns and potential areas for improvement in your onboarding process.
5. Consult with Straddle: If you’re unsure about the meaning or implication of certain codes, don’t hesitate to reach out to Straddle’s support team for clarification.

By leveraging these identity reason codes effectively, you can enhance your risk assessment process, improve your user experience, and make more informed decisions about customer verifications.

​

Reason Codes Documentation

​

Account Verification Codes

​

Device Verification Codes

​

Email Verification Codes

​

Phone Verification Codes

​

Address Verification Codes

​

General Information Codes

​

Risk Codes