API Reference

Note

Building a theme or module? Use the JavaScript wrapper instead of raw API calls when possible. It handles common boilerplate and tracks platform changes more gracefully.

Overview

FOSSBilling provides a REST API for integrating external systems and building custom functionality on top of the platform.

Tip

This API reference is evolving. For additional details, you can also refer to the BoxBilling API documentation — there have been no major breaking changes since the fork.

API Endpoints

Three main entrypoints:

Endpoint	Access Level	Purpose
/api/admin/*	Admin only	System management
/api/client/*	Authenticated clients	Client services
/api/guest/*	Public	No authentication needed

Request Format

• Method: All requests use POST
• Format: JSON for both request and response
• Naming: Lowercase with underscores (change_password)
• Nulls: Blank fields are included as null, not omitted
• Dates: ISO 8601 format

Authentication

Use HTTP Basic Auth with base64 encoding:

• Username: admin or client (depending on endpoint)
• Password: Your API key (found in client profile or admin dashboard)

Authorization: Basic base64_encode('admin:YOUR_API_KEY')

Most HTTP clients (curl, Postman) handle the encoding automatically.

Example Requests

curl

curl -X POST "https://example.com/api/admin/staff/create" \
  -H "Authorization: Basic $(echo -n 'admin:YOUR_API_KEY' | base64)" \
  -H "Content-Type: application/json" \
  -d '{
    "email": "hello@fossbilling.org",
    "password": "Testing123+",
    "name": "John Doe",
    "admin_group_id": 1,
    "status": "active"
  }'

Python

import requests
from requests.auth import HTTPBasicAuth

url = "https://example.com/api/admin/staff/create"
api_key = "YOUR_API_KEY"

payload = {
    "email": "hello@fossbilling.org",
    "password": "Testing123+",
    "name": "John Doe",
    "admin_group_id": 1,
    "status": "active"
}

auth = HTTPBasicAuth('admin', api_key)
headers = {"Content-Type": "application/json"}

response = requests.post(url, json=payload, auth=auth)
print(response.json())

Node.js

Run admin API calls from trusted server-side code only. Never expose an admin API key in browser JavaScript.

const url = "https://example.com/api/admin/staff/create";
const apiKey = "YOUR_API_KEY";

const payload = {
  email: "hello@fossbilling.org",
  password: "Testing123+",
  name: "John Doe",
  admin_group_id: 1,
  status: "active"
};

const headers = new Headers();
headers.set("Content-Type", "application/json");
headers.set("Authorization", "Basic " + Buffer.from("admin:" + apiKey).toString("base64"));

fetch(url, {
  method: "POST",
  headers: headers,
  body: JSON.stringify(payload)
})
.then(response => response.json())
.then(data => console.log(data))
.catch(error => console.error("Error:", error));

Response Format

Success:

{
  "result": { ... },
  "error": null
}

Error:

{
  "result": null,
  "error": {
    "message": "Error description",
    "code": 123
  }
}

Common Patterns

Endpoint Structure

/api/{role}/{module}/{action}

Examples:

• /api/admin/client/get_list
• /api/client/profile/get
• /api/guest/system/version

Pagination

List endpoints typically accept:

• page — Page number (starting at 1)
• per_page — Items per page

---

For assistance, join our Discord community.