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

# Customer Entities

> Create, list, update, suspend, reactivate, and delete customer Entities

**Auth:** secret key only. When API permissions are enabled, reads require `entity:read` and mutations require `entity:write`. Publishable keys cannot read the Entity directory.

List Entities with an optional `status`, `limit` from 1 to 100, and opaque `cursor`:

```http theme={null}
GET /customers/workspace_123/entities?status=active&limit=50
Authorization: Bearer sk_...
```

Read one Entity:

```http theme={null}
GET /customers/workspace_123/entities/user_42
Authorization: Bearer sk_...
```

Create or replace its display fields and status:

```http theme={null}
PUT /customers/workspace_123/entities/user_42
Authorization: Bearer sk_...
Idempotency-Key: entity-user-42-v1
Content-Type: application/json

{
  "name": "Asha",
  "status": "active",
  "metadata": { "role": "agent" }
}
```

The upsert payload is a complete snapshot. When changing only status, send the current `name` and `metadata` so they are not cleared.

Entity lifecycle operations never create billing events. If your product bills
per seat, your backend must track that seat separately through the Events API.

Bulk upsert accepts 1 to 500 unique external IDs:

```http theme={null}
POST /customers/workspace_123/entities/bulk-upsert
Authorization: Bearer sk_...
Idempotency-Key: entity-import-2026-07-22
Content-Type: application/json

{
  "entities": [
    { "external_id": "user_42", "name": "Asha", "status": "active", "metadata": {} },
    { "external_id": "user_43", "name": "Ben", "status": "suspended", "metadata": {} }
  ]
}
```

Delete through the lifecycle endpoint:

```http theme={null}
DELETE /customers/workspace_123/entities/user_42
Authorization: Bearer sk_...
Idempotency-Key: delete-user-42
```

Deletion is not a financial cascade. It preserves all source, allocation, operation, and audit rows. Retry an uncertain mutation with the same idempotency key and identical payload.