# Use Cases & Bindings

Use cases define how a workspace uses a specific communication channel. Each use case ties an approved channel setup to a named purpose - for example, an outbound voice use case for appointment reminders or an email use case for transactional notifications.

Base path: `/v1/{workspace_id}/use-cases`

## Endpoints

| Method   | Path                       | Description       |
| -------- | -------------------------- | ----------------- |
| `POST`   | `/use-cases`               | Create a use case |
| `GET`    | `/use-cases`               | List use cases    |
| `DELETE` | `/use-cases/{use_case_id}` | Delete a use case |

## Create a Use Case

`POST /v1/{workspace_id}/use-cases`

Create a voice or email use case. The request body is a discriminated union on the `channel` field.

**Permission required:** Channel.create

### Voice Use Case Request Body

| Field         | Type          | Required | Description                                                    |
| ------------- | ------------- | -------- | -------------------------------------------------------------- |
| `channel`     | string        | Yes      | One of `outbound_voice`, `inbound_voice`, `ringless_voicemail` |
| `entity_name` | string        | Yes      | Entity name (1-31 chars, letters/hyphens/spaces)               |
| `name`        | string        | Yes      | Use case name (1-31 chars, letters/hyphens/spaces)             |
| `description` | string        | No       | Description (max 2000 chars)                                   |
| `setup_id`    | string (UUID) | Yes      | ID of the telephony setup to associate                         |

### Email Use Case Request Body

| Field                  | Type           | Required | Description                                        |
| ---------------------- | -------------- | -------- | -------------------------------------------------- |
| `channel`              | string         | Yes      | Must be `email`                                    |
| `entity_name`          | string         | Yes      | Entity name (1-31 chars, letters/hyphens/spaces)   |
| `name`                 | string         | Yes      | Use case name (1-31 chars, letters/hyphens/spaces) |
| `description`          | string         | No       | Description (max 2000 chars)                       |
| `setup_id`             | string (UUID)  | Yes      | ID of the email setup to associate                 |
| `sender_email_address` | string (email) | Yes      | Sender email address                               |
| `email_type`           | string         | Yes      | One of `transactional`, `marketing`                |

### Response (201 Created)

| Field                    | Type              | Description                         |
| ------------------------ | ----------------- | ----------------------------------- |
| `id`                     | string (UUID)     | Use case ID                         |
| `channel`                | string            | Channel type                        |
| `entity_name`            | string            | Entity name                         |
| `name`                   | string            | Use case name                       |
| `description`            | string or null    | Description                         |
| `setup_id`               | string (UUID)     | Associated setup ID                 |
| `configuration_set_name` | string or null    | Configuration set name (email only) |
| `sender_email_address`   | string or null    | Sender email (email only)           |
| `email_type`             | string or null    | Email type (email only)             |
| `tier`                   | string or null    | Assigned tier                       |
| `created_at`             | string (ISO 8601) | Creation timestamp                  |
| `updated_at`             | string (ISO 8601) | Last update timestamp               |

### Error Responses

| Status | Description                                   |
| ------ | --------------------------------------------- |
| 403    | Insufficient permissions                      |
| 404    | Setup not found                               |
| 409    | Use case already exists or setup not approved |
| 422    | Invalid use case configuration                |
| 502    | Upstream service unavailable                  |
| 504    | Upstream service timed out                    |

## List Use Cases

`GET /v1/{workspace_id}/use-cases`

List use cases with optional filters.

**Permission required:** Channel.view

### Query Parameters

| Parameter     | Type          | Required | Description                                                                          |
| ------------- | ------------- | -------- | ------------------------------------------------------------------------------------ |
| `entity_name` | string        | No       | Filter by entity name                                                                |
| `channel`     | string        | No       | Filter by channel (`outbound_voice`, `inbound_voice`, `ringless_voicemail`, `email`) |
| `setup_id`    | string (UUID) | No       | Filter by setup ID. Requires `channel` to also be specified                          |

### Response (200 OK)

```json
{
  "items": [
    {
      "id": "uuid",
      "channel": "outbound_voice",
      "entity_name": "Appointment Reminders",
      "name": "Outbound Reminder",
      "description": "Reminder calls for upcoming appointments",
      "setup_id": "uuid",
      "configuration_set_name": null,
      "sender_email_address": null,
      "email_type": null,
      "tier": "standard",
      "created_at": "2026-06-01T12:00:00Z",
      "updated_at": "2026-06-01T12:00:00Z"
    }
  ]
}
```

### Error Responses

| Status | Description                           |
| ------ | ------------------------------------- |
| 403    | Insufficient permissions              |
| 422    | `setup_id` provided without `channel` |

## Delete a Use Case

`DELETE /v1/{workspace_id}/use-cases/{use_case_id}`

Delete a use case by ID. Voice use cases with active phone number assignments cannot be deleted.

**Permission required:** Channel.delete

### Path Parameters

| Parameter     | Type          | Description           |
| ------------- | ------------- | --------------------- |
| `use_case_id` | string (UUID) | Use case ID to delete |

### Response (204 No Content)

Empty response body on success.

### Error Responses

| Status | Description                                  |
| ------ | -------------------------------------------- |
| 403    | Insufficient permissions                     |
| 404    | Use case not found                           |
| 409    | Use case has active phone number assignments |
| 502    | Upstream service unavailable                 |
| 504    | Upstream service timed out                   |


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.amigo.ai/developer-guide/platform-api/platform-api/use-cases.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.