Outcome Types API

See also: Outcome Types concept and configuration for what this API powers, when to call it, and how it is configured.

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).

See the Outcome Types feature page for UI guidance and conceptual overview.

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.

[
  {
    "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

{
  "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.

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

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`

{
  "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.

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

Role requirements

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

Overview

Decisioning

Studio

Data

Algorithms & Models

Content & Metrics

Orchestration

Customers & Traces

Events & Attribution

Analytics

AI

Testing & Simulation

Export & Import

Admin

Integrations

Base path

List outcome types

Query parameters

System defaults

Response `200`

Error codes

Create an outcome type

Request body

Example request

Response `201`

Error codes

Update an outcome type

Request body

Response `200`

Error codes

Delete an outcome type (soft-delete)

Query parameters

Response `200`

Error codes

Role requirements

​Base path

​List outcome types

​Query parameters

​System defaults

​Response 200

​Error codes

​Create an outcome type

​Request body

​Example request

​Response 201

​Error codes

​Update an outcome type

​Request body

​Response 200

​Error codes

​Delete an outcome type (soft-delete)

​Query parameters

​Response 200

​Error codes

​Role requirements

Base path

List outcome types

Query parameters

System defaults

Response `200`

Error codes

Create an outcome type

Request body

Example request

Response `201`

Error codes

Update an outcome type

Request body

Response `200`

Error codes

Delete an outcome type (soft-delete)

Query parameters

Response `200`

Error codes

Role requirements