NUACOM API

Users & structure

Teams

A team is a named group of users in the account. Teams label users rather than extensions: they decide which call tags a user may see, where a conversation can be assigned, who receives the AI call recap email and which extensions the availability report shows. This group holds the v3 team list and the create, read, update and delete endpoints, plus, under Teams / Users, the membership endpoints. The v2 Departments endpoints work on the same records under their older name, so a team id here is a department id there.

Workflow (what the portal does)

  1. List: GET /v3/teams with page (15 teams per page; per_page is not read), sort (id or -id; id by default) and include: usersCount fills users_count, users embeds the full member list, team embeds a preview of at most three members. The response is {"data": [...], "links": {...}, "meta": {...}}; each team is id, name and users_count (null unless you include it). An unknown include or sort answers 400.
  2. Create: POST /v3/teams with name (required, at most 20 characters) and optional members, an array of user ids. Every id must be a user of your account whose membership has not been deleted; otherwise 422 with One or some of the provided users does not belong to this account.. Answers 201 with the team's id and name. Pick the ids from GET /v3/users (see Users).
  3. Read: GET /v3/teams/{teamId} answers id, name, users_count and users, the members as user rows (user_id, user_name, user_email, mobile, extension, user_active, last_login). An unknown id, or a team of another account, answers 404.
  4. Rename or replace the members: PUT /v3/teams/{teamId} takes the same body as create. members replaces the whole membership, and a request without members empties the team. Answers 200 with id and name.
  5. One member at a time: GET /v3/teams/{teamId}/users lists the members, 15 per page, as the user rows above; PUT /v3/teams/{teamId}/users/{user} adds the user (no body) and answers 200 with the team and its new users_count; DELETE /v3/teams/{teamId}/users/{user} removes them and answers 204. A {user} who is not a member of your account answers 404. The same membership is edited from the user's side with user.departments on PUT /v3/users/{user}.
  6. Delete: DELETE /v3/teams/{teamId} answers 204.

What a team does

Teams are used by reference, through their id, in these places:

  • Users: every row of GET /v3/users and the profile in GET /v3/users/{user} carry departments, the user's teams as id and name.
  • Call tags: a tag with the visibility rule {"type": 2, "allowed_id": <team id>} is shown only to the members of that team — see Call Tags.
  • Conversations: an SMS or WhatsApp conversation can be assigned to a team (department_id on the assign endpoint, assigned_department_id on the conversation), and the auto-assignment rules can target a team — see Conversations.
  • Extension activity: the availability report in Extensions takes departmentId and keeps only the extensions of that team's members.
  • AI call recaps: the recipients of the recap email are user ids and team ids written as d<id> — see Account.

A team owns no extension, number or queue. Whatever applies to a team applies to the extensions of its members: a user has at most one extension per account, so a team's extensions are its members' extensions.

Roles and access

  • Every endpoint in this group, writes included, is open to any authenticated user of the account; none requires an account admin. The v2 Departments endpoints, by contrast, allow writes to admins only.
  • Teams belong to the account of the token: another account's team id answers 404, and members may name only users of your account.
  • The ISO dates option (per account) changes the last_login format in member rows — see Dates and timezones.

Pitfalls

  • PUT /v3/teams/{teamId} is a full replacement: a body with only name removes every member. Send the complete members list, or use the per-member endpoints.
  • Team names are not unique: two teams can share a name, so key your data on id.
  • users_count is null on the list unless you add include=usersCount, and null on the create and update answers; users is present only on GET /v3/teams/{teamId} and with include=users.
  • include=team is a preview capped at three members per team; use include=users or the members endpoint for the full list.
  • The page size is fixed at 15; per_page is ignored.
  • Adding a user who is already a member answers 200 and changes nothing; removing a user who is not a member answers 204.
  • Validation errors answer 422 as {"errors": {...}}.
  • The same number identifies a team everywhere: id here, {department} in the v2 endpoints, allowed_id in call tag visibility and d<id> in the AI recap recipients.