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).
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.