Data from the "users" domain represent a user within an account. A user represents a person who can log in to the account.


It is not possible to modify an existing user via the API. Only the following actions are supported:

  • Retrieve all users

  • Add a user

  • Delete a user


URL structure:

  • /api/v1/users: All users of the account

Domain: users

Field nameTypeDescriptionExample
user_idintUnique ID of the user123
nametextName of the userJan Desmet
email_addresstextEmail address of the userjan@domain.be
statustextStatus of the user. Possible values: owner (primary user), active, activate (awaiting activation), pending (awaiting approval)active
rightslistRights of the user. Default is "all".all


Example in JSON:

{
  "user_id": 123,
  "name": "Jan Desmet",
  "email_address": "jan@domain.be",
  "status": "active",
  "rights": [
    "quotes", "projects"
  ]
}


Add user

Users can be added via a POST request to: /api/v1/users


You can create a new user or add an existing user to an account.
Whether it concerns a new or existing user is automatically determined based on the provided email address. So you only need to provide the user's email address.


Password or activation email

When adding a new user, you have two options:

  • Without password: the user automatically receives an activation email to set a password.

  • With password: the user can log in immediately using the provided password. In this case, no activation email will be sent.

When adding an existing user:

  • You cannot specify a password.

  • An activation email is always sent to confirm access to the account.

Examples

1. Add user with activation email:

{
  "name": "Jan Desmet",
  "email_address": "jan@domain.be"
}


2. Add user with password and rights:

{
  "name": "Jan Desmet",
  "email_address": "jan@domain.be",
  "password": "-MySecretPassword-",
  "rights": ["invoices", "read_subscriptions", "bank"]
}


3. Add user with SSO (automatic login):

{
  "name": "Jan Desmet",
  "email_address": "jan@domain.be",
  "password": "-MySecretPassword-",
  "sso": [{"identity": "1111111111111", "type": "google", "username": "Jan Desmet"}]
}


Delete user

To delete a user, use the user_id and issue a DELETE request to: /api/v1/users/{user_id}


Note: The primary user of an account cannot be deleted.