EzFin - API Documentation

Introduction

The EzFin API is a RESTful API that allows you to programmatically access and manage your financial data. This API follows REST conventions and returns JSON responses.

Base URL

https://ezfin.app/api

All API endpoints are relative to this base URL.

Authentication

EzFin uses Laravel Sanctum for API authentication. After logging in, you'll receive a bearer token that must be included in all subsequent requests.

Headers

Include these headers in all API requests:

{
    "Accept": "application/json",
    "Content-Type": "application/json",
    "Authorization": "Bearer YOUR_API_TOKEN"
}

Rate Limiting

API requests are limited to 60 requests per minute per authenticated user. Rate limit information is included in response headers:

X-RateLimit-Limit: Maximum requests per minute
X-RateLimit-Remaining: Remaining requests in current window
X-RateLimit-Reset: Unix timestamp when limit resets

Response Format

All API responses follow a consistent JSON structure:

Success Response

{
    "data": {...},
    "message": "Success message",
    "status": 200
}

Error Response

{
    "message": "Error description",
    "errors": {
        "field": ["validation error"]
    },
    "status": 422
}

Authentication Endpoints

POST/api/register

Create a new user account.

Request Body

{
    "name": "John Doe",
    "email": "john@example.com",
    "password": "password123",
    "password_confirmation": "password123",
    "language": "en",
    "currency": "USD"
}

Response

{
    "data": {
        "user": {
            "id": 1,
            "name": "John Doe",
            "email": "john@example.com"
        },
        "token": "1|laravel_sanctum_token..."
    },
    "message": "User registered successfully"
}

POST/api/login

Authenticate user and receive access token.

Request Body

{
    "email": "john@example.com",
    "password": "password123"
}

Response

{
    "data": {
        "user": {
            "id": 1,
            "name": "John Doe",
            "email": "john@example.com"
        },
        "token": "2|laravel_sanctum_token..."
    },
    "message": "Login successful"
}

POST/api/logout

Logout and revoke current access token.

Authentication required

Response

{
    "message": "Logged out successfully"
}

GET/api/user

Get current authenticated user details.

Authentication required

Response

{
    "data": {
        "id": 1,
        "name": "John Doe",
        "email": "john@example.com",
        "language": "en",
        "currency": "USD",
        "is_admin": false,
        "created_at": "2024-01-01T00:00:00Z"
    }
}

GET/api/tokens

List all API tokens for current user.

Authentication required

Response

{
    "data": [
        {
            "id": 1,
            "name": "Mobile App",
            "abilities": ["*"],
            "last_used_at": "2024-01-15T10:30:00Z",
            "created_at": "2024-01-01T00:00:00Z"
        }
    ]
}

Accounts

Manage financial accounts (checking, savings, credit cards, etc.)

GET/api/accounts

Get all accounts for authenticated user.

Authentication required

Query Parameters

Parameter	Type	Description
type	string	Filter by account type (checking, savings, credit_card, cash, investment)
include_archived	boolean	Include archived accounts (default: false)

Response

{
    "data": [
        {
            "id": 1,
            "name": "Main Checking",
            "type": "checking",
            "balance": 5000.00,
            "currency": "USD",
            "color": "#4F46E5",
            "icon": "account_balance",
            "is_archived": false,
            "created_at": "2024-01-01T00:00:00Z"
        }
    ]
}

POST/api/accounts

Create a new account.

Authentication required

Request Body

{
    "name": "Savings Account",
    "type": "savings",
    "balance": 10000.00,
    "currency": "USD",
    "color": "#10B981",
    "icon": "savings",
    "bank_name": "Example Bank",
    "account_number": "****1234"
}

Response

{
    "data": {
        "id": 2,
        "name": "Savings Account",
        "type": "savings",
        "balance": 10000.00,
        "currency": "USD",
        "color": "#10B981",
        "icon": "savings",
        "bank_name": "Example Bank",
        "account_number": "****1234",
        "is_archived": false,
        "created_at": "2024-01-15T00:00:00Z"
    },
    "message": "Account created successfully"
}

GET/api/accounts/{id}

Get specific account details.

Authentication required

Response

{
    "data": {
        "id": 1,
        "name": "Main Checking",
        "type": "checking",
        "balance": 5000.00,
        "currency": "USD",
        "color": "#4F46E5",
        "icon": "account_balance",
        "bank_name": "Example Bank",
        "account_number": "****5678",
        "is_archived": false,
        "transactions_count": 150,
        "created_at": "2024-01-01T00:00:00Z",
        "updated_at": "2024-01-15T00:00:00Z"
    }
}

PUT/api/accounts/{id}

Update account details.

Authentication required

Request Body

{
    "name": "Primary Checking",
    "balance": 5500.00,
    "color": "#6366F1"
}

DELETE/api/accounts/{id}

Delete an account. This will also delete all associated transactions.

Authentication required

Response

{
    "message": "Account deleted successfully"
}

Parameter	Type	Description
type	string	Filter by type (income, expense)

Transactions

Manage financial transactions (income, expenses, transfers).

GET/api/transactions

Get paginated list of transactions.

Authentication required

Query Parameters

Parameter	Type	Description
account_id	integer	Filter by account
category_id	integer	Filter by category
type	string	Filter by type (income, expense, transfer)
date_from	date	Start date (YYYY-MM-DD)
date_to	date	End date (YYYY-MM-DD)
page	integer	Page number (default: 1)
per_page	integer	Items per page (default: 20, max: 100)

Response

{
    "data": [
        {
            "id": 1,
            "type": "expense",
            "amount": 45.50,
            "description": "Grocery shopping",
            "date": "2024-01-15",
            "account": {
                "id": 1,
                "name": "Main Checking"
            },
            "category": {
                "id": 1,
                "name": "Groceries"
            },
            "tags": ["food", "weekly"],
            "created_at": "2024-01-15T10:30:00Z"
        }
    ],
    "links": {
        "first": "/api/transactions?page=1",
        "last": "/api/transactions?page=5",
        "prev": null,
        "next": "/api/transactions?page=2"
    },
    "meta": {
        "current_page": 1,
        "from": 1,
        "last_page": 5,
        "per_page": 20,
        "to": 20,
        "total": 95
    }
}

POST/api/transactions

Create a new transaction.

Authentication required

Request Body

{
    "type": "expense",
    "amount": 125.00,
    "description": "Monthly subscription",
    "date": "2024-01-15",
    "account_id": 1,
    "category_id": 5,
    "tags": ["subscription", "monthly"],
    "notes": "Annual plan - monthly billing"
}

Response

{
    "data": {
        "id": 100,
        "type": "expense",
        "amount": 125.00,
        "description": "Monthly subscription",
        "date": "2024-01-15",
        "account_id": 1,
        "category_id": 5,
        "tags": ["subscription", "monthly"],
        "notes": "Annual plan - monthly billing",
        "created_at": "2024-01-15T14:00:00Z"
    },
    "message": "Transaction created successfully"
}

POST/api/transactions (Transfer)

Create a transfer between accounts.

Authentication required

Request Body

{
    "type": "transfer",
    "amount": 1000.00,
    "description": "Transfer to savings",
    "date": "2024-01-15",
    "account_id": 1,        // From account
    "to_account_id": 2,     // To account
    "notes": "Monthly savings"
}

GET/api/transactions/statistics

Get transaction statistics for the authenticated user.

Authentication required

Query Parameters

Parameter	Type	Description
period	string	Time period (month, quarter, year)

Response

{
    "data": {
        "total_income": 5000.00,
        "total_expenses": 3500.00,
        "net_income": 1500.00,
        "average_daily_expense": 116.67,
        "largest_expense": {
            "amount": 1200.00,
            "description": "Rent payment",
            "date": "2024-01-01"
        },
        "most_used_category": {
            "id": 1,
            "name": "Groceries",
            "total": 650.00,
            "count": 12
        }
    }
}

Budgets

Create and track monthly budgets by category.

GET/api/budgets

Get all budgets for authenticated user.

Authentication required

Query Parameters

Parameter	Type	Description
month	integer	Filter by month (1-12)
year	integer	Filter by year

Response

{
    "data": [
        {
            "id": 1,
            "category": {
                "id": 1,
                "name": "Groceries"
            },
            "amount": 500.00,
            "spent": 325.50,
            "remaining": 174.50,
            "percentage": 65.1,
            "month": 1,
            "year": 2024,
            "created_at": "2024-01-01T00:00:00Z"
        }
    ]
}

POST/api/budgets

Create a new budget.

Authentication required

Request Body

{
    "category_id": 1,
    "amount": 600.00,
    "month": 2,
    "year": 2024
}

GET/api/budgets/progress

Get budget progress for current month.

Authentication required

Response

{
    "data": {
        "total_budget": 3000.00,
        "total_spent": 1850.00,
        "total_remaining": 1150.00,
        "overall_percentage": 61.67,
        "categories": [
            {
                "name": "Groceries",
                "budget": 500.00,
                "spent": 325.50,
                "percentage": 65.1,
                "status": "on_track"
            },
            {
                "name": "Entertainment",
                "budget": 200.00,
                "spent": 220.00,
                "percentage": 110.0,
                "status": "over_budget"
            }
        ],
        "month": 1,
        "year": 2024
    }
}

Financial Goals

Set and track financial goals.

GET/api/goals

Get all financial goals.

Authentication required

Response

{
    "data": [
        {
            "id": 1,
            "name": "Emergency Fund",
            "target_amount": 10000.00,
            "current_amount": 3500.00,
            "target_date": "2024-12-31",
            "progress_percentage": 35.0,
            "days_remaining": 320,
            "monthly_contribution_needed": 650.00,
            "created_at": "2024-01-01T00:00:00Z"
        }
    ]
}

POST/api/goals

Create a new financial goal.

Authentication required

Request Body

{
    "name": "Vacation Fund",
    "target_amount": 5000.00,
    "current_amount": 0,
    "target_date": "2024-07-01",
    "description": "Summer vacation to Europe"
}

POST/api/goals/{id}/add-funds

Add funds to a financial goal.

Authentication required

Request Body

{
    "amount": 500.00,
    "account_id": 2,
    "notes": "Monthly contribution"
}

Response

{
    "data": {
        "goal": {
            "id": 1,
            "name": "Emergency Fund",
            "current_amount": 4000.00,
            "progress_percentage": 40.0
        },
        "transaction": {
            "id": 150,
            "amount": 500.00,
            "description": "Goal contribution: Emergency Fund"
        }
    },
    "message": "Funds added successfully"
}

Recurring Transactions

Manage automated recurring transactions.

GET/api/recurring-transactions

Get all recurring transactions.

Authentication required

Response

{
    "data": [
        {
            "id": 1,
            "name": "Monthly Rent",
            "amount": 1200.00,
            "type": "expense",
            "frequency": "monthly",
            "next_date": "2024-02-01",
            "account": {
                "id": 1,
                "name": "Main Checking"
            },
            "category": {
                "id": 10,
                "name": "Housing"
            },
            "is_active": true,
            "created_at": "2024-01-01T00:00:00Z"
        }
    ]
}

POST/api/recurring-transactions

Create a recurring transaction.

Authentication required

Request Body

{
    "name": "Netflix Subscription",
    "amount": 15.99,
    "type": "expense",
    "frequency": "monthly",
    "start_date": "2024-01-15",
    "account_id": 1,
    "category_id": 5,
    "description": "Monthly streaming service"
}

POST/api/recurring-transactions/{id}/generate

Manually generate the next transaction for a recurring transaction.

Authentication required

Response

{
    "data": {
        "transaction": {
            "id": 200,
            "amount": 15.99,
            "description": "Netflix Subscription",
            "date": "2024-02-15"
        }
    },
    "message": "Transaction generated successfully"
}

GET/api/recurring-transactions/upcoming

Get upcoming recurring transactions for the next 30 days.

Authentication required

Response

{
    "data": [
        {
            "recurring_transaction_id": 1,
            "name": "Monthly Rent",
            "amount": 1200.00,
            "date": "2024-02-01",
            "days_until": 5
        }
    ]
}

Dashboard

Get dashboard data and analytics.

GET/api/dashboard

Get comprehensive dashboard data.

Authentication required

Response

{
    "data": {
        "accounts_summary": {
            "total_balance": 15000.00,
            "total_assets": 20000.00,
            "total_liabilities": 5000.00,
            "net_worth": 15000.00
        },
        "monthly_summary": {
            "income": 5000.00,
            "expenses": 3500.00,
            "savings": 1500.00,
            "savings_rate": 30.0
        },
        "budget_overview": {
            "total_budget": 4000.00,
            "spent": 3500.00,
            "remaining": 500.00,
            "percentage": 87.5
        },
        "recent_transactions": [...],
        "upcoming_bills": [...],
        "goals_progress": [...]
    }
}

GET/api/dashboard/widgets

Get individual dashboard widget data.

Authentication required

Query Parameters

Parameter	Type	Description
widgets	array	Comma-separated widget names

Reports

Generate financial reports and analytics.

GET/api/reports/income-expense

Generate income and expense report.

Authentication required

Query Parameters

Parameter	Type	Description
period	string	Time period (month, quarter, year, custom)
start_date	date	Start date for custom period
end_date	date	End date for custom period
group_by	string	Group results by (day, week, month, category)

Response

{
    "data": {
        "summary": {
            "total_income": 15000.00,
            "total_expenses": 10500.00,
            "net_income": 4500.00,
            "average_monthly_income": 5000.00,
            "average_monthly_expense": 3500.00
        },
        "income_by_category": [...],
        "expenses_by_category": [...],
        "trend_data": [...],
        "top_expenses": [...],
        "period": {
            "start": "2024-01-01",
            "end": "2024-01-31"
        }
    }
}

GET/api/reports/category

Generate detailed category analysis report.

Authentication required

GET/api/reports/cash-flow

Generate cash flow report.

Authentication required

GET/api/reports/net-worth

Track net worth over time.

Authentication required

Response

{
    "data": {
        "current_net_worth": 50000.00,
        "assets": {
            "total": 75000.00,
            "breakdown": [
                {
                    "type": "checking",
                    "amount": 5000.00
                },
                {
                    "type": "savings",
                    "amount": 20000.00
                },
                {
                    "type": "investment",
                    "amount": 50000.00
                }
            ]
        },
        "liabilities": {
            "total": 25000.00,
            "breakdown": [
                {
                    "type": "credit_card",
                    "amount": 5000.00
                },
                {
                    "type": "loan",
                    "amount": 20000.00
                }
            ]
        },
        "history": [...]
    }
}

Settings

Manage user settings and preferences.

GET/api/settings

Get user settings.

Authentication required

Response

{
    "data": {
        "language": "en",
        "currency": "USD",
        "date_format": "MM/DD/YYYY",
        "theme": "light",
        "notifications": {
            "email": true,
            "push": true,
            "budget_alerts": true,
            "bill_reminders": true
        },
        "privacy": {
            "show_profile": false,
            "share_statistics": false
        }
    }
}

PUT/api/settings

Update user settings.

Authentication required

Request Body

{
    "language": "pt-br",
    "currency": "BRL",
    "theme": "dark",
    "notifications": {
        "budget_alerts": false
    }
}

Notifications

Manage user notifications.

GET/api/notifications

Get user notifications.

Authentication required

Query Parameters

Parameter	Type	Description
unread_only	boolean	Show only unread notifications

Response

{
    "data": [
        {
            "id": "uuid-here",
            "type": "budget_alert",
            "title": "Budget Alert",
            "message": "You've used 90% of your Groceries budget",
            "data": {
                "budget_id": 1,
                "percentage": 90
            },
            "read_at": null,
            "created_at": "2024-01-15T10:00:00Z"
        }
    ]
}

POST/api/notifications/{id}/read

Mark notification as read.

Authentication required

POST/api/notifications/read-all

Mark all notifications as read.

Authentication required

Mobile-Specific Endpoints

Endpoints optimized for mobile applications.

GET/api/mobile/sync

Sync all user data for offline usage.

Authentication required

Query Parameters

Parameter	Type	Description
last_sync	timestamp	Last sync timestamp for delta updates

Response

{
    "data": {
        "accounts": [...],
        "categories": [...],
        "transactions": [...],
        "budgets": [...],
        "goals": [...],
        "settings": {...},
        "sync_timestamp": "2024-01-15T12:00:00Z"
    }
}

POST/api/mobile/device-token

Update device token for push notifications.

Authentication required

Request Body

{
    "token": "device_token_here",
    "platform": "ios"  // or "android"
}

GET/api/mobile/offline-data

Get minimal dataset for offline functionality.

Authentication required

Admin API

Administrative endpoints (requires admin privileges).

GET/api/admin/dashboard

Get admin dashboard statistics.

Admin authentication required

Response

{
    "data": {
        "users": {
            "total": 1250,
            "active": 980,
            "new_this_month": 45
        },
        "transactions": {
            "total": 125000,
            "total_volume": 5000000.00,
            "today": 450
        },
        "system": {
            "version": "1.0.0",
            "health": "healthy",
            "uptime": "45 days"
        }
    }
}

GET/api/admin/users

List all users (paginated).

Admin authentication required

Query Parameters

Parameter	Type	Description
search	string	Search by name or email
status	string	Filter by status (active, suspended)
role	string	Filter by role (user, admin)

POST/api/admin/users/{id}/toggle-admin

Toggle admin status for a user.

Admin authentication required

POST/api/admin/users/{id}/suspend

Suspend a user account.

Admin authentication required

Request Body

{
    "reason": "Terms of service violation",
    "duration_days": 30  // Optional, permanent if not specified
}

Error Codes

Common error codes and their meanings.

Code	Description
200	Success
201	Created
204	No Content
400	Bad Request
401	Unauthorized
403	Forbidden
404	Not Found
422	Validation Error
429	Too Many Requests
500	Internal Server Error

SDKs and Libraries

Official and community SDKs for various programming languages.

JavaScript/TypeScript

npm install @ezfin/sdk

Python

pip install ezfin-sdk

PHP

composer require ezfin/sdk

Ruby

gem install ezfin

Code Examples

JavaScript Example

// Initialize the client
const EzFin = require('@ezfin/sdk');
const client = new EzFin({
    apiKey: 'your_api_token_here'
});

// Get all accounts
const accounts = await client.accounts.list();

// Create a transaction
const transaction = await client.transactions.create({
    type: 'expense',
    amount: 50.00,
    description: 'Coffee shop',
    account_id: 1,
    category_id: 5,
    date: '2024-01-15'
});

// Get budget progress
const budgetProgress = await client.budgets.progress();

Python Example

from ezfin import Client

# Initialize the client
client = Client(api_key='your_api_token_here')

# Get all accounts
accounts = client.accounts.list()

# Create a transaction
transaction = client.transactions.create(
    type='expense',
    amount=50.00,
    description='Coffee shop',
    account_id=1,
    category_id=5,
    date='2024-01-15'
)

# Get budget progress
budget_progress = client.budgets.progress()

cURL Example

# Get all accounts
curl -X GET https://ezfin.app/api/accounts \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Accept: application/json"

# Create a transaction
curl -X POST https://ezfin.app/api/transactions \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Accept: application/json" \
  -H "Content-Type: application/json" \
  -d '{
    "type": "expense",
    "amount": 50.00,
    "description": "Coffee shop",
    "account_id": 1,
    "category_id": 5,
    "date": "2024-01-15"
  }'

Webhooks

Configure webhooks to receive real-time notifications about events in your account.

Available Events

transaction.created - New transaction created
transaction.updated - Transaction updated
transaction.deleted - Transaction deleted
budget.exceeded - Budget limit exceeded
goal.reached - Financial goal reached
recurring.processed - Recurring transaction processed

Webhook Payload

{
    "event": "transaction.created",
    "timestamp": "2024-01-15T10:30:00Z",
    "data": {
        "id": 123,
        "type": "expense",
        "amount": 50.00,
        "description": "Coffee shop",
        "account_id": 1,
        "category_id": 5
    }
}

Webhook Security

All webhook requests include a signature header for verification:

X-EzFin-Signature: sha256=SIGNATURE_HERE

Support

Need help with the API?

Email: api@ezfin.com
Documentation: Full Documentation
Status Page: status.ezfin.com
GitHub: github.com/ezfin/api

EzFin API Documentation

Introduction

Base URL

Authentication

Headers

Rate Limiting

Response Format

Success Response

Error Response

Authentication Endpoints

POST/api/register

Request Body

Response

POST/api/login

Request Body

Response

POST/api/logout

Response

GET/api/user

Response

GET/api/tokens

Response

Accounts

GET/api/accounts

Query Parameters

Response

POST/api/accounts

Request Body

Response

GET/api/accounts/{id}

Response

PUT/api/accounts/{id}

Request Body

DELETE/api/accounts/{id}

Response

Categories

GET/api/categories

Query Parameters

Response

POST/api/categories

Request Body

Transactions

GET/api/transactions

Query Parameters

Response

POST/api/transactions

Request Body

Response

POST/api/transactions (Transfer)

Request Body

GET/api/transactions/statistics

Query Parameters

Response

Budgets

GET/api/budgets

Query Parameters

Response

POST/api/budgets

Request Body

GET/api/budgets/progress

Response

Financial Goals

GET/api/goals

Response

POST/api/goals

Request Body

POST/api/goals/{id}/add-funds

Request Body

Response

Recurring Transactions

GET/api/recurring-transactions

Response

POST/api/recurring-transactions

Request Body

POST/api/recurring-transactions/{id}/generate

Response

GET/api/recurring-transactions/upcoming

Response

Dashboard

GET/api/dashboard