> ## Documentation Index
> Fetch the complete documentation index at: https://trysalty.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# People

> Humans — leads, contacts, customers. The most-used object.

People are the canonical CRUD resource — every object type follows this template. People, companies, and deals additionally expose a `POST /search` for structured filtering; the other object types are list + CRUD only.

## Endpoints

| Method   | Path             | Purpose                                                                         |
| -------- | ---------------- | ------------------------------------------------------------------------------- |
| `GET`    | `/people`        | List, paginated                                                                 |
| `POST`   | `/people`        | Create                                                                          |
| `GET`    | `/people/:id`    | Fetch one. `?expand=primary_company` inlines the company                        |
| `PATCH`  | `/people/:id`    | Update                                                                          |
| `DELETE` | `/people/:id`    | Soft-delete (moves to 30-day trash; restore via POST /trash/people/:id/restore) |
| `POST`   | `/people/search` | Filter, sort, paginate                                                          |

## Fields

| Field                      | Type           | Notes                                                     |
| -------------------------- | -------------- | --------------------------------------------------------- |
| `id`                       | uuid           | Server-assigned                                           |
| `email`                    | string \| null | Indexed (case-insensitive)                                |
| `first_name`, `last_name`  | string \| null |                                                           |
| `primary_company_id`       | uuid \| null   | Reference to a `companies` row                            |
| `custom_attributes`        | object         | Validated by the [schema engine](/docs/concepts/schema-engine) |
| `created_at`, `updated_at` | datetime       |                                                           |

## Create

```bash theme={null}
curl -X POST $SALTY_API/people \
  -H "Authorization: Bearer $SALTY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"email":"jane@acme.com","first_name":"Jane","custom_attributes":{"tier":"enterprise"}}'
```

## Expand the company

```bash theme={null}
curl "$SALTY_API/people/<id>?expand=primary_company" \
  -H "Authorization: Bearer $SALTY_API_KEY"
```

The response inlines `primary_company` using the same snake\_case serializer the `/companies` endpoint uses — no Drizzle field names leak through.

## Search

`POST /people/search` accepts a filter body. Operators: `equals | not_equals | contains | gt | gte | lt | lte | is_null`. Combinators: `and | or` (top-level only in v1). Custom attribute fields addressed via `custom_attributes.<key>`.

```bash theme={null}
curl -X POST $SALTY_API/people/search \
  -H "Authorization: Bearer $SALTY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "filter": {
      "and": [
        {"email": {"contains": "@acme.com"}},
        {"custom_attributes.tier": {"equals": "enterprise"}}
      ]
    },
    "sort": [{"created_at": "desc"}],
    "limit": 50
  }'
```

Returns the same `{ data, next_cursor }` envelope as the list endpoint.