Creating and Managing AMS via API

This article walks you through the first setup path for AMS using the public API: create users, create departments, link users to departments, then assign permission groups (roles).

Before you start

Required API permissions

• write_users (create users)
• write_departments (create departments)
• write_user_department (assign departments to users)
• read_groups (list permission groups)
• write_permission_user (assign permission groups to users)

Setup order

1. Step 1  Create users
2. Step 2  Create departments
3. Step 3  Assign departments to users
4. Step 4  List available permission groups
5. Step 5  Assign permission groups to users

Step 1  Create users

Create user login entities (accounts) that can later be placed into departments and permission groups. On creation, each user returns an ID which you’ll use in later steps.

Key notes

• Creating a user only creates the login entry. To make them functional, you must assign at least one permission group in Step 5.
• An initial “User Profile” is created with only name and surname.
• Company handling: If your current API user already has a company assigned, the company_id you pass may be ignored and set to your company. If your API user does not have a company (common in initial setup), company_id must match an existing company.
• OTP: set mail_otp to 1 to enable OTP, 0 to disable.
• If the company preference send_email_on_user_account_created is not 0, the user will receive an email to set their password (recommended when you’re ready to onboard).

Permission required: write_users

Example request body

{
  "name": "My Name",
  "surname": "My Surname",
  "email": "my.email@test.net",
  "company_id": 24,
  "mail_otp": 1,
  "service_number": "abc123"
}

Step 2  Create departments

Create the department structure your users should belong to. You can build a hierarchy using parent_id.

Key notes

• If parent_id is set, it must reference an existing department (otherwise you’ll receive an error).
• The company_id field is typically for internal use and may be discarded; departments usually inherit company from the calling user.

Permission required: write_departments

Example request body

{
  "name": "Department name",
  "parent_id": 42,
  "company_id": 42
}

Step 3  Assign departments to users

Link one (or multiple) departments to a user.

Endpoint: POST /v2/admin/users/{userId}/department

Permission required: write_user_department

Key notes

• The user and the departments must already exist.

Example request body

{
  "departments": [1, 2, 3]
}

Step 4  List available permission groups

Permission Groups bundle many individual permissions into an easy-to-assign role (e.g., Standard User, Power User, Admin).

Endpoint: GET /v2/admin/permission/groups

Permission required: read_groups

How groups work (plain English)

• Groups can be general (no company_id) or company-specific.
• If the calling user has a company, the company_id filter is typically ignored and your company is used.
• The response can include flags like editable and deletable to indicate what you’re allowed to manage.

Step 5  Assign permission groups to users

Add the user to the permission group(s) that match their role. This is what actually enables access to AMS features.

Endpoint: POST /v2/admin/user/{userId}/groups

Permission required: write_permission_user

Critical rules

• A user cannot change their own permissions (security).
• A user cannot grant another user more permissions than they currently have.
• Important: Any group not listed in the request will be removed from the user.

Example request body

{
  "groups": [1, 2]
}

Common errors

• permission.010 — Possible security breach (ask another manager to change your permissions)
• user.002 — User not found (check the userId)
• permission.011 — Cannot grant more power (ask a manager with higher permissions)
• permission.group.002 — Permission group not found (check group IDs in payload)