> For the complete documentation index, see [llms.txt](https://docs.shortcutco.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.shortcutco.com/developers/api-reference/reference/objects/lead.md).

# The lead object

The lead object in the Shortcut API - every field, an example, and the endpoints that return it.

A lead: someone who asked for service.

## Fields

| Field                             | Type                                  | Description                                                                                                                                                                                                                                                                 |
| --------------------------------- | ------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `id`                              | id                                    | The lead's id.                                                                                                                                                                                                                                                              |
| `object`                          | `"lead"`                              | Always `lead`.                                                                                                                                                                                                                                                              |
| `firstName`                       | string                                | First name.                                                                                                                                                                                                                                                                 |
| `lastName`                        | string                                | Last name.                                                                                                                                                                                                                                                                  |
| `companyName`                     | string or null                        | Company name, when the lead is a business.                                                                                                                                                                                                                                  |
| `email`                           | string or null                        | Email address, or null when none is on file.                                                                                                                                                                                                                                |
| `phone`                           | string or null                        | Phone number in E.164 form, such as `+14065550142`, or null.                                                                                                                                                                                                                |
| `address`                         | string                                | The service address.                                                                                                                                                                                                                                                        |
| `servicesRequested`               | array of string                       | What the lead asked for.                                                                                                                                                                                                                                                    |
| `specialRequests`                 | string or null                        | Anything else the lead said, or null.                                                                                                                                                                                                                                       |
| `estimatedHours`                  | number or null                        | The office's estimate of the work in hours, or null.                                                                                                                                                                                                                        |
| `sqFootage`                       | number or null                        | Square footage typed in by hand, or null.                                                                                                                                                                                                                                   |
| `status`                          | `pending`, `dismissed`                | `pending` leads are open; `dismissed` leads were set aside.                                                                                                                                                                                                                 |
| `lifecycleStage`                  | `lead`, `prospect`, `customer`        | `lead` until an estimate is sent (`prospect`) or a job is booked (`customer`).                                                                                                                                                                                              |
| `source`                          | `intake_form`, `manual`, `csv`, `api` | How the lead arrived: `intake_form` for the website form, `manual` for leads added in the app, `csv` for an import, `api` for leads created with the API (leads it created before October 2026 read `manual`). New values may be added; treat an unknown one like `manual`. |
| `customerId`                      | id or null                            | The customer account linked to the lead's email. It appears in the customers list and find\_customer once it has a job or the lead converts. Null when the lead is not linked, for example when its email belongs to a staff member.                                        |
| `propertyId`                      | id or null                            | The lead's property (service address), when linked.                                                                                                                                                                                                                         |
| `externalReferences`              | array of objects                      | Ids this lead has in your other systems, set with `externalReference`, the external upsert, or a link.                                                                                                                                                                      |
| `externalReferences[].source`     | string                                | The system the id comes from.                                                                                                                                                                                                                                               |
| `externalReferences[].externalId` | string                                | The object's id in that system.                                                                                                                                                                                                                                             |
| `createdAt`                       | timestamp                             | When the lead was created, ISO 8601 in UTC.                                                                                                                                                                                                                                 |
| `updatedAt`                       | timestamp                             | When the lead last changed, ISO 8601 in UTC.                                                                                                                                                                                                                                |

## Example

```json
{
  "id": "153fe9e3-118a-452a-8dd4-60710a1e9bb8",
  "object": "lead",
  "firstName": "Robin",
  "lastName": "Alvarez",
  "companyName": null,
  "email": "robin.alvarez@example.com",
  "phone": "(406) 555-0142",
  "address": "412 Elm St, Bozeman, MT 59715",
  "servicesRequested": [
    "Weekly mowing"
  ],
  "specialRequests": "Corner lot; gate on the side street.",
  "estimatedHours": 1.5,
  "sqFootage": 8200,
  "status": "pending",
  "lifecycleStage": "lead",
  "source": "intake_form",
  "customerId": "38d758fb-3521-4442-816b-cf892db60ad0",
  "propertyId": "40d0f49c-3d1b-4fe3-8965-6b2a35afa671",
  "externalReferences": [
    {
      "source": "mywebsite",
      "externalId": "contact-58213"
    }
  ],
  "createdAt": "2026-10-16T17:04:12.381Z",
  "updatedAt": "2026-10-16T17:04:12.381Z"
}
```

## Endpoints

| Endpoint                                             | What it does                       |
| ---------------------------------------------------- | ---------------------------------- |
| `GET /v1/leads`                                      | List leads                         |
| `POST /v1/leads`                                     | Create a lead                      |
| `GET /v1/leads/{id}`                                 | Get a lead                         |
| `PATCH /v1/leads/{id}`                               | Update a lead                      |
| `POST /v1/leads/{id}/dismiss`                        | Dismiss a lead                     |
| `PUT /v1/leads/{id}/external-references/{source}`    | Link a lead to your id             |
| `DELETE /v1/leads/{id}/external-references/{source}` | Unlink a lead from your id         |
| `POST /v1/leads/{id}/restore`                        | Restore a lead                     |
| `GET /v1/leads/external/{source}/{externalId}`       | Get a lead by your id              |
| `PUT /v1/leads/external/{source}/{externalId}`       | Create or update a lead by your id |