📋 API Overview
Quick Navigation
- Registration Validation Steps
- SSA Authorization
- User Authentication
- Password Management
- Contact Form
- User Profile Management
- Investment Management
- Withdrawal Management
- Plaid Banking Integration
- Spending Analysis
- Dwolla Payment Integration
- System Health Check
- Financial Details Management
- Two-Step Authentication
This comprehensive API provides a complete financial technology platform with multi-step registration validation, SSA authorization, advanced authentication flows, investment management, banking integration via Plaid, payment processing through Dwolla, spending analysis, withdrawal management, and robust security features
✅ Registration Validation
Validates user email and password before registration.
{
"email": "user@example.com",
"password": "Test@123#123"
}
{
"validated": true
}
{
"message": "Validation failed",
"errors": {
"email": ["Invalid email address"],
"password": ["Password must be at least 8 characters"]
}
}
Validates personal information during registration step 1.
{
"first_name": "John",
"last_name": "Doe",
"date_of_birth": "1990-01-01",
"is_us_citizen": true
}
{
"validated": true
}
Validates address information during registration step 2.
{
"address_line_1": "123 Main St",
"address_line_2": "Apt 4B",
"phone_number": "1234567890",
"state": "CA",
"city": "Los Angeles",
"zip_code": "90001"
}
{
"validated": true
}
🛡️ SSA Authorization
Submit SSA agreement for authorization.
{
"has_agreed_to_ssa_verification": true
}
{
"message": "Authorization saved successfully",
"data": {
"user_id": 123,
"has_agreed_to_ssa_verification": true,
"agreement_timestamp": "2025-06-09T12:00:00Z"
}
}
Retrieve current SSA authorization status.
{
"has_agreed_to_ssa_verification": true,
"agreement_timestamp": "2025-06-09T12:00:00Z"
}
{
"message": "No authorization record found",
"has_agreed_to_ssa_verification": false
}
🔑 User Authentication
Complete user registration with all required information.
{
"email": "user@example.com",
"password": "Test@123#123",
"first_name": "John",
"last_name": "Doe",
"phone_number": "1234567890",
"date_of_birth": "1990-01-01",
"is_us_citizen": true,
"address_line_1": "123 Main St",
"address_line_2": "Apt 4B",
"state": "CA",
"city": "Los Angeles",
"zip_code": "90001",
"none_of_the_above_apply": true,
"isEmail": true
}
{
"verification_token": "<token_string>"
}
{
"error": "Sorry, you can't create an account on this platform."
}
Authenticate user with email and password.
{
"email": "user@example.com",
"password": "Test@123#123"
}
{
"token": "<access_token>",
"verification_required": false
}
{
"message": "Email not verified",
"verification_required": true,
"verification_token": "<verify-only-token>"
}
{
"message": "Two-step authentication required",
"verification_required": true,
"verification_token": "<OTP_verification_token>"
}
Verify OTP for email verification or two-step authentication.
{
"otp": "123456"
}
{
"message": "Email verified successfully",
"token": "<access_token>"
}
Logout user and invalidate access token.
{
"message": "Logged out successfully"
}
🔄 Password Management
Request password reset verification code.
{
"email": "user@example.com"
}
{
"message": "Verification code sent",
"verification_token": "<verify-reset-token>"
}
Verify OTP before password reset.
{
"otp": "123456"
}
{
"message": "Verification successful",
"reset_token": "<reset-password-token>"
}
Reset user password with new credentials.
{
"password": "NewPass@123",
"password_confirmation": "NewPass@123"
}
{
"message": "Password updated successfully",
"token": "<access_token>"
}
{
"message": "Password updated. Email verification required.",
"verification_required": true,
"verification_token": "<verify-only-token>"
}
📧 Contact Form
Submit a contact form message from users to the support team. Used for customer support inquiries, feedback, and general communication. Automatically stores the submission in database and sends email notification to support team.
{
"email": "user@example.com",
"first_name": "John",
"last_name": "Doe",
"message": "I need help with my account settings."
}
{
"message": "Your message has been submitted successfully."
}
{
"message": "The given data was invalid.",
"errors": {
"email": ["The email field is required."],
"first_name": ["The first name field is required."],
"message": ["The message field is required."]
}
}
👤 User Profile Management
Retrieve the authenticated user's profile information including personal details and monthly financial data. Used in profile displays and dashboard to show current user information. Returns user data with related monthly financial information if available.
{
"data": {
"id": 123,
"email": "user@example.com",
"first_name": "John",
"last_name": "Doe",
"address_line_1": "123 Main St",
"address_line_2": "Apt 4B",
"city": "Los Angeles",
"state": "CA",
"zip_code": "90001",
"phone_number": "1234567890",
"is_verified": true,
"monthly_financial": {
"monthly_salary": 5000.00,
"monthly_basic_expenses": 2500.00,
"monthly_savings": 1000.00,
"matching_option": "aggressive",
"discretionary_spending_percentage": 80,
"selected_etf": "VOO"
}
}
}
Update user profile information including address and financial preferences. Supports updating address fields and monthly financial settings like matching options, spending percentages, and ETF selections. Uses database transactions to ensure data consistency across user and financial tables.
{
"address_line_1": "456 New St",
"city": "San Francisco",
"state": "CA",
"zip_code": "94102",
"matching_option": "conservative",
"discretionary_spending_percentage": 70,
"selected_etf": "IVV"
}
{
"data": {
"id": 123,
"email": "user@example.com",
"first_name": "John",
"last_name": "Doe",
"address_line_1": "456 New St",
"address_line_2": "Apt 4B",
"city": "San Francisco",
"state": "CA",
"zip_code": "94102",
"phone_number": "1234567890",
"is_verified": true,
"monthly_financial": {
"monthly_salary": 5000.00,
"monthly_basic_expenses": 2500.00,
"monthly_savings": 1000.00,
"matching_option": "conservative",
"discretionary_spending_percentage": 70,
"selected_etf": "IVV"
}
}
}
{
"error": "Failed to update user information",
"message": "Database transaction failed"
}
Change user's password with current password verification. Validates current password, ensures new password is different, updates password, and invalidates all existing tokens. Returns new authentication token after successful password change for continued access.
{
"current_password": "OldPass@123",
"password": "NewPass@456",
"password_confirmation": "NewPass@456"
}
{
"message": "Password changed successfully",
"token": "<new_access_token>"
}
{
"error": "Current password is incorrect"
}
{
"error": "New password must be different from current password"
}
Initiate email change process by sending verification code to new email address. Validates that new email is not already in use, generates OTP, and sends verification email. Includes rate limiting to prevent abuse and temporary caching of new email for verification.
{
"new_email": "newemail@example.com"
}
{
"message": "Verification code sent to new email"
}
{
"error": "Email is already in use"
}
{
"message": "Too many attempts. Please try later."
}
Complete email change process by verifying OTP sent to new email address. Validates OTP, updates user email, marks email as verified, and cleans up temporary data. Uses database transactions to ensure data consistency during email update process.
{
"otp": "123456"
}
{
"message": "Email updated successfully"
}
{
"error": "Email change request expired"
}
{
"error": "Invalid or expired verification code"
}
📈 Investment Management
Calculate projected investment growth over time using aggressive and conservative return scenarios. This endpoint generates growth projections for financial planning and investment visualization charts. Returns monthly data points for both aggressive (default 8%) and conservative (default 4%) growth scenarios.
{
"initial_investment": 10000.00,
"years": 10,
"aggressive_return": 0.08,
"conservative_return": 0.04
}
{
"time_points": [0, 0.083, 0.167, ...],
"aggressive_growth": [10000, 10066.23, 10133.02, ...],
"conservative_growth": [10000, 10032.98, 10066.12, ...]
}
{
"errors": {
"initial_investment": ["The initial investment field is required."],
"years": ["The years must be between 1 and 50."],
"aggressive_return": ["The aggressive return must be between 0 and 1."]
}
}
Calculate portfolio returns by comparing initial investment with current value. Used in portfolio performance tracking and dashboard displays to show investment gains/losses. Returns both dollar amounts and percentage returns with formatted strings for display.
{
"initial_investment": 10000.00,
"current_value": 12500.00
}
{
"dollar_return": 2500.00,
"percentage_return": 25.00,
"formatted_dollar_return": "$2,500.00",
"formatted_percentage_return": "25.00%"
}
{
"errors": {
"initial_investment": ["The initial investment field is required."],
"current_value": ["The current value must be a number."]
}
}
Create a new investment record for the authenticated user. Supports VOO and IVV investment types with automatic status tracking. Used when users make new investments through the platform to maintain portfolio records.
{
"amount": 5000.00,
"investment_type": "VOO",
"investment_date": "2025-01-15"
}
{
"message": "Investment saved successfully",
"investment": {
"id": 123,
"user_id": 456,
"amount": 5000.00,
"investment_type": "VOO",
"investment_date": "2025-01-15T00:00:00Z",
"investment_status": "completed",
"created_at": "2025-01-15T10:30:00Z",
"updated_at": "2025-01-15T10:30:00Z"
}
}
{
"errors": {
"amount": ["The amount field is required."],
"investment_type": ["The investment type must be VOO or IVV."],
"investment_date": ["The investment date must be a valid date."]
}
}
Retrieve paginated list of user's investments ordered by date (newest first). Used in portfolio dashboard and investment history views. Returns 10 investments per page with Laravel pagination metadata.
{
"current_page": 1,
"data": [
{
"id": 123,
"user_id": 456,
"amount": 5000.00,
"investment_type": "VOO",
"investment_date": "2025-01-15T00:00:00Z",
"investment_status": "completed",
"created_at": "2025-01-15T10:30:00Z",
"updated_at": "2025-01-15T10:30:00Z"
}
],
"first_page_url": "https://api.example.com/users/investments?page=1",
"from": 1,
"last_page": 1,
"per_page": 10,
"to": 1,
"total": 1
}
Update an existing investment record. Supports partial updates of amount, investment type, and status. Used for correcting investment data or updating investment status (pending, completed, failed). Only allows updating investments owned by the authenticated user for security.
{
"amount": 5500.00,
"investment_status": "completed"
}
{
"message": "Investment updated successfully",
"investment": {
"id": 123,
"user_id": 456,
"amount": 5500.00,
"investment_type": "VOO",
"investment_date": "2025-01-15T00:00:00Z",
"investment_status": "completed",
"created_at": "2025-01-15T10:30:00Z",
"updated_at": "2025-01-15T12:45:00Z"
}
}
{
"message": "Investment not found or access denied"
}
{
"errors": {
"investment_type": ["The investment type must be VOO or IVV."],
"investment_status": ["The investment status must be pending, completed, or failed."]
}
}
💳 Withdrawal Management
Request a withdrawal from user's savings account through Alpaca integration. Validates minimum withdrawal amount, checks available balance, verifies Plaid/Alpaca connections, and initiates transfer. Creates withdrawal record and processes transfer through Alpaca API with ACH relationship for bank transfer.
{
"amount": 1000.00
}
{
"message": "Withdrawal request submitted successfully",
"withdrawal_id": "transfer_abc123"
}
{
"error": "Minimum withdrawal amount is $10"
}
{
"error": "Insufficient funds. You have $2500.00 available."
}
{
"error": "No active Plaid connection found."
}
{
"error": "Missing Alpaca account details."
}
{
"error": "Insufficient withdrawable cash.",
"message": "Cash not yet settled",
"cash_withdrawable": 500.00,
"total_cash": 2500.00
}
🏦 Plaid Banking Integration
Create a link token for Plaid Link initialization to connect user's bank account. Used to initiate the bank account linking process in the mobile/web application. Returns a temporary token that expires and must be used in Plaid Link flow.
{
"link_token": "link-sandbox-12345678-abcd-efgh-ijkl-123456789012",
"expiration": "2025-01-15T14:30:00Z"
}
{
"error": "Failed to create link token",
"message": "Plaid API connection failed"
}
Exchange public token for access token and establish Plaid connection with Alpaca integration. Creates processor token, links bank to Alpaca for ACH transfers, sets up webhook, and syncs initial account data. This is the core endpoint that completes the bank account linking process.
{
"public_token": "public-sandbox-12345678-abcd-efgh-ijkl-123456789012",
"metadata_json": "{\"account_id\":\"account123\",\"institution\":{\"name\":\"Bank of America\"}}",
"institution": {
"institution_id": "ins_1",
"name": "Bank of America"
}
}
{
"message": "Plaid connection established successfully",
"access_token": "access-sandbox-12345678-abcd-efgh-ijkl-123456789012",
"connection_id": 123
}
{
"error": "Failed to link bank account to Alpaca.",
"details": {...}
}
Retrieve list of supported financial institutions from Plaid. Used to display available banks and credit unions for account linking. Returns institution details including names, IDs, and supported products.
{
"institutions": [
{
"institution_id": "ins_1",
"name": "Bank of America",
"products": ["transactions", "auth", "identity"],
"country_codes": ["US"]
},
{
"institution_id": "ins_2",
"name": "Chase",
"products": ["transactions", "auth"],
"country_codes": ["US"]
}
]
}
Retrieve user's connected bank accounts from Plaid. Shows all linked accounts with balances, types, and verification status. Creates local account records if they don't exist in database.
[
{
"id": 1,
"plaid_connection_id": 123,
"plaid_account_id": "account_123",
"name": "Checking Account",
"official_name": "Premium Checking",
"type": "depository",
"subtype": "checking",
"mask": "1234",
"balances": {
"available": 1500.00,
"current": 1500.00,
"limit": null
},
"verification_status": true
}
]
{
"error": "No active Plaid connection found"
}
Get user's spending history grouped by merchant with matching status. Supports automatic and manual matching modes based on user preferences. Returns merchant details, spending totals, and matching configuration for savings calculations.
[
{
"merchant_name": "Starbucks",
"merchant_entity_id": "merchant_123",
"logo": "https://logo.url/starbucks.png",
"total_spending": 125.50,
"matching_status": 1
},
{
"merchant_name": "Amazon",
"merchant_entity_id": "merchant_456",
"logo": "https://logo.url/amazon.png",
"total_spending": 89.99,
"matching_status": 0
},
{
"merchant_name": "Others",
"merchant_entity_id": "others",
"logo": null,
"total_spending": 45.75,
"matching_status": 0
}
]
Get weekly spending and savings data for current and previous week. Returns daily totals Monday-Sunday in EST timezone for chart visualization. Used in dashboard to show weekly spending patterns and savings performance.
{
"days": ["Mo", "Tu", "We", "Th", "Fr", "Sa", "Su"],
"current_week": {
"spending": [125.50, 89.99, 45.75, 200.00, 67.25, 150.00, 75.50],
"savings": [12.55, 8.99, 4.58, 20.00, 6.73, 15.00, 7.55]
},
"last_week": {
"spending": [110.25, 75.50, 55.25, 180.00, 95.75, 125.50, 85.25],
"savings": [11.03, 7.55, 5.53, 18.00, 9.58, 12.55, 8.53]
}
}
Get total spending and savings summary for the current year. Calculates year-to-date totals using EST timezone for accurate date ranges. Used in annual summary views and year-end reporting.
{
"total_spending": 15250.75,
"total_savings": 1525.08
}
Get performance metrics for specified time period (week/month/year). Calculates invested amounts, returns, and spending matching percentages. Used in performance dashboard to show investment and spending matching effectiveness.
?period=week // or ?period=month // or ?period=year
{
"invested": 750.25,
"return": 750.25,
"return_percentage": 15.25,
"spending_matched": 4920.50,
"spending_matched_percentage": 50
}
{
"message": "The given data was invalid.",
"errors": {
"period": ["The period must be one of: week, month, year."]
}
}
Get performance chart data for spending and savings over time. Returns data points for week (7 days), month (5 intervals), or year (12 months). Used to generate performance charts and trend visualizations in dashboard.
?period=week // or ?period=month // or ?period=year
{
"chart_data": [
{
"date": "2025-01-09",
"total_spent": 125.50,
"total_saved": 12.55
},
{
"date": "2025-01-10",
"total_spent": 89.99,
"total_saved": 8.99
},
{
"date": "2025-01-11",
"total_spent": 45.75,
"total_saved": 4.58
}
]
}
{
"chart_data": [
{
"date": "2024-02",
"total_spent": 1250.75,
"total_saved": 125.08
},
{
"date": "2024-03",
"total_spent": 1189.50,
"total_saved": 118.95
}
]
}
🏥 System Health Check
Check the health status of critical system components including database and cache services. Returns system status, component health, and performance metrics with latency measurements. Used for monitoring, load balancers, and automated health checks.
{
"status": "up",
"timestamp": "2025-01-15T10:30:00Z",
"services": {
"database": {
"status": "up",
"latency": 12.45
},
"cache": {
"status": "up",
"latency": 2.18
}
}
}
{
"status": "down",
"timestamp": "2025-01-15T10:30:00Z",
"error": "System health check failed",
"message": "Database connection failed",
"services": {
"database": {
"status": "down",
"error": "Database connection failed"
},
"cache": {
"status": "up",
"latency": 2.18
}
}
}
💰 Financial Details Management
Store or update user's initial financial information including monthly salary, basic expenses, and savings goals. This endpoint is used during onboarding to capture the user's financial profile for budgeting and spending analysis. Validates that total outflow (expenses + savings) doesn't exceed monthly income.
{
"monthly_salary": 5000.00,
"monthly_basic_expenses": 2500.00,
"monthly_savings": 1000.00
}
{
"message": "Financial details saved successfully",
"data": {
"monthly_salary": 5000.00,
"monthly_basic_expenses": 2500.00,
"monthly_savings": 1000.00
}
}
{
"error": "Total expenses and savings cannot exceed monthly salary"
}
{
"error": "Failed to save financial details",
"message": "Database connection failed"
}
Retrieve the authenticated user's current financial details and calculate discretionary cash available (DCS). This endpoint is used in the dashboard to display financial overview and spending capacity. Returns calculated discretionary spending amount based on salary minus fixed expenses and savings.
{
"data": {
"monthly_salary": 5000.00,
"monthly_basic_expenses": 1500.00,
"monthly_savings": 1000.00
}
}
{
"error": "Financial details not found"
}
{
"message": "Unauthenticated"
}
{
"error": "Failed to retrieve financial details",
"message": "Database query failed"
}
Update existing financial details with partial or complete data changes. Used when users need to modify their financial profile due to income changes, expense adjustments, or savings goal updates. Supports partial updates - only provided fields will be updated. Maintains validation that outflow doesn't exceed income.
{
"monthly_salary": 5500.00,
"monthly_savings": 1200.00
}
{
"message": "Financial details updated successfully",
"data": {
"id": 1,
"user_id": 123,
"monthly_salary": 5500.00,
"monthly_basic_expenses": 2500.00,
"monthly_savings": 1200.00,
"created_at": "2025-01-01T00:00:00Z",
"updated_at": "2025-01-15T10:30:00Z"
}
}
{
"error": "Financial details not found"
}
{
"error": "Total expenses and savings cannot exceed monthly salary"
}
{
"error": "Failed to update financial details",
"message": "Database update failed"
}
🛡️ Two-Step Authentication
Enable two-step authentication via email or phone.
// Email option
{
"type": "email",
"email": "user@example.com"
}
// Phone option
{
"type": "phone",
"phone": "+1234567890"
}
{
"message": "OTP sent. Please verify to enable two-step authentication.",
"two_step_type": "email"
}
Verify OTP to complete two-step authentication setup.
{
"otp": "123456"
}
{
"message": "Two-step authentication enabled successfully"
}