API reference

Welcome to the API Reference section. This guide provides all the general information you need to get started with our API.

Protocols

The API supports both REST and JSON-RPC 2.0 protocols. For each method, the following details are provided:

• REST API: Information about the HTTP method and endpoint to use.
• JSON-RPC: Method names to include in the request payload.

REST API

• URLs should be constructed as:
  • http://billing-hostname:3080/<endpoint-url>
• For example to get currencies exchange rate, you can use:
  • GET http://billing-hostname:3080/accounting/currencies/exchange-rate

JSON-RPC 2.0

• The API follows the JSON-RPC 2.0 specification.
• Use JSON-RPC method name to call the method:
  • Example: accounting.currencies.get_rate
• JSON-RPC requests should be sent as HTTP POST to:
  • http://billing-hostname:3080/
• The POST payload should include the JSON-RPC request message.

Security

The API is designed to be accessed over a secure connection, such as a VPN or a private network, to ensure the confidentiality and integrity of communication. It is the responsibility of the RPC clients to establish and maintain these secure channels when interacting with the API.

Authorization

There are two authentication mechanisms available for the API:

• API Keys (Preferred)
• JWTs (JSON Web Tokens) (Deprecated)

info

It is recommended to create a dedicated user for each of the integrations you make.

API key

API keys are the recommended authentication mechanism. To authenticate:

• Add an X-Api-Key HTTP header to each request with the value of the user's API key.
  • X-Api-Key: <API_KEY>
• API keys can be retrieved in the System / Users section by selecting a user and checking the API Key* field.
• If an invalid token is provided, the HTTP 401 status code will be returned.

JSON Web Tokens (JWTs)

warning

JWT authentication is deprecated and may be removed in the future. It is retained only for backward compatibility.

The JWT authentication process involves:

1. Authentication Request: Exchange login and password for a JWT token by calling the iam.auth.jwt.authenticate method. The response includes the token and its expiry timestamp.
2. Regular Requests: Include the token in the HTTP Authorization header:
   • Authorization: Bearer <TOKEN>
3. Token Refresh: Before the token expires, call iam.auth.jwt.refresh to obtain a new token.

If an invalid token is provided, the API will return a JSON-RPC Error Response with code -32005.

Role and Reseller settings

The Role defined for the user does not affect API requests. All methods are available to be called. However, the Reseller setting is enforced:

• For Reseller-limited entities, only entities associated with that Reseller will be accessible.
• For entities that are not limited by Reseller (e.g. Currencies), no filtering will be done.

Protocol extensions

Timezone conversion

The API supports timezone conversion for incoming and outgoing datetime values on a per-request basis. To enable this:

• Pass the __tz parameter in the request with a value in the Olson database format (e.g., America/New_York).
• If omitted, the server uses the timezone of the authenticated user (and if not set – the global system settings).
• If incoming datetime values include a timezone, the __tz parameter is ignored.

Examples

REST API

cURL

# Get details for the client #42.
curl -X GET http://billing-host:3080/clients/42 \
    -H "X-Api-Key: <API_KEY>"

# Set credit limit for client #42 to `1000`.
curl -X PATCH http://billing-host:3080/clients/42 \
    -H "X-Api-Key: <API_KEY>" \
    -d '{"credit": 1000}'

Python

import requests

# Define the base URL and API key.
BASE_URL = "http://billing-host:3080"
API_KEY = "<API_KEY>"

# Get details for the client #42.
response = requests.get(
    f"{BASE_URL}/clients/42",
    headers={"X-Api-Key": API_KEY}
)

if response.status_code == 200:
    print("Client details:", response.json())
else:
    print(f"Failed to get client details: {response.status_code} - {response.text}")

# Set credit limit for client #42 to `1000`.
response = requests.patch(
    f"{BASE_URL}/clients/42",
    headers={"X-Api-Key": API_KEY},
    json={"credit": 1000},
)

if response.status_code == 200:
    print("Credit limit updated successfully:", response.json())
else:
    print(f"Failed to update credit limit: {response.status_code} - {response.text}")

JSON-RPC

cURL

# Get details for the client #42.
curl -X POST http://billing-host:3080 \
    -H "X-Api-Key: <API_KEY>" \
    -d '{"jsonrpc": "2.0", "id": 1, "method": "clients.get", "params": {"id": 42}}'

# Set credit limit for client #42 to `1000`.
curl -X POST http://billing-host:3080 \
    -H "X-Api-Key: <API_KEY>" \
    -d '{"jsonrpc": "2.0", "id": 1, "method": "clients.update", "params": {"id": 42, "credit": 1000}}'

Python

import requests

# Define the base URL and API key.
API_URL = "http://billing-host:3080"
API_KEY = "<API_KEY>"

# Get details for the client #42.
response = requests.post(
    API_URL,
    headers={"X-Api-Key": API_KEY},
    json={
        "jsonrpc": "2.0",
        "id": 1,
        "method": "clients.get",
        "params": {
            "id": 42,
        },
    },
)

if response.status_code == 200:
    result = response.json()
    if "result" in result:
        print("Client details:", result["result"])
    else:
        print("Error in response:", result.get("error", "Unknown error"))
else:
    print(f"Failed to get client details: {response.status_code} - {response.text}")


# Set credit limit for client #42 to `1000`.
response = requests.post(
    API_URL,
    headers={"X-Api-Key": API_KEY},
    json={
        "jsonrpc": "2.0",
        "id": 1,
        "method": "clients.update",
        "params": {
            "id": 42,
            "credit": 1000,
        },
    },
)

if response.status_code == 200:
    result = response.json()
    if "result" in result:
        print("Credit limit updated successfully:", result["result"])
    else:
        print("Error in response:", result.get("error", "Unknown error"))
else:
    print(f"Failed to update credit limit: {response.status_code} - {response.text}")