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

# Outcome Types API

> Create, update, list, and delete outcome type definitions that classify customer interaction results.

<Note>
  **See also**: [Outcome Types concept and configuration](/studio/outcome-types) for what this API powers, when to call it, and how it is configured.
</Note>

Outcome types define the vocabulary of customer responses in the platform. Each outcome type has a classification (positive, negative, or neutral) and a category (impression or response). System-default outcome types are auto-seeded on first access.

All outcome types support **soft-delete** (a `deletedAt` timestamp is set instead of permanent removal), **version tracking** (the `version` field auto-increments on every update), and **audit logging** (before/after snapshots are recorded for every CRUD operation).

<Info>
  See the [Outcome Types feature page](/studio/outcome-types) for UI guidance and conceptual overview.
</Info>

## Base path

```
/api/v1/outcome-types
```

***

## List outcome types

```
GET /api/v1/outcome-types
```

Returns all outcome types for the current tenant, ordered by ordinal (ascending). If no outcome types exist, the system defaults are automatically seeded. By default, soft-deleted outcome types are excluded.

### Query parameters

| Parameter        | Required | Type   | Description                                                           |
| ---------------- | -------- | ------ | --------------------------------------------------------------------- |
| `includeDeleted` | No       | string | Set to `"true"` to include soft-deleted outcome types in the results. |

### System defaults

| Key              | Name                | Classification | Category   |
| ---------------- | ------------------- | -------------- | ---------- |
| `impression`     | Impression          | neutral        | impression |
| `click`          | Click               | positive       | response   |
| `dismiss`        | Dismiss             | negative       | response   |
| `accept`         | Accept              | positive       | response   |
| `convert`        | Convert             | positive       | response   |
| `not_presented`  | Not Presented       | neutral        | impression |
| `requested_info` | Requested More Info | positive       | response   |
| `not_interested` | Not Interested      | negative       | response   |
| `expired`        | Expired             | neutral        | impression |
| `deferred`       | Deferred            | neutral        | response   |

### Response `200`

Returns a flat array (not paginated) of all outcome types.

```json theme={null}
[
  {
    "id": "ot_001",
    "tenantId": "t_001",
    "key": "click",
    "name": "Click",
    "description": "",
    "classification": "positive",
    "category": "response",
    "isSystem": true,
    "ordinal": 1,
    "status": "active",
    "version": 1,
    "deletedAt": null,
    "createdAt": "2026-03-10T12:00:00.000Z",
    "updatedAt": "2026-03-10T12:00:00.000Z"
  }
]
```

### Error codes

| Code  | Reason                                |
| ----- | ------------------------------------- |
| `401` | Missing or invalid API key / session. |
| `403` | Insufficient role.                    |

***

## Create an outcome type

```
POST /api/v1/outcome-types
```

Creates a custom outcome type. Custom types have `isSystem: false` and can be fully edited or deleted.

### Request body

| Field            | Required | Type           | Description                                               |
| ---------------- | -------- | -------------- | --------------------------------------------------------- |
| `key`            | **Yes**  | string (1-255) | Unique key identifier (e.g., `"purchased"`, `"bounced"`). |
| `name`           | **Yes**  | string (1-255) | Display name.                                             |
| `description`    | No       | string         | Description. Default `""`.                                |
| `classification` | No       | enum           | `positive`, `negative`, `neutral`. Default `"neutral"`.   |
| `category`       | No       | enum           | `impression`, `response`. Default `"response"`.           |
| `ordinal`        | No       | integer (>= 0) | Sort order. Default `99`.                                 |
| `status`         | No       | enum           | `draft`, `active` (default), `paused`, `archived`.        |

### Example request

```json theme={null}
{
  "key": "purchased",
  "name": "Purchased",
  "classification": "positive",
  "category": "response",
  "ordinal": 10
}
```

### Response `201`

Returns the created outcome type object with `version: 1` and `deletedAt: null`. An audit log entry is created with a `create` action.

### Error codes

| Code  | Reason                                                                                        |
| ----- | --------------------------------------------------------------------------------------------- |
| `400` | Validation error (missing key or name).                                                       |
| `401` | Missing or invalid API key / session.                                                         |
| `403` | Insufficient role (requires `editor` or `admin`).                                             |
| `409` | An outcome type with that `key` already exists for the tenant (unique per `(tenantId, key)`). |
| `413` | Request body exceeds the 2 MB limit.                                                          |
| `415` | `Content-Type` is not `application/json`.                                                     |

***

## Update an outcome type

```
PUT /api/v1/outcome-types
```

Updates an existing outcome type. Only provided fields are changed. The `version` field is auto-incremented and a before/after audit snapshot is recorded.

<Warning>
  System outcome types (`isSystem: true`) only allow editing `name`, `description`, and `ordinal`. The `key`, `classification`, `category`, and `status` fields are locked for system types.
</Warning>

### Request body

| Field            | Required | Type    | Description                                 |
| ---------------- | -------- | ------- | ------------------------------------------- |
| `id`             | **Yes**  | string  | The outcome type ID to update.              |
| `key`            | No       | string  | Updated key (custom types only).            |
| `name`           | No       | string  | Updated display name.                       |
| `description`    | No       | string  | Updated description.                        |
| `classification` | No       | enum    | Updated classification (custom types only). |
| `category`       | No       | enum    | Updated category (custom types only).       |
| `ordinal`        | No       | integer | Updated sort order.                         |
| `status`         | No       | enum    | Updated status (custom types only).         |

### Response `200`

Returns the updated outcome type object with the incremented `version`.

### Error codes

| Code  | Reason                                |
| ----- | ------------------------------------- |
| `400` | Validation error.                     |
| `401` | Missing or invalid API key / session. |
| `403` | Insufficient role.                    |
| `404` | Outcome type not found.               |

***

## Delete an outcome type (soft-delete)

```
DELETE /api/v1/outcome-types?id={outcomeTypeId}
```

Soft-deletes a custom outcome type by setting its `deletedAt` timestamp. System outcome types cannot be deleted.

### Query parameters

| Parameter | Required | Type   | Description                |
| --------- | -------- | ------ | -------------------------- |
| `id`      | **Yes**  | string | Outcome type ID to delete. |

### Response `200`

```json theme={null}
{
  "deleted": true
}
```

### Error codes

| Code  | Reason                                               |
| ----- | ---------------------------------------------------- |
| `400` | Missing `id` query parameter, or soft-delete failed. |
| `401` | Missing or invalid API key / session.                |
| `403` | Cannot delete system outcome types.                  |
| `404` | Outcome type not found.                              |

<Note>
  To restore a soft-deleted outcome type, use `POST /api/v1/restore?entityType=outcomeType&id={outcomeTypeId}` (admin only).
</Note>

***

## Role requirements

| Method | Minimum role |
| ------ | ------------ |
| GET    | `viewer`     |
| POST   | `editor`     |
| PUT    | `editor`     |
| DELETE | `editor`     |