User

A user [User] is either an employee (an employee working for your company or a subcontractor), a generic resource (virtual or placeholder resource that represents a staffing need) or a guest user (a customer that can sign in to your OpenAir account and view information that is associated with them and the projects that your company delivers to them). Employees and guest users can sign into your company's OpenAir account. Employees (named resources) and generic resources can be booked to projects and tasks.

Review the Usage Guidelines for the User object.

—	XML	SOAP	REST	Database table
Object	`User`	`oaUser`	—	`user`
Supported Commands	`CreateUser`, `Read`, `Modify`, `Delete`	`createUser()`, `read()`, `modify()`, `upsert()`, `delete()`	—	—

—

XML

SOAP

REST

Database table

Object

User

oaUser

—

user

Supported Commands

CreateUser, Read, Modify, Delete

createUser(), read(), modify(), upsert(), delete()

—

The User object has the following standard properties:

Note:

User object properties may also include custom fields. The object type supports the custom equal to read method and the enable_custom read attribute.

XML	SOAP	Database	Description
`account_workscheduleid`	`account_workscheduleid`	`account.workschedule_id`	The ID of the associated company work schedule [`UserWorkSchedule`].
`acct_code`	`acct_code`	`acct_code`	Optional accounting code that can be used for integration with external accounting systems.
`active`	`active`	`active`	A 1/0 field indicating if the user is designated as an active user.
`addr`	—	—	The user's address. See Address Fields. The `Address` object must include an `email`.
—	`addr_addr1`	`address1`	First line of the user's address.
—	`addr_addr2`	`address2`	Second line of the user's address.
—	`addr_addr3`	`address3`	Third line of the user's address.
—	`addr_addr4`	`address4`	Fourth line of the user's address.
—	`addr_city`	`city`	The user's city.
—	`addr_contact_id`	—	The internal ID of the associated `Contact` object.
—	`addr_country`	`country`	The user's country.
—	`addr_email`	`email`	[Required] The user's Email address.
—	`addr_fax`	`fax`	The user's fax number.
—	`addr_first`	`first`	The user's first name.
—	`addr_id`	—	The internal ID of the associated `Address` object.
—	`addr_last`	`last`	The user's last name.
—	`addr_middle`	`middle`	The user's middle name.
—	`addr_mobile`	`mobile`	The user's mobile number.
—	`addr_phone`	`phone`	The user's phone number.
—	`addr_salutation`	`salutation`	The user's salutation.
—	`addr_state`	`state`	The user's state or region.
—	`addr_zip`	`zip`	The user's ZIP code or postal code.
`az_approvalprocess`	`az_approvalprocess`	`az_approvalprocess`	The internal ID of the approval process for expense authorizations submitted by the user. Mutually exclusive with `az_approver`.
`az_approver`	`az_approver`	`az_approver`	The internal ID of the `User` who approves expense authorizations submitted by the user (expense authorization owner), if a single approver process is used. Mutually exclusive with `az_approvalprocess`. Other possible values: `-1` — the expense authorization owner’s manager. `-2` — the manager of the expense authorization owner’s manager. `-4` — self (expense authorization owner).
`book_assign_stamp`	`book_assign_stamp`	—	Internal hash key.
`br_approvalprocess`	`br_approvalprocess`	`br_approvalprocess`	The internal ID of the approval process [`ApprovalProcess`] for booking requests for the user (requested resource) or for booking requests submitted by the user, depending on the OpenAir account configuration. Mutually exclusive with `br_approver`.
`br_approver`	`br_approver`	`br_approver`	The internal ID of the `User` who approves booking requests for the user (requested resource) or booking requests submitted by the user, depending on the OpenAir account configuration, if a single approver process is used. Mutually exclusive with `br_approvalprocess`. Other possible values: `-1` — the requested resource or the requester's manager. `-2` — the manager of the booked resource or the requester's manager. `-4` — self (booked resource or the requester). `-9` — submitter (requester). This option may not be available depending on your OpenAir account configuration.
`code`	`code`	`acct_code`	Optional accounting code that can be used for integration with external accounting systems. See also `acct_code`. In the XML and SOAP API, the `code` property duplicates the `acct_code` for back compatibility purposes.
`cost`	`cost`	`loaded_cost.cost`	[Write-only] New cost value. Used with `update_cost` Updating User Loaded Costs.
`cost_centerid`	`cost_centerid`	`cost_center_id`	The internal ID of the cost center [`Costcenter`] associated with the user.
`cost_currency`	`cost_currency`	`loaded_cost.currency`	[Write-only] Currency of the cost. Used with `update_cost` Updating User Loaded Costs.
`cost_end_date`	`cost_end_date`	`loaded_cost.end_date`	[Write-only] End date for the new loaded cost. If left blank, the new cost will have no end date. See Date Fields. Used with `update_cost` Updating User Loaded Costs.
`cost_lc_level`	`cost_lc_level`	`loaded_cost.lc_level`	[Write-only] If multiple loaded cost levels are enabled, use this field to hold the level of the loaded cost. Used with `update_cost` Updating User Loaded Costs.
`cost_start_date`	`cost_start_date`	`loaded_cost.start_date`	[Write-only] Start date for the new loaded cost. If left blank, the new cost will assume the current date as it's start date. See Date Fields. Used with `update_cost` Updating User Loaded Costs.
`created`	`created`	`created`	[Read-only] The date and time when the record was created. See Date Fields.
`currency`	`currency`	`currency`	The user's currency. Three-letter currency code.
`cv_attachment_id`	`cv_attachment_id`	`attachment_id`	The internal ID of the attachment [`Attachment`] associated with this user (the user's latest CV).
`departmentid`	`departmentid`	`department_id`	The internal ID of the department [`Department`] associated with the user.
`dr_approvalprocess`	`dr_approvalprocess`	`dr_approvalprocess`	The internal ID of the approval process [`ApprovalProcess`] for deal booking requests for the user (requested resource) or for deal booking requests submitted by the user, depending on the OpenAir account configuration. Mutually exclusive with `dr_approver`.
`dr_approver`	`dr_approver`	`dr_approver`	The internal ID of the `User` who approves deal booking requests for the user (requested resource) or deal booking requests submitted by the user, depending on the OpenAir account configuration, if a single approver process is used. Mutually exclusive with `dr_approvalprocess`. Other possible values: `-1` — the requested resource or the requester's manager. `-2` — the manager of the booked resource or the requester's manager. `-4` — self (booked resource or the requester). `-9` — submitter (requester). This option may not be available depending on your OpenAir account configuration.
`external_id`	`external_id`	`external_id`	The unique external ID of the user, if the record was imported from an external system.
`externalid`	`externalid`	`external_id`	The unique external ID of the user, if the record was imported from an external system. In the XML and SOAP API, the `externalid` property duplicates the `external_id` property.
`filterset_ids`	`filterset_ids`	—	A comma delimited list of internal IDs of filter sets [`Filterset`] that this object belongs to.
`filterset_stamp`	`filterset_stamp`	—	A unique string which changes when the primary filter set changes for the user.
`flags`	`flags`	—	User-specific settings. See Company and User Settings.
`generic`	`generic`	`generic`	A 1/0 field indicating whether this is a generic resource. Cannot be modified.
`hierarchy_node_ids`	`hierarchy_node_ids`	—	A comma delimited list of internal IDs of hierarchy nodes [`HierarchyNode`] that this object belongs to.
`hint`	`hint`	`hint`	The user's password hint.
`id`	`id`	`id`	[Read-only] The unique internal identifier of the user. Automatically assigned by OpenAir.
`is_user_schedule`	`is_user_schedule`	—	[Write-only] A 1/0 field indicating whether the user should draw their workschedule from an account_workschedule or draw from a custom workschedule. 0 sets the user workschedule to the account workschedule specified in account_workscheduleid, 1 constructs a custom workschedule from the supplied workschedule_workdays and workschedule_workhours fields. Used with `update_workschedule` Setting User Work Schedule.
`job_codeid`	`job_codeid`	`job_code_id`	The internal ID of the job code [`Jobcode`] associated with the user.
`km_filter_set`	`km_filter_set`	`km_filter_set`	The internal ID of the filter set override [`Filterset`] for the Workspaces application (module).
`line_managerid`	`line_managerid`	`line_manager_id`	The internal ID of the user's line manager (internal ID of another `User`). The user must exist, must not be marked as deleted, must be active and must not be a generic user.
`locked`	`locked`	`locked`	A 1/0 field indicating if the user is locked out of your company's OpenAir account.
`logintime`	`logintime`	`user_login.logintime`	The date and time of the user's last sign-in. See Date Fields.
`ma_filter_set`	`ma_filter_set`	`ma_filter_set`	The internal ID of the filter set override [`Filterset`] for the My Account application (module).
`mfa_status`	`mfa_status`	`mfa_status`	The user's two-factor authentication (2FA) status. The property is read-only if two-factor authentication is not enabled for your company's OpenAir account. Possible values: `0` – 2FA is not required. `1` – 2FA is required and the user must set up 2FA. `2` – 2FA is required and the user has paired an authenticator app with OpenAir. `7` – 2FA is required and the user has completed the 2FA setup.
`name`	`name`	`name`	The display name for the user in lists. This is generated automatically if not set.
`nickname`	`nickname`	`nickname`	[Required] The users nickname. This must be unique.
`om_filter_set`	`om_filter_set`	`om_filter_set`	The internal ID of the filter set override [`Filterset`] for the Opportunities application (module).
`password`	`password`	`password`	[Required] The user's password. Not returned when reading objects.
`password_forced_change`	`password_forced_change`	`password_forced_change`	A 1/0 field indicating if the user must change password on next sign in.
`payroll_code`	`payroll_code`	`payroll_code`	The payroll code for this user.
`pb_approvalprocess`	`pb_approvalprocess`	`pb_approvalprocess`	The internal ID of the approval process [`ApprovalProcess`] for proposals submitted by the user. Mutually exclusive with `pb_approver`.
`pb_approver`	`pb_approver`	`pb_approver`	The internal ID of the `User` who approves proposals submitted by the user (proposal owner), if a single approver process is used. Mutually exclusive with `pb_approvalprocess`. Other possible values: `-1` — the proposal owner’s manager. `-2` — the manager of the proposal owner’s manager. `-4` — self (proposal owner).
`picklist_label`	`picklist_label`	—	Label as shown on form picklist.
`pm_filter_set`	`pm_filter_set`	`pm_filter_set`	The internal ID of the filter set override [`Filterset`] for the Projects application (module).
`po_approvalprocess`	`po_approvalprocess`	`po_approvalprocess`	The internal ID of the approval process [`ApprovalProcess`] for purchase orders submitted by the user. Mutually exclusive with `po_approver`.
`po_approver`	`po_approver`	`po_approver`	The internal ID of the `User` who approves purchase orders submitted by the user (purchase order owner), if a single approver process is used. Mutually exclusive with `po_approvalprocess`. Other possible values: `-1` — the purchase order owner’s manager. `-2` — the manager of the purchase order owner’s manager. `-4` — self (purchase order owner).
`po_filter_set`	`po_filter_set`	`po_filter_set`	The internal ID of the filter set override [`Filterset`] for the Purchases application (module).
`pr_approvalprocess`	`pr_approvalprocess`	`pr_approvalprocess`	The internal ID of the approval process [`ApprovalProcess`] for purchase requests submitted by the user. Mutually exclusive with `pr_approver`.
`pr_approver`	`pr_approver`	`pr_approver`	The internal ID of the `User` who approves purchase requests submitted by the user (purchase request owner), if a single approver process is used. Mutually exclusive with `pr_approvalprocess`. Other possible values: `-1` — the purchase request owner’s manager. `-2` — the manager of the purchase request owner’s manager. `-4` — self (purchase request owner).
`primary_filter_set`	`primary_filter_set`	`primary_filter_set`	The internal ID of the user's primary filter set [`Filterset`]. Defaults to the default primary filter set if not set when adding a user.
`project_access_nodes`	`project_access_nodes`	`project_access_nodes`	Comma delimited list of internal IDs of hierarchy nodes [`HierarchyNode`] for project level access control.
`rate`	`rate`	`rate`	The hourly billing rate for the user's time.
`report_filter_set`	`report_filter_set`	`report_filter_set`	The internal ID of the filter set override [`Filterset`] for the Reports application (module).
`rm_filter_set`	`rm_filter_set`	`rm_filter_set`	The internal ID of the filter set override [`Filterset`] for the Resources application (module).
`rm_approvalprocess`	`rm_approvalprocess`	`rm_approvalprocess`	The internal ID of the approval process [`ApprovalProcess`] for bookings for the resource (user). Mutually exclusive with `rm_approver`.
`rm_approver`	`rm_approver`	`rm_approver`	The internal ID of the `User` who approves bookings for the user (resource), if a single approver process is used. Mutually exclusive with `rm_approvalprocess`. Other possible values: `-1` — the booked resource’s manager. `-2` — the manager of the booked resource's manager. `-4` — self (booked resource). `-9` — submitter. This option may not be available depending on your OpenAir account configuration.
`role_id`	`role_id`	`role_id`	The internal ID of the role [`Role`] associated with the user. Defaults to the default role if not set when adding a user.
`rpc_api_updated`	`rpc_api_updated`	`rpc_api_updated`	The date and time when the user's resource profile was last updated using OpenAir API. See Date Fields.
`rpc_updated_by`	`rpc_updated_by`	`rpc_updated_by`	The internal ID of the `User` who last updated the user's resource profile.
`rpc_user_updated`	`rpc_user_updated`	`rpc_user_updated`	The date and time when the user's resource profile was last updated using OpenAir UI. See Date Fields.
`sr_approvalprocess`	`sr_approvalprocess`	`sr_approvalprocess`	The internal ID of approval process [`ApprovalProcess`] for schedule requests (time-off requests) submitted by the user. Mutually exclusive with `sr_approver`.
`sr_approver`	`sr_approver`	`sr_approver`	The internal ID of the `User` who approves schedule requests (time-off requests) for the user (schedule request owner), if a single approver process is used. Mutually exclusive with `sr_approvalprocess`. Other possible values: `-1` — the schedule request owner’s manager. `-2` — the manager of the schedule request owner’s manager. `-4` — self (schedule request owner).
`ssn`	`ssn`	`ssn`	The user's social security number. Returned only if the authenticated user is an account administrator.
`ta_approvalprocess`	`ta_approvalprocess`	`ta_approvalprocess`	The internal ID of the approval process [`ApprovalProcess`] for timesheets submitted by the user. Mutually exclusive with `ta_approver`.
`ta_approver`	`ta_approver`	`ta_approver`	The internal ID of the `User` who approves timesheets submitted by the user (timesheet owner), if a single approver process is used. Mutually exclusive with `ta_approvalprocess`. Other possible values: `-1` — the timesheet owner’s manager. `-2` — the manager of the timesheet owner’s manager. `-4` — self (timesheet owner).
`ta_filter_set`	`ta_filter_set`	`ta_filter_set`	The internal ID of the filter set override [`Filterset`] for the Timesheets application (module).
`tag_end_date`	`tag_end_date`	`entity_tag.end_date`	[Write-only] End date for the new tag. If left blank, the end date for the new tag will be undefined and the new tag will assume default status for the user. See Date Fields. Used with `update_tag` Updating User Entity Tags.
`tag_group_attribute_id`	`tag_group_attribute_id`	`entity_tag.tag_group_attribute_id`	[Write-only] The ID of the tag group attribute [`TagGroupAttribute`] that is being assigned to the new tag. Used with `update_tag` Updating User Entity Tags.
`tag_group_id`	`tag_group_id`	`entity_tag.tag_group_id`	[Write-only] The ID of the tag group [`TagGroup`] for the new tag. Used with `update_tag` Updating User Entity Tags.
`tag_start_date`	`tag_start_date`	`entity_tag.start_date`	[Write-only] Start date for the new tag. If left blank, the start date for the new tag will be set to the current date. See Date Fields. Used with `update_tag` Updating User Entity Tags.
`tb_filter_set`	`tb_filter_set`	`tb_filter_set`	The internal ID of the filter set override [`Filterset`] for the Invoices application (module).
`te_allowance_approvalprocess`	`te_allowance_approvalprocess`	`te_allowance_approvalprocess`	The internal ID of the approval process [`ApprovalProcess`] for allowance reports submitted by the user. Mutually exclusive with `te_allowance_approver`.
`te_allowance_approver`	`te_allowance_approver`	`te_allowance_approver`	The internal ID of the `User` who approves allowance reports submitted by the user (allowance report owner), if a single approver process is used. Mutually exclusive with `te_allowance_approvalprocess`. Other possible values: `-1` — the allowance report owner’s manager. `-2` — the manager of the allowance report owner’s manager. `-4` — self (allowance report owner).
`te_approvalprocess`	`te_approvalprocess`	`te_approvalprocess`	The internal ID of the approval process [`ApprovalProcess`] for expense reports submitted by the user. Mutually exclusive with `te_approver`.
`te_approver`	`te_approver`	`te_approver`	The internal ID of the `User` who approves expense reports submitted by the user (expense report owner), if a single approver process is used. Mutually exclusive with `te_approvalprocess`. Other possible values: `-1` — the expense report owner’s manager. `-2` — the manager of the expense report owner’s manager. `-4` — self (expense report owner).
`te_filter_set`	`te_filter_set`	`te_filter_set`	The internal ID of the filter set override [`Filterset`] for the Expenses application (module).
`timezone`	`timezone`	`timezone`	The user's timezone. Defaults to the time zone for the company's account if not set when adding a user.
`type`	`type`	—	Legacy field.
`update_cost`	`update_cost`	—	[Write-only] Set to `1` to update loaded cost information automatically when adding or modifying a user. See Updating User Loaded Costs.
`update_tag`	`update_tag`	—	[Write-only] Set to `1` to update entity tag information automatically when adding or modifying a user. See Updating User Entity Tags.
`update_workschedule`	`update_workschedule`	—	[Write-only] Set to `1` to update work schedule information automatically when adding or modifying a user. See Setting User Work Schedule.
`updated`	`updated`	`updated`	[Read-only] Date and time when the record was last updated or modified. See Date Fields.
`user_locationid`	`user_locationid`	`user_location_id`	The internal ID of the user location [`UserLocation`] associated with the user.
`week_starts`	`week_starts`	`week_starts`	The first day of the week for the user: `0` – Monday `6` – Sunday Defaults to the first day of the week for the company's account if not set when adding a user.
`workschedule_workdays`	`workschedule_workdays`	—	A CSV list of workdays, with each value indicating a day in the schedule and values ranging from `0` (Monday) to `6` (Sunday). For example, “`0,1,4`” indicates that a user works on Monday, Tuesday and Friday. Used with `update_workschedule` Setting User Work Schedule.
`workschedule_workhours`	`workschedule_workhours`	—	A CSV list of values for the user's default workhours and workhours for each day. At least one value for workschedule_workhours must be submitted, but a value for each day may be submitted as well. For example, if the user's workschedule_workdays is set to “`0,1,4`”, then submitting a value of only “`8`” for workschedule_workhours sets the user's default hours to 8 and each workday assumes this value as well. In addition, submitting a workschedule_workdays value of “`8,1,2,3`” sets the user's default workhours to 8, sets Monday to 1, Tuesday to 2, and Friday to 3. Used with `update_workschedule` Setting User Work Schedule.
`workscheduleid`	`workscheduleid`	`workschedule_id`	The internal ID of the user's work schedule [`UserWorkSchedule`].

XML

SOAP

Database

Description

account_workscheduleid

account.workschedule_id

The ID of the associated company work schedule [UserWorkSchedule].

acct_code

Optional accounting code that can be used for integration with external accounting systems.

active

A 1/0 field indicating if the user is designated as an active user.

addr

—

The user's address. See Address Fields.

The Address object must include an email.

—

addr_addr1

address1

First line of the user's address.

—

addr_addr2

address2

Second line of the user's address.

—

addr_addr3

address3

Third line of the user's address.

—

addr_addr4

address4

Fourth line of the user's address.

—

addr_city

city

The user's city.

—

addr_contact_id

—

The internal ID of the associated Contact object.

—

addr_country

country

The user's country.

—

addr_email

email

[Required] The user's Email address.

—

addr_fax

fax

The user's fax number.

—

addr_first

first

The user's first name.

—

addr_id

—

The internal ID of the associated Address object.

—

addr_last

last

The user's last name.

—

addr_middle

middle

The user's middle name.

—

addr_mobile

mobile

The user's mobile number.

—

addr_phone

phone

The user's phone number.

—

addr_salutation

salutation

The user's salutation.

—

addr_state

state

The user's state or region.

—

addr_zip

zip

The user's ZIP code or postal code.

az_approvalprocess

The internal ID of the approval process for expense authorizations submitted by the user. Mutually exclusive with az_approver.

az_approver

The internal ID of the User who approves expense authorizations submitted by the user (expense authorization owner), if a single approver process is used. Mutually exclusive with az_approvalprocess.

Other possible values:

-1 — the expense authorization owner’s manager.
-2 — the manager of the expense authorization owner’s manager.
-4 — self (expense authorization owner).

book_assign_stamp

—

Internal hash key.

br_approvalprocess

The internal ID of the approval process [ApprovalProcess] for booking requests for the user (requested resource) or for booking requests submitted by the user, depending on the OpenAir account configuration. Mutually exclusive with br_approver.

br_approver

The internal ID of the User who approves booking requests for the user (requested resource) or booking requests submitted by the user, depending on the OpenAir account configuration, if a single approver process is used. Mutually exclusive with br_approvalprocess.

Other possible values:

-1 — the requested resource or the requester's manager.
-2 — the manager of the booked resource or the requester's manager.
-4 — self (booked resource or the requester).
-9 — submitter (requester). This option may not be available depending on your OpenAir account configuration.

code

acct_code

Optional accounting code that can be used for integration with external accounting systems.

See also acct_code. In the XML and SOAP API, the code property duplicates the acct_code for back compatibility purposes.

cost

loaded_cost.cost

[Write-only] New cost value.

Used with update_cost Updating User Loaded Costs.

cost_centerid

cost_center_id

The internal ID of the cost center [Costcenter] associated with the user.

cost_currency

loaded_cost.currency

[Write-only] Currency of the cost.

Used with update_cost Updating User Loaded Costs.

cost_end_date

loaded_cost.end_date

[Write-only] End date for the new loaded cost. If left blank, the new cost will have no end date. See Date Fields.

Used with update_cost Updating User Loaded Costs.

cost_lc_level

loaded_cost.lc_level

[Write-only] If multiple loaded cost levels are enabled, use this field to hold the level of the loaded cost.

Used with update_cost Updating User Loaded Costs.

cost_start_date

loaded_cost.start_date

[Write-only] Start date for the new loaded cost. If left blank, the new cost will assume the current date as it's start date. See Date Fields.

Used with update_cost Updating User Loaded Costs.

created

[Read-only] The date and time when the record was created. See Date Fields.

currency

The user's currency. Three-letter currency code.

cv_attachment_id

attachment_id

The internal ID of the attachment [Attachment] associated with this user (the user's latest CV).

departmentid

department_id

The internal ID of the department [Department] associated with the user.

dr_approvalprocess

The internal ID of the approval process [ApprovalProcess] for deal booking requests for the user (requested resource) or for deal booking requests submitted by the user, depending on the OpenAir account configuration. Mutually exclusive with dr_approver.

dr_approver

The internal ID of the User who approves deal booking requests for the user (requested resource) or deal booking requests submitted by the user, depending on the OpenAir account configuration, if a single approver process is used. Mutually exclusive with dr_approvalprocess.

Other possible values:

-1 — the requested resource or the requester's manager.
-2 — the manager of the booked resource or the requester's manager.
-4 — self (booked resource or the requester).
-9 — submitter (requester). This option may not be available depending on your OpenAir account configuration.

external_id

The unique external ID of the user, if the record was imported from an external system.

externalid

external_id

The unique external ID of the user, if the record was imported from an external system.

In the XML and SOAP API, the externalid property duplicates the external_id property.

filterset_ids

—

A comma delimited list of internal IDs of filter sets [Filterset] that this object belongs to.

filterset_stamp

—

A unique string which changes when the primary filter set changes for the user.

flags

—

User-specific settings. See Company and User Settings.

generic

A 1/0 field indicating whether this is a generic resource. Cannot be modified.

hierarchy_node_ids

—

A comma delimited list of internal IDs of hierarchy nodes [HierarchyNode] that this object belongs to.

hint

The user's password hint.

id

[Read-only] The unique internal identifier of the user. Automatically assigned by OpenAir.

is_user_schedule

—

[Write-only] A 1/0 field indicating whether the user should draw their workschedule from an account_workschedule or draw from a custom workschedule. 0 sets the user workschedule to the account workschedule specified in account_workscheduleid, 1 constructs a custom workschedule from the supplied workschedule_workdays and workschedule_workhours fields.

Used with update_workschedule Setting User Work Schedule.

job_codeid

job_code_id

The internal ID of the job code [Jobcode] associated with the user.

km_filter_set

The internal ID of the filter set override [Filterset] for the Workspaces application (module).

line_managerid

line_manager_id

The internal ID of the user's line manager (internal ID of another User). The user must exist, must not be marked as deleted, must be active and must not be a generic user.

locked

A 1/0 field indicating if the user is locked out of your company's OpenAir account.

logintime

user_login.logintime

The date and time of the user's last sign-in. See Date Fields.

ma_filter_set

The internal ID of the filter set override [Filterset] for the My Account application (module).

mfa_status

The user's two-factor authentication (2FA) status. The property is read-only if two-factor authentication is not enabled for your company's OpenAir account.

Possible values:

0 – 2FA is not required.
1 – 2FA is required and the user must set up 2FA.
2 – 2FA is required and the user has paired an authenticator app with OpenAir.
7 – 2FA is required and the user has completed the 2FA setup.

name

The display name for the user in lists. This is generated automatically if not set.

nickname

[Required] The users nickname. This must be unique.

om_filter_set

The internal ID of the filter set override [Filterset] for the Opportunities application (module).

password

[Required] The user's password. Not returned when reading objects.

password_forced_change

A 1/0 field indicating if the user must change password on next sign in.

payroll_code

The payroll code for this user.

pb_approvalprocess

The internal ID of the approval process [ApprovalProcess] for proposals submitted by the user. Mutually exclusive with pb_approver.

pb_approver

The internal ID of the User who approves proposals submitted by the user (proposal owner), if a single approver process is used. Mutually exclusive with pb_approvalprocess.

Other possible values:

-1 — the proposal owner’s manager.
-2 — the manager of the proposal owner’s manager.
-4 — self (proposal owner).

picklist_label

—

Label as shown on form picklist.

pm_filter_set

The internal ID of the filter set override [Filterset] for the Projects application (module).

po_approvalprocess

The internal ID of the approval process [ApprovalProcess] for purchase orders submitted by the user. Mutually exclusive with po_approver.

po_approver

The internal ID of the User who approves purchase orders submitted by the user (purchase order owner), if a single approver process is used. Mutually exclusive with po_approvalprocess.

Other possible values:

-1 — the purchase order owner’s manager.
-2 — the manager of the purchase order owner’s manager.
-4 — self (purchase order owner).

po_filter_set

The internal ID of the filter set override [Filterset] for the Purchases application (module).

pr_approvalprocess

The internal ID of the approval process [ApprovalProcess] for purchase requests submitted by the user. Mutually exclusive with pr_approver.

pr_approver

The internal ID of the User who approves purchase requests submitted by the user (purchase request owner), if a single approver process is used. Mutually exclusive with pr_approvalprocess.

Other possible values:

-1 — the purchase request owner’s manager.
-2 — the manager of the purchase request owner’s manager.
-4 — self (purchase request owner).

primary_filter_set

The internal ID of the user's primary filter set [Filterset]. Defaults to the default primary filter set if not set when adding a user.

project_access_nodes

Comma delimited list of internal IDs of hierarchy nodes [HierarchyNode] for project level access control.

rate

The hourly billing rate for the user's time.

report_filter_set

The internal ID of the filter set override [Filterset] for the Reports application (module).

rm_filter_set

The internal ID of the filter set override [Filterset] for the Resources application (module).

rm_approvalprocess

The internal ID of the approval process [ApprovalProcess] for bookings for the resource (user). Mutually exclusive with rm_approver.

rm_approver

The internal ID of the User who approves bookings for the user (resource), if a single approver process is used. Mutually exclusive with rm_approvalprocess.

Other possible values:

-1 — the booked resource’s manager.
-2 — the manager of the booked resource's manager.
-4 — self (booked resource).
-9 — submitter. This option may not be available depending on your OpenAir account configuration.

role_id

The internal ID of the role [Role] associated with the user. Defaults to the default role if not set when adding a user.

rpc_api_updated

The date and time when the user's resource profile was last updated using OpenAir API. See Date Fields.

rpc_updated_by

The internal ID of the User who last updated the user's resource profile.

rpc_user_updated

The date and time when the user's resource profile was last updated using OpenAir UI. See Date Fields.

sr_approvalprocess

The internal ID of approval process [ApprovalProcess] for schedule requests (time-off requests) submitted by the user. Mutually exclusive with sr_approver.

sr_approver

The internal ID of the User who approves schedule requests (time-off requests) for the user (schedule request owner), if a single approver process is used. Mutually exclusive with sr_approvalprocess.

Other possible values:

-1 — the schedule request owner’s manager.
-2 — the manager of the schedule request owner’s manager.
-4 — self (schedule request owner).

ssn

The user's social security number. Returned only if the authenticated user is an account administrator.

ta_approvalprocess

The internal ID of the approval process [ApprovalProcess] for timesheets submitted by the user. Mutually exclusive with ta_approver.

ta_approver

The internal ID of the User who approves timesheets submitted by the user (timesheet owner), if a single approver process is used. Mutually exclusive with ta_approvalprocess.

Other possible values:

-1 — the timesheet owner’s manager.
-2 — the manager of the timesheet owner’s manager.
-4 — self (timesheet owner).

ta_filter_set

The internal ID of the filter set override [Filterset] for the Timesheets application (module).

tag_end_date

entity_tag.end_date

[Write-only] End date for the new tag. If left blank, the end date for the new tag will be undefined and the new tag will assume default status for the user. See Date Fields.

Used with update_tag Updating User Entity Tags.

tag_group_attribute_id

entity_tag.tag_group_attribute_id

[Write-only] The ID of the tag group attribute [TagGroupAttribute] that is being assigned to the new tag.

Used with update_tag Updating User Entity Tags.

tag_group_id

entity_tag.tag_group_id

[Write-only] The ID of the tag group [TagGroup] for the new tag.

Used with update_tag Updating User Entity Tags.

tag_start_date

entity_tag.start_date

[Write-only] Start date for the new tag. If left blank, the start date for the new tag will be set to the current date. See Date Fields.

Used with update_tag Updating User Entity Tags.

tb_filter_set

The internal ID of the filter set override [Filterset] for the Invoices application (module).

te_allowance_approvalprocess

The internal ID of the approval process [ApprovalProcess] for allowance reports submitted by the user. Mutually exclusive with te_allowance_approver.

te_allowance_approver

The internal ID of the User who approves allowance reports submitted by the user (allowance report owner), if a single approver process is used. Mutually exclusive with te_allowance_approvalprocess.

Other possible values:

-1 — the allowance report owner’s manager.
-2 — the manager of the allowance report owner’s manager.
-4 — self (allowance report owner).

te_approvalprocess

The internal ID of the approval process [ApprovalProcess] for expense reports submitted by the user. Mutually exclusive with te_approver.

te_approver

The internal ID of the User who approves expense reports submitted by the user (expense report owner), if a single approver process is used. Mutually exclusive with te_approvalprocess.

Other possible values:

-1 — the expense report owner’s manager.
-2 — the manager of the expense report owner’s manager.
-4 — self (expense report owner).

te_filter_set

The internal ID of the filter set override [Filterset] for the Expenses application (module).

timezone

The user's timezone. Defaults to the time zone for the company's account if not set when adding a user.

type

—

Legacy field.

update_cost

—

[Write-only] Set to 1 to update loaded cost information automatically when adding or modifying a user. See Updating User Loaded Costs.

update_tag

—

[Write-only] Set to 1 to update entity tag information automatically when adding or modifying a user. See Updating User Entity Tags.

update_workschedule

—

[Write-only] Set to 1 to update work schedule information automatically when adding or modifying a user. See Setting User Work Schedule.

updated

[Read-only] Date and time when the record was last updated or modified. See Date Fields.

user_locationid

user_location_id

The internal ID of the user location [UserLocation] associated with the user.

week_starts

The first day of the week for the user:

0 – Monday
6 – Sunday

Defaults to the first day of the week for the company's account if not set when adding a user.

workschedule_workdays

—

A CSV list of workdays, with each value indicating a day in the schedule and values ranging from 0 (Monday) to 6 (Sunday). For example, “0,1,4” indicates that a user works on Monday, Tuesday and Friday.

Used with update_workschedule Setting User Work Schedule.

workschedule_workhours

—

A CSV list of values for the user's default workhours and workhours for each day. At least one value for workschedule_workhours must be submitted, but a value for each day may be submitted as well. For example, if the user's workschedule_workdays is set to “0,1,4”, then submitting a value of only “8” for workschedule_workhours sets the user's default hours to 8 and each workday assumes this value as well. In addition, submitting a workschedule_workdays value of “8,1,2,3” sets the user's default workhours to 8, sets Monday to 1, Tuesday to 2, and Friday to 3.

Used with update_workschedule Setting User Work Schedule.

workscheduleid

workschedule_id

The internal ID of the user's work schedule [UserWorkSchedule].

Usage Guidelines

Review the following guidelines:

Notes on relevant access privileges and role permissions:
- To view, create or modify a user record or generic user record, the primary filter set assigned to the authenticated user must allow access to that user record or generic user record.
- To modify a guest user record, the primary filter set assigned to the authenticated user must allow access to all users.
- To create or modify a user record (other than the authenticated user's own record), the authenticated user must be an administrator or have the View, modify, and create new users or View and modify users role permission.
- To modify user settings [flags], the authenticated user must be an administrator.
- All authenticated users can modify their own user record without the View, modify, and create new users and View and modify users role permission role permissions.
- The role_id property can be set to 1 (Administrator) only if the role authenticated user is Administrator.
- The filterset_ids property can be changed by any authenticated user with the Modify filter sets for existing things role permission, even if that authenticated does not have the View, modify, and create new users or View and modify users role permission.
- To create or modify a generic user record, the authenticated user must be an administrator or have the View and modify generics role permission.
To add users, use the CreateUser (XML API) or createUser() (SOAP API) command instead of the Add or add() command.
Limits are enforced to prevent you from creating or activating users if doing so would exceed the number of user licenses purchased for your account. If no user licenses of the appropriate type are available, the CreateUser (XML API) or createUser() (SOAP API) command creates a new user record, but sets it as inactive (clears the Active box on the employee record), and the CreateUser(XML API) or Modify(XML API) or modify() (SOAP API) commands cannot be used to activate a user record (to check the Active box on the employee record). For more information about OpenAir licensing and compliance, see Licenses.
You can use the generic attribute to 1 when reading User objects to return generic resources only. See Read Attributes.
When adding a user, default values are used for approval fields (<transaction>_approvalprocess and <transaction>_approver where <transaction>, typically a two-letter code, designates the transaction type) if not set. Unless default values were set when adding a user in the OpenAir UI, the head of the department associated with the user (if set), or the first account administrator (otherwise) is the default approver.
When adding or modifying a user, you can the following information for that user:
- Loaded cost – See Updating User Loaded Costs.
- Entity tag – See Updating User Entity Tags.
- Work schedule – See Setting User Work Schedule.

Updating User Loaded Costs

You can set or update user loaded cost information when creating or updating a user object. To do so, use the following property values:

Property	Value	Notes
`update_cost`	`1`	—
`cost_start_date`	Start date for the new loaded cost. See Date Fields. `Empty value` to use the current date.	—
`cost_end_date`	End date for the new loaded cost. See Date Fields. `Empty value` to leave the end date undefined, until the same level loaded cost is updated again.	If an empty value is used, the `cost_end_date` will be set automatically to a date preceding the `cost_start_date` of the new default loaded cost when the same level loaded cost is updated again. It is not possible to set a default value. All loaded cost information updated using this method is historical information
`cost`	New loaded cost value.	—
`cost_currency`	The currency of the new loaded cost value.	—
`cost_lc_level`	The loaded cost level, if multiple cost levels are enabled for your account. Defaults to `0` (primary loaded cost) if not specified.	—

Property

Value

Notes

update_cost

1

—

cost_start_date

Start date for the new loaded cost. See Date Fields.
Empty value to use the current date.

—

cost_end_date

End date for the new loaded cost. See Date Fields.
Empty value to leave the end date undefined, until the same level loaded cost is updated again.

If an empty value is used, the cost_end_date will be set automatically to a date preceding the cost_start_date of the new default loaded cost when the same level loaded cost is updated again. It is not possible to set a default value. All loaded cost information updated using this method is historical information

cost

New loaded cost value.

—

cost_currency

The currency of the new loaded cost value.

—

cost_lc_level

The loaded cost level, if multiple cost levels are enabled for your account. Defaults to 0 (primary loaded cost) if not specified.

—

To read user loaded cost information, use the LoadedCost object.

Updating User Entity Tags

You can set or update the user entity tags when creating or updating a user object. To do so, use the following property values:

Property	Value	Notes
`update_tag`	`1`	—
`tag_start_date`	Start date for the new entity tag. See Date Fields. `Empty value` to use the current date.	—
`tag_end_date`	End date for the new entity tag. See Date Fields. `Empty value` to leave the end date undefined, until the entity tag is updated with an empty value for `tag_end_date` again.	Use an empty value to set the entity tag as the default entity tag for the user valid from `tag_start_date`. If a default entity tag was set previously, the `tag_end_date` for the previous default entity tag is set automatically according to a date preceding the `tag_start_date` of the new default entity tag.
`tag_group_id`	ID of the tag group for the new entity tag.	—
`tag_group_attribute_id`	The ID of the tag group attribute assigned to the new entity tag.	—

Property

Value

Notes

update_tag

1

—

tag_start_date

Start date for the new entity tag. See Date Fields.
Empty value to use the current date.

—

tag_end_date

End date for the new entity tag. See Date Fields.
Empty value to leave the end date undefined, until the entity tag is updated with an empty value for tag_end_date again.

Use an empty value to set the entity tag as the default entity tag for the user valid from tag_start_date. If a default entity tag was set previously, the tag_end_date for the previous default entity tag is set automatically according to a date preceding the tag_start_date of the new default entity tag.

tag_group_id

ID of the tag group for the new entity tag.

—

tag_group_attribute_id

The ID of the tag group attribute assigned to the new entity tag.

—

To read user entity tag information, use the Entitytag object.

Setting User Work Schedule

You can set or update the user work schedule when creating or updating a user object. To do so, use the following property values:

Property	Value	Notes
`update_workschedule`	`1`	—
`is_user_schedule`	`1` to define a work schedule specific to the user. `0` to use the company work schedule with ID `account_workscheduleid`.	—
`workschedule_workdays`	Comma-separated list of numbers for usual work days. Each day of the week is represented by a number from `0` (Monday) to `6` (Sunday).	Used if `is_user_schedule` = `1`.
`workschedule_workhours`	Comma-separated list of numbers, if your account configuration allows for different work hours per day. The first value is the default number of hours per day, subsequent values are the number of hours for each work day listed in `workschedule_workdays`. Default number of hours per day, otherwise.	Used if `is_user_schedule` = `0`. To allow for different work hours, check the Enable distinct work hours per day on work schedule box on the Optional Features administration form (Administration > Global Settings > Optional Features)
`account_workscheduleid`	The ID of the company work schedule.	Used if `is_user_schedule` = `0`.

Property

Value

Notes

update_workschedule

1

—

is_user_schedule

1 to define a work schedule specific to the user.
0 to use the company work schedule with ID account_workscheduleid.

—

workschedule_workdays

Comma-separated list of numbers for usual work days. Each day of the week is represented by a number from 0 (Monday) to 6 (Sunday).

Used if is_user_schedule = 1.

workschedule_workhours

Comma-separated list of numbers, if your account configuration allows for different work hours per day. The first value is the default number of hours per day, subsequent values are the number of hours for each work day listed in workschedule_workdays.
Default number of hours per day, otherwise.

Used if is_user_schedule = 0.

To allow for different work hours, check the Enable distinct work hours per day on work schedule box on the Optional Features administration form (Administration > Global Settings > Optional Features)

account_workscheduleid

The ID of the company work schedule.

Used if is_user_schedule = 0.

To read user work schedule information, use the UserWorkschedule object.