# List Prospects

`GET /crm/prospects`

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

Returns a list of prospects, most recently created first. To filter by prospectName, billingEmail, crmId or prospectNumber, use POST crm/prospects/search.

Only ids, dates, customerType, dataSource, defaultCurrency and booleans filter this endpoint. To filter by prospectName, billingEmail, crmId or prospectNumber, use POST crm/prospects/search. converted true returns the prospects already turned into customers, false those not yet converted. An unrecognized customerType or dataSource returns an empty page, not an error. GET crm/prospects omits contacts[], which GET crm/prospects/:id and POST crm/prospects/search return.

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

## 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`. |
| `prospectId` | query | string | no | Limits results to the prospect with this id. |
| `customerType` | query | string | no | Limits results to prospects of this commercial relationship. Possible values: 'default', 'partner', 'endCustomer'. Any other value matches no prospect. Omit for every type. |
| `dataSource` | query | string | no | Limits results to prospects that originated in this system, for example 'Everest', 'Salesforce' or 'HubSpot'. A value naming no source matches no prospect. Omit for every source. |
| `defaultCurrency` | query | string | no | Limits results to prospects whose default currency is this code. Format ISO 4217, for example 'USD'. Omit for every currency. |
| `entityId` | query | string | no | Limits results to prospects owned by this legal entity. Omit for every entity. |
| `customerId` | query | string | no | Limits results to prospects converted to this customer. Omit for every customer. |
| `converted` | query | 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` | query | 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. |
| `modifiedFrom` | query | string | no | Limits results to prospects changed at or after this time, in UTC. Format YYYY-MM-DDTHH:mm:ss.sssZ. Inclusive. |
| `modifiedTo` | query | string | no | Limits results to prospects changed at or before this time, in UTC. Format YYYY-MM-DDTHH:mm:ss.sssZ. Inclusive. |
| `cursor` | query | string | no | The cursor from the previous response's pagination.nextCursor. Omit on the first request. |
| `pageSize` | query | number | no | The number of prospects per page. Defaults to 50, and a value above 200 is treated as 200, not rejected. |

## Response

`200` Success

Under `data` (listProspectsOutput):

| 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. |
| `pagination` | object | yes | The pagination details for this page. |
| `pagination.nextCursor` | string | no | The cursor for the next page. Pass it back as 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