Skill: Query Customer

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.

API endpoint

POST /api/quickbooks/v1.0/query-customer

---

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