Whistl API Integration Guide: Connect Your Financial Tools

Developers: integrate Whistl with your apps. Our API enables spending data access, blocking triggers, and accountability features. Here's everything you need to know.

Whistl API Overview

The Whistl API allows third-party apps to:

• Access spending data (with user permission)
• Trigger blocking interventions
• Read accountability partner status
• Write to Dream Board goals
• Receive real-time spending alerts

Getting Started

1. Create Developer Account

1. Visit developer.whistl.app
2. Sign up with your email
3. Verify your email
4. Create your first app

2. Get API Keys

Each app gets:

• Public key (for client-side)
• Secret key (server-side only!)
• Webhook secret (for webhooks)

3. Choose Your Integration Type

• Read-only: Access spending data
• Write: Modify goals, trigger blocks
• Full: Complete access (requires review)

Authentication

OAuth 2.0 Flow

1. Redirect user to Whistl authorization:
   GET https://api.whistl.app/oauth/authorize
     ?client_id=YOUR_CLIENT_ID
     &redirect_uri=YOUR_REDIRECT_URI
     &scope=read_spending
     &state=RANDOM_STATE

2. User authorizes your app

3. Whistl redirects back with code:
   YOUR_REDIRECT_URI?code=AUTH_CODE&state=RANDOM_STATE

4. Exchange code for token:
   POST https://api.whistl.app/oauth/token
   {
     "grant_type": "authorization_code",
     "code": "AUTH_CODE",
     "client_id": "YOUR_CLIENT_ID",
     "client_secret": "YOUR_CLIENT_SECRET",
     "redirect_uri": "YOUR_REDIRECT_URI"
   }

5. Receive access token:
   {
     "access_token": "ACCESS_TOKEN",
     "token_type": "Bearer",
     "expires_in": 3600,
     "refresh_token": "REFRESH_TOKEN"
   }

API Endpoints

Spending Data

# Get recent transactions
GET /v1/transactions
  ?limit=50
  &since=2026-01-01

Response:
{
  "transactions": [
    {
      "id": "txn_123",
      "amount": -45.99,
      "merchant": "Amazon",
      "category": "shopping",
      "timestamp": "2026-03-06T14:30:00Z",
      "risk_score": 0.72
    }
  ]
}

Risk Assessment

# Get current risk level
GET /v1/risk/current

Response:
{
  "risk_level": "high",
  "risk_score": 0.78,
  "factors": [
    "late_night",
    "high_velocity",
    "gambling_merchant"
  ],
  "recommended_action": "block"
}

Trigger Intervention

# Trigger spending block
POST /v1/interventions
{
  "type": "cooling_off",
  "duration_hours": 24,
  "reason": "User requested via partner app",
  "notify_partner": true
}

Response:
{
  "intervention_id": "int_456",
  "status": "active",
  "expires_at": "2026-03-07T14:30:00Z"
}

Dream Board Goals

# Create goal
POST /v1/dream-board/goals
{
  "name": "House Deposit",
  "target_amount": 80000,
  "current_amount": 12000,
  "deadline": "2027-12-31",
  "image_url": "https://..."
}

# Update progress
PATCH /v1/dream-board/goals/goal_123
{
  "current_amount": 15000
}

Webhooks

Receive real-time notifications:

Available Webhooks

• spending.high_risk - User at high risk
• spending.blocked - Transaction blocked
• goal.milestone - Goal milestone reached
• partner.notification - Partner action required

Webhook Setup

# Register webhook
POST /v1/webhooks
{
  "url": "https://yourapp.com/webhooks/whistl",
  "events": ["spending.high_risk", "spending.blocked"],
  "secret": "YOUR_WEBHOOK_SECRET"
}

# Webhook payload
{
  "id": "evt_789",
  "type": "spending.high_risk",
  "created_at": "2026-03-06T14:30:00Z",
  "data": {
    "user_id": "user_123",
    "risk_score": 0.85,
    "factors": ["late_night", "high_velocity"]
  }
}

Rate Limits

Privacy & Security

User Consent

Users must explicitly grant permission for each data type. They can revoke access anytime.

Data Handling

• All data encrypted in transit (TLS 1.3)
• Store tokens securely (never in client code)
• Respect user privacy settings
• Delete data when user revokes access

Compliance

• Australian Privacy Principles (APP)
• GDPR (for EU users)
• Open Banking CDR compliant

Use Cases

Financial Counseling Apps

Access client spending data (with permission) for better guidance.

Therapy Platforms

Monitor spending patterns for gambling/spending addiction recovery.

Employer Wellness Programs

Offer Whistl integration for employee financial wellness.

Banking Apps

Add Whistl's accountability features to existing banking apps.

SDK & Libraries

• JavaScript: npm install whistl-sdk
• Python: pip install whistl
• Ruby: gem install whistl-ruby
• Go: go get github.com/whistl/go-whistl

Sandbox Environment

Test without affecting real users:

• Sandbox API: https://sandbox-api.whistl.app
• Test users provided
• Mock transaction data
• No rate limits in sandbox

Support

• Documentation: developer.whistl.app/docs
• API Status: status.whistl.app
• Developer Forum: forum.whistl.app/developers
• Email: api-support@whistl.app

Conclusion: Build on Whistl

The Whistl API enables powerful integrations. Build tools that help people achieve financial accountability.

Related: Privacy & Security | Product Roadmap | Support Center