NUACOM API

Users & structure

Extensions

An extension is a SIP line on the account: a number in the range 10–9999, a display name, a subscription tier, an optional linked user and device. This group lists extensions, creates and deletes them and sets their live status; pricing previews, pre-pay creation and tier changes sit in the Extensions / Subscriptions group next to it. Per-extension settings such as voicemail, call handling and caller-ID preselection are set in the portal.

Workflow (what the portal does)

  1. List: GET /v2/extensions answers a plain array of {number, name, extension_is_used, subscription}. An admin sees the whole account; a regular user sees their own extension and the ones granted to them.
  2. Caller-ID numbers: GET /v2/extensions/available-cli lists the account's numbers an extension can present. GET /v2/user_info gives the calling user's profile and outbound CLI.
  3. Create (account admin): pick a tier from GET /v2/subscriptions, then
    • bill-pay and trial accounts call POST /v2/extensions/store with from, to (at most ten numbers per call), subscription_id and callerID;
    • pre-pay accounts buy the licences first in the portal, and create the extensions once the payment is confirmed.
  4. Subscriptions (account admin): add-subscription for an extension without one, change-subscription to move tiers. DELETE /v2/extensions/{extNumber}/subscription cancels the subscription and deletes the extension.
  5. Rename: PUT /v2/extensions/{extNumber}/set-name.
  6. Delete (account admin): DELETE /v2/extensions with an extensions[] body. An extension with a provisioned device cannot be deleted this way (422), and at least two extensions must remain (400).
  7. Queues: POST /v2/extensions/set-dynamic-agent-queue-status logs an extension in or out of a queue (queue, extension, action).
  8. Availability report: GET /v2/extension-activity returns each extension's online sessions for a date, optionally filtered by departmentId (from GET /v2/departments) or extensions.

Linking an extension to a user is done by an admin in the portal's Users screen.

Creating an extension

flowchart TD
    tier["GET /v2/subscriptions: pick a tier"] --> type{"Account type"}
    type -- "bill-pay or trial" --> billpay["POST /v2/extensions/store<br/>from, to, subscription_id, callerID"]
    billpay --> billready["Extension created"]
    type -- "pre-pay" --> buy["Buy the licences in the portal"] --> prepayready["Create the extensions once paid"]

Roles and access

  • Creating, deleting, renaming, changing subscriptions, pricing previews and the status endpoint require an account admin (403 otherwise).
  • Listing, the caller-ID lookups, the agent queue status (for your own extension) and the availability report are open to any authenticated user.
  • The ISO dates option switches the availability report's timestamps to ISO 8601.

Pitfalls

  • Numbers 112, 171, 777 and 999 are reserved. In a from–to range, numbers already taken are skipped silently; you only get an error when none is left.
  • callerID is copied as sent and is not validated. Use a number from available-cli.
  • Pre-pay creation and tier changes are asynchronous: 204 means the payment was accepted, not that the extension exists yet. Poll the list.
  • Pre-pay downgrades take effect on the first day of the next month; pre-pay upgrades are paid in the portal's checkout.
  • Cancelling a subscription deletes the extension, including its device link, voicemail and queue membership.
  • status values are case-sensitive: Busy or Active.
  • SIP credentials are never returned by the API; they are shown in the portal.
  • The availability report is account-wide: it is not filtered by the caller's permissions.