# List prospects

Operation ID: `listProspects`

Group: CRM › Prospects

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

`GET /crm/prospects`

Read-only: Reads and returns; changes nothing.

Lists prospects, most recently created first. 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.

This endpoint does not follow the standard collection rules in Pagination and querying.

- Page with `pageSize` (default 50, maximum 200, minimum 1) and `cursor`, not `page[size]` and `page[cursor]`.
- The response has the records in `data.items` and the next page's cursor in `data.pagination.nextCursor`.
- Filter with the plain query parameters listed below, such as `customerType`, not `filter[field][op]`.
- There is no `sort` or `fields`.

This endpoint ignores any query parameter it does not declare, and returns no error. A request that follows the standard rules therefore gets the first page, unfiltered, every time.

## 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`. |
| `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. Example: `"partner"`. |
| `dataSource` | query | string | no | Limits results to prospects from this system, for example 'Salesforce' or 'HubSpot'. Use 'Everest' for prospects created in Lensing. A value that matches no system returns no prospects. Omit it to include every system. |
| `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. Example: `"a1c4d7e0-5b62-4c19-8e73-9f0d2a6b4c88"`. |
| `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 data.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. Example: `50`. |

## Response

`200` Success

Under `data` (listProspectsOutput):

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `items` | array<object> | yes | The prospects on this page, most recently created first. An empty array when nothing matches. Example: `[{"id":"3b7d5e9c-1a24-4f80-9c6d-2e8f70b13a45","prospectNumber":"PR-1042","prospectName":"Northwind Logistics","billingEmail":"ap@northwind.example","crmId":"0035g00000ABCDEF","customerType":"default","dataSource":"Salesforce","defaultCurrency":"USD","entityId":"a1c4d7e0-5b62-4c19-8e73-9f0d2a6b4c88","entityName":"Acme Inc.","sameAsBillToAddress":true,"billToAddress":{"id":"6f9a2b1c-33d4-4a55-9e21-0b7c8d4e1f02","line1":"410 Terry Avenue North","city":"Seattle","stateProvince":"WA","country":"US","zipCode":"98109","contact":{"id":"b8d6e5f2-7a01-4c49-8f36-5e1b4c0a9d72","displayName":"Dana Whitfield","firstName":"Dana","lastName":"Whitfield","emailAddress":"dana.whitfield@northwind.example","workPhone":"+1-206-555-0142"}},"soldToAddress":{"id":"6f9a2b1c-33d4-4a55-9e21-0b7c8d4e1f02","line1":"410 Terry Avenue North","city":"Seattle","stateProvince":"WA","country":"US","zipCode":"98109","contact":{"id":"b8d6e5f2-7a01-4c49-8f36-5e1b4c0a9d72","displayName":"Dana Whitfield","firstName":"Dana","lastName":"Whitfield","emailAddress":"dana.whitfield@northwind.example","workPhone":"+1-206-555-0142"}},"lastModifiedDate":"2026-08-14T09:12:44.000Z"}]`. |
| `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 came from, for example 'Salesforce' or 'HubSpot'. Prospects created in Lensing have the value 'Everest'. |
| `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` | 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. Example: `{"nextCursor":"MTA","hasMore":true}`. |
| `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. |

```json
{
  "data": {
    "items": [
      {
        "id": "3b7d5e9c-1a24-4f80-9c6d-2e8f70b13a45",
        "prospectNumber": "PR-1042",
        "prospectName": "Northwind Logistics",
        "billingEmail": "ap@northwind.example",
        "crmId": "0035g00000ABCDEF",
        "customerType": "default",
        "dataSource": "Salesforce",
        "defaultCurrency": "USD",
        "entityId": "a1c4d7e0-5b62-4c19-8e73-9f0d2a6b4c88",
        "entityName": "Acme Inc.",
        "sameAsBillToAddress": true,
        "billToAddress": {
          "id": "6f9a2b1c-33d4-4a55-9e21-0b7c8d4e1f02",
          "line1": "410 Terry Avenue North",
          "city": "Seattle",
          "stateProvince": "WA",
          "country": "US",
          "zipCode": "98109",
          "contact": {
            "id": "b8d6e5f2-7a01-4c49-8f36-5e1b4c0a9d72",
            "displayName": "Dana Whitfield",
            "firstName": "Dana",
            "lastName": "Whitfield",
            "emailAddress": "dana.whitfield@northwind.example",
            "workPhone": "+1-206-555-0142"
          }
        },
        "soldToAddress": {
          "id": "6f9a2b1c-33d4-4a55-9e21-0b7c8d4e1f02",
          "line1": "410 Terry Avenue North",
          "city": "Seattle",
          "stateProvince": "WA",
          "country": "US",
          "zipCode": "98109",
          "contact": {
            "id": "b8d6e5f2-7a01-4c49-8f36-5e1b4c0a9d72",
            "displayName": "Dana Whitfield",
            "firstName": "Dana",
            "lastName": "Whitfield",
            "emailAddress": "dana.whitfield@northwind.example",
            "workPhone": "+1-206-555-0142"
          }
        },
        "lastModifiedDate": "2026-08-14T09:12:44.000Z"
      }
    ],
    "pagination": {
      "nextCursor": "MTA",
      "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