# Retrieve a prospect

Operation ID: `getProspect`

Group: CRM › Prospects

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

`GET /crm/prospects/{id}`

Read-only: Reads and returns; changes nothing.

Retrieves a prospect. To look a prospect up by its number, use POST crm/prospects/search with prospectNumber. This endpoint and POST crm/prospects/search return contacts[], every contact recorded against the prospect. GET crm/prospects omits it.

## 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`. |
| `id` | path | string | yes | The unique identifier of the prospect you want to retrieve. Example: `"3b7d5e9c-1a24-4f80-9c6d-2e8f70b13a45"`. |

## Response

`200` Success

Under `data` (getProspectOutput):

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `id` | string | yes | The unique identifier for the prospect. Example: `"3b7d5e9c-1a24-4f80-9c6d-2e8f70b13a45"`. |
| `prospectNumber` | string | no | The prospect number, for example 'PR-1042'. Absent while none has been assigned. Example: `"PR-1042"`. |
| `prospectName` | string | yes | The name of the prospect organization. Example: `"Northwind Logistics"`. |
| `billingEmail` | string | no | The email address invoices for this prospect would be sent to. Example: `"ap@northwind.example"`. |
| `crmId` | string | no | The identifier of this prospect in the external CRM system it was integrated from. Example: `"0035g00000ABCDEF"`. |
| `customerType` | string | no | The commercial relationship. Possible values: 'default', 'partner', 'endCustomer'. Example: `"default"`. |
| `dataSource` | string | no | The system the prospect came from, for example 'Salesforce' or 'HubSpot'. Prospects created in Lensing have the value 'Everest'. Example: `"Salesforce"`. |
| `defaultCurrency` | string | no | The currency quotes for this prospect default to. Format ISO 4217, for example 'USD'. Example: `"USD"`. |
| `entityId` | string | yes | The legal entity that owns the prospect. Example: `"a1c4d7e0-5b62-4c19-8e73-9f0d2a6b4c88"`. |
| `entityName` | string | no | The name of the legal entity that owns the prospect. See entityName on GET base/entities. Example: `"Acme Inc."`. |
| `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. |
| `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. Example: `true`. |
| `billToAddress` | object | no | The prospect's bill-to address, with the default contact for that role. Absent when none is recorded. Example: `{"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"}}`. |
| `billToAddress.id` | string | yes | The unique identifier for the address. |
| `billToAddress.line1` | string | no | The first address line: street number and name, or PO box. |
| `billToAddress.line2` | string | no | The second address line: apartment, suite, unit, building or floor. |
| `billToAddress.city` | string | no | The city or locality. |
| `billToAddress.stateProvince` | string | no | The state, province or region. Absent where the country has no such division. |
| `billToAddress.country` | string | no | The country, as a name or ISO 3166-1 code. |
| `billToAddress.zipCode` | string | no | The postal or ZIP code. |
| `billToAddress.attention` | string | no | The person or department that mail to this address is for. |
| `billToAddress.contact` | object | no | The default contact for this address role. Absent when the prospect has no default contact for it. |
| `billToAddress.contact.id` | string | yes | The unique identifier for the contact. |
| `billToAddress.contact.displayName` | string | no | The contact's display name, assembled from the name parts. |
| `billToAddress.contact.salutation` | string | no | The contact's form of address, for example 'Ms' or 'Dr'. |
| `billToAddress.contact.firstName` | string | no | The contact's given name. |
| `billToAddress.contact.middleName` | string | no | The contact's middle name or initial. |
| `billToAddress.contact.lastName` | string | no | The contact's family name. |
| `billToAddress.contact.suffix` | string | no | The contact's name suffix, for example 'Jr' or 'PhD'. |
| `billToAddress.contact.emailAddress` | string | no | The email address the contact is reached at. |
| `billToAddress.contact.workPhone` | string | no | The contact's work telephone number. |
| `soldToAddress` | object | no | The prospect's sold-to address, with the default contact for that role. Absent when none is recorded. Example: `{"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` | string | yes | The unique identifier for the address. |
| `soldToAddress.line1` | string | no | The first address line: street number and name, or PO box. |
| `soldToAddress.line2` | string | no | The second address line: apartment, suite, unit, building or floor. |
| `soldToAddress.city` | string | no | The city or locality. |
| `soldToAddress.stateProvince` | string | no | The state, province or region. Absent where the country has no such division. |
| `soldToAddress.country` | string | no | The country, as a name or ISO 3166-1 code. |
| `soldToAddress.zipCode` | string | no | The postal or ZIP code. |
| `soldToAddress.attention` | string | no | The person or department that mail to this address is for. |
| `soldToAddress.contact` | object | no | The default contact for this address role. Absent when the prospect has no default contact for it. |
| `soldToAddress.contact.id` | string | yes | The unique identifier for the contact. |
| `soldToAddress.contact.displayName` | string | no | The contact's display name, assembled from the name parts. |
| `soldToAddress.contact.salutation` | string | no | The contact's form of address, for example 'Ms' or 'Dr'. |
| `soldToAddress.contact.firstName` | string | no | The contact's given name. |
| `soldToAddress.contact.middleName` | string | no | The contact's middle name or initial. |
| `soldToAddress.contact.lastName` | string | no | The contact's family name. |
| `soldToAddress.contact.suffix` | string | no | The contact's name suffix, for example 'Jr' or 'PhD'. |
| `soldToAddress.contact.emailAddress` | string | no | The email address the contact is reached at. |
| `soldToAddress.contact.workPhone` | string | no | The contact's work telephone number. |
| `lastModifiedDate` | date-time | yes | The date and time the prospect record last changed, in UTC. Format YYYY-MM-DDTHH:mm:ss.sssZ. Example: `"2026-08-14T09:12:44.000Z"`. |
| `contacts` | array<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. Example: `[{"id":"b8d6e5f2-7a01-4c49-8f36-5e1b4c0a9d72","displayName":"Dana Whitfield","firstName":"Dana","lastName":"Whitfield","emailAddress":"dana.whitfield@northwind.example","workPhone":"+1-206-555-0142","isDefaultBillToContact":true,"isDefaultSoldToContact":true},{"id":"c9e7f6a3-8b12-4d50-9a47-6f2c5d1b0e83","displayName":"Ravi Menon","salutation":"Mr","firstName":"Ravi","lastName":"Menon","emailAddress":"ravi.menon@northwind.example","isDefaultBillToContact":false,"isDefaultSoldToContact":false}]`. |
| `contacts[].id` | string | yes | The unique identifier for the contact. |
| `contacts[].displayName` | string | no | The contact's display name, assembled from the name parts. |
| `contacts[].salutation` | string | no | The contact's form of address, for example 'Ms' or 'Dr'. |
| `contacts[].firstName` | string | no | The contact's given name. |
| `contacts[].middleName` | string | no | The contact's middle name or initial. |
| `contacts[].lastName` | string | no | The contact's family name. |
| `contacts[].suffix` | string | no | The contact's name suffix, for example 'Jr' or 'PhD'. |
| `contacts[].emailAddress` | string | no | The email address the contact is reached at. |
| `contacts[].workPhone` | string | no | The contact's work telephone number. |
| `contacts[].isDefaultBillToContact` | boolean | yes | Whether this is the default contact for the prospect's bill-to address. At most one contact is. |
| `contacts[].isDefaultSoldToContact` | boolean | yes | Whether this is the default contact for the prospect's sold-to address. At most one contact is. |

```json
{
  "data": {
    "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.",
    "customerId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
    "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",
    "contacts": [
      {
        "id": "b8d6e5f2-7a01-4c49-8f36-5e1b4c0a9d72",
        "displayName": "Dana Whitfield",
        "firstName": "Dana",
        "lastName": "Whitfield",
        "emailAddress": "dana.whitfield@northwind.example",
        "workPhone": "+1-206-555-0142",
        "isDefaultBillToContact": true,
        "isDefaultSoldToContact": true
      },
      {
        "id": "c9e7f6a3-8b12-4d50-9a47-6f2c5d1b0e83",
        "displayName": "Ravi Menon",
        "salutation": "Mr",
        "firstName": "Ravi",
        "lastName": "Menon",
        "emailAddress": "ravi.menon@northwind.example",
        "isDefaultBillToContact": false,
        "isDefaultSoldToContact": false
      }
    ]
  },
  "diagnostics": [
    {
      "code": "<code>",
      "message": "<message>",
      "severity": "error",
      "path": [
        "<path>"
      ],
      "details": "<details>"
    }
  ]
}
```

## Errors

| Code | Status |
| --- | --- |
| `NOT_FOUND` | 400 |

## Statuses

- `400` — Invalid request or business failure. Codes: NOT_FOUND
- `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