Use Cases & Bindings

Create, list, and delete channel use cases for voice and email communication.

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)

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