query()

IMPORTANT  The SOAP API entered a limited enhancement phase in Q4 2020. Access to version 1.6 will eventually be deactivated. At this time, there is no end-of-lifecycle date.

This API call executes a query against Autotask and returns an array of matching entities. The queries are built using the QueryXML format and will return a maximum of 500 records at once, sorted by their id value.

To query for additional records over the 500 maximum for a given set of search criteria, repeat the query and filter by id value > the previous maximum id value retrieved.

Currently, all entities and most fields are supported by the query() call. If an entity has any fields that cannot be queried, those fields are listed in the entity's description topic. For additional information on the QueryXML format, refer to .

Notes:

  • All API queries will be in Coordinated Universal Time (UTC).
  • Valid query() XML must comply with the following or an error message is generated:
    • Any field tag must contain an expression tag
    • An expression tag must contain an op attribute
  • Querying on protected UDFs is case sensitive.

  • VB entities allow 1 UDF per query.

  • For C# implemented entities, the number of unique UDFs in a query filter is limited to 5 UDFs. However, the same UDF can be used in the query many times with multiple conditionals and OR statements and not count against the limit of 5 UDFs.
  • When querying, if all UDF values for an entity are NULL, then no UDFs are returned; if any UDF has a value, then all UDFs are returned.
SOAP REST
Account Companies
AccountLocation CompanySiteConfigurations
Contact Contacts
Contract Contracts
InstalledProduct ConfigurationItems
Opportunity Opportunities
Product Products
Project Projects
SalesOrder SalesOrders
 

ServiceBundles

 

Services

Subscription Subscriptions
Task Tasks
Ticket Tickets

Each entity has a maximum number of active user-defined fields that you can define. For more information, refer to Managing user-defined fields.

IMPORTANT  You can only query by one user-defined field at a time.

To learn how to make PUT, PATCH, and POST requests to entities that support UDFs, refer to Creating resources via POST request in the REST API, Updating data via PUT request with the REST API and Updating data via PATCH request with the REST API.

Considerations

The following list outlines some general considerations for using the Web Services query() API call.

Permissions By default, the API User (system) (API-only) security level grants Full access permissions, but copies of this security level may have been modified. The API user must have access to the appropriate Autotask module for the entity type and sufficient rights to perform the specified API call.
Query Maximum Entities The Web Service API query() call will return a maximum of 500 objects per call, sorted by the id field. If you would like to retrieve more than 500 items, you should resubmit your query with a condition on the id field.
White Spacing API functions will trim all white spaces in the beginning and end of each string type entry.

Sample query() SOAP XML 1

Query Account example where the ID is greater than 0

            <?xml version="1.0" encoding="utf-8"?>
<soap:Envelope xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:xsd="http://www.w3.org/2001/XMLSchema">
  <soap:Header>
    <AutotaskIntegrations xmlns="http://autotask.net/ATWS/v1_6/">
          <IntegrationCode>[insert your own tracking identifier]</IntegrationCode>
    </AutotaskIntegrations>
  </soap:Header>
  <soap:Body>
    <query xmlns="http://autotask.net/ATWS/v1_6/">
      <sXML><![CDATA[<queryxml><entity>Account</entity><query><condition><field>id<expression op="greaterthan">0</expression></field></condition></query></queryxml>]]></sXML>
    </query>
  </soap:Body>
</soap:Envelope>

Sample query() SOAP XML 2

Query account where Account name begins with "ACME" and account type is a customer.

            <?xml version="1.0" encoding="utf-8"?>
<soap:Envelope xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:xsd="http://www.w3.org/2001/XMLSchema">
  <soap:Header>
    <AutotaskIntegrations xmlns="http://autotask.net/ATWS/v1_6/">
      <IntegrationCode>[insert your own tracking identifier]</IntegrationCode>
    </AutotaskIntegrations>
  </soap:Header>
  <soap:Body>
    <query xmlns="http://autotask.net/ATWS/v1_6/">
      <sXML><![CDATA[<queryxml><entity>Account</entity><query><condition><field>AccountName<expression op="beginswith">Acme</expression></field></condition></query></queryxml>]]></sXML>
    </query>
  </soap:Body>
</soap:Envelope>