Use Cases & Bindings

List channel use cases for voice, SMS, iMessage, and email, and bind each use case to the platform service that handles its conversations.

Use cases define how a workspace uses a specific communication channel, and service bindings connect each use case to the platform service that handles its conversations. 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
GET	/use-cases	List use cases
GET	/use-cases/ownership	List the use case IDs this workspace owns
GET	/use-cases/{use_case_id}/ownership	Get the workspace's ownership record for a use case
PUT	/use-cases/{use_case_id}/ownership	Claim ownership of a use case for the workspace
DELETE	/use-cases/{use_case_id}/ownership	Release the workspace's ownership of a use case
PUT	/use-cases/{use_case_id}/service-binding	Bind a use case to a platform service
DELETE	/use-cases/{use_case_id}/service-binding	Unbind a use case from its service
GET	/use-cases/{use_case_id}/service-binding	Get the current service binding

Use case lifecycle (create, update, delete) is managed through the channel management API (POST /v1/use-case, PUT /v1/use-case/{use_case_id}, DELETE /v1/use-case/{use_case_id}), authenticated with an OAuth2 client credential carrying the use-case:write scope on the target channel setup. See Channel Manager.

Create a Use Case

Create a use case through the channel management API. The request body is a discriminated union on the channel field: inbound_voice, outbound_voice, ringless_voicemail, and sms use cases associate a telephony setup, imessage use cases associate an iMessage setup, and email use cases associate an email setup plus a sender email address and email type (transactional or marketing).

Scope required: use-case:write on the target setup

POST /v1/use-case
Authorization: Bearer <oauth2_access_token>
Content-Type: application/json

List Use Cases

List use cases with optional filters by entity name, channel, and setup ID. Filtering by setup_id requires channel to also be specified.

Permission required: Channel.view

List channel use cases

get

List use cases with optional filters by entity_name, channel, setup_id. Requires Channel.view permission.

Authorizations

BearerAuth

AuthorizationstringRequired

API key issued via POST /v1/{workspace_id}/api-keys. Pass the returned api_key value as a Bearer token.

Path parameters

workspace_idstring · uuidRequired

Query parameters

entity_namestring · nullableOptional

channelstring · enum · nullableOptionalPossible values:

setup_idstring · uuid · nullableOptional

Responses

200

Successful Response

application/json

403

Insufficient permissions.

422

Validation Error

application/json

get/v1/{workspace_id}/use-cases

HTTPcURLJavaScriptPython

GET /v1/{workspace_id}/use-cases HTTP/1.1
Host: api.platform.amigo.ai
Authorization: Bearer YOUR_SECRET_TOKEN
Accept: */*

{
  "items": [
    {
      "id": "text",
      "channel": "text",
      "entity_name": "text",
      "name": "text",
      "description": "text",
      "setup_id": "text",
      "configuration_set_name": "text",
      "sender_email_address": "text",
      "email_type": "text",
      "tier": "text",
      "unsubscribable": true,
      "accepts_cold_inbound": true,
      "created_at": "2026-07-10T22:17:33.447Z",
      "updated_at": "2026-07-10T22:17:33.447Z"
    }
  ]
}

Delete a Use Case

Delete a use case by ID through the channel management API. Returns 409 while phone numbers or lines are still assigned to the use case - unassign them first.

Scope required: use-case:write on the target setup

DELETE /v1/use-case/{use_case_id}
Authorization: Bearer <oauth2_access_token>

Ownership

A workspace claims ownership of a channel-manager use case before binding it to a service. Claiming requires the Channel.ManageOwnership permission (admin tier), is idempotent (re-claiming an already-owned use case returns 200), and returns 409 if another workspace already owns the use case. Releasing ownership returns 409 while any service still binds the use case - unbind first.

Service Binding

A use case can be bound to a platform service. A binding is unique per workspace for a given service and channel pair: only one use case may bind a given (service, channel) at a time.

Bind a Service

Upserts a binding for the use case. If the use case already has a binding, the prior binding is replaced. A different use case cannot bind a service and channel pair that is already bound.

Permission required: Channel.create

Bind a use case to a platform service

put

Bind this use case to a platform service in the current workspace. PUT semantics — rebinding to a different service replaces the prior binding. Inbound webhook events for the use case will resolve to this workspace; outbound dispatch from the service will route through this use case for its channel. 409 if a different use case already binds the same (service, channel) pair. 404 if the service or use case is missing or belongs to another workspace. Requires Channel.create permission.

Authorizations

BearerAuth

AuthorizationstringRequired

API key issued via POST /v1/{workspace_id}/api-keys. Pass the returned api_key value as a Bearer token.

Path parameters

workspace_idstring · uuidRequired

use_case_idstring · uuidRequired

Body

application/json

service_idstring · uuidRequired

Responses

200

Successful Response

application/json

use_case_idstring · uuidRequired

service_idstring · uuidRequired

workspace_idstring · uuidRequired

channelstring · enumRequiredPossible values:

created_atstring · date-timeRequired

updated_atstring · date-timeRequired

403

Insufficient permissions.

404

Use case or service not found.

409

Service already has a different use case bound for this channel.

422

Unsupported use case channel.

502

Channel manager unavailable.

504

Channel manager timed out.

put/v1/{workspace_id}/use-cases/{use_case_id}/service-binding

HTTPcURLJavaScriptPython

PUT /v1/{workspace_id}/use-cases/{use_case_id}/service-binding HTTP/1.1
Host: api.platform.amigo.ai
Authorization: Bearer YOUR_SECRET_TOKEN
Content-Type: application/json
Accept: */*
Content-Length: 53

{
  "service_id": "123e4567-e89b-12d3-a456-426614174000"
}

{
  "use_case_id": "123e4567-e89b-12d3-a456-426614174000",
  "service_id": "123e4567-e89b-12d3-a456-426614174000",
  "workspace_id": "123e4567-e89b-12d3-a456-426614174000",
  "channel": "inbound_voice",
  "created_at": "2026-07-10T22:17:33.447Z",
  "updated_at": "2026-07-10T22:17:33.447Z"
}

Unbind a Service

Soft-unbinds the use case from its service. Fails if no live binding exists for the use case.

Permission required: Channel.delete

Unbind a use case from its platform service

delete

Release a use case from its bound service in this workspace. Soft-delete on the binding row. 404 if the use case is not currently bound (covers both 'never bound' and 'already unbound'). Requires Channel.delete permission.

Authorizations

BearerAuth

AuthorizationstringRequired

API key issued via POST /v1/{workspace_id}/api-keys. Pass the returned api_key value as a Bearer token.

Path parameters

workspace_idstring · uuidRequired

use_case_idstring · uuidRequired

Responses

204

Successful Response

No content

403

Insufficient permissions.

404

Use case is not bound to a service in this workspace.

422

Validation Error

application/json

delete/v1/{workspace_id}/use-cases/{use_case_id}/service-binding

HTTPcURLJavaScriptPython

DELETE /v1/{workspace_id}/use-cases/{use_case_id}/service-binding HTTP/1.1
Host: api.platform.amigo.ai
Authorization: Bearer YOUR_SECRET_TOKEN
Accept: */*

No content

Get the Service Binding

Returns the current service binding for the use case. Fails if no binding exists for the use case.

Permission required: Channel.view

Get the service binding for a use case

get

Return the platform service this use case is bound to in this workspace, or 404 if unbound. Requires Channel.view permission.

Authorizations

BearerAuth

AuthorizationstringRequired

API key issued via POST /v1/{workspace_id}/api-keys. Pass the returned api_key value as a Bearer token.

Path parameters

workspace_idstring · uuidRequired

use_case_idstring · uuidRequired

Responses

200

Successful Response

application/json

use_case_idstring · uuidRequired

service_idstring · uuidRequired

workspace_idstring · uuidRequired

channelstring · enumRequiredPossible values:

created_atstring · date-timeRequired

updated_atstring · date-timeRequired

403

Insufficient permissions.

404

Use case is not bound to a service in this workspace.

422

Validation Error

application/json

get/v1/{workspace_id}/use-cases/{use_case_id}/service-binding

HTTPcURLJavaScriptPython

GET /v1/{workspace_id}/use-cases/{use_case_id}/service-binding HTTP/1.1
Host: api.platform.amigo.ai
Authorization: Bearer YOUR_SECRET_TOKEN
Accept: */*

{
  "use_case_id": "123e4567-e89b-12d3-a456-426614174000",
  "service_id": "123e4567-e89b-12d3-a456-426614174000",
  "workspace_id": "123e4567-e89b-12d3-a456-426614174000",
  "channel": "inbound_voice",
  "created_at": "2026-07-10T22:17:33.447Z",
  "updated_at": "2026-07-10T22:17:33.447Z"
}