The API

Voiplix has its own HTTP API — a set of named methods under /api/<method>, called with plain GET/POST parameters and answered in XML (or HTML). If you already integrate against another telephony billing system's REST/XML API, this one will feel familiar.

What it is

Every call is a request to one method — /api/user_login, /api/active_calls_get, and so on — with parameters as query string or POST body fields. There is no separate API version or GraphQL-style schema: the method name in the URL is the operation.

Two kinds of calls exist:

  • Login (user_login) — a username and password, nothing signed.
  • Everything else — a username and a hash signature built from the call's parameters and the installation's secret key, proving the caller knows the secret without sending it on every request.

Enabling it

In the sidebar, go to System > Settings and select the REST/XML-API quick-link button (admin only, or an account with the API settings permission).

REST/XML-API settings — disabled by default, as shipped.
FieldMeaning
API enabled (Allow_API)Master switch. Off by default — every call is refused until this is Yes.
Allow GET requests (Allow_GET_API)Left at No (POST only), GET calls are refused — a sensible default, since GET parameters end up in server logs and browser history.
Disable hash checking (API_Disable_hash_checking)Leave at No (hash required). Setting it to Yes accepts unsigned calls — the setting's own label calls this out as insecure.
Response as text/xml (XML_API_Extension)Whether responses are served as text/xml or text/html. Either way the body is the same XML.
API Secret KeyThe shared secret used to sign every non-login call. At least 6 characters. Masked on this wiki.
Warning

Anyone who knows the API Secret Key can sign requests as this installation. Treat it like a password — do not paste it into a support ticket or a public script.

The hash signature

For every call except user_login, the server rebuilds the same signature and compares it to the hash parameter you send. To build it yourself:

  1. Take the method's parameter values, in a fixed order — each method that needs one defines its own list; everything else falls back to one global order.
  2. Concatenate those values, with nothing between them.
  3. Append the API Secret Key.
  4. Take the SHA1 hex digest of the result — that is the hash parameter.

You rarely need to do this by hand: the same page has a built-in Hash generator — enter the method and its parameters, and it computes the signature for you using the secret key already saved above.

The built-in hash generator — paste in a method and its parameters to get the signature.

Example calls

Replace your-server.example.com, api_user, YOUR_PASSWORD and YOUR_API_SECRET_KEY with your own values. Every call should go over HTTPS — the login call in particular sends the password as plain text in the request body.

1. Log in

curl -X POST https://your-server.example.com/api/user_login \
  -d "u=api_user" \
  -d "p=YOUR_PASSWORD"

No hash needed for this one call. A successful response is XML describing the account (including its uniquehash, usable with some methods in place of a username).

2. A signed data call

active_calls_get needs one parameter, u (the username) — so its signature is simply SHA1(u_value + secret_key):

curl -X POST https://your-server.example.com/api/active_calls_get \
  -d "u=api_user" \
  -d "hash=THE_SHA1_HASH_FROM_STEP_ABOVE"

Compute THE_SHA1_HASH_FROM_STEP_ABOVE with the Hash generator (method active_calls_get, one parameter u=api_user) rather than by hand — it already knows which parameters each method requires and in what order.

Tip

If a call is refused, the XML body says why in plain words — "API Requests are disabled", "GET Requests are disabled", "API must have Secret Key" or "Incorrect hash" — check that message before assuming the method name is wrong.

Check

After switching API enabled to Yes and saving a secret key, try the login call above from a terminal (not a browser address bar, so the password is not left in your browser history) and confirm you get back an XML response rather than an error message.