CustomFields

Custom fields are used to store additional information about a resource. The fields are defined by the system administrators and can be of various data types.

This page describes the schema for custom field values as shown in the response of a resource that has custom fields. There is an expanded schema for the custom field definitions at their own endpoint, as shown in the id_attr_type_uri field.

tip

The custom_fields object will only be included in the response if requested in $keys; see details below.

Editing Custom Fields

In general, to update Custom Field values for an object, when submitting a PUT request to update the object, you can include the custom_fields object in the request body. The custom_fields object should follow the basic schema shown here, but only needs to include the value field for each custom field you want to update. For example, this is enough to update two custom fields:

{
  "custom_fields": {
    "C41B2DDA662F4EF6B730F9CB6DB04696": {
      "value": "New Value"
    },
    "users_email": {
      "value": "new_email@example.com"
    }
}

Any custom fields not included in the custom_fields object will not be updated and will retain their current values. You can set the null value

Viewability

It's also important to note that Custom Fields are subject to viewability restrictions based on the "Reportability" property set by system administrators.

tip

Please note that access to view custom fields are automatically filtered by "Reportability", a property set by admins on the custom field definition that determines which User Roles are allowed to see the field. If you are not seeing a custom field that you expect to see, please check with your system administrator.

Examples

Here's an example value of custom_fields in a response:

"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"
  }

Note that there is an alternate representation available in most object types, where each custom field value is a separate key in the main object (not under custom_fields) in the following format, showing both a singular and multi-value example:

"users_attribs:C41B2DDA662F4EF6B730F9CB6DB04696": "XYZ Pay Group",
"users_attribs:users_skills": [
  "CRM admin - advanced"
]

This follows the pattern of users_attribs:<field_id>, where users_attribs is the internal table name for User custom fields. For other object types, the table name will be different, e.g. projects_attribs. This is a read-only representation for convenience and is not used for updating custom fields.

This more compact representation is always provided (unless $keys=$base was set). However, the custom_fields object will only be available if $keys=custom_fields or $keys=$extended was set.

custom_fields object

A map of custom fields. The key is the field ID and the value a description of the field.

Important: this will 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 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 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.

Example: XYZ Pay Group

CustomFields
{
  "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"
    }
  }
}

CustomFields

Editing Custom Fields​

Viewability​

Examples​

Editing Custom Fields

Viewability

Examples