Customers - Straddle Docs

Customers are the foundation of every payment flow in Straddle—representing the individuals or businesses who send and receive money through your platform. When you create a customer, Straddle automatically triggers identity verification, fraud screening, and compliance checks in real-time, enabling instant onboarding while maintaining security.

What This Guide Covers

This comprehensive guide provides everything you need to implement customer management:

Customer lifecycle: From creation through verification to ongoing monitoring
Identity verification: How automated KYC/AML checks work behind the scenes
Review process: Understanding and decisioning customers flagged for review
Business customers: Special requirements for company verification
Best practices: Optimizing approval rates while preventing fraud

The Customer Object

Every customer in Straddle represents either an individual person or a business entity. The customer object contains identity information, verification status, and metadata that enables secure payment processing.

Core Fields

Field	Type	Description
`id`	string	Unique identifier for the customer, generated by Straddle
`name`	string	Full name of the individual or business name
`type`	string	Type of customer: `individual` or `business`
`email`	string	Customer’s email address
`phone`	string	Customer’s phone number in E.164 format (+1234567890)
`external_id`	string	Your system’s unique identifier for this customer
`status`	string	Current verification status: `pending`, `review`, `verified`, `rejected`, `inactive`

Address Object

Field	Type	Description
`address.address1`	string	Primary address line
`address.address2`	string	Secondary address line (optional)
`address.city`	string	City name
`address.state`	string	State code (2-letter abbreviation)
`address.zip`	string	ZIP code (5 or 9 digits)

Compliance Profile

Field	Type	Description	Applies To
`compliance_profile.dob`	string	Date of birth (YYYY-MM-DD format)	Individual
`compliance_profile.ssn`	string	Full or last 4 digits of SSN (always masked in responses)	Individual
`compliance_profile.ein`	string	Employer Identification Number	Business
`compliance_profile.legal_business_name`	string	Legal entity name as registered	Business
`compliance_profile.website`	string	Company’s official website URL	Business
`compliance_profile.representatives`	array	List of authorized representatives with ownership details	Business

Additional Fields

Field	Type	Description
`device.ip_address`	string	IP address captured during customer creation (used for fraud detection)
`config`	object	Configuration options including sandbox testing outcomes
`metadata`	object	Custom key-value pairs for your reference
`created_at`	datetime	ISO 8601 timestamp of creation
`updated_at`	datetime	ISO 8601 timestamp of last update

Automatic Identity Verification

When you create a customer, Straddle automatically triggers a comprehensive verification pipeline that includes:

Identity

KYC

AML and Watchlist Monitoring

Customer Status Lifecycle

Every customer progresses through a defined verification lifecycle:

Status	Description	Next Actions
`pending`	Initial state, verification in progress	Wait for automatic verification to complete
`review`	Manual review required (rare edge cases)	Use `/review` endpoint to see details, then `/decision` to approve/reject
`verified`	Passed all verification checks	Ready to process payments
`rejected`	Failed verification requirements	Cannot process payments, may need new customer
`inactive`	Deactivated customer account	No longer able to transact

Security: SSN values are always masked in API responses. Use the /unmasked endpoint only when absolutely necessary and ensure proper access controls.

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 Review Status

When customers require manual review (status = review), use two endpoints to handle the review process:

1. Get Review Details

Retrieve detailed verification results using GET /v1/customers/{id}/review:

curl https://api.straddle.io/v1/customers/{id}/review \
  -H "Authorization: Bearer YOUR_API_KEY"

The review response includes:

identity_details: Complete identity verification results including KYC, watchlist, reputation scores
customer_details: Current customer information
messages: Specific issues or requirements
network_alerts: Any consortium fraud signals

2. Make a Decision

After reviewing the details, make a decision using PATCH /v1/customers/{id}/review:

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"  // or "rejected"
  }'

Accessing Sensitive Data

Compliance Alert: Access to unmasked data requires special permissions and generates audit logs. Only use when absolutely necessary for regulatory compliance or customer support.

Retrieve Unmasked Data

Use GET /v1/customers/{id}/unmasked to access full sensitive information:

curl https://api.straddle.io/v1/customers/{id}/unmasked \
  -H "Authorization: Bearer YOUR_API_KEY"

The unmasked endpoint returns:

Full SSN (not just last 4 digits)
Complete compliance profile data
All sensitive fields in plaintext

Best Practices

Optimize Approval Rates

Include full address (address1, city, state, zip)
Provide accurate phone numbers in E.164 format
Use legal names matching government IDs
Include SSN for immediate KYC verification

Handle Reviews Properly

Use /review endpoint to understand issues
Make timely decisions with /review PATCH
Document decision rationale for compliance
Monitor review rates to identify patterns

Maintain Security

Never log or store unmasked SSN data
Use /unmasked endpoint sparingly
Implement audit logging for sensitive access
Rotate API keys regularly

Use Webhooks

Set up customer status change notifications
React to review status immediately
Track verification success rates
Monitor for unusual patterns

Understanding Verification Results

The /review endpoint provides detailed verification results including:

KYC Results: Identity match confidence and specific field matches
Reputation Scores: Email, phone, and address risk assessments
Watchlist Results: Any sanctions, PEP, or adverse media hits
Network Alerts: Consortium fraud signals and patterns
Messages: Specific verification issues with reason codes

For complete reason code reference, see Reason Codes Guide.

Testing in Sandbox

Use the config.sandbox_outcome field to test different verification scenarios:

{
  "name": "Test User",
  "type": "individual",
  "config": {
    "sandbox_outcome": "verified"  // or "review", "rejected"
  }
  // ... other fields
}

Business Customers

Business customers require additional fields in the compliance profile:

ein: Employer Identification Number
legal_business_name: Official registered name
website: Company website
representatives: Array of authorized signers with ownership percentages

See Business Identity Guide for complete requirements.

Next Steps

API Reference

Complete endpoint documentation for customers

Business Identity

Special requirements for business verification

Reason Codes

Understanding verification messages and codes

Webhook Events

Set up real-time customer status notifications

Get Started

Identity

Bridge

Payments

Embed

Resources

​What This Guide Covers

​The Customer Object

​Core Fields

​Address Object

​Compliance Profile

​Additional Fields

​Automatic Identity Verification

​Customer Status Lifecycle

​Creating a Customer

​Retrieving Customer Information

​Updating Customer Information

​Listing Customers

​Handling Review Status

​1. Get Review Details

​2. Make a Decision

​Accessing Sensitive Data

​Retrieve Unmasked Data

​Best Practices

Optimize Approval Rates

Handle Reviews Properly

Maintain Security

Use Webhooks

​Understanding Verification Results

​Testing in Sandbox

​Business Customers

​Next Steps

API Reference

Business Identity

Reason Codes

Webhook Events

What This Guide Covers

The Customer Object

Core Fields

Address Object

Compliance Profile

Additional Fields

Automatic Identity Verification

Customer Status Lifecycle

Creating a Customer

Retrieving Customer Information

Updating Customer Information

Listing Customers

Handling Review Status

1. Get Review Details

2. Make a Decision

Accessing Sensitive Data

Retrieve Unmasked Data

Best Practices

Understanding Verification Results

Testing in Sandbox

Business Customers

Next Steps