Search companies

distru-search-companiesRead

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).

Inputs

Every tool also takes the common inputs.

FieldTypeRequiredDescription
limitintegerNoDefault: 10
cursorstringNonextCursor of the previous call; keep the other arguments unchanged.
categoriesstring[]NoResolve via distru-search-lookups (type COMPANY_CATEGORY).
citystringNoCase-insensitive substring of the city of one of the company's addresses.
hasBrokenQbCustomerbooleanNotrue: qbCustomerId is set but qbCustomer is null, inactive or deleted. false: unmapped, or mapped to an active qbCustomer that is not deleted.
hasBrokenQbVendorbooleanNotrue: qbVendorId is set but qbVendor is null, inactive or deleted. false: unmapped, or mapped to an active qbVendor that is not deleted.
hasOutstandingBalancebooleanNotrue: owes more than $0; false: $0 or less (a credit).
groupIdsstring[]NoResolve via distru-search-lookups (type COMPANY_GROUP).
idsstring[]No
isMyCompanybooleanNotrue: only the caller's own company record (exactly one); false: only counterparties.
lastOrderDateAfterstringNolastOrderDate 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.
lastOrderDateBeforestringNolastOrderDate 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.
licenseNumberstringNoCase-insensitive substring of a license number the company holds.
relationshipTypeIdsstring[]NoResolve via distru-search-lookups (type RELATIONSHIP_TYPE).
searchstringNoCase-insensitive substring of name or legal business name. Ranked by name similarity; sortBy ignored.
customFieldsobject[]NoSet one of contains, anyOf or onOrAfter/onOrBefore per entry. Records with no value for the field never match.
customFields[].customFieldIdstringYesResolve via distru-search-custom-fields.
customFields[].containsstringNoTEXT: case-insensitive substring.
customFields[].anyOfstring[]NoDROPDOWN, CHECKBOX: any of these options, case-sensitive.
customFields[].onOrAfterstringNoDATE: YYYY-MM-DD, company timezone.
customFields[].onOrBeforestringNoDATE: YYYY-MM-DD, company timezone.
sortByobjectNoDefault UPDATED_AT DESC. Ignored when search is set.
sortBy.directionenum
ASCDESC
Yes
sortBy.fieldenum
INSERTED_ATLAST_ORDER_DATENAMEOUTSTANDING_BALANCEPAST_DUE_BALANCEUPDATED_AT
YesOUTSTANDING_BALANCE: amount the company owes. LAST_ORDER_DATE: companies with no sales orders come last in both directions.
zipstringNoExact zip of one of the company's addresses, ignoring case; partial zips match nothing.

Output

Presence on a nested field assumes its parent exists.

FieldTypePresenceDescription
hasMorebooleanAlways
nextCursorstringCan be absent
totalCountintegerCan be absent
itemsobject[]Always
items[].idstringAlways
items[].namestringNull or absent
items[].isMyCompanybooleanAlways
items[].customFieldsobject[]Always
items[].customFields[].customFieldobjectAlways
items[].customFields[].customField.idstringAlways
items[].customFields[].customField.namestringAlways
items[].customFields[].customField.fieldTypeenum
CHECKBOXDATEDROPDOWNTEXT
Always
items[].customFields[].valuestringCan be nullNull when unset. DATE values are days (YYYY-MM-DD) in the company timezone; CHECKBOX values are the selected option names, separated by commas.
items[].legalBusinessNamestringNull or absent
items[].categorystringNull or absent
items[].creditBalancestringNull or absent
items[].outstandingBalancestringNull or absent
items[].pastDueBalancestringNull or absent
items[].outstandingBalanceThresholdintegerNull or absent
items[].invoiceEmailstringNull or absent
items[].defaultPaymentTermobjectNull or absent
items[].defaultPaymentTerm.idstringAlways
items[].defaultPaymentTerm.namestringNull or absent
items[].ownerobjectNull or absent
items[].owner.idstringAlways
items[].owner.fullNamestringNull or absent
items[].defaultInventoryLocationobjectNull or absent
items[].defaultInventoryLocation.idstringAlways
items[].defaultInventoryLocation.namestringNull or absent
items[].lastOrderDatestringNull or absent
items[].relationshipTypeobjectNull or absent
items[].relationshipType.idstringAlways
items[].relationshipType.namestringAlways
items[].groupobjectNull or absent
items[].group.idstringAlways
items[].group.namestringAlways
items[].emailstringNull or absent
items[].phonestringNull or absent
items[].websitestringNull or absent
items[].qbCustomerIdstringNull or absent
items[].qbCustomerobjectNull or absent
items[].qbCustomer.displayNamestringAlways
items[].qbCustomer.activebooleanAlways
items[].qbCustomer.isDeletedbooleanAlways
items[].qbVendorIdstringNull or absent
items[].qbVendorobjectNull or absent
items[].qbVendor.displayNamestringAlways
items[].qbVendor.activebooleanAlways
items[].qbVendor.isDeletedbooleanAlways
items[].leaflinkBrandIdstringNull or absent
items[].leaflinkCustomerIdstringNull 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.