# Returns the prospects that match the given criteria.

`POST /crm/prospects/search`

Group: CRM › Prospects · Operation ID: `searchProspects`

Use this endpoint for criteria a query string cannot carry: text matches the prospect name and billingEmail an email, each of customerType, dataSource and defaultCurrency takes several values at once, and crmId and prospectNumber are kept out of the URL. Criteria combine with AND, and a list within one criterion is an OR. A match returns the prospect in full, including contacts[], which GET crm/prospects omits.

[Open in the interactive reference](https://docs.api.lensing.ai/?op=searchProspects)

## 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`: searchProspectsInput.

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `text` | string | no | Limits results to prospects whose name contains this text. The match is case-insensitive. |
| `billingEmail` | string | no | Limits results to the prospect with this billing email address. The match is exact. |
| `crmId` | string | no | Limits results to the prospect with this identifier in the external CRM system. The match is exact. |
| `prospectNumber` | string | no | Limits results to the prospect with this number, for example 'PR-1042'. The match is exact. |
| `customerType` | array of string, one of `"default"`, `"partner"`, `"endCustomer"` | no | Limits results to prospects of any of these commercial relationships. Possible values: 'default', 'partner', 'endCustomer'. Omit or pass an empty array for every type. |
| `dataSource` | array of string | no | Limits results to prospects that originated in any of these systems, for example 'Everest', 'Salesforce' or 'HubSpot'. Omit or pass an empty array for every source. |
| `defaultCurrency` | array of string | no | Limits results to prospects whose default currency is any of these codes. Each is an ISO 4217 code, for example 'USD'. Omit or pass an empty array for every currency. |
| `entityId` | string | no | Limits results to prospects owned by this legal entity. Omit for every entity. |
| `customerId` | string | no | Limits results to prospects converted to this customer. Omit for every customer. |
| `converted` | boolean | no | Limits results to prospects already converted to a customer when true, and to those not yet converted when false. Omit for both. |
| `sameAsBillToAddress` | boolean | no | Limits results to prospects whose sold-to address repeats their bill-to address when true, and to the rest when false. Omit for both. |
| `lastModifiedDate` | object | no | Limits results by when the prospect last changed, in UTC. Both bounds are inclusive, and omitting one leaves that side open. |
| `lastModifiedDate.start` | string | no | The earliest change time to include, inclusive. Format YYYY-MM-DDTHH:mm:ss.sssZ. |
| `lastModifiedDate.end` | string | no | The latest change time to include, inclusive. Format YYYY-MM-DDTHH:mm:ss.sssZ. |
| `page` | object | no | The page to return. Omit for the first page at the default size. |
| `page.cursor` | string | no | The cursor from the previous response's pagination.nextCursor. Omit on the first request. |
| `page.size` | number | no | The number of prospects per page. Defaults to 50, and a value above 200 is treated as 200, not rejected. |

Example:

```json
{
  "text": "northwind",
  "billingEmail": "<billingEmail>",
  "crmId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
  "prospectNumber": "<prospectNumber>",
  "customerType": [
    "partner",
    "endCustomer"
  ],
  "dataSource": [
    "<dataSource>"
  ],
  "defaultCurrency": [
    "USD"
  ],
  "entityId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
  "customerId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
  "converted": true,
  "sameAsBillToAddress": true,
  "lastModifiedDate": {
    "start": "<start>",
    "end": "<end>"
  },
  "page": {
    "size": 50
  }
}
```

## Response

`200` Success

Under `data` (searchProspectsOutput):

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `items` | array of object | yes | The prospects on this page, most recently created first. An empty array when nothing matches. |
| `items[].id` | string | yes | The unique identifier for the prospect. |
| `items[].prospectNumber` | string | no | The prospect number, for example 'PR-1042'. Absent while none has been assigned. |
| `items[].prospectName` | string | yes | The name of the prospect organization. |
| `items[].billingEmail` | string | no | The email address invoices for this prospect would be sent to. |
| `items[].crmId` | string | no | The identifier of this prospect in the external CRM system it was integrated from. |
| `items[].customerType` | string | no | The commercial relationship. Possible values: 'default', 'partner', 'endCustomer'. |
| `items[].dataSource` | string | no | The system the prospect originated in, for example 'Everest', 'Salesforce' or 'HubSpot'. |
| `items[].defaultCurrency` | string | no | The currency quotes for this prospect default to. Format ISO 4217, for example 'USD'. |
| `items[].entityId` | string | yes | The legal entity that owns the prospect. |
| `items[].entityName` | string | no | The name of the legal entity that owns the prospect. See entityName on GET base/entities. |
| `items[].customerId` | string | no | The identifier of the customer created from this prospect. Absent until the prospect has been converted, so its presence marks a converted prospect. See id on GET accounting/customers/:id. |
| `items[].sameAsBillToAddress` | boolean | no | Whether the sold-to address repeats the bill-to address. soldToAddress is populated either way, so you never have to resolve this flag to read an address. |
| `items[].billToAddress` | object | no | The prospect's bill-to address, with the default contact for that role. Absent when none is recorded. |
| `items[].billToAddress.id` | string | yes | The unique identifier for the address. |
| `items[].billToAddress.line1` | string | no | The first address line: street number and name, or PO box. |
| `items[].billToAddress.line2` | string | no | The second address line: apartment, suite, unit, building or floor. |
| `items[].billToAddress.city` | string | no | The city or locality. |
| `items[].billToAddress.stateProvince` | string | no | The state, province or region. Absent where the country has no such division. |
| `items[].billToAddress.country` | string | no | The country, as a name or ISO 3166-1 code. |
| `items[].billToAddress.zipCode` | string | no | The postal or ZIP code. |
| `items[].billToAddress.attention` | string | no | The person or department that mail to this address is for. |
| `items[].billToAddress.contact` | object | no | The default contact for this address role. Absent when the prospect has no default contact for it. |
| `items[].billToAddress.contact.id` | string | yes | The unique identifier for the contact. |
| `items[].billToAddress.contact.displayName` | string | no | The contact's display name, assembled from the name parts. |
| `items[].billToAddress.contact.salutation` | string | no | The contact's form of address, for example 'Ms' or 'Dr'. |
| `items[].billToAddress.contact.firstName` | string | no | The contact's given name. |
| `items[].billToAddress.contact.middleName` | string | no | The contact's middle name or initial. |
| `items[].billToAddress.contact.lastName` | string | no | The contact's family name. |
| `items[].billToAddress.contact.suffix` | string | no | The contact's name suffix, for example 'Jr' or 'PhD'. |
| `items[].billToAddress.contact.emailAddress` | string | no | The email address the contact is reached at. |
| `items[].billToAddress.contact.workPhone` | string | no | The contact's work telephone number. |
| `items[].soldToAddress` | object | no | The prospect's sold-to address, with the default contact for that role. Absent when none is recorded. |
| `items[].soldToAddress.id` | string | yes | The unique identifier for the address. |
| `items[].soldToAddress.line1` | string | no | The first address line: street number and name, or PO box. |
| `items[].soldToAddress.line2` | string | no | The second address line: apartment, suite, unit, building or floor. |
| `items[].soldToAddress.city` | string | no | The city or locality. |
| `items[].soldToAddress.stateProvince` | string | no | The state, province or region. Absent where the country has no such division. |
| `items[].soldToAddress.country` | string | no | The country, as a name or ISO 3166-1 code. |
| `items[].soldToAddress.zipCode` | string | no | The postal or ZIP code. |
| `items[].soldToAddress.attention` | string | no | The person or department that mail to this address is for. |
| `items[].soldToAddress.contact` | object | no | The default contact for this address role. Absent when the prospect has no default contact for it. |
| `items[].soldToAddress.contact.id` | string | yes | The unique identifier for the contact. |
| `items[].soldToAddress.contact.displayName` | string | no | The contact's display name, assembled from the name parts. |
| `items[].soldToAddress.contact.salutation` | string | no | The contact's form of address, for example 'Ms' or 'Dr'. |
| `items[].soldToAddress.contact.firstName` | string | no | The contact's given name. |
| `items[].soldToAddress.contact.middleName` | string | no | The contact's middle name or initial. |
| `items[].soldToAddress.contact.lastName` | string | no | The contact's family name. |
| `items[].soldToAddress.contact.suffix` | string | no | The contact's name suffix, for example 'Jr' or 'PhD'. |
| `items[].soldToAddress.contact.emailAddress` | string | no | The email address the contact is reached at. |
| `items[].soldToAddress.contact.workPhone` | string | no | The contact's work telephone number. |
| `items[].lastModifiedDate` | string (date-time) | yes | The date and time the prospect record last changed, in UTC. Format YYYY-MM-DDTHH:mm:ss.sssZ. |
| `items[].contacts` | array of object | yes | Every contact recorded against the prospect, with the two per-role defaults flagged. An empty array when the prospect has none. GET crm/prospects/:id and POST crm/prospects/search return this array. GET crm/prospects omits it. |
| `items[].contacts[].id` | string | yes | The unique identifier for the contact. |
| `items[].contacts[].displayName` | string | no | The contact's display name, assembled from the name parts. |
| `items[].contacts[].salutation` | string | no | The contact's form of address, for example 'Ms' or 'Dr'. |
| `items[].contacts[].firstName` | string | no | The contact's given name. |
| `items[].contacts[].middleName` | string | no | The contact's middle name or initial. |
| `items[].contacts[].lastName` | string | no | The contact's family name. |
| `items[].contacts[].suffix` | string | no | The contact's name suffix, for example 'Jr' or 'PhD'. |
| `items[].contacts[].emailAddress` | string | no | The email address the contact is reached at. |
| `items[].contacts[].workPhone` | string | no | The contact's work telephone number. |
| `items[].contacts[].isDefaultBillToContact` | boolean | yes | Whether this is the default contact for the prospect's bill-to address. At most one contact is. |
| `items[].contacts[].isDefaultSoldToContact` | boolean | yes | Whether this is the default contact for the prospect's sold-to address. At most one contact is. |
| `pagination` | object | yes | The pagination details for this page. |
| `pagination.nextCursor` | string | no | The cursor for the next page. Pass it back as page.cursor. Absent on the last page. |
| `pagination.hasMore` | boolean | yes | Whether another page follows. A full page may still be the last, so branch on this. |

## Statuses

- `400` — Invalid request or business failure
- `401` — Missing or invalid access token
- `403` — Not authorized
- `404` — Not found
- `429` — Too many requests
- `500` — Internal server error