Customers represent the end users who send or receive payments through your integration. They represent the individuals or businesses involved in payment transactions with a Straddle account. This guide will walk you through the process of creating, managing, and verifying customers using Straddle’s API. This guide explains how to create and manage customers while maintaining compliance and security.

​
The Customer Object

A customer in Straddle is an entity (individual or business) that you interact with for payment purposes.
FieldTypeDescriptionRequired?
idstringUnique identifier for the customer, generated by Straddle.
namestringFull name of the individual or business name.
typestringType of customer (individual or business).
emailstringCustomer’s email address.
phonestringCustomer’s phone number in E.164 format.
external_idstringYour system’s unique identifier for this customer.
statusstringCurrent status of the customer (pending, review, verified, rejected, inactive).
addressobjectCustomer’s address information.
↳ address1stringPrimary address line.
↳ address2stringSecondary address line (optional).
↳ citystringCity name.
↳ statestringState or province code.
↳ zipstringPostal or ZIP code.
↳ countrystringCountry code (ISO 3166-1 alpha-2).
↳ typestringType of address (residential or commercial).
compliance_profileobjectInformation used for identity verification.
↳ dobstringDate of birth (YYYY-MM-DD format).
↳ ssnstringFull or last 4 digits of Social Security Number (masked in responses).
↳ einstringEmployer Identification Number (for business customers).
↳ legal_business_namestringTwo-letter abbreviation of the state where the business was originally registered (for business customers).
↳ websitestringURL of the company’s official website (for business customers).
↳ representativesobjectA list of people associated with the Business. (for business customers).
deviceobjectInformation about the device used during customer creation.
↳ ip_addressstringIP address of the device.
metadataobjectUser-defined key-value pairs for storing additional information.
created_atdatetimeTimestamp of when the customer record was created.
updated_atdatetimeTimestamp of the most recent update to the customer record.

​
Identity Built-in

When you create a customer, Straddle automatically initiates the identity verification process. This process includes:
The result of this verification process determines the customer’s status, which can be one of the following:
  • pending: Initial status when the customer is created
  • review: Additional review is needed
  • verified: Customer has passed all verification checks
  • rejected: Customer failed verification checks
  • inactive: Customer is no longer active

​
Customer Attributes

​
Customer Status Details

StatusDescription
pendingInitial status when the customer is created.
reviewAdditional review is needed for verification.
verifiedCustomer has passed all verification checks.
rejectedCustomer failed verification checks.
inactiveCustomer is no longer active.

​
Creating a Customer

To create a customer, you’ll use the POST /v1/customers endpoint. Here’s an example of how to create a customer using the Straddle API: 
curl -X POST https://api.straddle.io/v1/customers \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "John Doe",
    "type": "individual",
    "email": "john.doe@example.com",
    "phone": "+1234567890",
    "address": {
      "address1": "123 Main St",
      "city": "Anytown",
      "state": "CA",
      "zip": "12345",
      "type": "residential"
    },
    "compliance_profile": {
      "dob": "1990-01-01",
      "ssn": "123-45-6789"
    },
    "external_id": "cust_123",
    "metadata": {
      "user_id": "user_123"
    }
  }'
This request creates a new customer with the provided information. The response will include a unique id for the customer, which you’ll use for future operations.
Ensure that you handle sensitive information like SSNs securely and in compliance with relevant regulations.

​
Retrieving Customer Information

To retrieve information about a customer, use the GET /v1/customers/{id} endpoint: 
curl https://api.straddle.io/v1/customers/{id} \
  -H "Authorization: Bearer YOUR_API_KEY"

​
Updating Customer Information

You can update a customer’s information using the PUT /v1/customers/{id} endpoint: 
curl -X PUT https://api.straddle.io/v1/customers/{id} \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "John Smith",
    "email": "john.smith@example.com"
  }'
Updating certain fields may trigger a re-verification process, which could change the customer’s status.

​
Listing Customers

To retrieve a list of customers, use the GET /v1/customers endpoint. This endpoint supports pagination and various filter options: 
curl "https://api.straddle.io/v1/customers?page_number=1&page_size=10&sort_by=created_at&sort_order=desc" \
  -H "Authorization: Bearer YOUR_API_KEY"
You can filter customers by various parameters such as status, type, created_from, created_to, and more. Refer to the API reference for a complete list of available filters.

​
Handling Customer Reviews

When a customer’s status is set to review, it means additional verification is needed. You can use the GET /v1/customers/{id}/review endpoint to retrieve detailed information about the review: 
curl https://api.straddle.io/v1/customers/{id}/review \
  -H "Authorization: Bearer YOUR_API_KEY"
The response will include detailed information about the verification process, including any specific issues that need to be addressed. To update the status of a customer under review, use the PATCH /v1/customers/{id}/review endpoint: 
curl -X PATCH https://api.straddle.io/v1/customers/{id}/review \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "status": "verified"
  }'

​
Working with Unmasked Customer Data

In certain situations, you may need to access unmasked customer data. This is sensitive information and should be handled with care. To retrieve unmasked customer data, use the GET /v1/customers/{id}/unmasked endpoint: 
curl https://api.straddle.io/v1/customers/{id}/unmasked \
  -H "Authorization: Bearer YOUR_API_KEY"
Access to unmasked data is restricted and requires special permissions. Ensure you have the necessary authorization before attempting to access this endpoint.

​
Best Practices for Working with Customers

  1. Provide as much information as possible: The more information you provide when creating a customer, the more accurate the verification process will be.
  2. Handle verification failures gracefully: If a customer’s verification fails, provide clear instructions on what they need to do next.
  3. Keep customer information up to date: Regularly update customer information to ensure accuracy and maintain compliance.
  4. Use webhooks: Set up webhooks to receive real-time notifications about changes in customer status or verification results.
  5. Respect privacy: Only collect and store the minimum amount of personal information necessary for your business operations.
  6. Implement proper error handling: Be prepared to handle various API errors and provide appropriate feedback to your users.
  7. Use pagination for listing customers: When retrieving large lists of customers, always use pagination to improve performance and responsiveness.
  8. Leverage metadata: Use the metadata field to store additional information about customers that’s specific to your business needs.
  9. Implement proper access controls: Ensure that only authorized personnel have access to sensitive customer information, especially unmasked data.
  10. Regular audits: Periodically review your customer data and processes to ensure ongoing compliance with regulations and best practices.

​
Understanding Reason Codes

Straddle uses reason codes to provide detailed information about verification results. These codes can help you understand why a customer might have failed verification or been flagged for review. Here are some common reason codes:
  • I1001: Identity not found within Consortium Institutions
  • R201: The input SSN is invalid
  • R551: Email address is invalid
  • R603: Phone number is invalid
  • R703: Address is invalid or does not exist
For a complete list of reason codes and their meanings, refer to the Reason Codes Reference.

​
Handling Specific Use Cases

​
High-Risk Customers

For customers flagged as high-risk, you may want to implement additional verification steps:
  1. Request additional documentation
  2. Conduct manual review
  3. Implement transaction limits

​
Business Customers

When working with business customers, you’ll need to collect additional information:
  1. Business name
  2. Business type (LLC, Corporation, etc.)
  3. Tax ID (EIN for US businesses)
  4. Information about business owners or authorized representatives
For more information on Business Identity verification, refer to the Business Identity guide.

​
Conclusion

Understanding and effectively managing customers is crucial for successful integration with Straddle. By leveraging Straddle Identity, you can ensure that you’re interacting with verified individuals and businesses, reducing the risk of fraud and enhancing the security of your payment operations. Remember that customer management is an ongoing process. Regularly review and update your practices to ensure they align with the latest regulations and industry best practices. For more detailed information about the customer-related API endpoints, refer to the Customers API Reference.