# Search vendors

Operation ID: `searchVendor`

Group: Accounting › Vendors

[Open in the interactive reference](https://docs.api.lensing.ai/lensing/v1/endpoints/searchVendor)

`POST /accounting/vendors/search`

Read-only: A read that takes its filters in the body. Changes nothing, and ignores Idempotency-Key.

Searches vendors. You can filter by name, number, type, status, legal entity, contact email, or external identifier. The vendorName, mainContactEmail, and entityId filters are available here and not on GET accounting/vendors.

## Parameters

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `Api-Version` | header | string · 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. Example: `{"status":"active"}`. |
| `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. Example: `{"size":50}`. |
| `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. |

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

## Response

`200` Success

Under `data` (searchVendorOutput):

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `items` | array<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 general ledger account this vendor's spend defaults to. See id on GET accounting/accounts/:id. |
| `items[].lastModifiedDate` | 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. |

```json
{
  "data": {
    "items": [
      {
        "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
        "vendorName": "<vendorName>",
        "vendorNumber": "<vendorNumber>",
        "vendorType": "<vendorType>",
        "vendorSubType": "<vendorSubType>",
        "status": "<status>",
        "paymentTerms": "<paymentTerms>",
        "preferredCurrency": "<preferredCurrency>",
        "preferredLanguage": "<preferredLanguage>",
        "independentContractor": "<independentContractor>",
        "externalVendorId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
        "origin": "<origin>",
        "mainContactName": "<mainContactName>",
        "mainContactEmail": "<mainContactEmail>",
        "mainContactPhone": "<mainContactPhone>",
        "billingEmail": "<billingEmail>",
        "entityId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
        "defaultAccountId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
        "lastModifiedDate": "2026-01-15T09:30:00.000Z"
      }
    ],
    "pagination": {
      "nextCursor": "<nextCursor>",
      "hasMore": true
    }
  },
  "diagnostics": [
    {
      "code": "<code>",
      "message": "<message>",
      "severity": "error",
      "path": [
        "<path>"
      ],
      "details": "<details>"
    }
  ]
}
```

## Statuses

- `400` — Invalid request or business failure
- `401` — The request carries no valid access token.
- `403` — Not authorized
- `404` — Not found
- `429` — Too many requests from this client address. The response has no body and no `Retry-After` header.
- `500` — Internal server error