Version: Next

Provisioning API

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 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 the Script type of handlers, they are designed for internal usage within the system.

Best practice example

Here is an example based on https://hostname/handler-endpoint usage.

Open the Provisioning API 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()

Event payload

Structure

Within notification, the handler will be called with a JSON-formatted data payload. The payload has the 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 (check Payload Samples below)

Supported events

Please note that some payload samples below contain reduced payload as they fully replicate the data structures within CoreAPI. Please refer to the respective documentation within the system interface in the Integration/CoreAPI Docs section for full format of the structure.

Clients management

Event ID – clients.create: the client has been created.

Payload sample:

{
  "event": {
    "dt": "2000-01-01T00:00:00+00:00",
    "events_id": "clients.create",
    "object_id": 12
  },
  "data": {
    "id": 12,
    "name": "My name",
    "companies_id": 3,
    ...
  }
}

Event ID – clients.update: the client's details have been updated.

Payload sample:

{
  "event": {
    "dt": "2000-01-01T00:00:00+00:00",
    "events_id": "clients.update",
    "object_id": 12
  },
  "data": {
    "id": 12,
    "name": "My changed name"
  }
}

Event ID – clients.archive: the client has been archived.

Payload sample:

{
  "event": {
    "dt": "2000-01-01T00:00:00+00:00",
    "events_id": "clients.archive",
    "object_id": 12
  },
  "data": {}
}

Event ID – clients.delete: the client has been completely deleted. Not to be confused with archived.

Payload sample:

{
  "event": {
    "dt": "2000-01-01T00:00:00+00:00",
    "events_id": "clients.delete",
    "object_id": 12
  },
  "data": {}
}

Event ID – clients.balance_zero: the client's balance became ≤ 0.

Payload sample:

{
  "event": {
    "dt": "2000-01-01T00:00:00+00:00",
    "events_id": "clients.balance_zero",
    "object_id": 12
  },
  "data": {}
}

Event ID – clients.balance_notzero: the client's balance became > 0.

Payload sample:

{
  "event": {
    "dt": "2000-01-01T00:00:00+00:00",
    "events_id": "clients.balance_notzero",
    "object_id": 12
  },
  "data": {}
}

Event ID – clients.custom_fields.update:the client's Custom Field has been updated.

Payload sample:

{
  "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"
  }
}

Accounts management

Event ID – clients.accounts.create: the account has been created.

Payload sample:

{
  "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",
    ...
  }
}

Event ID – clients.accounts.update: the account's details have been updated.

Payload sample:

{
  "event": {
    "dt": "2000-01-01T00:00:00+00:00",
    "events_id": "clients.accounts.update",
    "object_id": 12
  },
  "data": {
    "id": 12,
    "name": "My changed account"
  }
}

Event ID – clients.accounts.delete: the account has been completely deleted.

Payload sample:

{
  "event": {
    "dt": "2000-01-01T00:00:00+00:00",
    "events_id": "clients.accounts.delete",
    "object_id": 12
  },
  "data": {}
}

Subscriptions management

Event ID – clients.subscriptions.assign: the subscription has been assigned.

Payload sample:

{
  "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",
    ...
  }
}

Event ID – clients.subscriptions.activate: the subscription has been activated.

Payload sample:

{
  "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",
    ...
  }
}

Event ID – clients.subscriptions.deactivate: the subscription has been deactivated.

Payload sample:

{
  "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",
    ...
  }
}

Event ID – clients.subscriptions.renew: the subscription has been renewed.

Payload sample:

{
  "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,
    ...
  }
}

Event ID – clients.subscriptions.close: the subscription has been closed.

Payload sample:

{
  "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",
    ...
  }
}

DIDs

Event ID – dids.create: the DID has been created.

Payload sample:

{
  "event": {
    "dt": "2000-01-01T00:00:00+00:00",
    "events_id": "dids.create",
    "object_id": "123"
  },
  "data": {
    "id": 123,
    "did": "999",
    "tag": null,
    "notes": null,
    "status": "reserved",
    "hold_dt": null,
    "accounts_id": null,
    "operators_id": 1,
    "hold_next_status": "reserved",
    "clients_packages_id": null
  }
}

Event ID – dids.update: the DID has been updated.

Payload sample:

{
  "event": {
    "dt": "2000-01-01T00:00:00+00:00",
    "events_id": "dids.update",
    "object_id": "123"
  },
  "data": {
    "id": 123,
    "did": "999",
    "tag": null,
    "notes": "SOME NOTES",
    "operators_id": 1,
    "hold_next_status": "reserved",
  }
}

Event ID – dids.activate: the DID has been activated.

Payload sample:

{
  "event": {
    "dt": "2000-01-01T00:00:00+00:00",
    "events_id": "dids.activate",
    "object_id": "123"
  },
  "data": {
    "id": 123,
    "status": "active",
    "hold_dt": null,
    "accounts_id": 176,
    "clients_packages_id": 2
  }
}

Event ID – dids.stock: the DID has been put in stock.

Payload sample:

{
  "event": {
    "dt": "2000-01-01T00:00:00+00:00",
    "events_id": "dids.stock",
    "object_id": "123"
  },
  "data": {
    "id": 123,
    "status": "instock",
    "hold_dt": null,
    "accounts_id": null,
    "clients_packages_id": null
  }
}

Event ID – dids.block: the DID has been blocked.

Payload sample:

{
  "event": {
    "dt": "2000-01-01T00:00:00+00:00",
    "events_id": "dids.block",
    "object_id": "123"
  },
  "data": {
    "id": 123,
    "status": "blocked",
    "hold_dt": null,
  }
}

Event ID – dids.reserve: the DID has been reserved.

Payload sample:

{
  "event": {
    "dt": "2000-01-01T00:00:00+00:00",
    "events_id": "dids.reserve",
    "object_id": "123"
  },
  "data": {
    "id": 123,
    "status": "reserved",
    "hold_dt": null,
    "accounts_id": null,
    "clients_packages_id": null
  }
}

Event ID – dids.hold: the DID has been put on hold.

Payload sample:

{
  "event": {
    "dt": "2000-01-01T00:00:00+00:00",
    "events_id": "dids.hold",
    "object_id": "123"
  },
  "data": {
    "id": 123,
    "status": "hold",
    "hold_dt": "2024-03-13 11:35:21+0000",
  }
}

Event ID – dids.archive: the DID has been archived.

Payload sample:

{
  "event": {
    "dt": "2000-01-01T00:00:00+00:00",
    "events_id": "dids.archive",
    "object_id": "123"
  },
  "data": {
    "id": 123,
    "status": "archive",
    "hold_dt": null,
    "accounts_id": null,
    "clients_packages_id": null
  }
}

Email Rates Manager

Event ID – email_rates_manager.import: the import file has been prepared for further processing by the task specified in the Provisioning API handler settings, and the import process was stopped.

Payload sample:

{
  "data":
  {
    "mailbox":
    {
      "login": "[email protected]",
      "host": "imap.gmail.com"
    },
    "message":
    {
      "from": "Sender <[email protected]>",
      "id": "77798",
      "subject": "Subject of the message"
    },
    "queue":
    {
      <IMPORT_QUEUE> (see importd.process_success method for extra details)
    }
  },
  "event":
  {
    "dt": "2022-01-24T15:44:47.216756+00:00",
    "events_id": "email_rates_manager.import",
    "object_id": "77798"
  }
}

Event ID – email_rates_manager.rate_tables_no_match: no Rate Tables match received email.

Payload sample:

{
  "data":
  {
    "credentials":
    {
      "login": "[email protected]",
      "host": "imap.gmail.com"
    },
    "message":
    {
      "from": "Sender <[email protected]>",
      "id": "77798",
      "subject": "Subject of the message"
    }
  },
  "event":
  {
    "dt": "2022-01-24T15:44:47.216756+00:00",
    "events_id": "email_rates_manager.rate_tables_no_match",
    "object_id": "77798"
  }
}

Event ID – email_rates_manager.no_attachments: no attachments have been identified.

Payload sample:

{
  "data":
  {
    "credentials":
    {
      "login": "[email protected]",
      "host": "imap.gmail.com"
    },
    "message":
    {
      "from": "Sender <[email protected]>",
      "id": "77798",
      "subject": "Subject of the message"
    },
    "rate_tables":
    [
      {
        "id": 74,
        "name": "Rate Table A"
      },
      {
        "id": 7,
        "name": "Rate TAble B"
      }
    ]
  },
  "event":
  {
    "dt": "2022-01-24T15:44:47.216756+00:00",
    "events_id": "email_rates_manager.no_attachments",
    "object_id": "77798"
  }
}

Event ID – email_rates_manager.file_processing_error: the file processing error.

Payload sample:

{
  "data":
  {
    "error":
    {
      "code": "incorrect-file-ext",
      "message": "Can't process file: /opt/jerasoft/vcs-data/files/xJv/xJv5aMoqMKoNK1s2hwlJ8ik4bF3aiMVi (test_import_9999.zip). File is not a zip file"
    },
    "credentials":
    {
      "login": "[email protected]",
      "host": "imap.gmail.com"
    },
    "message":
    {
      "from": "Sender <[email protected]>",
      "id": "77798",
      "subject": "Subject of the message"
    },
    "rate_tables":
    [
      {
        "id": 74,
        "name": "Rate Table A"
      },
      {
        "id": 7,
        "name": "Rate TAble B"
      }
    ]
  },
  "event":
  {
    "dt": "2022-01-24T15:44:47.216756+00:00",
    "events_id": "email_rates_manager.no_attachments",
    "object_id": "77798"
  }
}

Import Manager

Event ID – importd.process_success: the import attempt was successful.

Payload sample:

{
  "data":
  {

    "main": {
<IMPORT_CONFIG>
    },

    "queue": {
<IMPORT_QUEUE>
    }

  },

  "event":
  {
    "dt": "2022-07-14T13:12:02.918034+00:00",
    "events_id": "importd.process_success",
    "object_id": "62"
  }
}

Event ID – importd.process_failed: the import attempt has failed.

Payload sample:

{
  "data":
  {
    "main": <IMPORT_CONFIG>
    "queue": <IMPORT_QUEUE>
  },
  "event":
  {
    "dt": "2022-07-14T13:12:02.918034+00:00",
    "events_id": "importd.process_failed",
    "object_id": "62"
  }
}

Charges

Event ID – accounting.charges.create: the Transaction of Type "Charge" has been created.

Payload sample:

{
  "data":
  {
    "id": 2220,
    "c_dt": "2022-07-06 00:00:00+0000",
    "tags": [],
    "type": "charge",
    "notes": "t",
    "taxes": null,
    "amount": 10,
    ...
  },
  "event":
  {
    "dt": "2022-07-22T11:41:09.253251+00:00",
    "events_id": "accounting.charges.create",
    "object_id": "2220"
  }
}

Event ID – accounting.charges.delete: the Transaction of Type "Charge" has been removed.

Payload sample:

{
  "data": [],
  "event":
  {
    "dt": "2022-07-22T11:41:44.650430+00:00",
    "events_id": "accounting.charges.delete",
    "object_id": "2220"
  }
}

Event ID – accounting.charges.update: the Transaction of Type "Charge" has been edited.

Payload sample:

{
  "data":
  {
    "id": 2220,
    "c_dt": "2022-07-06 00:00:00+0000",
    "tags": [],
    "type": "charge",
    "notes": "t_1",
    "taxes": null,
    "amount": 10,
    ...
  },
  "event":
  {
    "dt": "2022-07-22T11:41:27.298884+00:00",
    "events_id": "accounting.charges.update",
    "object_id": "2220"
  }
}

Payments

Event ID – accounting.payments.create: the Transaction of Type "Payment" has been created.

Payload sample:

{
 "data":
  {
    "id": 2223,
    "c_dt": "2022-07-14 00:00:00+0000",
    "tags": [],
    "type": "payment",
    "notes": "test",
    "taxes": null,
    "amount": 1,
    "status": "approved",
    ...
  },
 "event":
  {
    "dt": "2022-07-22T11:49:41.212852+00:00",
    "events_id": "accounting.payments.create",
    "object_id": "2223"
  }
}

Event ID – accounting.payments.delete: the Transaction of Type "Payment" has been removed.

Payload sample:

{
  "data": [],
  "event":
  {
    "dt": "2022-07-22T11:49:53.178009+00:00",
    "events_id": "accounting.payments.delete",
    "object_id": "2223"
  }
}

Event ID – accounting.payments.update: the Transaction of Type "Payment" has been edited.

Payload sample:

{
  "data":
  {
    "id": 2223,
    "c_dt": "2022-07-14 00:00:00+0000",
    "tags": [],
    "type": "payment",
    "notes": "test",
    "taxes": null,
    "amount": 10,
    ...
  },
  "event":
  {
    "dt": "2022-07-22T11:49:45.263719+00:00",
    "events_id": "accounting.payments.update",
    "object_id": "2223"
  }
}

tip

For more information about configuring and monitoring the hooks for Provisioning API, visit our respective article in User Guide.
If you need to process some of the actions that are not listed here, contact our support for a feature request.

Handlers​

Event payload​

Structure​

Supported events​

Clients management​

Accounts management​

Subscriptions management​

DIDs​

Email Rates Manager​

Import Manager​

Charges​

Payments​

Handlers

Event payload

Structure

Supported events

Clients management

Accounts management

Subscriptions management

DIDs

Email Rates Manager

Import Manager

Charges

Payments