Docs for all releases
View User Guide 3.26 or visit our current documentation home page.
The Provisioning API provides a mechanism for real-time integration with 3rd party systems, including softswitches, gateways, and CRM systems. The mechanism calls pre-defined handlers on the occurrence of specific events in the system.
While Core API and Management API sub-systems answer to requests, Provisioning API pushes data as soon as an event occurs. For example, you can monitor the client's balance status via this functionality. Thus, when the client's balance is below zero, you can configure the system to send a notification to an external system to avoid any disruptions to your organization's current processes.
Handlers
A typical handler should be configured as is HTTPS or HTTP with an URL of the script, which will get HTTP POST requests about each event occurrence.
Please avoid using Script type of the handlers, they are designed for internal usage within the system.
Best practice example
There is an example based on https://hostname/handler-endpoint usage.
Open the Provisioning section and start creating a handler.
- Specify the name, type, and status.
- In the Event field, select Clients Create event from the drop-down list.
- In the Task field, indicate HTTPS type and define the URL for the handler, for example, my-domain.org/api.
- Click Apply.
Find an example of the http://handler below:
from flask import Flask, request import json app = Flask(__name__) @app.route("/api", methods=['GET', 'POST']) def api(): data = json.loads(request.data) return json.dumps(data) if __name__ == "__main__": app.run()
Supported Events
The Provisioning API supports the following list of events:
- Clients
- clients.create
- clients.update
- clients.archive
- clients.delete
- clients.balance_zero
- clients.balance_notzero
- clients.custom_fields.update
- Accounts
- clients.accounts.create
- clients.accounts.update
- clients.accounts.delete
- Subscriptions
- clients.subscriptions.assign
- clients.subscriptions.activate
- clients.subscriptions.deactivate
- clients.subscriptions.renew
- clients.subscriptions.close
- Email Rates Manager
- email_rates_manager.import
- Import Manager
- importd.process_success
- importd.process_failed
Payload Structure
During notification the handler will be called with JSON-formatted data payload. The payload has following structure:
event
dt
- the date-time of the event in the ISO8601 format;events_id
- ID of the event occurred (helpful, when multiple events are handled by the same handler);object_id
- the entity, to which the event happened;
data
- data related to the specific event.
{ "event": { "dt": "2000-01-01T00:00:00+00:00", "events_id": "clients.update", "object_id": 12 }, "data": { "id": 12, "field": "some-value" } }
The clients.accounts.delete
, clients.archive
, clients.balance_notzero
, clients.balance_zero
, and clients.delete
events send empty data: {} (as we send the event info, there is no need to duplicate it in data).
Note
The clients.custom_fields_update
event has been renamed to clients.custom_fields.update
starting from JeraSoft Billing v3.23 for consistency.
Payload Details
Clients
Actions:
- create
{ "event": { "dt": "2000-01-01T00:00:00+00:00", "events_id": "clients.create", "object_id": 12 }, "data": { "id": 12, "name": "Customer A", "companies_id": 67, "currencies_id": 10, ... } }
- update
{ "event": { "dt": "2000-01-01T00:00:00+00:00", "events_id": "clients.update", "object_id": 12 }, "data": { "id": 12, "name": "My changed name" } }
- delete
{ "event": { "dt": "2000-01-01T00:00:00+00:00", "events_id": "clients.delete", "object_id": 12 }, "data": {} }
- archive
{ "event": { "dt": "2000-01-01T00:00:00+00:00", "events_id": "clients.archive", "object_id": 12 }, "data": {} }
- custom fields update
{ "event": { "dt": "2000-01-01T00:00:00+00:00", "events_id": "clients.custom_fields.update", "object_id": 12 }, "data": { "id": 12, "custom-field-name": "custom-field-value" } }
- balance became >=0
{ "event": { "dt": "2000-01-01T00:00:00+00:00", "events_id": "clients.balance_notzero", "object_id": 12 }, "data": {} }
- balance became <=0
{ "event": { "dt": "2000-01-01T00:00:00+00:00", "events_id": "clients.balance_zero", "object_id": 12 }, "data": {} }
Accounts
Actions:
- create
{ "event": { "dt": "2000-01-01T00:00:00+00:00", "events_id": "clients.accounts.create", "object_id": 12 }, "data": { "id": 12, "clients_id": 7, "name": "My account", "auth_type": "name", ... } }
- update
{ "event": { "dt": "2000-01-01T00:00:00+00:00", "events_id": "clients.accounts.update", "object_id": 12 }, "data": { "id": 12, "name": "My changed account" } }
- delete
{ "event": { "dt": "2000-01-01T00:00:00+00:00", "events_id": "clients.accounts.delete", "object_id": 12 }, "data": {} }
Subscriptions
Actions:
- assign
{ "event": { "dt": "2000-01-01T00:00:00+00:00", "events_id": "clients.subscriptions.assign", "object_id": 12 }, "data": { "id": 12, "clients_id": 34, "packages_id": 56, "stop_dt": "2023-01-01T00:00:00+00:00", ... } }
- activate
{ "event": { "dt": "2000-01-01T00:00:00+00:00", "events_id": "clients.subscriptions.activate", "object_id": 12 }, "data": { "id": 12, "clients_id": 34, "packages_id": 56, "stop_dt": "2023-01-01T00:00:00+00:00", "condition": "activated", ... } }
- deactivate
{ "event": { "dt": "2000-01-01T00:00:00+00:00", "events_id": "clients.subscriptions.deactivate", "object_id": 12 }, "data": { "id": 12, "clients_id": 34, "packages_id": 56, "stop_dt": "2023-01-01T00:00:00+00:00", "condition": "deactivated", ... } }
- renew
{ "event": { "dt": "2000-01-01T00:00:00+00:00", "events_id": "clients.subscriptions.renew", "object_id": 12 }, "data": { "id": 12, "clients_id": 34, "packages_id": 56, "stop_dt": "2023-01-01T00:00:00+00:00", "renew_count": 1, ... } }
- close
{ "event": { "dt": "2000-01-01T00:00:00+00:00", "events_id": "clients.subscriptions.close", "object_id": 12 }, "data": { "id": 12, "clients_id": 34, "packages_id": 56, "stop_dt": "2000-01-01T00:00:00+00:00", ... } }
Tip
- For more information about configuring and monitoring the hooks for Provisioning API, visit our respective article User Guide > System > Provisioning API.
- If you need to process some of the actions that are not listed here, contact our support for a feature request.