Users

Manage user access in the Amili system. Users are associated with Accounts and can be granted access to all Creditors within that Account using the account_admin access group. Users can also be granted more specific access to individual Creditors through other access groups.

User endpoints

• GET /users - List all users (paginated)
• GET /users/{userId} - Get a specific user
• POST /users - Create a new user

See Account for managing the business entities users belong to. See swagger Application for list of available applications. See swagger Access-Group for documentation and and management of access groups.

Authentication Method

The recommended authentication method for users is OAuth authentication (Microsoft, Google, etc.):

• email_oauth (string, required) - OAuth email address
• oauth_type (string, required) - OAuth provider type (e.g., "microsoft", "google")*
• oauth_subscriber (string, optional) - OAuth subscriber ID for multi-tenant scenarios

Example Request

Below is an example of creating a user with OAuth authentication. Other operations follow similar request/response patterns with the same data structure.

URL: POST /users

Headers:

x-api-key: {your_access_token}
Content-Type: application/json

Request Body:

{
  "account": "674dbeaf08847b9501cc9132",
  "name": "Jane Doe",
  "email_data": {
    "email": "jane.doe@domain.se"
  },
  "oauth_type": "microsoft",
  "email_oauth": "jane.doe@domain.se",
  "data_access": [
    {
      "access_group": "60e7fdefc90dc3e2ddd6c7ad"
    }
  ],
  "is_enabled": true,
  "applications": [
    {
      "application": "60e7fdefc90dc3e2ddd6c7af"
    },
    {
      "application": "60e7fdefc90dc3e2ddd6c7b0"
    }
  ]
}

Response Code: 201 Created

Response Body:

{
  "_updated": "Fri, 29 Aug 2025 07:45:25 GMT",
  "_created": "Fri, 29 Aug 2025 07:45:25 GMT",
  "_etag": "8be4d5fc86d77d226b0f83f8593de42334a0a192",
  "_id": "68678ed98d8dc95ece127944",
  "_status": "OK"
}

Parameters

Request Body Properties

Note: One of account, partner, or solicitor is required.

Property	Type	Required	Description
account	string	Yes (or partner/solicitor)	Account ID - for account users
partner	string	Yes (or account/solicitor)	Partner ID - for partner users
solicitor	object	Yes (or account/partner)	Solicitor details - for solicitor users (see Solicitor Properties below)
name	string	Yes	User's full name
description	string	No	User description
email_data	object	No	Email information (see Email Data Properties below)
mobile_number_data	object	No	Mobile number information (see Mobile Number Data Properties below)
oauth_type	string	Yes (for OAuth)	OAuth authentication type (e.g. "microsoft", "google")*
email_oauth	string	Yes (for OAuth)	OAuth email address
oauth_subscriber	string	No	OAuth subscriber ID (requires oauth_type and email_oauth)
data_access	array	No	List of access group assignments
is_enabled	boolean	No	Whether user is active (default: true)
applications	array	No	List of application assignments
log_invoice_registrations	boolean	No	Log invoice registrations (default: false)
log_case_registrations	boolean	No	Log case registrations (default: false)
log_creditor_payments	boolean	No	Log creditor payments (default: false)
log_creditor_cancellations	boolean	No	Log creditor cancellations (default: false)
log_creditor_creditings	boolean	No	Log creditor creditings (default: false)
system_user	boolean	No	Whether system user (default: false)
managed_by_external_system	boolean	No	Whether user is managed by external system (default: false)
external_id	string	No	External system identifier
main_unit	string	No	Reference to user unit (ObjectId)
ui_structures	array	No	UI structure references (list of objects with ui_structure)
manager	string	No	Reference to manager user (ObjectId)

Email Data Properties

Property	Type	Required	Description
email	string	Yes	Email address

Mobile Number Data Properties

Property	Type	Required	Description
mobile_number	string	Yes	Mobile number

Solicitor Properties

Property	Type	Required	Description
office	string	Yes	Solicitor office ID (ObjectId)
function	string	No	Solicitor function*
external_consult	boolean	No	Whether external consultant (default: false)
position	string	No	Position title
team	string	No	Team ID (ObjectId)

Data Access Properties

Data access entries can include temporal restrictions using from and until fields.

Property	Type	Required	Description
access_group	string	Yes	Access group ID**
from	string	No	Date from which access is valid (RFC 1123 format)
until	string	No	Date until which access is valid (RFC 1123 format)
granted_date	string	No	Access grant date (readonly, cascade updated)
access_group_name	string	No	Access group name (readonly, cascade updated)
access_group_account_name	string	No	Associated account name (readonly, cascade updated)
access_group_creditor_name	string	No	Associated creditor name (readonly, cascade updated)
access_group_partner_name	string	No	Associated partner name (readonly, cascade updated)
access_group_type	string	No	Access group type (e.g. "admin")* (readonly, cascade updated)

Application Properties

Property	Type	Required	Description
application	string	Yes	Application ID***
application_name	string	No	Application name (e.g. "ada_ui")*

Response Properties

Property	Type	Required	Description
_id	string	Yes	Unique identifier for the user
_created	string	Yes	Creation timestamp
_updated	string	Yes	Last update timestamp
_etag	string	Yes	Entity tag for concurrency control
_status	string	Yes	Request status (e.g. "OK")*

Validation Rules

User Type Requirement:

• One of account, partner, or solicitor is required (any_of_required)
• These fields are mutually exclusive - provide only one

OAuth Authentication:

• oauth_type and email_oauth are required for OAuth authentication
• oauth_subscriber is optional and requires both oauth_type and email_oauth to be set

Uniqueness Constraints: The following key pairs must be unique:

• (partner, name, email_oauth) - for partner users with OAuth
• (account, name, email_oauth) - for account users with OAuth

Data Access Temporal Restrictions:

• from and until fields in data_access entries allow time-bound access
• Both fields use RFC 1123 datetime format
• Access is valid from from date (inclusive) to until date (exclusive)

Cascade Updates: Several fields in data_access are automatically updated when related documents change:

• granted_date - Set when access is granted
• access_group_name - Updated from access_group.name
• access_group_account_name - Updated from access_group.account.name
• access_group_creditor_name - Updated from access_group.creditor.name
• access_group_partner_name - Updated from access_group.partner.name
• access_group_type - Updated from access_group.type

*) For complete list of values and details, please see User **) For available access groups and details, please see Access Group ***) For available applications and details, please see Application