Filtering

You can use the filter attribute to specify search criteria when retrieving a list of objects using the Read (XML API) or read() (SOAP API) command. The response will only include the objects matching the conditions specified in the request.

The following table lists the supported values for the filter attribute. To apply multiple filters or search criteria, use a single filter attribute and a comma-separated list of filter values. For example, you can set the filter attribute to newer-than,older-than,approved-timesheets to return only approved timesheets or objects associated with approved timesheets updated within a certain date range.

Important:

Make sure there are no spaces between the commas and the filter values.

Note:

In the following table "objects associated with a(n) <associated object type>" means that one of the properties of the object type requested references the ID of the <associated object type> object. For example, an object associated with an expense report (envelope) has the property envelope_id or envelopeid. You should not use a filter if the requested object type does not reference the associated object on which the filter is based. For example, you should not use the filter open-envelopes when reading Project objects.

Filter Value	Response
open-envelopes	Returns only open expense reports (envelopes) or objects associated with an open expense report (envelope).
approved-envelopes	Returns only approved expense reports (envelopes) or objects associated with an approved expense report (envelope).
rejected-envelopes	Returns only rejected expense reports (envelopes) or objects associated with a rejected expense report (envelope).
submitted-envelopes	Returns only submitted expense reports (envelopes) or objects associated with a submitted expense report (envelope).
nonreimbursed-envelopes	Returns envelopes that have a non-zero balance attribute. Returns only expense reports (envelopes) that have a non-zero balance or objects associated with expense reports (envelopes) that have a non-zero balance.
reimbursable-envelope	Returns only reimbursable expense reports (envelopes) or objects associated with a reimbursable expense report (envelope).
open-slips	Returns only open charges (slips) or objects associated with an open charge (slip).
approved-slips	Returns only approved charges (slips) or objects associated with an approved charge (slip).
open-timesheets	Returns only open timesheets or objects associated with an open timesheet.
approved-timesheets	Returns only approved timesheets or objects associated with an approved timesheet.
rejected-timesheets	Returns only rejected timesheets or objects associated with a rejected timesheet.
submitted-timesheets	Returns only submitted timesheets or objects associated with a submitted timesheet.
approved-revenue-recognition-transactions	Returns only revenue recognition transactions belonging to approved revenue containers.
not-exported	Returns only objects that have not been marked as exported. Include an ImporExport argument object to specify the application the objects should be exported to. See Read Not Exported Charges with all Method — C# and Read Not Exported Charges with all Method — Java.
newer-than	Date filter. Returns only objects that have a value in the updated field (or in the field specified using the field attribute) that is newer than the date specified. See Date Filters Usage.
older-than	Date filter. Returns only objects that have a value in the updated field (or in the field specified using the field attribute) that is older-than the date specified. See Date Filters Usage.
date-equal-to	Date filter. Returns only objects that have a value in the updated field (or in the field specified using the field attribute) that is equal to the date specified. See Date Filters Usage.
date-not-equal-to	Date filter. Returns only objects that have a value in the updated field (or in the field specified using the field attribute) that is not equal to the date specified. See Date Filters Usage.

Date Filters Usage

You can use date filters listed in the above table to specify search criteria when retrieving a list of objects using the Read (XML API) or read() (SOAP API) command.

By default, date filters compare the updated field to the date specified. Use the field attribute in conjunction with the filter attribute to set date filters and compare any date fields other than updated.

Important:

Always double check date values in your requests to ensure they are in the correct format and avoid any potential errors or unexpected behavior.

To apply multiple date filters or search criteria:

• Use a comma-separated list to specify the date fields for multiple date filters in the same order as the filters those fields apply to.

  Important:

  Make sure there are no spaces between the commas and the values.

• Include Date argument objects in the same order as the date filters those arguments apply to as part of the objects collection in your request.

Sample codes:

• XML API – Read with all Method and Date Filters

• SOAP API – Read Not Exported Expense Reports with all Method and Date Filter — C# and Read with all Method and Date Filters — Java.