Devices & device rules

Listing and reading devices (SIP accounts), creating, updating and deleting them, and the digit-manipulation rules attached to one device.

devices_get

Lists one customer's devices.

Who may call it: admin, reseller, accountant or partner, for a customer inside their own scope.

Also reachable as: /api/device_list.

Hash parameter order: user_id.

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

<page>
  <devices>
    <device>
      <device_id>3327</device_id>
      <device_type>SIP</device_type>
      <devicegroup_id>0</devicegroup_id>
      <primary_device>yes</primary_device>
      <username>1010</username>
      <secret>••••••••••••</secret>
      <ipaddr></ipaddr>
      <port>0</port>
    </device>
  </devices>
</page>

Errors: user_id is empty, User not found, Device not found (user exists, owned, but has no devices), or Dont_be_so_smart (user exists but isn't owned by the caller).

device_details_get

Every stored field of one device — not a curated subset: the handler walks every column on the row.

Who may call it: admin, reseller, accountant or partner. A plain user account gets You are not authorized to view this page.

Hash parameter order: device_id, then device_u — fixed for this method (not the shared fallback list).

curl -X POST https://api.example.com/api/device_details_get \
  -d "u=admin" \
  -d "device_id=3327" \
  -d "hash=PLACEHOLDER_HASH"

Example response shape (every device column, plus a codec block — field names only, no real values):

<page>
  <user_id>3031</user_id>
  <name>1010</name>
  <username>1010</username>
  <secret>••••••••••••</secret>
  <extension>1010</extension>
  <device_type>SIP</device_type>
  <host>dynamic</host>
  <context>voiplix-from-internal</context>
  ... every other device column ...
  <codecs>
    <audio_codecs>ulaw, alaw</audio_codecs>
    <video_codecs></video_codecs>
  </codecs>
</page>

Two columns are deliberately left out of that dump: portal_password (the customer portal's own password hash) and portal_last_login_ip. Error: Access Denied (no caller), Device was not found (missing or not owned).

device_create

Creates a new device (SIP account) for a customer, with a random secret and a default or chosen extension.

Who may call it: admin, reseller, accountant or partner for a customer inside their scope, or any account creating a device for itself (user_id equal to the caller's own id).

Hash parameter order: not in the fixed-order table, so the shared list applies — in practice just description and pin, in that order, since those are the only parameters above that appear in the shared list at all.

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

<page>
  <status>device_created</status>
  <id>3400</id>
  <username>1099</username>
  <password>••••••••••••</password>
</page>

<status> is literally the word device_created on success, not a sentence. Errors include Dont_be_so_smart (owner outside the caller's scope), User was not found, CallerID must be numeric, Extension is already used, Extension is an emergency or service number, Language is invalid, and a license-limit message when the installation's device count is maxed out.

device_update

Changes settings on an existing device — only the fields you send are touched.

Who may call it: same scope rule as device_create (owner, its own owning staff account, or the device's own account).

Hash parameter order: this method has its own fixed order in the code — device, authentication, username, host, port — carried over unchanged from an older hash list. The last three overlap with parameters above; authentication and host aren't read by this handler at all, but if you happen to send them they still count towards the hash string. Simplest in practice: include only device and, if you're renaming it, username, in that order.

curl -X POST https://api.example.com/api/device_update \
  -d "u=admin" \
  -d "device=3327" \
  -d "call_limit=2" \
  -d "hash=PLACEHOLDER_HASH"

<page>
  <status>
    <success>Device successfully updated</success>
  </status>
</page>

Errors (nested the same way, as <status><error>...</error></status>): Device was not found, Username and Password cannot be the same, Password_is_too_short, Password has invalid symbols, Device name has invalid symbols, Device name is already used, Extension has incorrect format, Extension is already used, Extension is an emergency or service number, Language is invalid.

device_delete

Deletes a device. Refuses if any DID is still assigned to it — unassign first (see DIDs).

Who may call it: same scope rule as device_create/device_update.

Also reachable as: /api/device_destroy.

Hash parameter order: device (shared list — this method has no dedicated order).

curl -X POST https://api.example.com/api/device_delete \
  -d "u=admin" \
  -d "device=3400" \
  -d "hash=PLACEHOLDER_HASH"

<page>
  <status>Device was deleted</status>
</page>

Errors: Bad login, Device was not found, Dont_be_so_smart (outside scope), Device has assigned DIDs.

Device rules

A device rule rewrites the dialled or calling number on one device (the same feature as the device's Rules tab in the product). These three methods share one access check that is narrower than the rest of this page: only admin and reseller — not accountant, not a self-service device owner.

device_rules_get

Who may call it: admin or reseller.

Hash parameter order: device_id — fixed for this method.

curl -X POST https://api.example.com/api/device_rules_get \
  -d "u=admin" \
  -d "device_id=3327" \
  -d "hash=PLACEHOLDER_HASH"

<page>
  <status>
    <device_rules>
      <device_rule>
        <device_id>3327</device_id>
        <enabled>1</enabled>
        <pr_type>dst</pr_type>
        <name>Demo rule</name>
        <cut>0</cut>
        <add>9</add>
      </device_rule>
    </device_rules>
  </status>
</page>

Errors: You are not authorized to use this functionality (logged in, wrong type), Access Denied (anonymous), Device was not found, Device has no rules.

device_rule_create

Hash parameter order: device_id — fixed for this method.

curl -X POST https://api.example.com/api/device_rule_create \
  -d "u=admin" \
  -d "device_id=3327" \
  -d "name=Demo rule" \
  -d "add=9" \
  -d "hash=PLACEHOLDER_HASH"

<page>
  <status>
    <status>Rule added</status>
  </status>
</page>

Errors (same doubled shape, with <error> instead): Device was not found, name cannot be blank, both add and cut cannot be blank.

device_rule_delete

Hash parameter order: device_rule_id — fixed for this method.

curl -X POST https://api.example.com/api/device_rule_delete \
  -d "u=admin" \
  -d "device_rule_id=42" \
  -d "hash=PLACEHOLDER_HASH"

<page>
  <status>
    <status>Device rule was successfully deleted</status>
  </status>
</page>

Error: Devicerule was not found (unknown id, or the device it belongs to isn't in the caller's scope).

Check

Call devices_get for demo user 3031 and confirm devices 3327 and 3328 both come back with the extensions shown on their pages in the product.