Read

Retrieves one or more objects of the type specified based on the method, attributes and other parameters passed.

Syntax

            <Read type="ObjectType" method="method name" attr_name1="attr_value1" attr_name2="attr_value2">
</Read> 

          

Usage

Use the Read command to retrieve one or more objects of a specific type.

Define the type of objects to retrieve, the read method, the maximum number of objects to return (limit) and any optional attributes. See ReadRequest.

Attributes

Name	Description
type	[Required] The type of object to return. For information about supported object types, see List of Supported Business Object Types.
method	[Required] The name of the read method to be used. The read method lets you specify whether to return all objects, only the objects matching or not matching a search query object, or the custom field values for a specific object. See Read Methods.
limit	[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.
optional attributes	The attributes lets you 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. See Read Attributes.

Arguments

Name	Description
ObjectType	Used with the equal to, not equal to, and custom equal to methods. An object of the same type as the objects to return with the object property values that returned objects should match or not match.
Date objects	Used with date filters. A Date object for each date filter defined by the filter attribute, if any. See Date Filters Usage.
ImportExport	Used with not-exported filter. An ImportExport object specifies the application the object was not exported to. <ImportExport> <application>MyApp</application> </ImportExport>
_Return	An object listing the object properties to return. <_Return> <property1/> <property2/> <property3/> </_Return> The _Return object, must be the last argument passed (immediately before the Read command closing tag). If omitted or empty, the response includes all standard object properties for each returned object. Unless the attribute exclude_flags is set to 1 , the response also includes the flags property for User or Company objects. If the attribute enable_custom is set to 1, the response also includes all custom fields for the object type.

Response

ObjectType objects.

Sample Codes

Read with all Method and Date Filters

The following example returns up to a thousand time entries for dates between July 1, 2023 and August 1, 2023 using newer-than and older-than date filters. The only properties included in the response are the time entry internal ID, the number of hours and minutes, the associated project internal ID, and the associated project task internal ID.

              <Read type ="Task" filter="newer-than,older-than" field="date,date" method="all" limit="1000">
   <Date>
      <year>2023</year>
      <month>07</month>
      <day>01</day>
   </Date>
   <Date>
      <year>2023</year>
      <month>08</month>
      <day>01</day>
   </Date>
   <_Return>
      <id/>
      <hours/>
      <minutes/>
      <projectid/>
      <projecttaskid/>
   </_Return>
</Read> 

            

Read with equal to Method and Date Filter

The following example returns up to a thousand time entries for dates after January 1, 2023 that are associated with the customer with internal ID 5 and that are not associated with any charges (charge internal ID is null). The only properties included in the response are the time entry internal ID, the number of hours and minutes, the associated project internal ID, and the associated project task internal ID.

              <Read type ="Task" method="equal to" filter="newer-than" field="date" limit="1000">
   <Date>
      <year>2023</year>
      <month>01</month>
      <day>01</day>
   </Date>
   <Task>
      <slipid/>
      <customerid>5</customerid>
   </Task>
   <_Return>
      <id/>
      <hours/>
      <minutes/>
      <projectid/>
      <projecttaskid/>
   </_Return>
</Read> 

            

Read Expense Reports Pending Reimbursement with equal to Method

The following example returns a list of up to a thousand approved expense reports pending reimbursement.

              <Read type="Envelope" method="equal to" filter="nonreimbursed-envelopes" limit="1000">
   <Envelope>
      <status>A</status>
   </Envelope>
</Read> 

            

Read with not equal to Method Matching a Custom Field

The following example returns a list of up to a thousand projects that do not match the specified values for both custom field my_custom_field and standard object property tax_locationid.

              <Read type="Project" enable_custom="1" method="not equal to" limit="1000">
     <Project>
          <my_custom_field__c>756</my_custom_field__c>
          <tax_locationid>5</tax_locationid>
     </Project>
</Read> 

            

Read the Foreign Exchange Rate for a Currency on a Specific Date

The following example returns the foreign exchange rate for the counter currency (EUR) against the base currency (USD) with a 10 decimal point precision.

Tip:

Read the Currencyrate object with equal to method to get a foreign exchange rate for a counter currency (or quote currency) against a base currency on a specific day.

              <Read type="Currencyrate" method="equal to" limit="1000" filter="date-equal-to" field="date" base_currency="USD" precision="10">
   <Currencyrate>
      <csymbol>EUR</csymbol>
      <type/>
   </Currencyrate>
   <Date>
      <year>2016</year>
      <month>09</month>
      <day>01</day>
   </Date>
</Read> 

            

Read Custom Field Values with custom equal to Method

The following example returns the values of custom fields netsuite_customer_id and export_customer_to_ns for the customer with internal Id 22 as CustomField objects.

              <Read type="Customer" method="custom equal to" field_names="netsuite_customer_id,export_customer_to_ns" limit="1000" >
   <Customer>
      <id>22</id>
   </Customer> 
</Read> 

            

Note:

If you omit the field_names attribute, the values of all custom fields for the object are returned as CustomField objects..

Read Objects Associated with a Specific User with user Method

The following example returns the values of custom fields netsuite_customer_id and export_customer_to_ns for the customer with internal Id 22 as CustomField objects.

              <Read type="Uprate" method="user" limit="1000" >
   <User>
      <id>22</id>
   </User> 
</Read> 

            

Read Not Exported Charges with all Method

The following example returns the list of up to a thousand Slip objects that were not exported to the application MyApp.

              <Read type ="Slip" filter="not-exported" method="all" limit="1000" >
   <ImportExport>
      <application>MyApp</application>
   </ImportExport> 
</Read>