UserModifiableFields

These are fields in the User object that can be modified (not necessarily by the user in question) or given as input when creating a new User.

tip

Note that only user_login and fullname are required when creating a new User.

Note: If using SSO (Single Sign-On), the user_login field usually needs to match the user's email address, UPN, or other primary identifier in the external authentication system.

warning

The new_pw, new_pw2, and expire_new_pw fields should only be used when intending to change the user's password.

custom_fields object

An object with Custom Fields for this record. The key is the field ID and the value a description of the field. Additional details here: CustomFields Schema

tip

Updating Custom Field values

When creating or updating an existing object that uses Custom Fields, for example a User record, you can follow this custom_field key structure to update the custom field values. The value field is the only required field for updating a custom field value; other fields such as pname will be ignored.

info

Important: depending on the endpoint, this may only be included in the response if $keys=custom_fields or $keys=$extended was set as a query parameter.

There is also a more compact representation available in most object types, where each custom field value is a separate key in the main object (not under custom_fields).

See the CustomFields Schema page for more detailed information on these topics.

property name* CustomFieldValue

A specific instance (value) of a Custom field for a particular object.

id_attr_typestring

The unique internal ID of this Custom Field definition (same as id field)

Example: 2DDD372DC4D3422D9E73F6DE936C4265

attr_typestring

Datatype of the custom field. The basic types available are:

STRING - a variable-length string.
CHAR - a fixed-length string. (The value may be padded with spaces.)
NUMBER - a floating-point number.
INTEGER - an integer (whole number).
TIMESTAMP - a date and time, stored in Unix epoch format.
DATE - a YYYYMMDD (F8) date.

In addition, most types can be modified with a prefix to indicate whether they are "select lists" (ENUM or enumerated) or "multi-select lists" (M_ENUM) which can take on multiple values.

Strings and char may also have a maximum length specified, such as STRING_100.

Example: ["STRING_100","ENUM_STRING_20","M_ENUM_STRING_252","ENUM_INTEGER","NUMBER"]

descriptionstring

Description of custom field

pnamestring

Name of custom field

Example: Pay Group

id_attr_type_uristring

URI of the custom field to get more information about the custom field definition.

Example: /api/v1/custom_fields/E07526A217164D1B94188279A8A0E4D9

valuestring

Value of the custom field for this object. To update the value, see the note on the CustomFields schema page.

Note that when modifying Custom Fields of objects like Users or Projects, only the value key will be checked; other fields like the Custom Field pname will be ignored.

Example: XYZ Pay Group

group_names object[]

A list of Groups (names and IDs) that the object belongs to.

This is a read-only list. To change the Groups that an object belongs to, use the groups field.

See GroupFields for additional information about Groups and this field.

Array [

iduuid

The Group ID.

pnamestring

The Group name.

uristring

The URI of the Group.

WARNING: this field is planned in a future release but is not yet available.

]

groupsuuid[]

A list of Group IDs that the object belongs to. See GroupFields for additional information about Groups and this field.

Example: ["5088C427E8B64EBEBE1C5B5961DB1902","3553F715A6F54DAB95D0D25B08468195"]

is_hiddenboolean

Indicates whether the object is hidden.

See also status

hiddenboolean

Indicates whether the user is hidden.

Read-only alias for is_hidden.

statusstring

The status of the user; either hidden, active, or inactive.

Possible values: [Hidden, Loggable and Reportable, Reportable Only]

Example: Loggable and Reportable

status_codestring

The internal code for the status of the object; either:

lr for Loggable and Reportable
ro for Reportable Only
h for Hidden

Possible values: [lr, ro, h]

Example: lr

user_loginstringrequired

The login name of the user.

Example: john.smith@example.com

fullnamestringrequired

The full name of the user.

Example: John Smith

u_commentstring

The default comment on the user's time entry screen.

default_memorized_sheetstring

The ID of the user's default memorized timesheet.

dropdownthresholdinteger

The number of items in a selection list to trigger a forced search.

hideboolean

Indicates whether the user is hidden.

Note: the User object is the only one that uses this field; other objects use is_hidden.

expire_new_pwboolean

Whether the user's new password should expire after the first login.

This is a write-only field that does not appear in User object responses.

new_pwstring

The new password for the user.

The password must also be set in the new_pw2 field to confirm the change.

This is a write-only field that does not appear in User object responses.

new_pw2string

The new password for the user, repeated to confirm the change.

The password must also be set in the new_pw field to confirm the change.

This is a write-only field that does not appear in User object responses.

rolesstring[]

A list of role IDs belonging to this user.

This list can be modified to change the user's roles.

timerecs_ininteger

The number of blank rows to show on the entry screen.

Example: 3

time_periodstring

The "Entry Screen period" (time-span) associated with the user's Time Entry screen.

Example: default_weekly

expense_periodstring

The "Entry Screen period" (time-span) associated with the user's Expense Entry screen.

Example: default_weekly

custom_periodstring

The "Entry Screen period" (time-span) associated with the user's Custom Entry screen.

Example: default_weekly

expense_guistring

The Entry Screen ID (aka GUI) of the user's Expense Entry screen.

time_guistring

The Entry Screen ID (aka GUI) of the user's Time Entry screen.

travel_guistring

The Entry Screen ID (aka GUI) of the user's Custom Entry screen.

UserModifiableFields
{
  "user_login": "john.smith@example.com",
  "fullname": "John Smith",
  "u_comment": "string",
  "status": "Loggable and Reportable",
  "default_memorized_sheet": "string",
  "dropdownthreshold": 0,
  "hide": true,
  "expire_new_pw": true,
  "new_pw": "string",
  "new_pw2": "string",
  "roles": [
    "string"
  ],
  "timerecs_in": 3,
  "time_period": "default_weekly",
  "expense_period": "default_weekly",
  "custom_period": "default_weekly",
  "expense_gui": "string",
  "time_gui": "string",
  "travel_gui": "string",
  "custom_fields": {
    "C41B2DDA662F4EF6B730F9CB6DB04696": {
      "attr_type": "ENUM_STRING_252",
      "description": "Employee pay group.",
      "id_attr_type": "C41B2DDA662F4EF6B730F9CB6DB04696",
      "id_attr_type_uri": "/api/v1/custom_fields/C41B2DDA662F4EF6B730F9CB6DB04696",
      "pname": "Pay Group",
      "value": "XYZ Pay Group"
    },
    "users_email": {
      "attr_type": "STRING_252",
      "description": "Email address",
      "id_attr_type": "users_email",
      "id_attr_type_uri": "/api/v1/custom_fields/users_email",
      "pname": "Email Address",
      "value": "username@example.com"
    }
  },
  "group_names": [
    {
      "id": "5088C427E8B64EBEBE1C5B5961DB1902",
      "pname": "Sales"
    },
    {
      "id": "3553F715A6F54DAB95D0D25B08468195",
      "pname": "Accounting"
    }
  ],
  "groups": [
    "5088C427E8B64EBEBE1C5B5961DB1902",
    "3553F715A6F54DAB95D0D25B08468195"
  ],
  "is_hidden": true,
  "hidden": true,
  "status_code": "lr"
}