Users & balance

Listing accounts, reading one account's details, checking a balance four different ways, and topping up or deducting a balance.

users_get

Lists the accounts the caller manages.

Who may call it: admin, reseller, accountant or partner accounts. A plain user account gets Access Denied.

Note

This is the one method that checks a real password instead of just a username: p must be the caller's own account password, not the customer's. It's a separate, older login path baked into this one method — the hash below is still required on top of it.

Parameter	Required	In hash	Meaning
`u`	Yes	1st	Caller's own username.
`p`	Yes	2nd	Caller's own password, plain text.

Hash parameter order: u, then p — this is one of the few methods where u itself is part of the hash.

curl -X POST https://api.example.com/api/users_get \
  -d "u=admin" \
  -d "p=YOUR_PASSWORD" \
  -d "hash=PLACEHOLDER_HASH"

Example response shape:

<page>
  <status>
    <users>
      <user>
        <id>3031</id>
        <username>democompany</username>
        <first_name>...</first_name>
        <last_name>...</last_name>
        <balance>0.000000000000000</balance>
        <blocked>0</blocked>
        <lcr_id>349</lcr_id>
        <tariff_id>593</tariff_id>
        <owner_id>0</owner_id>
        <usertype>user</usertype>
      </user>
      ...
    </users>
  </status>
</page>

Empty scope answers <status><error>No Users found</error></status>.

Users list in the product: username, name, type, tariff, balance and status columns for every account the caller manages. — The Users list — the same accounts `users_get` returns, with the same fields.

user_details_get

The full profile of one account: master data, address, balance, credit limit, invoice preferences and warning-e-mail settings.

Who may call it: any account type, for its own profile. An admin or reseller can also read a different account inside their own scope by passing user_id or username.

Parameter	Required	In hash	Meaning
`u`	Yes	—	Caller's username.
`user_id`	No	1st	Admin/reseller only: numeric id of the account to look up instead of the caller's own.
`username`	No	2nd	Admin/reseller only: username of the account to look up instead of `user_id`.

Hash parameter order: user_id, then username — only the ones you send.

curl -X POST https://api.example.com/api/user_details_get \
  -d "u=admin" \
  -d "user_id=3031" \
  -d "hash=PLACEHOLDER_HASH"

Example response shape (trimmed):

<page>
  <pagename>Personal_details</pagename>
  <language>en</language>
  <userid>3031</userid>
  <details>
    <main_detail>
      <account>Prepaid</account>
      <balance>0.00 EUR</balance>
      <balance_number>0.000000000000000</balance_number>
      <balance_currency>EUR</balance_currency>
      <credit>0.000000000000000</credit>
      <blocked>0</blocked>
      <hidden>0</hidden>
    </main_detail>
    <other_details>
      <username>democompany</username>
      <first_name>...</first_name>
      <surname>...</surname>
      ...
    </other_details>
    <registration>...</registration>
    <invoices>...</invoices>
    <warning_balance>...</warning_balance>
  </details>
</page>

Note the top-level tag is a bare <error>, not <status><error>, for this method's failure case (Access Denied or User was not found).

user_balance_get

Looks up one account's balance by username, with an optional currency conversion.

Note

This method is unusual: it never reads u at all. The account named in username is the caller — its own Allow_API switch and API Secret Key are what get checked, not an admin's. It's built for a single customer's own device or script to ask "what's my balance", not for a staff account to look someone else up (use user_details_get or users_get for that).

Also reachable as: /api/balance.

Only answers at all if the installation has switched on balance-checking (the confline Devices_Check_Ballance); otherwise every variant below — this one and the three plain-text ones — answers Feature_Disabled / Feature disabled instead of a number.

Parameter	Required	In hash	Meaning
`username`	Yes	1st	The account to look up — also the account whose API settings apply.
`currency`	No	2nd	A currency name to convert into, or `USER` to use the account's own currency.
`user_currency`	No	—	`1` also converts to the account's own currency and adds a `<currency>` tag to the response.

Hash parameter order: username, then currency.

curl -X POST https://api.example.com/api/user_balance_get \
  -d "username=democompany" \
  -d "hash=PLACEHOLDER_HASH"

<page>
  <balance>12.50</balance>
</page>

Failure: <page><error>Feature_Disabled</error></page> or <page><error>User_Not_Found</error></page> — both literal, untranslated keys, not sentences.

The three plain-text balance lookups

Built for a phone display or a one-line script: no hash, no u — the token you send is the credential. Content type is text/plain: just the number, or one of the error strings below, with no XML around it. All three still need Allow_API switched on for the account they resolve to (and, for a GET request, Allow GET requests too) — only the hash step is skipped.

Method	Bearer parameter	Optional	Looked up by
`user_simple_balance_get` also `/api/simple_balance`	`id` = the account's `uniquehash` (shown after a successful `user_login`)	`currency`	uniquehash
`user_balance_get_by_psw`	`id` = a device's SIP secret	—	device secret → its owning account
`user_balance_get_by_username`	`id` = a device's SIP username and `secret` = that device's SIP secret (both required)	`currency` (or `USER` for the account's own currency)	device username + secret → its owning account

curl "https://api.example.com/api/user_simple_balance_get/DEMO_UNIQUEHASH"

Response body on success: just 12.500000000000000 — no tags. On failure, the exact text differs by method (worth matching literally, not just checking for "not found"):

Method	Feature switched off	Not found
`user_simple_balance_get`	`Feature_Disabled`	`User_Not_Found`
`user_balance_get_by_psw`	`Feature_Disabled`	`User_Not_Found`
`user_balance_get_by_username`	`Feature disabled` (space, lower-case)	`User was not found` (a full sentence)

Warning

Those three failure strings really are inconsistent between the two methods — it isn't a typo in this reference. Match each method against its own exact string, or just check whether the body parses as a number.

user_balance_update

Adds to (or subtracts from) a customer's balance. This is a delta, not a new absolute balance — sending balance=10 adds 10 to whatever the account already has.

Who may call it: admin, reseller or partner, to change the balance of a customer inside their own scope.

Also reachable as: /api/user_balance_change.

Parameter	Required	In hash	Meaning
`u`	Yes	—	Caller's username (admin or reseller).
`user_id`	Yes	1st	Numeric id of the customer, must belong to the caller.
`balance`	Yes	2nd	The amount to add — a negative number subtracts. Digits, one optional leading `+`/`-`, one optional decimal point.

Hash parameter order: user_id, then balance.

curl -X POST https://api.example.com/api/user_balance_update \
  -d "u=admin" \
  -d "user_id=3031" \
  -d "balance=10.00" \
  -d "hash=PLACEHOLDER_HASH"

<page>
  <status>User balance updated</status>
  <user>
    <username>democompany</username>
    <id>3031</id>
    <balance>10.000000000000000</balance>
  </user>
</page>

Failures: Bad login (no caller), User was not found (wrong or unowned user_id), or — reproduced exactly as the product sends it, typo included — User balance not updeted when balance isn't a valid number.

Check

Call user_balance_get (or one of the plain-text variants) for a demo account and confirm the number matches what the Users list shows for that account in the product itself.