API Access

ShulNET 2.0 provides a comprehensive REST API for programmatic access to all system functionality. Use the API to integrate with external systems, build custom dashboards, automate reporting, or create mobile applications.

🔗 Interactive API Documentation

For complete endpoint documentation with interactive testing, visit /docs/api

Getting Started with the API

Step 1: Create an API Token

  1. Navigate to API Tokens

    From the admin menu, go to System → API Tokens

  2. Create a New Token

    Click the "Create Token" button and provide the following information:

    • Token Name - A descriptive name for your integration (e.g., "Financial Reporting Script", "Mobile App", "CRM Integration")
    • Email - Your admin email address
    • Password - Your account password for verification

  3. Copy Your Token

    ⚠️ Important: The API token is displayed only once for security reasons. Copy it immediately and store it in a secure location. If you lose the token, you'll need to create a new one.

Step 2: Make Your First API Request

All API requests require authentication using a Bearer token in the Authorization header.

Authentication Header Format

Authorization: Bearer YOUR_TOKEN_HERE

Example: Fetch Member List

curl -X GET "https://your-domain.com/api/admin/members" \
  -H "Authorization: Bearer YOUR_TOKEN_HERE" \
  -H "Accept: application/json"

Example: Generate Income Summary Report

curl -X GET "https://your-domain.com/admin/reports/income-summary?start_date=2026-01-01&end_date=2026-01-31" \
  -H "Authorization: Bearer YOUR_TOKEN_HERE" \
  -H "Accept: application/json"

Example Response

{
  "start_date": "2026-01-01",
  "end_date": "2026-01-31",
  "total_revenue": 45250.00,
  "payment_count": 127,
  "categories": {
    "membership_dues": 28500.00,
    "tuition": 12000.00,
    "event_revenue": 3250.00,
    "donations": 1200.00,
    "other_income": 300.00
  }
}

Available API Endpoints

The API provides access to all major system functionality. Visit /docs/api for the complete list of endpoints.

Core Resources

Resource Description Base Endpoint
Members Member profiles, contact information, and membership data /api/admin/members
Students Hebrew school student enrollment and records /api/admin/students
Invoices Invoice creation, retrieval, and management /api/admin/invoices
Payments Payment processing and history /api/admin/payments
Events Event management and RSVP tracking /api/admin/events
Reports Financial reports and analytics /admin/reports/*

Financial Reports Endpoints

Report Method Endpoint
Income Summary GET /admin/reports/income-summary
Event Revenue GET /admin/reports/event-revenue
Outstanding Balances GET /admin/reports/outstanding-balances
Aging Report GET /admin/reports/aging
Revenue by Source GET /admin/reports/revenue-by-source
Member Growth GET /admin/reports/member-growth
Tuition Revenue GET /admin/reports/tuition-revenue
Payment Methods GET /admin/reports/payment-methods
Budget vs. Actual POST /admin/reports/budget-vs-actual

Security Best Practices

🔒 Keep Your Tokens Secure

API tokens provide full admin access to your system. Treat them like passwords and follow these security practices:

Managing API Tokens

Viewing Active Tokens

Navigate to System → API Tokens to view all active tokens. Each token displays:

Revoking Tokens

To revoke a token (permanently disable API access):

  1. Go to System → API Tokens
  2. Find the token you want to revoke
  3. Click the trash icon next to the token
  4. Confirm the deletion

Note: Revoking a token is immediate and cannot be undone. Any applications using that token will immediately lose access.

Common Use Cases

1. Automated Financial Reporting

Schedule scripts to fetch financial reports and send them to stakeholders:

2. CRM Integration

Sync member data with external CRM systems:

3. Custom Dashboards

Build executive dashboards with real-time data:

4. Accounting System Integration

Sync financial data with QuickBooks or similar:

Rate Limits

To ensure system stability and fair usage, API requests are subject to rate limiting:

If you exceed these limits, you'll receive a 429 Too Many Requests response. Wait for the rate limit window to reset before making additional requests.

Response Headers

Rate limit information is included in response headers:

  • X-RateLimit-Limit - Maximum requests per window
  • X-RateLimit-Remaining - Remaining requests in current window
  • X-RateLimit-Reset - Time when the rate limit resets (Unix timestamp)

Error Handling

The API uses standard HTTP status codes and returns detailed error messages in JSON format.

Common Status Codes

Status Code Meaning Action
200 OK Request succeeded Process the response data
401 Unauthorized Invalid or missing token Check your Authorization header
403 Forbidden Token lacks required permissions Ensure you're using an admin token
404 Not Found Resource doesn't exist Verify the endpoint URL and resource ID
422 Unprocessable Entity Validation error Check the error message for details
429 Too Many Requests Rate limit exceeded Wait and retry after the reset time
500 Internal Server Error Server error Contact support if the issue persists

Error Response Format

{
  "message": "Validation error",
  "errors": {
    "email": ["The email field is required."],
    "amount": ["The amount must be greater than 0."]
  }
}

Support and Resources

📚 Additional Resources

Need Help?

If you encounter issues or have questions about API integration:

  • Check the interactive API documentation at /docs/api
  • Review the error message and status code
  • Verify your token is active in System → API Tokens
  • Contact your system administrator for assistance