> 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/customer.md).

# The customer object

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

A customer: someone the workspace serves.

## Fields

| Field                             | Type                                                                                 | Description                                                                                                                                                                                                                                                                                                                            |
| --------------------------------- | ------------------------------------------------------------------------------------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `id`                              | id                                                                                   | The customer's id.                                                                                                                                                                                                                                                                                                                     |
| `object`                          | `"customer"`                                                                         | Always `customer`.                                                                                                                                                                                                                                                                                                                     |
| `firstName`                       | string                                                                               | First name.                                                                                                                                                                                                                                                                                                                            |
| `lastName`                        | string                                                                               | Last name.                                                                                                                                                                                                                                                                                                                             |
| `companyName`                     | string or null                                                                       | Company name, when the customer is a business.                                                                                                                                                                                                                                                                                         |
| `email`                           | string or null                                                                       | Email address, or null when the customer has none on file.                                                                                                                                                                                                                                                                             |
| `phone`                           | string or null                                                                       | Phone number as entered in the app.                                                                                                                                                                                                                                                                                                    |
| `status`                          | `active`, `inactive`, `invited`                                                      | `active` customers are served; `inactive` customers were deactivated.                                                                                                                                                                                                                                                                  |
| `tags`                            | array of objects                                                                     | Tags in the order they were attached.                                                                                                                                                                                                                                                                                                  |
| `tags[].id`                       | id                                                                                   | The tag's id.                                                                                                                                                                                                                                                                                                                          |
| `tags[].name`                     | string                                                                               | The tag's name as shown in the app.                                                                                                                                                                                                                                                                                                    |
| `externalReferences`              | array of objects                                                                     | Ids this customer has in your other systems, set with `externalReference` or the external upsert.                                                                                                                                                                                                                                      |
| `externalReferences[].source`     | string                                                                               | The system the id comes from.                                                                                                                                                                                                                                                                                                          |
| `externalReferences[].externalId` | string                                                                               | The object's id in that system.                                                                                                                                                                                                                                                                                                        |
| `createdAt`                       | timestamp                                                                            | When the customer was created, ISO 8601 in UTC.                                                                                                                                                                                                                                                                                        |
| `updatedAt`                       | timestamp                                                                            | When the customer last changed, ISO 8601 in UTC.                                                                                                                                                                                                                                                                                       |
| `properties`                      | array of [property](/developers/api-reference/reference/objects/property.md) objects | The customer's properties, oldest first. Only in answers from `POST /v1/customers`, `GET /v1/customers/{id}`, `PUT /v1/customers/{id}/external-references/{source}`, `DELETE /v1/customers/{id}/external-references/{source}`, `GET /v1/customers/external/{source}/{externalId}`, `PUT /v1/customers/external/{source}/{externalId}`. |

## Example

```json
{
  "id": "866b19f9-82b5-4540-8eff-90877b49cbce",
  "object": "customer",
  "firstName": "Robin",
  "lastName": "Alvarez",
  "companyName": null,
  "email": "robin.alvarez@example.com",
  "phone": "(406) 555-0142",
  "status": "active",
  "tags": [
    {
      "id": "2b7e279a-27c8-42e1-8412-9e28205cd96f",
      "name": "Corner lot"
    }
  ],
  "externalReferences": [
    {
      "source": "mywebsite",
      "externalId": "contact-58213"
    }
  ],
  "createdAt": "2026-10-16T17:04:12.381Z",
  "updatedAt": "2026-10-16T17:04:12.381Z",
  "properties": [
    {
      "id": "536f0846-4fb9-438d-8c03-7ed4484dba1b",
      "object": "property",
      "label": "Home",
      "address": "412 Elm St, Bozeman, MT 59715",
      "latitude": 45.6793,
      "longitude": -111.0373,
      "squareFeet": 8200,
      "status": "active",
      "createdAt": "2026-10-16T17:04:12.381Z",
      "updatedAt": "2026-10-16T17:04:12.381Z"
    }
  ]
}
```

## Endpoints

| Endpoint                                                 | What it does                           |
| -------------------------------------------------------- | -------------------------------------- |
| `GET /v1/customers`                                      | List customers                         |
| `POST /v1/customers`                                     | Create a customer                      |
| `GET /v1/customers/{id}`                                 | Get a customer                         |
| `PATCH /v1/customers/{id}`                               | Update a customer                      |
| `POST /v1/customers/{id}/deactivate`                     | Deactivate a customer                  |
| `PUT /v1/customers/{id}/external-references/{source}`    | Link a customer to your id             |
| `DELETE /v1/customers/{id}/external-references/{source}` | Unlink a customer from your id         |
| `POST /v1/customers/{id}/reactivate`                     | Reactivate a customer                  |
| `GET /v1/customers/external/{source}/{externalId}`       | Get a customer by your id              |
| `PUT /v1/customers/external/{source}/{externalId}`       | Create or update a customer by your id |