# Delete Klass

> DELETE /v1/klasses/{id} · Core resources API

Source: https://developer.kustomer.com/api/core-resources/delete-klass

```http
DELETE https://{orgname}.api.kustomerapp.com/v1/klasses/{id}
Authorization: Bearer <API key>
```

## Authorization

Requires any one of these roles: `org.permission.klass.delete`; or legacy `org.admin.klass.write`. The API key or user must hold at least one of them. Legacy roles predate permission sets and still work.

Deletes a Klass based on the unique Klass ID.

### Note
> You cannot delete a Klass if KObjects (custom objects) exist for the Klass in your Kustomer organization.

## About Klasses

A Klass is a custom object type that you define, such as "Order" or "Subscription", with its own name, icon, color and attributes. Each record of that type is a KObject.

Kustomer's built-in objects cover customers, companies and conversations. A Klass adds a new type of object for data from your own systems: orders, flight bookings, devices, returns. The Klass is the definition; the records themselves are [KObjects](https://developer.kustomer.com/api/core-resources#kobjects-custom-objects). For example, the `ecomm-order` Klass defines what an order looks like, and order #4417 is one KObject of that Klass. Admins manage Klasses in Kustomer's settings, and apps usually ship theirs in the [app definition](https://developer.kustomer.com/docs/apps/klasses) so every org that installs the app gets the same type.

A Klass is created once, then its attributes are defined by setting [custom attribute metadata](https://developer.kustomer.com/api/core-resources#custom-attributes) on the resource `kobject.<name>`, such as `kobject.ecomm-order`. The attribute names' suffixes set their types, for example `orderStatusStr` or `totalPriceNum`.

#### Key fields

| Field | Meaning |
| --- | --- |
| `name` | The system name used in KObject paths, such as `/v1/klasses/ecomm-order`. Letters, digits, `_` and `-`, unique in the org. It can't be changed after creation, so prefix it with your app or company name. |
| `displayName` | The label agents see. |
| `icon`, `color` | The icon (a Material Design Icons name, such as `basket`) and color used on timeline cards. |
| `status` | `enabled` or `disabled`. |
| `klassSchema` | Set to `task` to make the Klass a task type. Its KObjects then track `status` (`open` or `done`), assignment and completion times. |
| `mixins` | Agent-facing features to turn on for the Klass's records (see below). |

#### Mixins

| Mixin | Effect |
| --- | --- |
| `creatable` | Agents can create records of this Klass in Kustomer. |
| `editable` | Agents can edit the records' attributes in Kustomer. |
| `assignable` | Records can be assigned to users and teams, and used in routing queue rules. |
| `commentable` | Agents can add [comments](https://developer.kustomer.com/api/core-resources#comments) to the records. |

#### Which endpoint to use

| To | Call |
| --- | --- |
| List the org's Klasses | [`GET /v1/klasses`](https://developer.kustomer.com/api/core-resources/get-klasses) |
| Define a new custom object type | [`POST /v1/klasses`](https://developer.kustomer.com/api/core-resources/create-klass) |
| Read or update a Klass | [`GET`](https://developer.kustomer.com/api/core-resources/get-klass-by-id) or [`PUT /v1/klasses/{id}`](https://developer.kustomer.com/api/core-resources/update-klass-by-id) |
| Remove a Klass that has no records | [`DELETE /v1/klasses/{id}`](https://developer.kustomer.com/api/core-resources/delete-klass) |

Klass endpoints take the Klass's ID, while KObject endpoints take its `name`, so keep both. `GET /v1/klasses` returns only enabled Klasses by default; pass `status` (`enabled`, `existing_only` or `disabled`) to list others, or `name` to find one by name. You can't delete a Klass while any KObjects of it exist, so delete or migrate those first.

Related: [KObjects (custom objects)](https://developer.kustomer.com/api/core-resources#kobjects-custom-objects), [Custom attributes](https://developer.kustomer.com/api/core-resources#custom-attributes), [Klasses in app definitions](https://developer.kustomer.com/docs/apps/klasses), [KViews](https://developer.kustomer.com/api/apps-platform#kviews-klass-views)

### Recipes

#### 1. Set up a custom object type from a script

Create a Klass and its typed attributes in one repeatable setup script, for example when onboarding a new org to your integration.

**Step 1.** [`GET /v1/klasses`](https://developer.kustomer.com/api/core-resources/get-klasses.md). Check whether the Klass already exists so the script can run twice. Filter by `name`; an empty `data` array means it doesn't. Only enabled Klasses are returned by default, so pass `status=disabled` too if an admin may have disabled it.

```bash title="cURL"
curl "https://api.kustomerapp.com/v1/klasses?name=ecomm-order" \
  --header "Authorization: Bearer $KUSTOMER_API_KEY"
```

```bash title="kusty"
KLASS_ID=$(kusty api GET /v1/klasses --query name=ecomm-order | jq -r '.data[0].id // empty')
```

**Step 2.** [`POST /v1/klasses`](https://developer.kustomer.com/api/core-resources/create-klass.md). Create it if it's missing. `name` is permanent and becomes part of every KObject path, so prefix it with your app or company name. Kustomer stores it lowercase and singular. Choose `mixins` for what agents may do with the records. Keep the returned `id` for Klass endpoints and the `name` for KObject endpoints.

```bash title="cURL"
curl --request POST "https://api.kustomerapp.com/v1/klasses" \
  --header "Authorization: Bearer $KUSTOMER_API_KEY" \
  --header "Content-Type: application/json" \
  --data '{
    "name": "ecomm-order",
    "displayName": "Order",
    "icon": "basket",
    "color": "#64943E",
    "mixins": ["commentable"]
  }'
```

```bash title="kusty"
kusty api POST /v1/klasses \
  --field name=ecomm-order --field displayName=Order --field icon=basket \
  --field 'mixins:=["commentable"]'
```

**Step 3.** [`PUT /v1/metadata/{resource}`](https://developer.kustomer.com/api/core-resources/update-custom-attribute-metadata.md). Define the attributes on the resource `kobject.<name>`. The suffix of each attribute name sets its type, and `displayName` and `enumeration` control how agents see it. This call merges, so rerunning it with the same body is safe.

```bash title="cURL"
curl --request PUT "https://api.kustomerapp.com/v1/metadata/kobject.ecomm-order" \
  --header "Authorization: Bearer $KUSTOMER_API_KEY" \
  --header "Content-Type: application/json" \
  --data '{
    "properties": {
      "orderStatusStr": { "displayName": "Status", "enumeration": ["placed", "paid", "shipped", "delivered"] },
      "totalPriceNum": { "displayName": "Total" },
      "orderedAt": { "displayName": "Ordered" }
    }
  }'
```

```bash title="kusty"
kusty api PUT /v1/metadata/kobject.ecomm-order --data @order-attributes.json
```

> If you ship an app, define the Klass in the [app definition](https://developer.kustomer.com/docs/apps/klasses) instead, so every org that installs it gets the same type.

#### 2. Let agents comment on a Klass's records

Turn on another agent-facing feature, such as comments, for an existing Klass without dropping the ones it already has.

**Step 1.** [`GET /v1/klasses/{id}`](https://developer.kustomer.com/api/core-resources/get-klass-by-id.md). Read the Klass's current `mixins`. The list you send next replaces it, so start from what's there.

```bash title="cURL"
curl "https://api.kustomerapp.com/v1/klasses/$KLASS_ID" \
  --header "Authorization: Bearer $KUSTOMER_API_KEY"
```

```bash title="kusty"
MIXINS=$(kusty api GET /v1/klasses/$KLASS_ID | jq -c '(.data.attributes.mixins // []) + ["commentable"] | unique')
```

**Step 2.** [`PUT /v1/klasses/{id}`](https://developer.kustomer.com/api/core-resources/update-klass-by-id.md). Send the full list with `commentable` added. Agents can then add [comments](https://developer.kustomer.com/api/core-resources#comments) to the records in the agent desktop. Task Klasses need certain mixins, so a list that drops one of those fails with `400`.

```bash title="cURL"
curl --request PUT "https://api.kustomerapp.com/v1/klasses/$KLASS_ID" \
  --header "Authorization: Bearer $KUSTOMER_API_KEY" \
  --header "Content-Type: application/json" \
  --data '{"mixins": ["assignable", "commentable"]}'
```

```bash title="kusty"
kusty api PUT /v1/klasses/$KLASS_ID --field "mixins:=$MIXINS"
```

#### 3. Remove a Klass you no longer need

Retire a custom object type, either by hiding it or by deleting its records and then the Klass itself.

**Step 1.** [`PUT /v1/klasses/{id}`](https://developer.kustomer.com/api/core-resources/update-klass-by-id.md). To stop using a Klass without losing its data, set `status` to `disabled`. It drops out of `GET /v1/klasses` unless you ask for `status=disabled`. Stop here if that's enough.

```bash title="cURL"
curl --request PUT "https://api.kustomerapp.com/v1/klasses/$KLASS_ID" \
  --header "Authorization: Bearer $KUSTOMER_API_KEY" \
  --header "Content-Type: application/json" \
  --data '{"status": "disabled"}'
```

```bash title="kusty"
kusty api PUT /v1/klasses/$KLASS_ID --field status=disabled
```

**Step 2.** [`GET /v1/klasses/{name}`](https://developer.kustomer.com/api/core-resources/get-kobjects-custom-objects.md). To delete it, first collect the IDs of all its records. KObject endpoints take the Klass `name`, not its ID.

```bash title="cURL"
curl "https://api.kustomerapp.com/v1/klasses/$KLASS_NAME?pageSize=100" \
  --header "Authorization: Bearer $KUSTOMER_API_KEY"
```

```bash title="kusty"
kusty api GET /v1/klasses/$KLASS_NAME --all | jq -r '.data.id' > kobject-ids.txt
```

**Step 3.** [`DELETE /v1/klasses/{name}/{id}`](https://developer.kustomer.com/api/core-resources/delete-kobject-custom-object-by-id.md). Delete each record. Each delete returns `204 No Content`.

```bash title="cURL"
curl --request DELETE "https://api.kustomerapp.com/v1/klasses/$KLASS_NAME/$KOBJECT_ID" \
  --header "Authorization: Bearer $KUSTOMER_API_KEY"
```

```bash title="kusty"
while read -r ID; do
  kusty api DELETE /v1/klasses/$KLASS_NAME/$ID --confirm --yes
done < kobject-ids.txt
```

**Step 4.** [`DELETE /v1/klasses/{id}`](https://developer.kustomer.com/api/core-resources/delete-klass.md). Delete the Klass by its ID. While any KObject of the Klass still exists, the API refuses with `409 Conflict`.

```bash title="cURL"
curl --request DELETE "https://api.kustomerapp.com/v1/klasses/$KLASS_ID" \
  --header "Authorization: Bearer $KUSTOMER_API_KEY"
```

```bash title="kusty"
kusty api DELETE /v1/klasses/$KLASS_ID --confirm --yes
```

> Deleting records is permanent. For many thousands of records, [bulk deletes](https://developer.kustomer.com/api/core-resources/bulk-delete-kobjects-custom-objects) remove up to 100 per request as a background job.

### Example object

A real record from [`GET /v1/klasses/{id}`](https://developer.kustomer.com/api/core-resources/get-klass-by-id.md):

```json
{
  "type": "klass",
  "id": "5826a39b0fcc2514008b2a92",
  "attributes": {
    "name": "order",
    "displayName": "Order",
    "icon": "foobar",
    "status": "enabled",
    "mixins": [
      "assignable"
    ],
    "updatedAt": "2016-11-12T05:07:39.754Z",
    "createdAt": "2016-11-12T05:07:39.754Z"
  },
  "relationships": {
    "org": {
      "links": {
        "self": "/v1/orgs/57bb5d2e32e83a130052e94e"
      },
      "data": {
        "type": "org",
        "id": "57bb5d2e32e83a130052e94e"
      }
    },
    "kobjects": {
      "links": {
        "self": "/v1/klasses/purchases"
      }
    }
  },
  "links": {
    "self": "/v1/klasses/5826a39b0fcc2514008b2a92"
  }
}
```

Fields:

- `id` (string): The Klass ID, which the Klass endpoints take. KObject endpoints take the `name` instead, so store both.
- `attributes.name` (string): The system name used in KObject paths and types, such as `/v1/klasses/order` and `kobject.order`. Kustomer stores it lowercase and singular, and it can't be changed after creation.
- `attributes.displayName` (string): The label agents see for this type of record. You can change it at any time.
- `attributes.icon` (string): The Material Design Icons name shown on the records' timeline cards. A KObject can override it with its own `icon`.
- `attributes.status` (string): `enabled` or `disabled`. `GET /v1/klasses` returns only enabled Klasses unless you pass `status`.
- `attributes.mixins` (array): Agent-facing features turned on for the records: `creatable`, `editable`, `assignable` and `commentable`. `PUT` replaces the whole list, so send every mixin you want to keep.
- `relationships.kobjects` (object): A link to this Klass's records, with no `data`. List them with `GET /v1/klasses/{name}`.

### Relationships

- Points to **KObjects (custom objects)** via `relationships.kobjects` (list): The records of this type. Each KObject belongs to one Klass, and KObject endpoints name the Klass in their path, such as `/v1/klasses/order/{id}`.
- Referenced by **Comments** via `relationships.klass`: On a comment, the Klass of the KObject it's on. `data.id` is the Klass `name`, not its ID.
- Referenced by **KObjects (custom objects)** via `relationships.klass`: Every KObject belongs to exactly one Klass, its type. KObject endpoints name the Klass in the path, and the Klass's `kobjects` link lists its records.
- Referenced by **Snooze options** via `relationships.parentId`: The Klass a custom object snooze option belongs to, sent as `parentId` (or `parentName`) when the option is created. `GET /v1/snoozes/klass/{id}` lists the options for one Klass.
- Referenced by **Sub-statuses** via `relationships.parentId`: The Klass a custom object sub-status belongs to, sent as `parentId` (or `parentName`) on create and used to filter `GET /v1/sub-statuses`. Records of that Klass can use its sub-statuses; conversation sub-statuses have no Klass.

### Permissions

Fewest roles for a read-only integration: `org.permission.klass.read`. For every endpoint: `org.permission.klass.read`, `org.permission.klass.create`, `org.permission.klass.delete`, `org.permission.klass.update`.

### Events

Workflow actions:

- `kustomer.klass.create` (Klass: Create): required inputs `name`, `status`
- `kustomer.klass.find-by-klassname` (Klass: Lookup (By Klass name)): required inputs `klassName`

## Path parameters

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `id` | string | yes | Unique Klass ID. |

## Responses

### 204

No Content

### 401

Unauthorized

### 403

Forbidden

### 404

Not Found

## Example request

```bash
curl --request DELETE \
  --url 'https://api.kustomerapp.com/v1/klasses/5826a39b0fcc2514008b2a92' \
  --header "Authorization: Bearer $KUSTOMER_API_KEY"
```