Skill: Query Customer

Search for customers in QuickBooks Online by name, email, phone, company, balance, or status with flexible pattern matching.

The Query Customer skill searches for customer records in QuickBooks Online. It supports a wide range of filter criteria and LIKE pattern matching, making it useful for both precise lookups and fuzzy searches.

Parameters

Parameter	Type	Required	Description
`display_name`	`string`	No	The customer’s display name. Supports LIKE patterns (e.g., `%Acme%`).
`given_name`	`string`	No	The customer’s first name. Supports LIKE patterns.
`family_name`	`string`	No	The customer’s last name. Supports LIKE patterns.
`company_name`	`string`	No	The customer’s associated company name. Supports LIKE patterns.
`primary_email_addr`	`string`	No	The customer’s primary email address. Supports LIKE patterns.
`primary_phone`	`string`	No	The customer’s primary phone number.
`active`	`boolean`	No	Filter by active status. `true` for active customers, `false` for inactive. Defaults to returning both.
`balance`	`string`	No	Filter by balance. Supports comparison operators (e.g., `> 0`, `= 0`, `< 1000`).
`create_time_start`	`string`	No	Filter customers created on or after this date (`YYYY-MM-DD`).
`create_time_end`	`string`	No	Filter customers created on or before this date (`YYYY-MM-DD`).
`last_updated_start`	`string`	No	Filter customers updated on or after this date (`YYYY-MM-DD`).
`last_updated_end`	`string`	No	Filter customers updated on or before this date (`YYYY-MM-DD`).
`max_results`	`integer`	No	Maximum number of results to return. Defaults to 100.

LIKE pattern matching

Several text parameters support SQL-style LIKE patterns:

Pattern	Matches
`Acme`	Exact match: “Acme”
`%Acme%`	Contains: “Acme Corp”, “The Acme Company”
`Acme%`	Starts with: “Acme Corp”, “Acme LLC”
`%Inc`	Ends with: “Acme Inc”, “Widget Inc”

Tip

When a user says “Find customers named Smith,” the agent typically searches with family_name set to %Smith% to catch partial matches. If the search returns too many results, the agent may refine with additional filters.

Example usage

A user might trigger this skill by saying:

“Look up the customer record for Acme Corporation.”

The agent would invoke this skill with:

display_name: %Acme%

Or for a more targeted search:

“Show me all active customers with an outstanding balance over $5,000.”

The agent would invoke:

active: true
balance: > 5000

Response structure

The skill returns an array of customer records, each containing:

Id — the QuickBooks customer ID (used by other skills).
DisplayName — the customer’s display name.
GivenName / FamilyName — first and last name.
CompanyName — associated company.
PrimaryEmailAddr — email address.
PrimaryPhone — phone number.
Balance — current outstanding balance.
Active — whether the customer is active.
BillAddr / ShipAddr — billing and shipping addresses.
MetaData — creation and last-updated timestamps.

Related skills: Customer Upsert | Search Invoices | Sales by Customer Report