Read Methods

The following table lists the supported methods for reading objects using the XML API or SOAP API. For each supported read method, the table includes a description of the API response.

Note:

Most available business object types support the all, equal to and not equal to methods except where otherwise noted in the reference material for each business object type. See XML and SOAP API Business Object Reference.

Method	Response
`all`	Returns all objects. Sample codes: XML API – Read with all Method and Date Filters SOAP API – Read Not Exported Charges with all Method — C# and Read with all Method and Date Filters — Java
`equal to`	Returns objects that are matching the search query object specified as argument in the read command. The read command must include a search query object as argument. The search query object must be of the same type as the objects you want to retrieve. Include all the standard object property values and custom field values that the returned objects must match. When using the XML API, set the attribute `enable_custom` to `1` if you include custom field values in the search query object. Important: Calculated fields are not supported. You cannot include properties corresponding to calculated fields in your search query object. The SOAP API lets you specify multiple `equal to` or `not equal to` conditions combined with `and` or `or` logical operators. See Combining Relational Methods Using Logical Operators (SOAP API). Sample codes: XML API – Read with equal to Method and Date Filter and Read Expense Reports Pending Reimbursement with equal to Method SOAP API – Read with equal to Method — C# and Read with equal to Method — Java
`not equal to`	Returns objects that are not matching the search query object specified as argument in the read command. The read command must include a search query object as argument. The search query object must be of the same type as the objects you want to retrieve. Include all the standard object property values and custom field values that the returned objects must not match. Important: Calculated fields are not supported. You cannot include properties corresponding to calculated fields in your search query object. The SOAP API lets you specify multiple `equal to` or `not equal to` conditions combined with `and` or `or` logical operators. See Combining Relational Methods Using Logical Operators (SOAP API). Sample codes: XML API – Read with not equal to Method Matching a Custom Field SOAP API – Read with not equal to Method — C# and Read with not equal to Method — Java
`custom equal to`	Returns the custom field values for the object with the internal ID in the search query object. Custom field values are returned as `CustomField` objects (See CustomField). The read command must include a search query object as argument. The search query object must be of the same type as the objects you want to retrieve and must include the internal ID [`id`] of the object for which you want to retrieve custom field values. Note: All business object types that support custom fields support the `custom equal to` method. Returned objects include custom field values along with standard object properties by default when using the SOAP API. When using the XML API, you can set the `enable_custom` attribute to `1` to include custom field values in the returned object properties along with standard object properties. Sample codes: XML API – Read Custom Field Values with custom equal to Method SOAP API – Read Custom Field Values with custom equal to Method — C#
`user`	Note: All business objects with a `userid` reference fields support the `project` method. Returns objects associated with the user matching the internal ID specified in the `User` search query object. When reading `Projecttask` objects, returns project tasks assigned to the user.
`project`	Note: All business objects with a `projectid` reference fields and `Projecttaskassign` support the `project` method. Returns objects associated with the project matching the internal ID specified in the `Project` search query object. When reading `Projecttaskassign` objects, returns project task assignments for tasks in the project.

Method

Response

all

Returns all objects.

Sample codes:

XML API – Read with all Method and Date Filters
SOAP API – Read Not Exported Charges with all Method — C# and Read with all Method and Date Filters — Java

equal to

Returns objects that are matching the search query object specified as argument in the read command.

The read command must include a search query object as argument. The search query object must be of the same type as the objects you want to retrieve. Include all the standard object property values and custom field values that the returned objects must match. When using the XML API, set the attribute enable_custom to 1 if you include custom field values in the search query object.

Important:

Calculated fields are not supported. You cannot include properties corresponding to calculated fields in your search query object.

The SOAP API lets you specify multiple equal to or not equal to conditions combined with and or or logical operators. See Combining Relational Methods Using Logical Operators (SOAP API).

Sample codes:

XML API – Read with equal to Method and Date Filter and Read Expense Reports Pending Reimbursement with equal to Method
SOAP API – Read with equal to Method — C# and Read with equal to Method — Java

not equal to

Returns objects that are not matching the search query object specified as argument in the read command.

Important:

Calculated fields are not supported. You cannot include properties corresponding to calculated fields in your search query object.

The SOAP API lets you specify multiple equal to or not equal to conditions combined with and or or logical operators. See Combining Relational Methods Using Logical Operators (SOAP API).

Sample codes:

XML API – Read with not equal to Method Matching a Custom Field
SOAP API – Read with not equal to Method — C# and Read with not equal to Method — Java

custom equal to

Returns the custom field values for the object with the internal ID in the search query object. Custom field values are returned as CustomField objects (See CustomField).

The read command must include a search query object as argument. The search query object must be of the same type as the objects you want to retrieve and must include the internal ID [id] of the object for which you want to retrieve custom field values.

Note:

All business object types that support custom fields support the custom equal to method.

Returned objects include custom field values along with standard object properties by default when using the SOAP API.

When using the XML API, you can set the enable_custom attribute to 1 to include custom field values in the returned object properties along with standard object properties.

Sample codes:

XML API – Read Custom Field Values with custom equal to Method
SOAP API – Read Custom Field Values with custom equal to Method — C#

user

Note:

All business objects with a userid reference fields support the project method.

Returns objects associated with the user matching the internal ID specified in the User search query object. When reading Projecttask objects, returns project tasks assigned to the user.

project

Note:

All business objects with a projectid reference fields and Projecttaskassign support the project method.

Returns objects associated with the project matching the internal ID specified in the Project search query object. When reading Projecttaskassign objects, returns project task assignments for tasks in the project.

Combining Relational Methods Using Logical Operators (SOAP API)

The SOAP API lets you combine equal to or not equal to methods using and or or logical operators.

To do so:

Set the method parameter to a list of equal to and not equal to relational operator methods, each separated by a comma followed by an and or or logical operator. An and logical operator is used by default if not specified. The use of grouping or parentheses to modify precedence is not supported.
Pass the same number of search query objects as arguments. There must be one search query object for each listed method.

Examples:

If method is set to equal to,not equal to, which is the same as equal to,and not equal to, the response returns object that match the first search query object but do not match the second search query object.
If method is set to equal to,or equal to,and not equal to, the response returns object that do not match the third search query object and match either the first search query object or the second search query object.

Sample code: Read with Multiple equal to Methods Combined with Explicit OR Condition — C#.