Returns the vendors that match the given filters.

POST /accounting/vendors/search

Group: Accounting › Vendors · Operation ID: searchVendor

All filters are optional and are combined with AND. Omit every filter to match all vendors. Lookups by vendorName, vendorNumber, mainContactEmail and externalVendorId live here rather than on the collection.

Open in the interactive reference

Parameters

Name In Type Required Description
Api-Version header "v1" yes The API version this request targets, named by its public identifier. Required on every request; omitting it, or naming a version this company does not have, is answered with 400. This document describes version v1.

Request body

Required, application/json: searchVendorInput.

Field Type Required Description
filters object no The filters to apply. A vendor must match every filter you send. Omit to return all vendors.
filters.id string no Limits results to the vendor with this identifier.
filters.vendorName string no Limits results to vendors with this exact name. The match is case-sensitive.
filters.vendorNumber string no Limits results to vendors with this vendor number. It is not guaranteed unique, so this can return several vendors.
filters.vendorType string no Limits results to vendors of this kind. Accepted values: 'supplier', 'contractor', 'tax', 'benefits', 'payrollProvider', 'healthInsurance'. Any other value matches no vendor.
filters.vendorSubType string no Limits results to vendors of this sub-type. Accepted values: 'direct', 'indirect'. Any other value matches no vendor.
filters.status string no Limits results to vendors in this lifecycle status. Accepted values: 'active', 'inactive'. Any other value matches no vendor.
filters.entityId string no Limits results to vendors registered under this legal entity. An id that matches no entity returns no vendor. See id on GET base/entities.
filters.mainContactEmail string no Limits results to vendors whose main contact has this email address. Useful for finding a duplicate before creating another vendor.
filters.externalVendorId string no Limits results to vendors with this external identifier. It is not unique, so this can return several vendors.
page object no Pagination controls. Omit for the first page.
page.cursor string no The cursor from the previous response's pagination.nextCursor. Omit for the first page.
page.size number no The number of vendors per page. Defaults to 50. A value above 200 is treated as 200, not rejected.

Example:

{
  "filters": {
    "status": "active"
  },
  "page": {
    "size": 50
  }
}

Response

200 Success

Under data (searchVendorOutput):

Field Type Required Description
items array of object yes The vendors on this page, most recently created first. An empty array when nothing matches.
items[].id string yes The unique identifier for the vendor.
items[].vendorName string yes The legal or trading name of the vendor.
items[].vendorNumber string no The vendor number, for example 'V-2041'. Absent until one has been assigned.
items[].vendorType string yes The kind of vendor. Possible values: 'supplier', 'contractor', 'tax', 'benefits', 'payrollProvider', 'healthInsurance'.
items[].vendorSubType string no A finer classification within the vendor type. Possible values: 'direct', 'indirect'.
items[].status string yes The lifecycle status of the vendor. Possible values: 'active', 'inactive'. An inactive vendor stays readable so historical documents still resolve, and is not offered for new ones.
items[].paymentTerms string yes The default payment-terms key applied to this vendor's bills, for example 'net30' or 'dueOnReceipt'. Stored as supplied.
items[].preferredCurrency string no The currency the vendor prefers to be paid in. Format ISO 4217, for example 'USD'.
items[].preferredLanguage string no The language the vendor prefers for messages.
items[].independentContractor string no Whether the vendor is an independent contractor. Possible values: 'yes', 'no', 'unsure'.
items[].externalVendorId string no The identifier this vendor has in an external system. It is not unique.
items[].origin string no The source system that created the vendor, for example 'app'.
items[].mainContactName string no The name of the vendor's main contact.
items[].mainContactEmail string no The email address of the vendor's main contact.
items[].mainContactPhone string no The phone number of the vendor's main contact.
items[].billingEmail string no The email address invoices and remittance advice are sent to.
items[].entityId string no The legal entity the vendor is registered under. See id on GET base/entities.
items[].defaultAccountId string no The GL account this vendor's spend defaults to. See id on GET accounting/accounts/:id.
items[].lastModifiedDate string (date-time) yes The date and time the vendor last changed, in UTC. Format YYYY-MM-DDTHH:mm:ss.sssZ.
pagination object yes The pagination cursor for this page.
pagination.nextCursor string no The cursor for the next page. Pass it as page.cursor. Absent on the last page.
pagination.hasMore boolean yes True when more matches remain beyond this page.

Statuses