NUACOM API

Users & structure

Users

A user is a person who signs in to the NUACOM portal and apps: a name, email, mobile number and timezone, plus one membership per account they belong to that carries the account-level settings — admin or regular user, portal access, mobile extension, call-recording access, status and permissions. This group holds the legacy pair GET /v2/users_list and GET /v2/user_info and the v3 family: the paginated list, one user, the update, and the caller's own profile. A user is linked to at most one extension per account (managed in Extensions) and belongs to any number of teams; creating, suspending and deleting users is done in the portal.

Workflow (what the portal does)

  1. Who is calling: GET /v2/user_info answers the session context the apps load at start-up: user_id, user_name, account_id, account_name, user_country, time_zone, user_shared_accounts (the other accounts the user is active in), user_admin, recording_access, outbound_cli, user_extension (only when the user has an extension) and call_events. With an API key this describes the user the key acts as (see Authentication).
  2. My profile: GET /v3/users/me returns the caller's own user record: user_id, user_name, user_email, mobile, country_dial_code, time_zone, last_login, extension (the number, or "" when none), user_active and account (one membership row per account the user is active in).
  3. List: GET /v3/users with page and per_page (default 25, no maximum), newest first. Each row is user_id, user_name, user_email, mobile, last_login, extension, user_active and departments (the user's teams, id and name); the response is {"data": [...], "links": {...}, "meta": {...}}. Active, suspended and awaiting-activation members are listed; deleted ones are not. GET /v2/users_list is the same set as one flat, unpaginated array in the V1 shape: each row adds the membership flags (account_admin, web_access, call_recording, mobile_extension, user_active, active_in_account), country_iso_code, country_dial_code, is_auth_2fa_enabled, user_extension and outbound_cli. Two optional switches: checkAdmin=1 makes a regular user receive only their own row, and enterprise_only=true keeps only users whose extension has an Enterprise or Unlimited subscription.
  4. One user: GET /v3/users/{user} by user_id answers {"user": {...}}: the profile with its departments and an account array listing every membership the user has, each carrying the flags above. A user who is not a member of your account, or was deleted, answers 404.
  5. Edit (what the Users screen saves): PUT /v3/users/{user} with the complete form:
    • user.user_name (required, at most 64 characters), user.mobile (at most 30), user.country_dial_code (integer), user.time_zone (IANA name, at most 20 characters), user.is_auth_2fa_enabled (boolean);
    • the membership flags as 0/1: user.account_admin, user.web_access, user.mobile_extension, user.call_recording;
    • user.departments: the teams as [{"value": <team id>}] — the list replaces the user's teams;
    • pages: the ids of the portal pages the user may open — pages left out are revoked. Page ids are assigned in the portal (Settings → Users → Permissions); the API has no public catalogue of them. The answer is {"success": true}. user.extension is accepted but ignored, and permissions are not part of the form: both are set in the portal.
  6. Teams: a user's departments are the account's teams. Add or remove a member with PUT /v3/teams/{teamId}/users/{user} and DELETE /v3/teams/{teamId}/users/{user}, list a team's members with GET /v3/teams/{teamId}/users and the teams themselves with GET /v3/teams. The v2 GET /v2/departments endpoints work on the same objects under the older name.

Creating, suspending and deleting users is done in the portal (Settings → Users); there is no public endpoint for it. Deleting a user there offers to hand their private contacts to a colleague first.

Reading a user

  • Admin or regular user: account_admin on the membership (user_admin in /v2/user_info). An admin sees the whole account and may call the admin-only endpoints; a regular user sees their own extension plus what their permissions grant, and admin-only endpoints answer 403. The flag is per account: the same person can be an admin in one account and a regular user in another.
  • Call recording access: call_recording is the portal's "Call Recording Access" toggle. Through the API every user, admins included, needs it on to play recordings, and the account's recording add-on or the extension's subscription must include recording; recording_access in /v2/user_info is that combined answer.
  • Status: user_active is 0 suspended, 1 active or 2 awaiting activation (the user has not completed sign-up). Deleted users never appear.
  • Portal and mobile: web_access — may sign in to the web portal; mobile_extension — may use a mobile extension.
  • Extension: extension (v3) or user_extension (v2) is the number of the user's extension in this account, and outbound_cli the caller ID that extension presents. Linking is done by an admin in the portal's Users screen; the extension itself is managed in Extensions.
  • Timezone: time_zone is the user's IANA timezone. It is the default for every date the API formats for that user when you send no X-Timezone header.
  • last_login: null when the user has never signed in. With the account's ISO dates option the value is ISO 8601 in the X-Timezone you send, UTC by default (2024-08-28T09:15:00+01:00); without it, /v2/users_list gives wall-clock Y-m-d H:i:s and the v3 endpoints keep only the day (midnight, serialised as a UTC timestamp). See Dates and timezones.
  • Several accounts: a user may belong to more than one account. active_in_account marks the one they are currently working in, user_shared_accounts lists the others, and the account array of the v3 profile has one row per membership — pick yours by account_id.
  • API keys: a key acts as the user who created it; that user's admin flag, permissions and recording access decide what the key sees, and GET /v2/user_info with the key tells you who that is. See Authentication.

Roles and access

  • Every endpoint in this group accepts any authenticated user; none is restricted to account admins. The lists are not filtered by the caller's permissions either: a regular user sees every member, except with checkAdmin=1 on /v2/users_list.
  • The ISO dates option (per account) changes the last_login format as described above.
  • A user outside your account answers 404 from /v3/users/{user}.

Pitfalls

  • The pagination links of GET /v3/users use users= as the page parameter, but the endpoint reads page: following links.next returns the first page again. Build the URL yourself from meta.current_page and meta.last_page.
  • /v2/users_list returns user_id, user_active and country_dial_code as strings ("123", "1", "353"); the v3 endpoints return integers.
  • PUT /v3/users/{user} is a full replacement with no partial update: send every user.* field, user.departments and pages even when unchanged. A missing field fails the request with 500, not 422.
  • user.time_zone is limited to 20 characters, so longer IANA names (America/Argentina/Buenos_Aires) are rejected with 422.
  • A suspended member is listed and readable, but a PUT on them fails with 500.
  • departments is present only where the endpoint loads it: in the list and in /v3/users/{user}.
  • /v2/user_info omits user_extension and call_events rather than returning null when the user has no extension or has not enabled call events.