Read Attributes

You can use attributes to modify the response when reading objects using the XML API or SOAP API. Some attributes control API features available for most supported object types, other attributes can only be used when reading a specific object type.

The following table lists the supported attributes, and for each attribute, the object types and methods that supports the attribute if it can only be used when reading a specific object type or with a specific method, and a description of its usage.

Attribute	Object Type	Supported Methods	Usage
`base_currency`	`Currencyrate`	`all`, `equal to`	Set the `base_currency` attribute to a three-letter currency code to get the exchange rates against the specified base currency.
`between_date`	`Entitytag`	`equal to`, `not equal to`	XML API Only — Use the `between_date` to set the exact date when the entity tag applied. The response includes only entity tags with `start_date` before and `end_date` after the date specified. The value must be a date in the following format `yyyy-mm-dd` (`2023-11-26`, for example). Set `between_date` to `0000-00-00` to return all entries with no start and end dates.
`calculate_hours`	`Timesheet`	`all`, `equal to`, `not equal to`, `user`	Set the `calculate_hours` attribute to `1` to return the minimum number of hours required [`min_hour`] and the maximum number of hours allowed [`max_hour`] on the timesheet as per applicable timesheet rules (Administration > Application Settings > Timesheets > Timesheet Rules).
`clear_filter_cache`	—	`all`, `custom equal to`, `equal to`, `not equal to`, `project`, `user`	Set the `clear_filter_cache` attribute to `1` to clear the filter set cache and read the latest available data including any objects that were created recently. When using an OAuth 2.0 access token to authenticate API requests, the API uses cached filter set information —information about objects which the authenticated user can access according to the filter set assigned to that user— to optimize performance. By default, read requests using a valid access token do not include objects created after the access token was issued, even if the user can access the new objects in the UI. If new objects are expected, you can clear and regenerate the cached filter set information using the . Important: Use the `clear_filter_cache` attribute sparingly to avoid performance deterioration. After you use the attribute in a read request, you should not use it again in subsequent read requests unless you expect objects created after the filter set information cache was last generated in the response. Each access token scope has its own filter set caching mechanism. If using the same access token with the REST, XML and SOAP API in your integration, clearing the cache for XML API requests does not clear the cache for REST API and SOAP API requests.
`deleted`	—	`all`, `custom equal to`, `equal to`, `not equal to`, `project`, `user`	Set the `deleted` attribute to `1` to return objects that are marked as deleted. Can be used together with `newer-than` filter to return objects deleted after a specific date. Set the `include_nondeleted` attribute to `1` to include objects that are not marked as deleted as well as objects that are marked as deleted.
`enable_custom`	—	`all`, `equal to`, `not equal to`, `project`, `user`	XML API Only — Set the `enable_custom` attribute to `1` to include custom field values in the returned object properties inline with standard object properties. Custom field values are included in the returned object properties by default when using the SOAP API.
`end_date`	`Schedulebyday`	`all`	The `end_date` attribute must be set when retrieving `Schedulebyday` objects using the `read all` method. The value must be a date in the following format `yyyy-mm-dd` (`2023-11-26`, for example). You must specify a date range (start date and end date) for which you want to retrieve employee work schedules per date. The XML API or SOAP API returns error code `10` with the message "`Invalid parameters, specify start_date, end_date, and user_filter attributes`" otherwise.
`exclude_flags`	`Company` `User`	`equal to`, `not equal to`	XML API Only — Set the `exclude_flags` attribute to `1` to exclude account or user settings from the response.
`field`	—	`all`, `custom equal to`, `equal to`, `not equal to`, `project`, `user`	Use the `field` attribute in conjunction with the `filter` attribute to set date filters and compare any date fields other than `updated`. See Filtering.
`field_names`	—	`custom equal to`	Use the `field_names` attribute to list the custom field to be returned. The value must be a comma-separated list of custom field names. Listed custom fields must be for the requested object type.
`filter`	—	`all`, `custom equal to`, `equal to`, `not equal to`, `project`, `user`	Use the `filter` attribute to return only objects that follow one or more filter criteria. By default, date filters compare the `updated` field to the date specified. Use the `field` attribute to compare any date fields other than `updated`. For more information about the Filtering feature and filter criteria, see Filtering.
`generic`	`User`	`all`	Set the `generic` attribute to `1` to return generic resources (users) only. By default the API returns named resources (users) only.
`include_flags`	`Company` `User`	`all`, `equal to`, `not equal to`	SOAP API Only — Set the `include_flags` attribute to `1` to include account or user settings from the response. The `flag` value is a `oaSwitch` object.
`include_nondeleted`	—	`all`, `custom equal to`, `equal to`, `not equal to`, `project`, `user`	Use the `include_nondeleted` attribute in conjunction with the `deleted` attribute to include objects that are not marked as deleted as well as objects that are marked as deleted.
`limit`	—	`all`, `custom equal to`, `equal to`, `not equal to`, `project`, `user`	[Required] Use the `limit` attribute to control the response pagination with an offset (the number of objects to skip) and the maximum number of objects to be returned per page. See Pagination.
`order`	—	`all`, `custom equal to`, `equal to`, `not equal to`, `project`, `user`	XML API Only — Use the `order` attribute to sort the returned list by the specified property in ascending or descending order.
`precision`	`Currencyrate`	`all`, `equal to`	Use the `precision` attribute to set the decimal precision (maximum number of digits to the right of the decimal point) for foreign currency exchange rate values.
`start_date`	`Schedulebyday`	`all`	The `start_date` attribute must be set when retrieving `Schedulebyday` objects using the `read all` method. The value must be a date in the following format `yyyy-mm-dd` (`2023-10-26`, for example). You must specify a date range (start date and end date) for which you want to retrieve employees work schedule per date. The XML API or SOAP API returns error code `10` with the message "`Invalid parameters, specify start_date, end_date, and user_filter attributes`" otherwise.
`tag_with_name`	`Entitytag`	`equal to`, `not equal to`	Set the `tag_with_name` attribute to `1` to include the name of the associated tag group attribute [`tag_group_attribute_name`] as property the response. By default, only the internal ID of the tag group attribute is returned but not the name.
`user_filter`	`Schedulebyday`	`all`	The `user_filter` attribute must be set when retrieving `Schedulebyday` objects using the `read all` method. The value must be a comma-separated list of user internal IDs. You must specify the employees for whom you want to retrieve the work schedules per date. The XML API or SOAP API returns error code `10` with the message "`Invalid parameters, specify start_date, end_date, and user_filter attributes`" otherwise.
`with_project_only`	`Customer`	`all`, `equal to`, `not equal to`, `user`	Set the `with_project_only` attribute to `1` to return only customers associated to one or more project.

Attribute

Object Type

Supported Methods

Usage

base_currency

Currencyrate

all, equal to

Set the base_currency attribute to a three-letter currency code to get the exchange rates against the specified base currency.

between_date

Entitytag

equal to, not equal to

XML API Only — Use the between_date to set the exact date when the entity tag applied. The response includes only entity tags with start_date before and end_date after the date specified. The value must be a date in the following format yyyy-mm-dd (2023-11-26, for example).

Set between_date to 0000-00-00 to return all entries with no start and end dates.

calculate_hours

Timesheet

all, equal to, not equal to, user

Set the calculate_hours attribute to 1 to return the minimum number of hours required [min_hour] and the maximum number of hours allowed [max_hour] on the timesheet as per applicable timesheet rules (Administration > Application Settings > Timesheets > Timesheet Rules).

clear_filter_cache

—

all, custom equal to, equal to, not equal to, project, user

Set the clear_filter_cache attribute to 1 to clear the filter set cache and read the latest available data including any objects that were created recently.

When using an OAuth 2.0 access token to authenticate API requests, the API uses cached filter set information —information about objects which the authenticated user can access according to the filter set assigned to that user— to optimize performance. By default, read requests using a valid access token do not include objects created after the access token was issued, even if the user can access the new objects in the UI. If new objects are expected, you can clear and regenerate the cached filter set information using the .

Important:

Use the clear_filter_cache attribute sparingly to avoid performance deterioration. After you use the attribute in a read request, you should not use it again in subsequent read requests unless you expect objects created after the filter set information cache was last generated in the response.

Each access token scope has its own filter set caching mechanism. If using the same access token with the REST, XML and SOAP API in your integration, clearing the cache for XML API requests does not clear the cache for REST API and SOAP API requests.

deleted

—

all, custom equal to, equal to, not equal to, project, user

Set the deleted attribute to 1 to return objects that are marked as deleted. Can be used together with newer-than filter to return objects deleted after a specific date.

Set the include_nondeleted attribute to 1 to include objects that are not marked as deleted as well as objects that are marked as deleted.

enable_custom

—

all, equal to, not equal to, project, user

XML API Only — Set the enable_custom attribute to 1 to include custom field values in the returned object properties inline with standard object properties.

Custom field values are included in the returned object properties by default when using the SOAP API.

end_date

Schedulebyday

all

The end_date attribute must be set when retrieving Schedulebyday objects using the read all method. The value must be a date in the following format yyyy-mm-dd (2023-11-26, for example). You must specify a date range (start date and end date) for which you want to retrieve employee work schedules per date. The XML API or SOAP API returns error code 10 with the message "Invalid parameters, specify start_date, end_date, and user_filter attributes" otherwise.

exclude_flags

Company
User

equal to, not equal to

XML API Only — Set the exclude_flags attribute to 1 to exclude account or user settings from the response.

field

—

all, custom equal to, equal to, not equal to, project, user

Use the field attribute in conjunction with the filter attribute to set date filters and compare any date fields other than updated. See Filtering.

field_names

—

custom equal to

Use the field_names attribute to list the custom field to be returned. The value must be a comma-separated list of custom field names. Listed custom fields must be for the requested object type.

filter

—

all, custom equal to, equal to, not equal to, project, user

Use the filter attribute to return only objects that follow one or more filter criteria.

By default, date filters compare the updated field to the date specified. Use the field attribute to compare any date fields other than updated.

For more information about the Filtering feature and filter criteria, see Filtering.

generic

User

all

Set the generic attribute to 1 to return generic resources (users) only. By default the API returns named resources (users) only.

include_flags

Company
User

all, equal to, not equal to

SOAP API Only — Set the include_flags attribute to 1 to include account or user settings from the response. The flag value is a oaSwitch object.

include_nondeleted

—

all, custom equal to, equal to, not equal to, project, user

Use the include_nondeleted attribute in conjunction with the deleted attribute to include objects that are not marked as deleted as well as objects that are marked as deleted.

limit

—

all, custom equal to, equal to, not equal to, project, user

[Required] Use the limit attribute to control the response pagination with an offset (the number of objects to skip) and the maximum number of objects to be returned per page. See Pagination.

order

—

all, custom equal to, equal to, not equal to, project, user

XML API Only — Use the order attribute to sort the returned list by the specified property in ascending or descending order.

precision

Currencyrate

all, equal to

Use the precision attribute to set the decimal precision (maximum number of digits to the right of the decimal point) for foreign currency exchange rate values.

start_date

Schedulebyday

all

The start_date attribute must be set when retrieving Schedulebyday objects using the read all method. The value must be a date in the following format yyyy-mm-dd (2023-10-26, for example). You must specify a date range (start date and end date) for which you want to retrieve employees work schedule per date. The XML API or SOAP API returns error code 10 with the message "Invalid parameters, specify start_date, end_date, and user_filter attributes" otherwise.

tag_with_name

Entitytag

equal to, not equal to

Set the tag_with_name attribute to 1 to include the name of the associated tag group attribute [tag_group_attribute_name] as property the response. By default, only the internal ID of the tag group attribute is returned but not the name.

user_filter

Schedulebyday

all

The user_filter attribute must be set when retrieving Schedulebyday objects using the read all method. The value must be a comma-separated list of user internal IDs. You must specify the employees for whom you want to retrieve the work schedules per date. The XML API or SOAP API returns error code 10 with the message "Invalid parameters, specify start_date, end_date, and user_filter attributes" otherwise.

with_project_only

Customer

all, equal to, not equal to, user

Set the with_project_only attribute to 1 to return only customers associated to one or more project.