Search companies
distru-search-companiesReadSearches the companies the caller's company does business with — its customers and vendors — plus the one record for its own company, flagged isMyCompany; set isMyCompany when a question hinges on which company is the user's own (e.g. products they vend or sell themselves).
Inputs
Every tool also takes the common inputs.
| Field | Type | Required | Description |
|---|---|---|---|
| limit | integer | No | Default: 10 |
| cursor | string | No | nextCursor of the previous call; keep the other arguments unchanged. |
| categories | string[] | No | Resolve via distru-search-lookups (type COMPANY_CATEGORY). |
| city | string | No | Case-insensitive substring of the city of one of the company's addresses. |
| hasBrokenQbCustomer | boolean | No | true: qbCustomerId is set but qbCustomer is null, inactive or deleted. false: unmapped, or mapped to an active qbCustomer that is not deleted. |
| hasBrokenQbVendor | boolean | No | true: qbVendorId is set but qbVendor is null, inactive or deleted. false: unmapped, or mapped to an active qbVendor that is not deleted. |
| hasOutstandingBalance | boolean | No | true: owes more than $0; false: $0 or less (a credit). |
| groupIds | string[] | No | Resolve via distru-search-lookups (type COMPANY_GROUP). |
| ids | string[] | No | |
| isMyCompany | boolean | No | true: only the caller's own company record (exactly one); false: only counterparties. |
| lastOrderDateAfter | string | No | lastOrderDate on or after. Leaves out companies with no sales orders other than canceled or merged ones. YYYY-MM-DD (start of day, company timezone) or ISO 8601 with a UTC offset. |
| lastOrderDateBefore | string | No | lastOrderDate on or before. Leaves out companies with no sales orders other than canceled or merged ones. YYYY-MM-DD (end of day, company timezone) or ISO 8601 with a UTC offset. |
| licenseNumber | string | No | Case-insensitive substring of a license number the company holds. |
| relationshipTypeIds | string[] | No | Resolve via distru-search-lookups (type RELATIONSHIP_TYPE). |
| search | string | No | Case-insensitive substring of name or legal business name. Ranked by name similarity; sortBy ignored. |
| customFields | object[] | No | Set one of contains, anyOf or onOrAfter/onOrBefore per entry. Records with no value for the field never match. |
| customFields[]. | string | Yes | Resolve via distru-search-custom-fields. |
| customFields[]. | string | No | TEXT: case-insensitive substring. |
| customFields[]. | string[] | No | DROPDOWN, CHECKBOX: any of these options, case-sensitive. |
| customFields[]. | string | No | DATE: YYYY-MM-DD, company timezone. |
| customFields[]. | string | No | DATE: YYYY-MM-DD, company timezone. |
| sortBy | object | No | Default UPDATED_AT DESC. Ignored when search is set. |
| sortBy. | enumASCDESC | Yes | |
| sortBy. | enumINSERTED_ATLAST_ORDER_DATENAMEOUTSTANDING_BALANCEPAST_DUE_BALANCEUPDATED_AT | Yes | OUTSTANDING_BALANCE: amount the company owes. LAST_ORDER_DATE: companies with no sales orders come last in both directions. |
| zip | string | No | Exact zip of one of the company's addresses, ignoring case; partial zips match nothing. |
Output
Presence on a nested field assumes its parent exists.
| Field | Type | Presence | Description |
|---|---|---|---|
| hasMore | boolean | Always | |
| nextCursor | string | Can be absent | |
| totalCount | integer | Can be absent | |
| items | object[] | Always | |
| items[]. | string | Always | |
| items[]. | string | Null or absent | |
| items[]. | boolean | Always | |
| items[]. | object[] | Always | |
| items[]. | object | Always | |
| items[]. | string | Always | |
| items[]. | string | Always | |
| items[]. | enumCHECKBOXDATEDROPDOWNTEXT | Always | |
| items[]. | string | Can be null | Null when unset. DATE values are days (YYYY-MM-DD) in the company timezone; CHECKBOX values are the selected option names, separated by commas. |
| items[]. | string | Null or absent | |
| items[]. | string | Null or absent | |
| items[]. | string | Null or absent | |
| items[]. | string | Null or absent | |
| items[]. | string | Null or absent | |
| items[]. | integer | Null or absent | |
| items[]. | string | Null or absent | |
| items[]. | object | Null or absent | |
| items[]. | string | Always | |
| items[]. | string | Null or absent | |
| items[]. | object | Null or absent | |
| items[]. | string | Always | |
| items[]. | string | Null or absent | |
| items[]. | object | Null or absent | |
| items[]. | string | Always | |
| items[]. | string | Null or absent | |
| items[]. | string | Null or absent | |
| items[]. | object | Null or absent | |
| items[]. | string | Always | |
| items[]. | string | Always | |
| items[]. | object | Null or absent | |
| items[]. | string | Always | |
| items[]. | string | Always | |
| items[]. | string | Null or absent | |
| items[]. | string | Null or absent | |
| items[]. | string | Null or absent | |
| items[]. | string | Null or absent | |
| items[]. | object | Null or absent | |
| items[]. | string | Always | |
| items[]. | boolean | Always | |
| items[]. | boolean | Always | |
| items[]. | string | Null or absent | |
| items[]. | object | Null or absent | |
| items[]. | string | Always | |
| items[]. | boolean | Always | |
| items[]. | boolean | Always | |
| items[]. | string | Null or absent | |
| items[]. | string | Null or absent |
What the AI reads
Searches the companies the caller's company does business with — its customers and vendors — plus the one record for its own company, flagged isMyCompany; set isMyCompany when a question hinges on which company is the user's own (e.g. products they vend or sell themselves). For a company's contacts, locations and licenses, use distru-get-company. outstandingBalance is what the company owes. pastDueBalance is the unpaid amount on invoices of delivered or completed sales orders due before today, less unapplied credit; never below 0 or above outstandingBalance. outstandingBalanceThreshold is the company's balance threshold, in dollars, compared with its outstanding balance or, if your company settings choose it, its past due balance: above it Distru shows warnings and sends alerts, and unless your company settings allow orders over it, this company's sales orders can't move past Pending; null uses your company's default threshold. creditBalance is its unapplied credit. qbCustomerId and qbVendorId are its QuickBooks customer and vendor IDs, null when not mapped. qbCustomer and qbVendor are null when mapped but Distru has no current copy of the QuickBooks record. isDeleted means QuickBooks no longer has the record, and active indicates whether the record is active in QuickBooks. An invoice sync re-maps a deleted or missing customer by name, or creates one, but fails on an inactive one. lastOrderDate is the order date of its most recent sales order that wasn't canceled or merged. For who owes money, set hasOutstandingBalance to true and sort by OUTSTANDING_BALANCE descending; for who is late paying, sort by PAST_DUE_BALANCE descending. For customers who haven't ordered since a date, set lastOrderDateBefore to that date. To find companies whose QuickBooks customer or vendor mapping no longer works (one cause of the sync errors in distru-search-quickbooks-activities), set hasBrokenQbCustomer or hasBrokenQbVendor.