API: Query for One Object

The API: Query for One Object action searches Autotask and returns a single matching entity. This is a low-level API action that makes a single API call, returning the first result that matches your query conditions.

Single API Call Action

This is a single API call action. You define the query conditions and the action makes one API call to retrieve the result. Learn more about the difference between workflow actions and single API call actions.

When to Use This Action

Use this action when:

• You need to find a specific entity (ticket, contact, account, etc.)
• You expect exactly one result or want only the first match
• You need entity data for use in later actions

For multiple results, use API: Query for Object(s) instead.

Configuration

Connection

Field	Description
Autotask Connection	Select the Autotask connection to use. If you have multiple connections, you can override the default.

Query

Field	Description
Autotask Entity Type to Query	The type of entity to search for (e.g., Ticket, Contact, Account).
Query Parameters	Filter conditions to find the entity. Use AND/OR groups to build complex queries.
Sort Results	If multiple entities match, sorting determines which one is returned. The first result after sorting is used.

Options

Field	Description
Generate an exception if no results	Stop the workflow if no matching entity is found.
Generate an exception if more than one result	Stop the workflow if multiple entities match. Useful when you expect exactly one result.

Advanced

Field	Description
Suppress Autotask API exceptions	If enabled, the workflow continues even if the Autotask API returns an error.

How to Query for an Entity

1. Select Autotask Direct API: API: Query for one object from the action dropdown
2. Choose the Autotask Entity Type to Query
3. Add query conditions to filter results
4. Optionally configure sorting
5. Store the result in a variable for use in later actions

Query Builder

Build filter conditions using:

• All of these (AND): All conditions must match
• Any of these (OR): At least one condition must match

For each condition:

1. Select a field (e.g., TicketNumber, Email, AccountName)
2. Choose an operator (equals, contains, greater than, etc.)
3. Enter the value to match (supports template variables)

Nest groups to create complex logic combining AND and OR conditions.

Returned Variables

When you configure Store the results in Variable, the matching entity becomes available:

Variable	Type	Description
(root)	object	The matching entity with all properties and linked entities

Linked Entities

The returned object includes related entities automatically. For example, querying a Ticket returns:

• The Ticket with all its properties
• Linked Contact with their properties
• Linked Account with their properties
• Linked Resource (assignee) with their properties

Example usage:

• {{custom.ticket.TicketNumber}}: The ticket number
• {{custom.ticket.Contact.Email}}: The contact's email
• {{custom.ticket.Account.AccountName}}: The account name

Example Use Cases

Find Ticket by Number

Look up a specific ticket:

Setting	Value
Entity Type	Ticket
Condition	TicketNumber equals {{custom.parsedTicketNumber}}

Find Contact by Email

Look up a contact for the email sender:

Setting	Value
Entity Type	Contact
Condition	EMailAddress equals {{email.from.address}}

Find Most Recent Ticket for Account

Get the newest open ticket:

Setting	Value
Entity Type	Ticket
Conditions	AccountID equals {{custom.account.id}} AND Status not equal to 5
Sort	CreateDate (Descending)

Find Account by Domain

Look up an account by website:

Setting	Value
Entity Type	Account
Condition	WebAddress contains {{email.from.domain}}

Difference from Query for Multiple Objects

Feature	Query One	Query Multiple
Returns	Single object	Array of objects
Best for	Known single result	Search/list results
Access syntax	{{custom.result.Property}}	{{custom.results[0].Property}}
Use with	Direct property access	Iterate action for looping

FAQs

What happens if no results match?

The variable is empty/null. Enable "Generate an exception if no results" to stop the workflow when this happens.

What if multiple results match?

Only the first result (after sorting) is returned. Enable "Generate an exception if more than one result" if you need to ensure uniqueness.

How do I check if a result was found?

Use a condition in the next action: {{custom.result.id}} exists or is not empty.

Can I query User-Defined Fields?

Yes. UDFs appear in the field selector with the prefix UDF:.

Related Actions

• API: Query for Object(s): Return multiple results
• API: Create an Object: Create entities
• API: Update an Object: Modify entities