Users

>>>

GET /api/users
Get users list

Returns the list of authenticated user’s current company users.

Supported Formats

json

Examples

[
  {
    "id":3,
    "name":"Approver 2",
    "email":"approver2@burucorp.com",
    "last_sign_in_at":"2017-10-31T18:50:10.714Z",
    "sign_in_count":1,
    "locale":"fi",
    "roles":["employee","accountant"],
    "state":"accepted",
    "ssn":"160583-1664",
    "email_is_confirmed":true
  }
]
>>>

GET /api/users/extended_index
Get users' details list

Returns the list of authenticated user’s current company users.

Each user in the list includes the same fields as each user in GET /api/users list + the following additional fields:

  • user’s approvers list

  • user’s IBAN

  • user’s BIC

  • user’s external ID

  • user’s employment termination date

  • user’s settings

Supported Formats

json
>>>

POST /api/users
Add new user

Add new user and set his current company settings

Params

Param name Description
user
required

User params

Validations:

  • Must be a Hash
user[name]
required

User full name

Validations:

  • Must be a String
user[email]
required

Validations:

  • Must be a String
user[ssn]
optional , nil allowed

User’s Social Security Number

Validations:

  • Must be a String
user[iban]
optional , nil allowed

IBAN

Validations:

  • Must be a String
user[bic]
optional , nil allowed

BIC

Validations:

  • Must be a String
user[locale]
optional , nil allowed

Validations:

  • Must be one of: en, fi, sv.
user[send_reminder_emails]
optional , nil allowed

Defaults to true

Validations:

  • Must be one of: true, false, 1, 0.
user[country_id]
optional , nil allowed

Country id of a user. Determines default user currency in UI.

Validations:

  • Must be a Integer
user[nationality_id]
optional , nil allowed

Country id of a user’s . Dictates SSN validation rules.

Validations:

  • Must be a Integer
user[gender]
optional , nil allowed

Legal Gender. We support LGBTI Rights, but are constrained by the Tax Authorities in terms of which Gender alternatives we can report to them. We will update the alternatives as soon as we are allowed to do so.

Validations:

  • Must be one of: female, male.
user[birthday]
optional , nil allowed

User birthday

Validations:

  • Must be a String
user[roles]
optional , nil allowed

An array of user roles. Can be one of a few of the following: “employee”, “manager”, “accountant”, “approver”, “money_checker”. Only the managers can update roles.

Validations:

  • Must be an array of String
user[employment_termination_date]
optional , nil allowed

Employment termination date, e.g. “2023-01-14”. User will be automatically removed from the company after that date.

Validations:

  • Must be a String
user[on_vacation]
optional , nil allowed

Defaults to false

Validations:

  • Must be one of: true, false, 1, 0.
user[vacation_start_date]
optional , nil allowed

User vacation start date: on the start of that date on_vacation setting will be set to true automatically.

Validations:

  • Must be a String
user[vacation_end_date]
optional , nil allowed

User vacation end date: the next day after that date on_vacation setting will be set to false automatically.

Validations:

  • Must be a String
user[settings_attributes]
optional , nil allowed

Validations:

  • Must be an Array of nested elements
user[settings_attributes][default_cost_centers]
optional , nil allowed

User’s default cost centers. Format: {"DIMENSION_NAME":COST_CENTER_ID,...}, e.g. {"Office":123,"Project":456}.

Validations:

  • Must be a Hash
user[settings_attributes][default_asset_account_id]
optional , nil allowed

Validations:

  • Must be a Integer
user[settings_attributes][default_expense_account_id]
optional , nil allowed

Validations:

  • Must be a Integer
user[settings_attributes][mileage_vehicle_category_id]
optional , nil allowed

Validations:

  • Must be a Integer
user[settings_attributes][allowance_country_category_id]
optional , nil allowed

Validations:

  • Must be a Integer
user[settings_attributes][allowance_account_id]
optional , nil allowed

Validations:

  • Must be a Integer
user[settings_attributes][allowance_abroad_account_id]
optional , nil allowed

Validations:

  • Must be a Integer
user[settings_attributes][mileage_account_id]
optional , nil allowed

Validations:

  • Must be a Integer
user[settings_attributes][ir_mileage_code]
optional , nil allowed

Validations:

  • Must be a Integer
user[settings_attributes][ir_daily_allowance_code]
optional , nil allowed

Validations:

  • Must be a Integer
user[settings_attributes][reimbursement_account_code]
optional , nil allowed

Validations:

  • Must be a String
user[settings_attributes][stand_in_approver_id]
optional , nil allowed

Stand-in user_id, should be different from user_id

Validations:

  • Must be a Integer
user[settings_attributes][send_data_to_incomes_register]
optional , nil allowed

Validations:

  • Must be one of: true, false, 1, 0.
user[settings_attributes][password_auth_disabled]
optional , nil allowed

Enforce SSO authentication

Validations:

  • Must be one of: true, false, 1, 0.
user[approvers_attributes]
optional , nil allowed

Add/Remove user approvers. Current user should have “manager” role to edit approvers

Validations:

  • Must be an Array of nested elements
user[approvers_attributes][id]
optional , nil allowed

User approver id, required if user approver already exists. If it’s not supplied, new user approver will be added

Validations:

  • Must be a Integer
user[approvers_attributes][approver_id]
required

Approver id

Validations:

  • Must be a Integer
user[approvers_attributes][operator]
required

Operator specifying approver process logic

Validations:

  • Must be one of: then, or.
user[approvers_attributes][_destroy]
optional , nil allowed

Pass “true” here to delete an existing approver

Validations:

  • Must be one of: true, false, 1, 0.
user[current_tax_card]
optional , nil allowed

Validations:

  • Must be a Hash
user[current_tax_card][tax_percentage]
optional , nil allowed

User’s current tax card tax percentage, must be either less than 100 (e.g. 25 for 25%) or less than 1 (e.g. 0.34 for 34%)

Validations:

  • Must be a Float
user[address_attributes]
optional , nil allowed

User address

Validations:

  • Must be a Hash
user[address_attributes][street]
optional , nil allowed

Street address.

Validations:

  • Must be a String
user[address_attributes][city]
optional , nil allowed

City of the address, or Post Office.

Validations:

  • Must be a String
user[address_attributes][postal_code]
optional , nil allowed

Postal Code of the address.

Validations:

  • Must be a String
user[address_attributes][country_id]
optional , nil allowed

Country id of an address.

Validations:

  • Must be a Integer
user[address_attributes][latitude]
optional , nil allowed

Geographic Latitude from Google Maps

Validations:

  • Must be a decimal number.
user[address_attributes][longitude]
optional , nil allowed

Geographic Longitude from Google Maps

Validations:

  • Must be a decimal number.
skip_notification
optional

Skip sending invitation notification. Defaults to “false”

Validations:

  • Must be one of: true, false, 1, 0.
>>>

PUT /api/users/:id
Edit existing user

Edit user and his current company settings

Params

Param name Description
user
required

User params

Validations:

  • Must be a Hash
user[name]
optional

User full name

Validations:

  • Must be a String
user[email]
optional

Validations:

  • Must be a String
user[ssn]
optional , nil allowed

User’s Social Security Number

Validations:

  • Must be a String
user[iban]
optional , nil allowed

IBAN

Validations:

  • Must be a String
user[bic]
optional , nil allowed

BIC

Validations:

  • Must be a String
user[locale]
optional , nil allowed

Validations:

  • Must be one of: en, fi, sv.
user[send_reminder_emails]
optional , nil allowed

Defaults to true

Validations:

  • Must be one of: true, false, 1, 0.
user[country_id]
optional , nil allowed

Country id of a user. Determines default user currency in UI.

Validations:

  • Must be a Integer
user[nationality_id]
optional , nil allowed

Country id of a user’s . Dictates SSN validation rules.

Validations:

  • Must be a Integer
user[gender]
optional , nil allowed

Legal Gender. We support LGBTI Rights, but are constrained by the Tax Authorities in terms of which Gender alternatives we can report to them. We will update the alternatives as soon as we are allowed to do so.

Validations:

  • Must be one of: female, male.
user[birthday]
optional , nil allowed

User birthday

Validations:

  • Must be a String
user[roles]
optional , nil allowed

An array of user roles. Can be one of a few of the following: “employee”, “manager”, “accountant”, “approver”, “money_checker”. Only the managers can update roles.

Validations:

  • Must be an array of String
user[employment_termination_date]
optional , nil allowed

Employment termination date, e.g. “2023-01-14”. User will be automatically removed from the company after that date.

Validations:

  • Must be a String
user[on_vacation]
optional , nil allowed

Defaults to false

Validations:

  • Must be one of: true, false, 1, 0.
user[vacation_start_date]
optional , nil allowed

User vacation start date: on the start of that date on_vacation setting will be set to true automatically.

Validations:

  • Must be a String
user[vacation_end_date]
optional , nil allowed

User vacation end date: the next day after that date on_vacation setting will be set to false automatically.

Validations:

  • Must be a String
user[settings_attributes]
optional , nil allowed

Validations:

  • Must be an Array of nested elements
user[settings_attributes][default_cost_centers]
optional , nil allowed

User’s default cost centers. Format: {"DIMENSION_NAME":COST_CENTER_ID,...}, e.g. {"Office":123,"Project":456}.

Validations:

  • Must be a Hash
user[settings_attributes][default_asset_account_id]
optional , nil allowed

Validations:

  • Must be a Integer
user[settings_attributes][default_expense_account_id]
optional , nil allowed

Validations:

  • Must be a Integer
user[settings_attributes][mileage_vehicle_category_id]
optional , nil allowed

Validations:

  • Must be a Integer
user[settings_attributes][allowance_country_category_id]
optional , nil allowed

Validations:

  • Must be a Integer
user[settings_attributes][allowance_account_id]
optional , nil allowed

Validations:

  • Must be a Integer
user[settings_attributes][allowance_abroad_account_id]
optional , nil allowed

Validations:

  • Must be a Integer
user[settings_attributes][mileage_account_id]
optional , nil allowed

Validations:

  • Must be a Integer
user[settings_attributes][ir_mileage_code]
optional , nil allowed

Validations:

  • Must be a Integer
user[settings_attributes][ir_daily_allowance_code]
optional , nil allowed

Validations:

  • Must be a Integer
user[settings_attributes][reimbursement_account_code]
optional , nil allowed

Validations:

  • Must be a String
user[settings_attributes][stand_in_approver_id]
optional , nil allowed

Stand-in user_id, should be different from user_id

Validations:

  • Must be a Integer
user[settings_attributes][send_data_to_incomes_register]
optional , nil allowed

Validations:

  • Must be one of: true, false, 1, 0.
user[settings_attributes][password_auth_disabled]
optional , nil allowed

Enforce SSO authentication

Validations:

  • Must be one of: true, false, 1, 0.
user[approvers_attributes]
optional , nil allowed

Add/Remove user approvers. Current user should have “manager” role to edit approvers

Validations:

  • Must be an Array of nested elements
user[approvers_attributes][id]
optional , nil allowed

User approver id, required if user approver already exists. If it’s not supplied, new user approver will be added

Validations:

  • Must be a Integer
user[approvers_attributes][approver_id]
optional

Approver id

Validations:

  • Must be a Integer
user[approvers_attributes][operator]
optional

Operator specifying approver process logic

Validations:

  • Must be one of: then, or.
user[approvers_attributes][_destroy]
optional , nil allowed

Pass “true” here to delete an existing approver

Validations:

  • Must be one of: true, false, 1, 0.
user[current_tax_card]
optional , nil allowed

Validations:

  • Must be a Hash
user[current_tax_card][tax_percentage]
optional , nil allowed

User’s current tax card tax percentage, must be either less than 100 (e.g. 25 for 25%) or less than 1 (e.g. 0.34 for 34%)

Validations:

  • Must be a Float
user[address_attributes]
optional , nil allowed

User address

Validations:

  • Must be a Hash
user[address_attributes][street]
optional , nil allowed

Street address.

Validations:

  • Must be a String
user[address_attributes][city]
optional , nil allowed

City of the address, or Post Office.

Validations:

  • Must be a String
user[address_attributes][postal_code]
optional , nil allowed

Postal Code of the address.

Validations:

  • Must be a String
user[address_attributes][country_id]
optional , nil allowed

Country id of an address.

Validations:

  • Must be a Integer
user[address_attributes][latitude]
optional , nil allowed

Geographic Latitude from Google Maps

Validations:

  • Must be a decimal number.
user[address_attributes][longitude]
optional , nil allowed

Geographic Longitude from Google Maps

Validations:

  • Must be a decimal number.
>>>

GET /api/users/:id
Get user details by id

Returns user fields and a few nested entities

Supported Formats

json

Examples

{
  "id":3,
  "name":"Manager AltCorp",
  "email":"manager@altcorp.com",
  "ssn":"0000000-0",
  "last_sign_in_at":"2016-03-16T10:01:54.163Z",
  "sign_in_count":3,
  "roles":["manager"],
  "forward_email_address":"71882469-5381-456d-b71b-80825c1320ac@app.bezala.com",
  "send_reminder_emails":true,
  "iban":null,
  "bic":null,
  "locale":"en",
  "state":"accepted",
  "memberships":1,
  "country_id":1,
  "unconfirmed_email":null,
  "external_id":"42",
  "email_is_confirmed":true,
  "employment_termination_date":"2025-01-01",
  "nationality_id": 2,
  "gender": null,
  "birthday": "2023-11-07",
  "on_vacation": true,
  "vacation_start_date": "2024-05-07",
  "vacation_end_date": "2024-05-17",
  "settings": {
    "id":31,
    "user_id":3,
    "company_id":1,
    "default_asset_account_id":null,
    "default_expense_account_id":60,
    "default_cost_centers":null,
    "mileage_vehicle_category_id":null,
    "allowance_country_category_id":null,
    "send_data_to_incomes_register":true,
    "password_auth_disabled":false
  },
  "company": {"id":2,"name":"Alternative Corp","send_data_to_incomes_register":true,"show_reward_form":false},
  "current_tax_card": {"id":35,"user_id":3,"image":{"url":null},"tax_percentage":"0.6","is_current":true},
  "approvers": [
    {"id":101,"company_id":2,"approver_id":4,"user_id":3,"operator":"then","name":"John Smith","position":1}
  ],
  "country": {"id":1,"name":"Finland","currency":"EUR","currency_symbol":"€"},
  "address":
    {
      "street":"233 Main str.",
      "city":"New York",
      "postal_code":"19321",
      "country_id":4,
      "latitude":"40.709476",
      "longitude":"-74.007296",
    }
}
>>>

DELETE /api/users/:id
Delete user from the current company by id

Removes user from the company by deleting his company membership. The user account stays intact and can be reinvited later. All of the user’s transactions are kept intact.

Supported Formats

json
>>>

PUT /api/users/:id/change_company/:company_id
Change current user's current company id

Changes current user’s current company to one of the companies available for the user

>>>

PUT /api/users/:id/switch_to_another_company
Change current user's current company id to the 1st available one

Changes current company to the first one available where the current user has an accepted membership.

If no companies with an accepted memberships are available (other than the current) - then returns an error “No companies to switch” with 404 response status